|
NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION | IRIX CONFIGURATION | IRIX ENVIRONMENT VARIABLES | CAVEAT | COPYRIGHT NOTICE | FILES | SEE ALSO | COLOPHON |
PMSOCKS(1) General Commands Manual PMSOCKS(1)
pmsocks - shell wrapper for performance monitoring across firewalls
pmsocks path [args ...]
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 http://www.progsoc.uts.edu.au/~delius/ .
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.
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.
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
(delius@progsoc.org).
/etc/tsocks.conf
configuration file
pmcd(1), pminfo(1), pmlogger(1), pmval(1), X(1), PMAPI(3),
resolver(5), and tsocks(5).
This page is part of the PCP (Performance Co-Pilot) project.
Information about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
pcp@oss.sgi.com. This page was obtained from the project's upstream
Git repository ⟨git://git.pcp.io/pcp⟩ on 2017-07-05. 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
to man-pages@man7.org
Performance Co-Pilot PCP PMSOCKS(1)
Pages that refer to this page: pmie_check(1), pmlogger_check(1), pmnewlog(1)