-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
373 lines (341 loc) · 12.6 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http:https://www.w3.org/TR/html4/loose.dtd">
<?xml version="1.0" encoding="iso-8859-1"?>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<title>UDP Proxy for EPICS Channel-Access Tunneling with SSH</title>
<meta name="generator" content="Amaya, see http:https://www.w3.org/Amaya/">
<style type="text/css" title="Amaya theme">
/* Modern style for Amaya Editor Lite */
/* default rules for the whole document */
body {
font-size: 12pt;
font-family: Helvetica, Arial, sans-serif;
font-weight: normal;
font-style: normal;
color: black;
background-color: white;
line-height: 1.2em;
margin-left: 4em;
margin-right: 2em;
}
/* paragraphs */
p {
padding: 0;
margin-top: 1em;
margin-bottom: 1em;
text-align: left;
}
/* headings */
h1 {
font-size: 180%;
font-weight: bold;
font-style: normal;
font-variant: small-caps;
text-align: left;
padding: 0;
margin-top: 1.7em;
margin-bottom: 1.7em;
}
h2 {
font-size: 150%;
font-weight: bold;
font-style: normal;
padding: 0;
margin-top: 1.5em;
margin-bottom: 1.1em;
}
h3 {
font-size: 130%;
font-weight: bold;
font-style: normal;
padding: 0;
margin-top: 1.3em;
margin-bottom: 1.1em;
}
h4 {
font-size: 110%;
font-weight: bold;
font-style: normal;
padding: 0;
margin-top: 1.1em;
margin-bottom: 1.1em;
}
h5 {
font-size: 100%;
font-weight: bold;
font-style: italic;
padding: 0;
margin-top: 1em;
margin-bottom: 1em;
}
h6 {
font-size: 100%;
font-weight: normal;
font-style: italic;
padding: 0;
margin-top: 1em;
margin-bottom: 1em;
}
/* divisions */
div {
padding: 0;
margin-top: 0em;
margin-bottom: 0em;
}
/* lists */
ul, ol {
padding: 0 0 0 3em;
margin-top: 1em;
margin-bottom: 1em;
}
ul ul, ol ol, ul ol, ol ul {
margin-top: 1em;
margin-bottom: 1em;
}
li {
padding: 0;
margin-top: 1em;
margin-bottom: 1em;
text-align: left;
}
li p {
margin-top: 1em;
margin-bottom: 1em;
}
dl {
padding: 0;
margin-top: 1em;
margin-bottom: 1em;
margin-left: 1em;
}
dl dl {
margin-top: 0em;
margin-bottom: 0em;
}
dt {
padding: 0;
font-weight: bold;
margin-top: .3em;
margin-bottom: .3em;
}
dd {
padding: 0;
margin-top: .3em;
margin-left: 3em;
margin-bottom: .3em;
}
dl p {
margin-top: .3em;
margin-bottom: .3em;
}
/* inline */
strong {
font-weight: bold;
}
em {
font-style: italic;
}
code {
font-family: Courier New, Courier, monospace;
}
ins {
background-color: yellow;
text-decoration: underline;
}
del {
text-decoration: line-through;
}
/* anchors */
a[href] {
color: blue;
text-decoration: underline;
}
/* end */
</style>
</head>
<body>
<h1>UDP Proxy for EPICS Channel-Access Tunneling with SSH</h1>
<h2>What's New?</h2>
<dl>
<dt>2013/11/1 - Caxy-2.0.1 released</dt>
<dd><ul>
<li>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.</li>
<li>Server mode has been added (-S). This is useful under Android (an
Android port is available).</li>
<li>Code better modularized. Can use relevant classes w/o a 'main'
application (useful under Android).</li>
<li>Use ProxifiedSocketChannel class for the TCP tunnel (when
<em>not</em> 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).</li>
</ul>
</dd>
</dl>
<h2>Introduction</h2>
<p>The <a href="http:https://www.aps.anl.gov/epics/">EPICS</a> <a
href="http:https://www.aps.anl.gov/epics/docs/ca.php">CA protocol</a> 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.</p>
<p>This site presents the <strong><em>caxy</em></strong> proxy software that
encapsulates (and modifies) CA-UDP messages for tunneling them via TCP.</p>
<h2>Dynamic TCP Tunneling with SSH and SOCKS</h2>
<p>TCP connections can easily be forwarded through a secure channel using <a
href="http:https://www.openssh.org/">openssh</a>'s '-D' option (<a
href="http:https://www.chiark.greenend.org.uk/~sgtatham/putty/">putty</a> under
windows implements an equivalent feature). Assume you have a 'insidehost'
machine which is only reachable via ssh but has connectivity to an <a
href="http:https://www.aps.anl.gov/epics/">EPICS</a> CA subnet. You want to connect
to EPICS IOCs on that subnet from an 'outsidelaptop' machine which is somewhere
out on the internet:</p>
<pre> <code>outsidelaptop> ssh -D 1080 user@insidehost</code></pre>
<p>opens a secure connection to 'insidehost' from 'outsidelaptop'. The command
also starts a <a href="http:https://en.wikipedia.org/wiki/SOCKS">SOCKS</a> 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).</p>
<p>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 '<a
href="http:https://en.wikipedia.org/wiki/Comparison_of_proxifiers">proxifier</a>'
software (e.g., <a name="tsocks" id="tsocks"
href="http:https://tsocks.sourceforge.net/">tsocks</a> or <a
href="http:https://www.inet.no/dante/">dante</a>) which intercepts the connect()
system-call and sets up a connection through a SOCKS proxy instead.</p>
<p>Using a patched CA client library you define a SOCKS proxy and then use CA
clients as usual:</p>
<pre><code> export EPICS_SOCKS_PROXY=localhost:1080
caget SOME_PV</code></pre>
<p>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 '.'):</p>
<pre> <code>. socksify
caget SOME_PV</code></pre>
<p>The described procedure (start <code>ssh</code> with <code>-D</code>, 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 <strong><em>does
not work</em></strong> by itself because the UDP parts of CA have not been
dealt with properly.</p>
<p>This is where the <strong>caxy</strong> software comes to our rescue.
<strong>caxy</strong> encapsulates the UDP portions of the CA protocol and
forwards them through a secure TCP channel. <strong>caxy</strong> properly
deals with</p>
<ul>
<li>CA search request and reply messages (requests typically are UDP
broadcasts)</li>
<li>CA beacons</li>
</ul>
<h2>CAXY -- Channel Access UDP Proxy</h2>
<p>The <strong>caxy</strong> software handles the UDP aspects of the
Channel-Access protocol, encapsulating UDP messages and forwarding them through
a secure channel. <strong>caxy</strong> is written in <em>java</em> - there is
usually no need for compiling anything. Just download 'caxy.jar' and execute on
any platform (which supports java). <strong>caxy</strong> also supports
starting up a complete tunnel for CA-UDP. Using a system with <code>ssh</code>
available you start a CA-UDP tunnel simply with:</p>
<pre> <code>outsidelaptop> java -jar caxy.jar -- ssh -D1080 user@insidehost java -jar caxy.jar -I</code></pre>
<p>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).</p>
<p>For beacons to be propagated from the 'inside' to the 'outside' a
CA-repeater must be running on the 'inside' (<strong>caxy</strong> 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.</p>
<h2>Why Should I Use CAXY?</h2>
<p>Some obvious alternatives to <strong>caxy</strong> exist:</p>
<dl>
<dt>EPICS base >= <a
href="http:https://www.aps.anl.gov/epics/base/R3-14/12-docs/CAref.html#Environmen">3.14.12
supports CA search request via TCP</a>.</dt>
<dd>Yes - but it would require you to add each and every IOC to the
<strong>EPICS_CA_NAME_SERVERS</strong>. <strong>caxy</strong> can use
normal UDP broadcasts on the 'inside' without the need for assembling a
cumbersome-to-maintain list of all IOCs. The
<strong>EPICS_CA_NAME_SERVERS</strong> feature seems to be more useful in
combination with a CA gateway.</dd>
</dl>
<dl>
<dt>I can run a CA <a
href="http:https://www.aps.anl.gov/epics/extensions/gateway/index.php">gateway</a></dt>
<dd>Sure you can. But you might have to build, configure and maintain it.
Using <strong>caxy</strong> 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.</dd>
</dl>
<p>Finally - if you are a <a
href="http:https://epics-jca.sourceforge.net/jca/">JCA</a> / <a
href="http:https://epics-jca.sourceforge.net/caj/">CAJ</a> / <a
href="http:https://css.desy.de/content/index_eng.html">CSS</a> user: CAJ may
currently not support CA search requests via TCP. However,
<strong>caxy</strong> <em>does</em> work with CAJ/CSS and a patch adding native
SOCKS proxy support for CAJ is available.</p>
<h2>Prerequisites</h2>
<ul>
<li>Sufficiently recent CA protocol (>= V4.8 which dates back quite a
while; EPICS 3.14.1 from 10 years ago uses V4.11)</li>
<li>ssh server on 'inside' network which allows port forwarding</li>
<li>ssh client with SOCKS proxy server (openssh, putty)</li>
<li>patched CA/Com libraries (C/C++ std. version or 'CAJ', java
implementation) <strong><em>or</em></strong> proxifier software (tsocks,
dante)</li>
<li>JRE 1.5 (1.6 or later recommended)</li>
<li>caxy.jar (download here)</li>
</ul>
<h2>Downloads</h2>
<ul>
<li><a href="dist/caxy-2.0.1-jre-1.6.jar">Binary jar file</a> (requires JRE
>= 1.6). If you want you can rename the jar file e.g., to 'caxy.jar'
after downloading.</li>
<li><a href="dist-1.5/caxy-2.0.1-jre-1.5.jar">Binary jar file built with
JDK-1.5</a> (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.</li>
<li><a href="srcdist/caxy-2.0.1-source.jar">Source distribution</a> (requires
JDK >= 1.5 and Apache ANT to rebuild)</li>
<li><a href="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/till-s/caxy">git
repository</a>. You can view a currently checked out version following this
link or clone it using the link URL.</li>
</ul>
<ul>
<li><a href="patches/base-3.14.12.1-socks-proxy.diff">patch to add native
SOCKS proxy support to EPICS-3.14.12</a>. You can also download the latest
version from <a
href="https://bugs.launchpad.net/epics-base/+bug/1012788">here</a> (look
for patch file).The patched EPICS libraries may be instructed to use a ssh
SOCKS proxy by setting
<pre><code>
export EPICS_SOCKS_PROXY=localhost</code></pre>
</li>
<li><a href="patches/caj-1.1.x-socks-proxy-1.0.diff">patch to add native
SOCKS proxy support to CAJ</a> (see <a
href="documentation/caxy.html#section_7_1_1_1">here</a> for more
information).</li>
<li>Pre-built (JDK 1.6) versions of CAJ with SOCKS support: <a
href="caj-1.1.7-socks-proxy.jar">caj-1.1.7</a>, <a
href="caj-1.1.8-socks-proxy.jar">caj-1.1.8</a>, <a
href="caj-1.1.9-socks-proxy.jar">caj-1.1.9</a>, <a
href="caj-1.1.10-socks-proxy.jar">caj-1.1.10</a>.</li>
</ul>
<h2>Documentation</h2>
<p>More comprehensive <a href="documentation/caxy.html">documentation is
available here</a> (included with source distribution).</p>
<dl>
<dt></dt>
</dl>
</body>
</html>