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 com
pliant sockd daemon and the necessary access controls are
satisfied.
LINUX CONFIGURATION
On Linux, 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 config
uration file is also installed with minimum default set
tings. 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 fire
wall 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 dis
tribution. This distribution may be obtained via
ftp://coast.cs.purdue.edu/pub/tools/unix/socks/
If other socks clients are being used, then it is gener
ally 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 substi
tuted 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 customiza
tion 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.
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 connec
tions to pmcd(1). When using pmsocks, this may
need to be increased from the default (5 sec
onds) due to the additional delays introduced as
a result of using sockd. See PMAPI(3) for fur
ther details about this variable.
IRIX DIAGNOSTICS
Network connections which use libpcp_socks are reported
via syslogd(1M) to /var/adm/SYSLOG. All logged messages
contain the string libpcp_socks. Debugging may be enabled
using the SOCKS_DEBUG environment variable, as described
above.
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 config
ure 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
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 mem
ory 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(4)) to resolve host names to
IP addresses. This may or may not be capable of
resolving host names on the other side of the fire
wall.
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 ``Con
nection Refused'' error messages are returned, it is
not immediately obvious whether pmcd(1) is returning
the error or sockd.
LINUX COPYRIGHT NOTICE
tsocks is covered by the GPL license and is copyright
Shaun Clowes (delius@progsoc.org).
IRIX COPYRIGHT NOTICE
Socks support Copyright (c) 1989 Regents of the University
of California. All rights reserved. Portions of Socks
support Copyright (c) 1993, 1994, 1995 by NEC Systems Lab
oratory.
LINUX FILES
/etc/tsocks.conf
configuration file
IRIX FILES
/etc/pcp_socks.conf
configuration file
/usr/pcp/lib/libpcp_socks.so
the socks library dso(5)
/var/adm/SYSLOG
file containing pmsocks log messages
resolver(5) and tsocks(5).
ON IRIX, SEE ALSO
resolver(4) and dso(5).
SEE ALSO
pmcd(1), pmchart(1), pminfo(1), pmlogger(1), pmval(1),
X(1) and PMAPI(3).
Man(1) output converted with
man2html