Unix/Linux Go Back    


CentOS 7.0 - man page for pmsocks (centos section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


PMSOCKS(1)									       PMSOCKS(1)

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  con-
       nections  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  com-
       mon  customization  would be to specify direct connections for all hosts on the local sub-
       net, 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  fur-
		 ther 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

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

Performance Co-Pilot			       PCP				       PMSOCKS(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 10:23 PM.