# pcp-ss

## NAME



           **pcp-ss** - report socket statistics
    


## SYNOPSIS



           **pcp**[_pcp options_] **ss**[_ss options_]
    


## DESCRIPTION



           **pcp-ss** reports socket statistics collected by the pmdasockets(1)
           PMDA agent.  The command is intended to be reasonably compatible
           with many of the ss(8) command line options and reporting formats,
           but also offer the advantages of local or remote monitoring (in
           live mode) and also historical replay from a previously recorded
           PCP archive.  Note that since **ss**(1) has many command line options,
           many of which are the same as standard PCP command line options as
           described in PCPIntro(1), the **pcp-ss** tool should always be invoked
           by users using the **pcp** front-end.  This allows standard PCP
           commandline options such as **-h** , **-a** , **-S** , **-T** , **-O** , **-z** , etc to be
           passed without conflict with **ss**(1) options.  See the **EXAMPLES**
           sections below for typical usage and command lines.
    
           Live mode uses the **pcp -h** _host_ option and requires the
           pmdasockets(1) PMDA to be installed and enabled on the target _host_
           (local or remote), see pmdasockets(1) for details on how to enable
           the **sockets** PMDA on a particular host.  The default source is live
           metrics collected on **localhost** , if neither of the **-h** or **-a** options
           are given.
    
           Historical/archive replay uses the **pcp -a** _archive_ option, where
           _archive_ is the basename of a previously recorded PCP archive.  The
           archive replay feature is particularly useful because socket
           statistics can be reported for a designated time using the **pcp**
           **--origin** option (which defaults to the start time of the archive).
    


## EXAMPLES



           **pcp ss**
                Display default basic socket information for the local host.
                This includes **Netid**(**tcp** , **udp** , etc), **State**(**ESTAB** , **TIME_WAIT** ,
                etc), **Recv-Q** and **Send-Q** queue lengths and the local and peer
                address and port for each socket.
    
           **pcp -h** _somehost_ **ss -noemitauO**
                Display the same basic socket information as above for the
                host _somehost_ , which may be the default **localhost**.  The
                additional command line arguments (**-noemitauO**) display one
                line per socket (**-O**), numeric (**-n**) service names (default),
                timer information (**-o**), extended socket details (**-e**), socket
                memory usage (**-m**), internal TCP information (**-i**), both udp
                (**-u**) and tcp sockets (**-t**) and both listening and non-
                listening sockets (**-a**).
    
           **pcp -a** _somearchive_ **-S'@Wed 16 Jun 2021 12:57:21' ss -noemitauO**
                Display the same information as the above example, but for
                the archive _somearchive_ starting at the given time **Wed 16 Jun**
                **2021 12:57:21**.  Note the literal **@** prefix is required for an
                absolute time, see PCPIntro(1) for details.  The archive must
                of course contain data for the requested time. You can use
                **pmlogdump -l** _somearchive_ to examine the time bounds of
                _somearchive_.
    
           **pcp -a** _somearchive_ **-O-0 ss -noemitauO**
                As above, but with an offset of zero seconds (**-O-0**) before
                the current end of _somearchive_ , i.e. the most recently logged
                data. Note that _somearchive_ may be currently growing (i.e.
                being logged with pmlogger(1)).
    


## OPTIONS



           Due to the large number of options supported by **pcp-ss** , the pcp(1)
           command should always be used to invoke **pcp-ss** in order to specify
           options such as the metrics source (host or archive) and also (in
           archive mode), the requested start time or offset, and timezone
           using the following options:
    
           **-h** , **--host**
                The remote hostname to connect to in live mode.
    
           **-a** , **--archive**
                The archive file to use for historical sampling
    
           **-O** , **--origin**
                The time offset to use within an archive (implies **-a**)
    
           **-S** , **--start**
                The start time (e.g. in ctime(3) format) to use when
                replaying an archive.
    
           **-Z** , **--timezone**
                Use a specific timezone.  Since **pcp-ss** doesn't report
                timestamps, this only affects the interpretation of an
                absolute starting time (**-S**) or offset (**-O**).
    
           **-z** , **--hostzone**
                In archive mode, use the timezone of the archive rather than
                the timezone on the local machine running **pcp-ss**.  The
                timezone, start and finish times of the archive may be
                examined using pmlogdump(1) with the **-L** option.
    
           The above **pcp** options become indirectly available to the **pcp-ss**
           command via environment variables - refer to PCPIntro(1) for a
           complete description of these options.
    
           The additional command line options available for **pcp-ss** itself
           are:
    
           **-h** , **--help**
                show help message and exit
    
           **-V** , **--version**
                output version information
    
           **-n** , **--numeric**
                don't resolve service names (currently always set)
    
           **-a** , **--all**
                display all sockets
    
           **-l** , **--listening**
                display listening sockets
    
           **-o** , **--options**
                show timer information
    
           **-e** , **--extended**
                show detailed socket information
    
           **-m** , **--memory**
                show socket memory usage
    
           **-i** , **--info**
                show internal TCP information
    
           **-4** , **--ipv4**
                display only IP version 4 sockets
    
           **-6** , **--ipv6**
                display only IP version 6 sockets
    
           **-t** , **--tcp**
                display only TCP sockets
    
           **-u** , **--udp**
                display only UDP sockets
    
           **-H** , **--noheader**
                Suppress header line
    
           **-O** , **--oneline**
                socket's data printed on a single line
    


## REPORT



           The columns in the **pcp-ss** report vary according to the command
           line options and have the same interpretation as described in
           ss(8).
    
           One difference with **pcp-ss** is that the first line in the report
           begins with '**# Timestamp** ' followed by the timestamp (in the
           requested timezone, see **-z** and **-Z** above) of the sample data from
           the host or archive source.  Following the timestamp is the
           currently active filter string for the metrics source.  In archive
           mode, the active filter can be changed dynamically, even whilst
           the archive is being recorded.  This is different to ss(8) where
           the filter is optionally specified on the command line of the tool
           and is always 'live', i.e.  ss(8) does not support retrospective
           replay.  With **pcp-ss** , the filter is stored in the back-end PMDA,
           see pmdasockets(1), in the metric **network.persocket.filter.** The
           default filter is **state connected** , which can be changed by storing
           a new string value in the **network.persocket.filter** metric using
           pmstore(1), e.g.  **pmstore network.persocket.filter "state**
           **established"**.  This will override the persistent default filter,
           which is stored in a PMDA configuration file and loaded each time
           the sockets PMDA is started.  See pmdasockets(1) for further
           details and see ss(8) for details of the filter syntax and
           examples.
    


## PCP ENVIRONMENT



           Environment variables with the prefix **PCP_** are used to
           parameterize the file and directory names used by PCP.  On each
           installation, the file _/etc/pcp.conf_ contains the local values for
           these variables.  The **$PCP_CONF** variable may be used to specify an
           alternative configuration file, as described in pcp.conf(5).
    
           For environment variables affecting PCP tools, see
           pmGetOptions(3).
    


* * *