1PMSOCKS(1) General Commands Manual PMSOCKS(1)
2
6 pmsocks - shell wrapper for performance monitoring across firewalls
7
9 pmsocks path [args ...]
10
12 pmsocks allows Performance Co-Pilot (PCP) clients running on hosts
13 located on the internal side of a TCP/IP firewall to monitor remote
14 hosts on the other side of the firewall. This assumes the firewall has
15 been configured with a compliant sockd daemon and the necessary access
16 controls are satisfied.
17
19 pmsocks uses the tsocks(5) library, which is not included with PCP.
20 You can get tsocks from http://www.progsoc.uts.edu.au/~delius/.
21
23 On IRIX, pmsocks is simply a shell wrapper that sets the appropriate
24 environment variables and then executes the path program with args
25 arguments (if any). pmsocks works by setting the _RLD_LIST environment
26 variable (see rld(1)) to load a dynamic shared library (see dso(5))
27 containing stubs for ``socksified'' network library functions; This
28 ``socksified'' library is installed at /usr/pcp/lib/libpcp_socks.so.
29 There are a number of conditions required for this to be successful and
31 the user is strongly advised to read this whole manual page (in partic‐
32 ular the CAVEAT section below) before attempting to use pmsocks.
33 When pmsocks is installed, the /etc/pcp_socks.conf configuration file
35 is also installed with minimum default settings. These settings spec‐
36 ify that socket connections to the local host should be made directly,
37 without contacting any socks server daemon. This is necessary so that
38 PCP clients will be able to establish a local connection to the X(1)
39 server, and use PCP connections, possibly via a sockd daemon, to moni‐
40 tor remote hosts. In the present implementation of pmsocks, non-direct
41 connections to the X(1) server do not work, hence if the display is
42 remote, then the remote host must be on the same side of the firewall
43 and /etc/pcp_socks.conf must be configured to connect directly to that
44 host.
45 The format of /etc/pcp_socks.conf is identical to /etc/socks.conf as
47 documented in the CSTC-4.2 socks distribution. This distribution may
48 be obtained via information contained in the socks FAQ at
49 ftp://coast.cs.purdue.edu/pub/tools/unix/socks/
50 If other socks clients are being used, then it is generally safe to
52 remove /etc/pcp_socks.conf and instead make a symbolic link to
53 /etc/socks.conf. The file formats are identical.
54 The default configuration should be customized to suit the local envi‐
56 ronment so that connections to hosts located on the same side of the
57 firewall as the local host do not use the socks daemon unnecessarily.
58 The default configuration is
59 direct LOCALHOSTNAME 255.255.255.255 # direct localhost
61 sockd 0.0.0.0 0.0.0.0 # contact sockd everywhere else
62 Note that the string LOCALHOSTNAME is dynamically substituted at run
64 time with the name of the local host, as obtained by a call to gethost‐
65 name(2). Assuming the real IP address of the local host is 1.2.3.4 and
66 that a normal class-c subnet is used locally, the most common cus‐
67 tomization would be to specify direct connections for all hosts on the
68 local subnet, by inserting another ``direct'' line as follows:
69 direct LOCALHOSTNAME 255.255.255.255 # direct localhost
71 direct 1.2.3.0 255.255.255.0 # direct on local subnet
72 sockd 0.0.0.0 0.0.0.0 # contact sockd everywhere else
73 The order of lines is important - the first line matching the requested
75 destination IP address during a connect(2) call (after the requested IP
76 address has been masked by the third parameter of the
77 /etc/pcp_socks.conf line), specifies via the first parameter whether to
78 contact the socks daemon or whether to attempt a direct connection.
79
81 There are several environment variables used by pmsocks as follows:
82 SOCKS_SERVER
84 Specifies the host name or IP address of the host running the
85 sockd daemon. Usually this is the name of the firewall host.
86 SOCKS_PORT
88 The TCP/IP port to use when contacting sockd on the
89 SOCKS_SERVER host. The default is 1080.
90 SOCKS_NS The host name of the name server to use, usually to resolve
92 the IP address of SOCKS_SERVER.
93 SOCKS_DEBUG
95 If present in the environment, libpcp_socks will print debug‐
96 ging information to the stderr stream. There are only two
97 levels of debugging, on or off. This is only really useful
98 for the developers because the debugging information assumes
99 knowledge of the libpcp_socks source code.
100 SOCKS_BANNER
102 If this is set, whenever a client calls libpcp_socks it will
103 echo a message to stdout containing version information.
104 This can be useful to check libpcp_socks is working in the
105 absence of verbose logging.
106 _RLD_LIST pmsocks sets this to exactly
108 /usr/pcp/lib/libpcp_socks.so:DEFAULT
109 It is strongly recommended this NOT be set in the environment
110 of interactive shells.
111 PMCD_CONNECT_TIMEOUT
113 Specifies the time-out, in seconds, for connections to
114 pmcd(1). When using pmsocks, this may need to be increased
115 from the default (5 seconds) due to the additional delays
116 introduced as a result of using sockd. See PMAPI(3) for fur‐
117 ther details about this variable.
118
120 The following notes should be considered carefully:
121 0) Because sockd can only handle TCP/IP sockets, pmsocks never
123 attempts to use sockd for sockets of type SOCK_DGRAM or if the
124 domain parameter in a call to socket(2) is PF_UNIX (unix domain
125 sockets should never need to use sockd anyway).
126 1) Some firewall products do not support ``socksified'' applications,
128 and in these cases, pmsocks cannot be used. In this case, it will
129 be necessary to configure the firewall to allow connections
130 through the firewall for the PMCD communications port, typically
131 tcp/4321.
132 2) The PCP protocol is TPC/IP-based and works with the socks proto‐
134 col, but connections which use UDP/DATAGRAM sockets or remote X11
135 connections via sockd may not work. If the remote display host is
136 on the same side of the firewall as the application, this may be
137 circumvented by configuring the remote display host to use direct
138 connections - see above. Also, using X11 display options which
139 use shared memory may hang the X server when used with pmsocks.
140 3) If the pmsocks configuration file is not present, then pmsocks
142 will exit with an error message.
143 4) pmsocks uses the locally configured name server or resolver (see
145 resolver(5)) to resolve host names to IP addresses. This may or
146 may not be capable of resolving host names on the other side of
147 the firewall.
148 5) When used over a WAN, often the sockd daemon will be a long way
150 from the application. This may result in PCP client connections
151 timing out before connecting to the remote pmcd. If this is
152 occurring, set the environment variable PMCD_CONNECT_TIMEOUT to a
153 higher value than the default (5 seconds). Refer to PMAPI(3) for
154 further details about this variable.
155 6) When using pmsocks to connect to pmcd(1), but ``Connection
157 Refused'' error messages are returned, it is not immediately obvi‐
158 ous whether pmcd(1) is returning the error or sockd.
159
161 tsocks is covered by the GPL license and is copyright Shaun Clowes
162 (delius@progsoc.org).
163
165 /etc/tsocks.conf
166 configuration file
167
169 pmcd(1), pminfo(1), pmlogger(1), pmval(1), X(1), PMAPI(3), resolver(5),
170 and tsocks(5).
171Performance Co-Pilot PCP PMSOCKS(1)