Adding upstream version 6.8.0.upstream/6.8.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 607 insertions, 0 deletions

diff --git a/man/man8/ss.8 b/man/man8/ss.8
new file mode 100644
index 0000000..4ece41f
--- /dev/null
+++ b/man/man8/ss.8
@@ -0,0 +1,607 @@
+.TH SS 8
+.SH NAME
+ss \- another utility to investigate sockets
+.SH SYNOPSIS
+.B ss
+.RI [ options ] " [ FILTER ]"
+.SH DESCRIPTION
+.B ss
+is used to dump socket statistics. It allows showing information similar
+to
+.IR netstat .
+It can display more TCP and state information than other tools.
+
+.SH OPTIONS
+When no option is used ss displays a list of open non-listening
+sockets (e.g. TCP/UNIX/UDP) that have established connection.
+.TP
+.B \-h, \-\-help
+Show summary of options.
+.TP
+.B \-V, \-\-version
+Output version information.
+.TP
+.B \-H, \-\-no-header
+Suppress header line.
+.TP
+.B \-O, \-\-oneline
+Print each socket's data on a single line.
+.TP
+.B \-n, \-\-numeric
+Do not try to resolve service names. Show exact bandwidth values, instead of human-readable.
+.TP
+.B \-r, \-\-resolve
+Try to resolve numeric address/ports.
+.TP
+.B \-a, \-\-all
+Display both listening and non-listening (for TCP this means
+established connections) sockets.
+.TP
+.B \-l, \-\-listening
+Display only listening sockets (these are omitted by default).
+.TP
+.B \-B, \-\-bound-inactive
+Display only TCP bound but inactive (not listening, connecting, etc.) sockets
+(these are omitted by default).
+.TP
+.B \-o, \-\-options
+Show timer information. For TCP protocol, the output format is:
+.RS
+.P
+timer:(<timer_name>,<expire_time>,<retrans>)
+.P
+.TP
+.B <timer_name>
+the name of the timer, there are five kind of timer names:
+.RS
+.P
+.B on
+: means one of these timers: TCP retrans timer, TCP early retrans
+timer and tail loss probe timer
+.P
+.BR keepalive ": tcp keep alive timer"
+.P
+.BR timewait ": timewait stage timer"
+.P
+.BR persist ": zero window probe timer"
+.P
+.BR unknown ": none of the above timers"
+.RE
+.TP
+.B <expire_time>
+how long time the timer will expire
+.P
+.TP
+.B <retrans>
+how many times the retransmission occurred
+.RE
+.TP
+.B \-e, \-\-extended
+Show detailed socket information. The output format is:
+.RS
+.P
+uid:<uid_number> ino:<inode_number> sk:<cookie>
+.P
+.TP
+.B <uid_number>
+the user id the socket belongs to
+.P
+.TP
+.B <inode_number>
+the socket's inode number in VFS
+.P
+.TP
+.B <cookie>
+an uuid of the socket
+.RE
+.TP
+.B \-m, \-\-memory
+Show socket memory usage. The output format is:
+.RS
+.P
+skmem:(r<rmem_alloc>,rb<rcv_buf>,t<wmem_alloc>,tb<snd_buf>,
+.br
+.RS
+.RS
+f<fwd_alloc>,w<wmem_queued>,o<opt_mem>,
+.RE
+.RE
+.br
+.RS
+.RS
+bl<back_log>,d<sock_drop>)
+.RE
+.RE
+.P
+.TP
+.B <rmem_alloc>
+the memory allocated for receiving packet
+.P
+.TP
+.B <rcv_buf>
+the total memory can be allocated for receiving packet
+.P
+.TP
+.B <wmem_alloc>
+the memory used for sending packet (which has been sent to layer 3)
+.P
+.TP
+.B <snd_buf>
+the total memory can be allocated for sending packet
+.P
+.TP
+.B <fwd_alloc>
+the memory allocated by the socket as cache, but not used for
+receiving/sending packet yet. If need memory to send/receive packet,
+the memory in this cache will be used before allocate additional
+memory.
+.P
+.TP
+.B <wmem_queued>
+The memory allocated for sending packet (which has not been sent to layer 3)
+.P
+.TP
+.B <opt_mem>
+The memory used for storing socket option, e.g., the key for TCP MD5 signature
+.P
+.TP
+.B <back_log>
+The memory used for the sk backlog queue. On a process context, if the
+process is receiving packet, and a new packet is received, it will be
+put into the sk backlog queue, so it can be received by the process
+immediately
+.P
+.TP
+.B <sock_drop>
+the number of packets dropped before they are de-multiplexed into the socket
+.RE
+.TP
+.B \-p, \-\-processes
+Show process using socket.
+.TP
+.B \-T, \-\-threads
+Show thread using socket. Implies
+.BR \-p .
+.TP
+.B \-i, \-\-info
+Show internal TCP information. Below fields may appear:
+.RS
+.P
+.TP
+.B ts
+show string "ts" if the timestamp option is set
+.P
+.TP
+.B sack
+show string "sack" if the sack option is set
+.P
+.TP
+.B ecn
+show string "ecn" if the explicit congestion notification option is set
+.P
+.TP
+.B ecnseen
+show string "ecnseen" if the saw ecn flag is found in received packets
+.P
+.TP
+.B fastopen
+show string "fastopen" if the fastopen option is set
+.P
+.TP
+.B cong_alg
+the congestion algorithm name, the default congestion algorithm is "cubic"
+.P
+.TP
+.B wscale:<snd_wscale>:<rcv_wscale>
+if window scale option is used, this field shows the send scale factor
+and receive scale factor
+.P
+.TP
+.B rto:<icsk_rto>
+tcp re-transmission timeout value, the unit is millisecond
+.P
+.TP
+.B backoff:<icsk_backoff>
+used for exponential backoff re-transmission, the actual
+re-transmission timeout value is icsk_rto << icsk_backoff
+.P
+.TP
+.B rtt:<rtt>/<rttvar>
+rtt is the average round trip time, rttvar is the mean deviation of
+rtt, their units are millisecond
+.P
+.TP
+.B ato:<ato>
+ack timeout, unit is millisecond, used for delay ack mode
+.P
+.TP
+.B mss:<mss>
+max segment size
+.P
+.TP
+.B cwnd:<cwnd>
+congestion window size
+.P
+.TP
+.B pmtu:<pmtu>
+path MTU value
+.P
+.TP
+.B ssthresh:<ssthresh>
+tcp congestion window slow start threshold
+.P
+.TP
+.B bytes_acked:<bytes_acked>
+bytes acked
+.P
+.TP
+.B bytes_received:<bytes_received>
+bytes received
+.P
+.TP
+.B segs_out:<segs_out>
+segments sent out
+.P
+.TP
+.B segs_in:<segs_in>
+segments received
+.P
+.TP
+.B send <send_bps>bps
+egress bps
+.P
+.TP
+.B lastsnd:<lastsnd>
+how long time since the last packet sent, the unit is millisecond
+.P
+.TP
+.B lastrcv:<lastrcv>
+how long time since the last packet received, the unit is millisecond
+.P
+.TP
+.B lastack:<lastack>
+how long time since the last ack received, the unit is millisecond
+.P
+.TP
+.B pacing_rate <pacing_rate>bps/<max_pacing_rate>bps
+the pacing rate and max pacing rate
+.P
+.TP
+.B rcv_space:<rcv_space>
+a helper variable for TCP internal auto tuning socket receive buffer
+.P
+.TP
+.B tcp-ulp-mptcp flags:[MmBbJjecv] token:<rem_token(rem_id)/loc_token(loc_id)> seq:<sn> sfseq:<ssn> ssnoff:<off> maplen:<maplen>
+MPTCP subflow information
+.P
+.RE
+.TP
+.B \-\-tos
+Show ToS and priority information. Below fields may appear:
+.RS
+.P
+.TP
+.B tos
+IPv4 Type-of-Service byte
+.P
+.TP
+.B tclass
+IPv6 Traffic Class byte
+.P
+.TP
+.B class_id
+Class id set by net_cls cgroup. If class is zero this shows priority
+set by SO_PRIORITY.
+.RE
+.TP
+.B \-\-cgroup
+Show cgroup information. Below fields may appear:
+.RS
+.P
+.TP
+.B cgroup
+Cgroup v2 pathname. This pathname is relative to the mount point of the hierarchy.
+.RE
+.TP
+.B \-\-tipcinfo
+Show internal tipc socket information.
+.TP
+.B \-K, \-\-kill
+Attempts to forcibly close sockets. This option displays sockets that are
+successfully closed and silently skips sockets that the kernel does not support
+closing. It supports IPv4 and IPv6 sockets only.
+.TP
+.B \-s, \-\-summary
+Print summary statistics. This option does not parse socket lists obtaining
+summary from various sources. It is useful when amount of sockets is so huge
+that parsing /proc/net/tcp is painful.
+.TP
+.B \-E, \-\-events
+Continually display sockets as they are destroyed
+.TP
+.B \-Z, \-\-context
+As the
+.B \-p
+option but also shows process security context. If the
+.B \-T
+option is used, also shows thread security context.
+.sp
+For
+.BR netlink (7)
+sockets the initiating process context is displayed as follows:
+.RS
+.RS
+.IP "1." 4
+If valid pid show the process context.
+.IP "2." 4
+If destination is kernel (pid = 0) show kernel initial context.
+.IP "3." 4
+If a unique identifier has been allocated by the kernel or netlink user,
+show context as "unavailable". This will generally indicate that a
+process has more than one netlink socket active.
+.RE
+.RE
+.TP
+.B \-z, \-\-contexts
+As the
+.B \-Z
+option but also shows the socket context. The socket context is
+taken from the associated inode and is not the actual socket
+context held by the kernel. Sockets are typically labeled with the
+context of the creating process, however the context shown will reflect
+any policy role, type and/or range transition rules applied,
+and is therefore a useful reference.
+.TP
+.B \-N NSNAME, \-\-net=NSNAME
+Switch to the specified network namespace name.
+.TP
+.B \-b, \-\-bpf
+Show socket classic BPF filters (only administrators are allowed to get these
+information).
+.TP
+.B \-4, \-\-ipv4
+Display only IP version 4 sockets (alias for -f inet).
+.TP
+.B \-6, \-\-ipv6
+Display only IP version 6 sockets (alias for -f inet6).
+.TP
+.B \-0, \-\-packet
+Display PACKET sockets (alias for -f link).
+.TP
+.B \-t, \-\-tcp
+Display TCP sockets.
+.TP
+.B \-u, \-\-udp
+Display UDP sockets.
+.TP
+.B \-d, \-\-dccp
+Display DCCP sockets.
+.TP
+.B \-w, \-\-raw
+Display RAW sockets.
+.TP
+.B \-x, \-\-unix
+Display Unix domain sockets (alias for -f unix).
+.TP
+.B \-S, \-\-sctp
+Display SCTP sockets.
+.TP
+.B \-\-tipc
+Display tipc sockets (alias for -f tipc).
+.TP
+.TP
+.B \-\-vsock
+Display vsock sockets (alias for -f vsock).
+.TP
+.B \-\-xdp
+Display XDP sockets (alias for -f xdp).
+.TP
+.B \-M, \-\-mptcp
+Display MPTCP sockets.
+.TP
+.B \-\-inet-sockopt
+Display inet socket options.
+.TP
+.B \-f FAMILY, \-\-family=FAMILY
+Display sockets of type FAMILY.  Currently the following families are
+supported: unix, inet, inet6, link, netlink, vsock, tipc, xdp.
+.TP
+.B \-A QUERY, \-\-query=QUERY, \-\-socket=QUERY
+List of socket tables to dump, separated by commas. The following identifiers
+are understood: all, inet, tcp, udp, raw, unix, packet, netlink, unix_dgram,
+unix_stream, unix_seqpacket, packet_raw, packet_dgram, dccp, sctp, tipc,
+vsock_stream, vsock_dgram, xdp, mptcp. Any item in the list may optionally be
+prefixed by an exclamation mark
+.RB ( ! )
+to exclude that socket table from being dumped.
+.TP
+.B \-D FILE, \-\-diag=FILE
+Do not display anything, just dump raw information about TCP sockets
+to FILE after applying filters. If FILE is - stdout is used.
+.TP
+.B \-F FILE, \-\-filter=FILE
+Read filter information from FILE.  Each line of FILE is interpreted
+like single command line option. If FILE is - stdin is used.
+.TP
+.B FILTER := [ state STATE-FILTER ] [ EXPRESSION ]
+Please take a look at the official documentation for details regarding filters.
+
+.SH STATE-FILTER
+
+.B STATE-FILTER
+allows one to construct arbitrary set of states to match. Its syntax is
+sequence of keywords state and exclude followed by identifier of
+state.
+.TP
+Available identifiers are:
+
+All standard TCP states:
+.BR established ", " syn-sent ", " syn-recv ", " fin-wait-1 ", " fin-wait-2 ", " time-wait ", " closed ", " close-wait ", " last-ack ", "
+.BR  listening " and " closing.
+
+.B all
+- for all the states
+
+.B connected
+- all the states except for
+.BR listening " and " closed
+
+.B synchronized
+- all the
+.B connected
+states except for
+.B syn-sent
+
+.B bucket
+- states, which are maintained as minisockets, i.e.
+.BR time-wait " and " syn-recv
+
+.B big
+- opposite to
+.B bucket
+
+.B bound-inactive
+- bound but otherwise inactive sockets (not listening, connecting, etc.)
+
+.SH EXPRESSION
+
+.B EXPRESSION
+allows filtering based on specific criteria.
+.B EXPRESSION
+consists of a series of predicates combined by boolean operators. The possible operators in increasing
+order of precedence are
+.B or
+(or | or ||),
+.B and
+(or & or &&), and
+.B not
+(or !). If no operator is between consecutive predicates, an implicit
+.B and
+operator is assumed. Subexpressions can be grouped with "(" and ")".
+.P
+The following predicates are supported:
+
+.TP
+.B {dst|src} [=] HOST
+Test if the destination or source matches HOST. See HOST SYNTAX for details.
+.TP
+.B {dport|sport} [OP] [FAMILY:]:PORT
+Compare the destination or source port to PORT. OP can be any of "<", "<=", "=", "!=",
+">=" and ">". Following normal arithmetic rules. FAMILY and PORT are as described in
+HOST SYNTAX below.
+.TP
+.B dev [=|!=] DEVICE
+Match based on the device the connection uses. DEVICE can either be a device name or the
+index of the interface.
+.TP
+.B fwmark [=|!=] MASK
+Matches based on the fwmark value for the connection. This can either be a specific mark value
+or a mark value followed by a "/" and a bitmask of which bits to use in the comparison. For example
+"fwmark = 0x01/0x03" would match if the two least significant bits of the fwmark were 0x01.
+.TP
+.B cgroup [=|!=] PATH
+Match if the connection is part of a cgroup at the given path.
+.TP
+.B autobound
+Match if the port or path of the source address was automatically allocated
+(rather than explicitly specified).
+.P
+Most operators have aliases. If no operator is supplied "=" is assumed.
+Each of the following groups of operators are all equivalent:
+.RS
+.IP \(bu 2
+= == eq
+.IP \(bu
+!= ne neq
+.IP \(bu
+> gt
+.IP \(bu
+< lt
+.IP \(bu
+>= ge geq
+.IP \(bu
+<= le leq
+.IP \(bu
+! not
+.IP \(bu
+| || or
+.IP \(bu
+& && and
+.RE
+.SH HOST SYNTAX
+.P
+The general host syntax is [FAMILY:]ADDRESS[:PORT].
+.P
+FAMILY must be one of the families supported by the -f option. If not given
+it defaults to the family given with the -f option, and if that is also
+missing, will assume either inet or inet6. Note that all host conditions in the
+expression should either all be the same family or be only inet and inet6. If there
+is some other mixture of families, the results will probably be unexpected.
+.P
+The form of ADDRESS and PORT depends on the family used. "*" can be used as
+a wildcard for either the address or port. The details for each family are as
+follows:
+.TP
+.B unix
+ADDRESS is a glob pattern (see
+.BR fnmatch (3))
+that will be matched case-insensitively against the unix socket's address. Both path and abstract
+names are supported. Unix addresses do not support a port, and "*" cannot be used as a wildcard.
+.TP
+.B link
+ADDRESS is the case-insensitive name of an Ethernet protocol to match. PORT
+is either a device name or a device index for the desired link device, as seen
+in the output of ip link.
+.TP
+.B netlink
+ADDRESS is a descriptor of the netlink family. Possible values come from
+/etc/iproute2/nl_protos. PORT is the port id of the socket, which is usually
+the same as the owning process id. The value "kernel" can be used to represent
+the kernel (port id of 0).
+.TP
+.B vsock
+ADDRESS is an integer representing the CID address, and PORT is the port.
+.TP
+.BR inet \ and\  inet6
+ADDRESS is an ip address (either v4 or v6 depending on the family) or a DNS
+hostname that resolves to an ip address of the required version. An ipv6
+address must be enclosed in "[" and "]" to disambiguate the port separator. The
+address may additionally have a prefix length given in CIDR notation (a slash
+followed by the prefix length in bits). PORT is either the numerical
+socket port, or the service name for the port to match.
+
+.SH USAGE EXAMPLES
+.TP
+.B ss -t -a
+Display all TCP sockets.
+.TP
+.B ss -t -a -Z
+Display all TCP sockets with process SELinux security contexts.
+.TP
+.B ss -u -a
+Display all UDP sockets.
+.TP
+.B ss -o state established '( dport = :ssh or sport = :ssh )'
+Display all established ssh connections.
+.TP
+.B ss -x src /tmp/.X11-unix/*
+Find all local processes connected to X server.
+.TP
+.B ss -o state fin-wait-1 '( sport = :http or sport = :https )' dst 193.233.7/24
+List all the tcp sockets in state FIN-WAIT-1 for our apache to network
+193.233.7/24 and look at their timers.
+.TP
+.B ss -a -A 'all,!tcp'
+List sockets in all states from all socket tables but TCP.
+.SH SEE ALSO
+.BR ip (8),
+.br
+.BR RFC " 793 "
+- https://tools.ietf.org/rfc/rfc793.txt (TCP states)
+
+.SH AUTHOR
+.I ss
+was written by Alexey Kuznetsov, <kuznet@ms2.inr.ac.ru>.
+.PP
+This manual page was written by Michael Prokop <mika@grml.org>
+for the Debian project (but may be used by others).