PMSOCKS(1)                 General Commands Manual                PMSOCKS(1)

NAME         top

       pmsocks - shell wrapper for performance monitoring across firewalls

SYNOPSIS         top

       pmsocks path [args ...]

DESCRIPTION         top

       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.


       pmsocks uses the tsocks(5) library, which is not included with PCP.
       You can get tsocks from .


       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

       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

       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

       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 # direct localhost
          sockd # 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 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

          direct LOCALHOSTNAME # direct localhost
          direct # direct on local subnet
          sockd # 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


       There are several environment variables used by pmsocks as follows:

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

                 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.

                 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.

                 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
                 It is strongly recommended this NOT be set in the
                 environment of interactive shells.

                 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         top

       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.


       tsocks is covered by the GPL license and is copyright Shaun Clowes

FILES         top

                 configuration file

SEE ALSO         top

       pmcd(1), pminfo(1), pmlogger(1), pmval(1), X(1), PMAPI(3),
       resolver(5), and tsocks(5).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨git://⟩ on 2017-03-13.  If you discover
       any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page, or
       you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail

Performance Co-Pilot                 PCP                          PMSOCKS(1)