Ubuntu Manpage: pmsocks - shell wrapper for performance monitoring across firewalls

NAME

       pmsocks - shell wrapper for performance monitoring across firewalls

SYNOPSYS

       pmsocks path [args ...]

DESCRIPTION

       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 sockd daemon and the necessary access controls are satisfied.

CONFIGURATION

       pmsocks uses the  tsocks(5)  library,  which  is  not  included  with  PCP.   You  can  get  tsocks  from
       http://www.progsoc.uts.edu.au/~delius/.

IRIX CONFIGURATION

       On  IRIX,  pmsocks  is  simply  a  shell wrapper that sets the appropriate environment variables and then
       executes the path program with  args  arguments  (if  any).   pmsocks  works  by  setting  the  _RLD_LIST
       environment  variable  (see  rld(1))  to  load a dynamic shared library (see dso(5)) containing stubs for
       ``socksified''   network   library   functions;   This   ``socksified''   library   is    installed    at
       /usr/pcp/lib/libpcp_socks.so.

       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 CAVEAT section below) before attempting to use pmsocks.

       When pmsocks is installed, the /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 X(1) server, and use PCP connections, possibly via a sockd daemon,
       to monitor remote hosts.  In the present implementation of pmsocks, non-direct connections  to  the  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 /etc/pcp_socks.conf must be configured to connect directly to that host.

       The format of /etc/pcp_socks.conf is identical to /etc/socks.conf as documented  in  the  CSTC-4.2  socks
       distribution.  This distribution may be obtained via information contained in the socks FAQ at
                                    ftp://coast.cs.purdue.edu/pub/tools/unix/socks/

       If  other  socks  clients  are  being  used,  then it is generally safe to remove /etc/pcp_socks.conf and
       instead make a symbolic link to /etc/socks.conf.  The file formats are identical.

       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

          direct LOCALHOSTNAME 255.255.255.255 # direct localhost
          sockd 0.0.0.0 0.0.0.0 # contact sockd everywhere else

       Note  that  the  string  LOCALHOSTNAME  is dynamically substituted at run time with the name of the local
       host, as obtained by a call to gethostname(2).  Assuming the real IP address of the local host is 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:

          direct LOCALHOSTNAME 255.255.255.255 # direct localhost
          direct 1.2.3.0 255.255.255.0 # direct on local subnet
          sockd 0.0.0.0 0.0.0.0 # contact sockd everywhere else

       The  order  of lines is important - the first line matching the requested destination IP address during a
       connect(2) call (after the  requested  IP  address  has  been  masked  by  the  third  parameter  of  the
       /etc/pcp_socks.conf  line),  specifies  via  the  first  parameter whether to contact the socks daemon or
       whether to attempt a direct connection.

IRIX ENVIRONMENT VARIABLES

There are several environment variables used by pmsocks as follows:

SOCKS_SERVER
Specifies the host name or IP address of the host running the sockd daemon. Usually this is
the name of the firewall host.

SOCKS_PORT
The TCP/IP port to use when contacting sockd on the SOCKS_SERVER host. The default is 1080.

SOCKS_NS The host name of the name server to use, usually to resolve the IP address of SOCKS_SERVER.

SOCKS_DEBUG
If present in the environment, libpcp_socks will print debugging information to the 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 libpcp_socks source code.

SOCKS_BANNER
If this is set, whenever a client calls libpcp_socks it will echo a message to stdout
containing version information. This can be useful to check libpcp_socks is working in the
absence of verbose logging.

_RLD_LIST pmsocks sets this to exactly /usr/pcp/lib/libpcp_socks.so:DEFAULT
It is strongly recommended this NOT be set in the environment of interactive shells.

PMCD_CONNECT_TIMEOUT
Specifies the time-out, in seconds, for connections to pmcd(1). When using pmsocks, this may
need to be increased from the default (5 seconds) due to the additional delays introduced as a
result of using sockd. See PMAPI(3) for further details about this variable.

CAVEAT

The following notes should be considered carefully:

0) Because sockd can only handle TCP/IP sockets, pmsocks never attempts to use sockd for sockets of
type SOCK_DGRAM or if the domain parameter in a call to socket(2) is PF_UNIX (unix domain sockets
should never need to use sockd anyway).

1) Some firewall products do not support ``socksified'' applications, and in these cases, 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.

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 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 pmsocks.

3) If the pmsocks configuration file is not present, then pmsocks will exit with an error message.

4) pmsocks uses the locally configured name server or resolver (see 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.

5) When used over a WAN, often the sockd daemon will be a long way from the application. This may
result in PCP client connections timing out before connecting to the remote pmcd. If this is
occurring, set the environment variable PMCD_CONNECT_TIMEOUT to a higher value than the default (5
seconds). Refer to PMAPI(3) for further details about this variable.

6) When using pmsocks to connect to pmcd(1), but ``Connection Refused'' error messages are returned, it
is not immediately obvious whether pmcd(1) is returning the error or sockd.

COPYRIGHT NOTICE

       tsocks is covered by the GPL license and is copyright Shaun Clowes (delius@progsoc.org).

FILES

       /etc/tsocks.conf
                 configuration file