1PMSOCKS(1)                  General Commands Manual                 PMSOCKS(1)
2
3
4

NAME

6       pmsocks - shell wrapper for performance monitoring across firewalls
7

SYNOPSYS

9       pmsocks path [args ...]
10

DESCRIPTION

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

CONFIGURATION

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

IRIX CONFIGURATION

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
30       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
34       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
46       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
51       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
55       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
60          direct LOCALHOSTNAME 255.255.255.255 # direct localhost
61          sockd 0.0.0.0 0.0.0.0 # contact sockd everywhere else
62
63       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
70          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
74       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

IRIX ENVIRONMENT VARIABLES

81       There are several environment variables used by pmsocks as follows:
82
83       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
87       SOCKS_PORT
88                 The  TCP/IP  port  to  use  when  contacting  sockd  on   the
89                 SOCKS_SERVER host.  The default is 1080.
90
91       SOCKS_NS  The  host  name of the name server to use, usually to resolve
92                 the IP address of SOCKS_SERVER.
93
94       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
101       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
107       _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
112       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

CAVEAT

120       The following notes should be considered carefully:
121
122       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
127       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
133       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
141       3)   If the pmsocks configuration file is  not  present,  then  pmsocks
142            will exit with an error message.
143
144       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
149       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
156       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

FILES

165       /etc/tsocks.conf
166                 configuration file
167

SEE ALSO

169       pmcd(1), pminfo(1), pmlogger(1), pmval(1), X(1), PMAPI(3), resolver(5),
170       and tsocks(5).
171
172
173
174Performance Co-Pilot                  PCP                           PMSOCKS(1)
Impressum