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

NAME

       pmsocks - shell wrapper for performance monitoring across firewalls

SYNOPSIS

       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