UDP Proxy for EPICS Channel-Access Tunneling with SSH

What's New?

2013/11/1 - Caxy-2.0.1 released

• Bump of protocol version (i.e., both 'inside' and 'outside' must run version 2.0 or later). The change is small but not backwards compatible. It allows the outside to detect that the tunnel has been established.
• Server mode has been added (-S). This is useful under Android (an Android port is available).
• Code better modularized. Can use relevant classes w/o a 'main' application (useful under Android).
• Use ProxifiedSocketChannel class for the TCP tunnel (when not using ssh's stdio). This allows for easy 'proxification' of the CA tunnel connection itself. No dedicated ssh tunnel is then necessary (-D 1080 is all you need). Nevertheless: under normal circumstances the most convenient method to set up a tunnel is using ssh's STDIO (RTM).

Introduction

The EPICS CA protocol uses both, TCP and UDP messages. While it is easy to tunnel the former using the powerful port-forwarding features of SSH it is not straightforward to tunnel UDP messages.

This site presents the caxy proxy software that encapsulates (and modifies) CA-UDP messages for tunneling them via TCP.

Dynamic TCP Tunneling with SSH and SOCKS

TCP connections can easily be forwarded through a secure channel using openssh's '-D' option (putty under windows implements an equivalent feature). Assume you have a 'insidehost' machine which is only reachable via ssh but has connectivity to an EPICS CA subnet. You want to connect to EPICS IOCs on that subnet from an 'outsidelaptop' machine which is somewhere out on the internet:

  outsidelaptop> ssh -D 1080  user@insidehost

opens a secure connection to 'insidehost' from 'outsidelaptop'. The command also starts a SOCKS proxy server on 'outsidelaptop' port 1080 which allows you to forward any TCP connection to a destination reachable from 'insidehost' through the secure channel (only the stretch between 'outsidelaptop' and 'insidehost' is encrypted/secure).

In order to let a CA client use the SOCKS proxy server you must either patch the CA client library (so that it natively supports SOCKS proxies) or use so-called 'proxifier' software (e.g., tsocks or dante) which intercepts the connect() system-call and sets up a connection through a SOCKS proxy instead.

Using a patched CA client library you define a SOCKS proxy and then use CA clients as usual:

  export EPICS_SOCKS_PROXY=localhost:1080
  caget SOME_PV

If you use a proxifier then you 'proxify' a shell session and use CA clients as usual (the proxifier software usually requires you to write a configuration file; consult the documentation). Using e.g., 'dante' (note the '.'):

  . socksify
  caget SOME_PV

The described procedure (start ssh with -D, use patched or proxified CA client) is enough to handle the TCP parts of the CA protocol. However, using the described steps is not enough and does not work by itself because the UDP parts of CA have not been dealt with properly.

This is where the caxy software comes to our rescue. caxy encapsulates the UDP portions of the CA protocol and forwards them through a secure TCP channel. caxy properly deals with

• CA search request and reply messages (requests typically are UDP broadcasts)
• CA beacons

CAXY -- Channel Access UDP Proxy

The caxy software handles the UDP aspects of the Channel-Access protocol, encapsulating UDP messages and forwarding them through a secure channel. caxy is written in java - there is usually no need for compiling anything. Just download 'caxy.jar' and execute on any platform (which supports java). caxy also supports starting up a complete tunnel for CA-UDP. Using a system with ssh available you start a CA-UDP tunnel simply with:

  outsidelaptop> java -jar caxy.jar -- ssh -D1080 user@insidehost java -jar caxy.jar -I

After setting up such a tunnel, a patched or proxified CA client "just works", transparently connecting to any PV on the 'inside' network. It is assumed that the login script on 'insidehost' already sets up the CA environment correctly (otherwise, a setup script could easily be executed by the ssh command).

For beacons to be propagated from the 'inside' to the 'outside' a CA-repeater must be running on the 'inside' (caxy does not attempt to start a repeater). For beacons to be seen by clients on the 'outside' a CA-repeater must also be running on the 'outside' but the standard CA clients usually take care of starting a repeater when necessary.

Why Should I Use CAXY?

Some obvious alternatives to caxy exist:

EPICS base >= 3.14.12 supports CA search request via TCP.

Yes - but it would require you to add each and every IOC to the EPICS_CA_NAME_SERVERS. caxy can use normal UDP broadcasts on the 'inside' without the need for assembling a cumbersome-to-maintain list of all IOCs. The EPICS_CA_NAME_SERVERS feature seems to be more useful in combination with a CA gateway.

I can run a CA gateway

Sure you can. But you might have to build, configure and maintain it. Using caxy you can just download and run a jar file. Easier and faster to get going. Also, if multiple people start running gateways on 'insidehost' then you will have to think about how to pick port numbers and make sure you set set them up and tunnel them correctly and w/o conflicting with other users.

Finally - if you are a JCA / CAJ / CSS user: CAJ may currently not support CA search requests via TCP. However, caxy does work with CAJ/CSS and a patch adding native SOCKS proxy support for CAJ is available.

Prerequisites

• Sufficiently recent CA protocol (>= V4.8 which dates back quite a while; EPICS 3.14.1 from 10 years ago uses V4.11)
• ssh server on 'inside' network which allows port forwarding
• ssh client with SOCKS proxy server (openssh, putty)
• patched CA/Com libraries (C/C++ std. version or 'CAJ', java implementation) or proxifier software (tsocks, dante)
• JRE 1.5 (1.6 or later recommended)
• caxy.jar (download here)

Downloads

• Binary jar file (requires JRE >= 1.6). If you want you can rename the jar file e.g., to 'caxy.jar' after downloading.
• Binary jar file built with JDK-1.5 (no auto_addr_list support on 'inside' -- irrelevant for 'outside', i.e., you can run this on the 'outside' and still have auto_addr_list support as long as you run the variant built for 1.6 on the 'inside'). If you want you can rename the jar file e.g., to 'caxy.jar' after downloading.
• Source distribution (requires JDK >= 1.5 and Apache ANT to rebuild)
• git repository. You can view a currently checked out version following this link or clone it using the link URL.

• patch to add native SOCKS proxy support to EPICS-3.14.12. You can also download the latest version from here (look for patch file).The patched EPICS libraries may be instructed to use a ssh SOCKS proxy by setting

    
    export EPICS_SOCKS_PROXY=localhost

• patch to add native SOCKS proxy support to CAJ (see here for more information).
• Pre-built (JDK 1.6) versions of CAJ with SOCKS support: caj-1.1.7, caj-1.1.8, caj-1.1.9, caj-1.1.10.

Documentation

More comprehensive documentation is available here (included with source distribution).