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
|
'\"macro stdmacro
.\"
.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMSOCKS 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmsocks\f1 \- shell wrapper for performance monitoring across firewalls
.\" literals use .B or \f3
.\" arguments use .I or \f2
.SH SYNOPSYS
\f3pmsocks\f1
\f2path\f1
[\f2args\f1 ...]
.SH DESCRIPTION
.B pmsocks
allows Performance Co-Pilot (PCP) clients running on
hosts located on the internal side of a TCP/IP firewall to monitor
remote hosts on the other side of the firewall.
This assumes the firewall has been configured
with a compliant
.B sockd
daemon and the necessary access controls are satisfied.
.SH "CONFIGURATION"
.B pmsocks
uses the
.BR tsocks (5)
library, which is not included with PCP.
You can get
.B tsocks
from
.IR http://www.progsoc.uts.edu.au/~delius/ .
.SH "IRIX CONFIGURATION"
On IRIX,
.B pmsocks
is simply a shell wrapper that sets the appropriate environment variables
and then executes the
.I path
program with
.I args
arguments (if any).
.B pmsocks
works by setting the
.B _RLD_LIST
environment variable (see
.BR rld (1))
to load a dynamic shared library (see
.BR dso (5))
containing stubs for ``socksified'' network library functions;
This ``socksified'' library is installed at
.IR /usr/pcp/lib/libpcp_socks.so .
.PP
There are a number of conditions required for this
to be successful and the user is strongly advised to
read this whole manual page (in particular the
.B CAVEAT
section below) before attempting to use
.BR pmsocks .
.PP
When
.B pmsocks
is installed, the
.I /etc/pcp_socks.conf
configuration file is also installed with
minimum default settings.
These settings specify that socket connections to the
local host should be made directly, without
contacting any socks server daemon.
This is necessary so that PCP clients
will be able to establish a local connection to the
.BR X (1)
server,
and use PCP connections, possibly via a
.B sockd
daemon, to monitor remote hosts.
In the present implementation of
.BR pmsocks ,
non-direct connections to the
.BR X (1)
server do not work, hence if the
display is remote, then the remote host must be on the same side of the
firewall and
.I /etc/pcp_socks.conf
must be configured to connect directly to that host.
.PP
The format of
.I /etc/pcp_socks.conf
is identical to
.IR /etc/socks.conf
as documented in the
.I "CSTC-4.2"
socks distribution.
This distribution may be obtained via
information contained in the socks FAQ at
.ce 1
ftp://coast.cs.purdue.edu/pub/tools/unix/socks/
.PP
If other socks clients are being used, then it is
generally safe to remove
.I /etc/pcp_socks.conf
and instead make a symbolic link to
.IR /etc/socks.conf .
The file formats are identical.
.PP
The default configuration should be customized to suit the
local environment so that connections to hosts
located on the same side of the firewall as the local host
do not use the socks daemon unnecessarily.
The default configuration
is
.sp 1
.in 1i
direct LOCALHOSTNAME 255.255.255.255 # direct localhost
.br
sockd 0.0.0.0 0.0.0.0 # contact sockd everywhere else
.in
.sp 1
Note that the string
.B LOCALHOSTNAME
is dynamically substituted at run time with the name of the local host,
as obtained by a call to
.BR gethostname (2).
Assuming the real IP address of the local host is
.B 1.2.3.4
and that a normal class-c subnet is used locally,
the most common customization would be to
specify direct connections for all hosts on the
local subnet, by inserting another ``direct'' line as follows:
.sp 1
.in 1i
direct LOCALHOSTNAME 255.255.255.255 # direct localhost
.br
direct 1.2.3.0 255.255.255.0 # direct on local subnet
.br
sockd 0.0.0.0 0.0.0.0 # contact sockd everywhere else
.in
.PP
The order of lines is important \- the first line
matching the requested destination IP address during a
.BR connect (2)
call (after the requested IP address has been
masked by the third parameter of the
.IR /etc/pcp_socks.conf
line),
specifies via the first parameter whether to contact the socks daemon
or whether to attempt a direct connection.
.SH "IRIX ENVIRONMENT VARIABLES"
There are several environment variables used by
.B pmsocks
as follows:
.TP 10
.B SOCKS_SERVER
Specifies the host name or IP address of the host
running the
.B sockd
daemon.
Usually this is the name of the firewall host.
.TP 10
.B SOCKS_PORT
The TCP/IP port to use when contacting
.B sockd
on the
.B SOCKS_SERVER
host.
The default is
.BR 1080 .
.TP 10
.B SOCKS_NS
The host name of the name server to use,
usually to resolve the IP address of
.BR SOCKS_SERVER .
.TP 10
.B SOCKS_DEBUG
If present in the environment,
.B libpcp_socks
will print debugging information to the
.I stderr
stream.
There are only two levels of debugging, on or off.
This is only really useful for the developers
because the debugging information assumes
knowledge of the
.B libpcp_socks
source code.
.TP 10
.B SOCKS_BANNER
If this is set, whenever a client calls
.B libpcp_socks
it will echo a message to
.I stdout
containing version information.
This can be useful to check
.B libpcp_socks
is working in the absence of verbose logging.
.TP 10
.B _RLD_LIST
.B pmsocks
sets this to exactly
.B /usr/pcp/lib/libpcp_socks.so:DEFAULT
.br
It is strongly recommended this NOT be set
in the environment of interactive shells.
.TP 10
.B PMCD_CONNECT_TIMEOUT
Specifies the time-out, in seconds, for connections to
.BR pmcd (1).
When using
.BR pmsocks ,
this may need to be increased from the default (5 seconds)
due to the additional delays introduced as a result of using
.BR sockd .
See
.BR PMAPI (3)
for further details about this variable.
.SH CAVEAT
The following notes should be considered carefully:
.TP 5
0)
Because
.B sockd
can only handle TCP/IP sockets,
.B pmsocks
never attempts to use
.B sockd
for sockets of type
.B SOCK_DGRAM
or if the
.B domain
parameter in a call to
.BR socket (2)
is
.B PF_UNIX
(unix domain sockets should never need to use
.B sockd
anyway).
.TP 5
1)
Some firewall products do not support ``socksified'' applications,
and in these cases,
.B pmsocks
cannot be used.
In this case, it will be necessary to configure the firewall to allow
connections through the firewall for the PMCD communications port,
typically tcp/4321.
.TP 5
2)
The PCP protocol is TPC/IP-based and works with the socks protocol,
but connections which use UDP/DATAGRAM sockets
or remote X11 connections via
.B sockd
may not work.
If the remote display host is on the same side of the firewall
as the application, this may be circumvented by configuring
the remote display host to use direct connections - see above.
Also, using X11 display options which use shared memory may hang
the X server when used with
.BR pmsocks .
.TP 5
3)
If the
.B pmsocks
configuration file is not present, then
.B pmsocks
will exit with an error message.
.TP 5
4)
.B pmsocks
uses the locally configured name server or resolver
(see
.BR resolver (5))
to resolve host names to IP addresses.
This may or may not be capable of resolving host names
on the other side of the firewall.
.TP 5
5)
When used over a WAN, often the
.B sockd
daemon will be a long way from the application.
This may result in PCP client connections timing out before
connecting to the remote
.BR pmcd .
If this is occurring, set the environment variable
.B PMCD_CONNECT_TIMEOUT
to a higher value than the default (5 seconds).
Refer to
.BR PMAPI (3)
for further details about this variable.
.TP 5
6)
When using
.B pmsocks
to connect to
.BR pmcd (1),
but
.I "``Connection Refused''"
error messages are returned,
it is not immediately obvious whether
.BR pmcd (1)
is returning the error or
.BR sockd .
.SH "COPYRIGHT NOTICE"
.B tsocks
is covered by the GPL license and is copyright
Shaun Clowes (delius@progsoc.org).
.SH "FILES"
.TP 10
.B /etc/tsocks.conf
configuration file
.SH "SEE ALSO"
.BR pmcd (1),
.BR pminfo (1),
.BR pmlogger (1),
.BR pmval (1),
.BR X (1),
.BR PMAPI (3),
.BR resolver (5),
and
.BR tsocks (5).
|