Debian Codegraph @

upstream/debian-trixie/man8/ss.8

raw
1 .TH SS 8
2 .SH NAME
3 ss \- another utility to investigate sockets
4 .SH SYNOPSIS
5 .B ss
6 .RI [ options ] " [ FILTER ]"
7 .SH DESCRIPTION
8 .B ss
9 is used to dump socket statistics. It allows showing information similar
10 to
11 .IR netstat .
12 It can display more TCP and state information than other tools.
13
14 .SH OPTIONS
15 When no option is used ss displays a list of open non-listening
16 sockets (e.g. TCP/UNIX/UDP) that have established connection.
17 .TP
18 .B \-h, \-\-help
19 Show summary of options.
20 .TP
21 .B \-V, \-\-version
22 Output version information.
23 .TP
24 .B \-H, \-\-no-header
25 Suppress header line.
26 .TP
27 .B \-Q, \-\-no-queues
28 Suppress sending and receiving queue columns.
29 .TP
30 .B \-O, \-\-oneline
31 Print each socket's data on a single line.
32 .TP
33 .B \-n, \-\-numeric
34 Do not try to resolve service names. Show exact bandwidth values, instead of human-readable.
35 .TP
36 .B \-r, \-\-resolve
37 Try to resolve numeric address/ports.
38 .TP
39 .B \-a, \-\-all
40 Display both listening and non-listening (for TCP this means
41 established connections) sockets.
42 .TP
43 .B \-l, \-\-listening
44 Display only listening sockets (these are omitted by default).
45 .TP
46 .B \-B, \-\-bound-inactive
47 Display only TCP bound but inactive (not listening, connecting, etc.) sockets
48 (these are omitted by default).
49 .TP
50 .B \-o, \-\-options
51 Show timer information. For TCP protocol, the output format is:
52 .RS
53 .P
54 timer:(<timer_name>,<expire_time>,<retrans>)
55 .P
56 .TP
57 .B <timer_name>
58 the name of the timer, there are five kind of timer names:
59 .RS
60 .P
61 .B on
62 : means one of these timers: TCP retrans timer, TCP early retrans
63 timer and tail loss probe timer
64 .P
65 .BR keepalive ": tcp keep alive timer"
66 .P
67 .BR timewait ": timewait stage timer"
68 .P
69 .BR persist ": zero window probe timer"
70 .P
71 .BR unknown ": none of the above timers"
72 .RE
73 .TP
74 .B <expire_time>
75 how long time the timer will expire
76 .P
77 .TP
78 .B <retrans>
79 how many times the retransmission occurred
80 .RE
81 .TP
82 .B \-e, \-\-extended
83 Show detailed socket information. The output format is:
84 .RS
85 .P
86 uid:<uid_number> ino:<inode_number> sk:<cookie>
87 .P
88 .TP
89 .B <uid_number>
90 the user id the socket belongs to
91 .P
92 .TP
93 .B <inode_number>
94 the socket's inode number in VFS
95 .P
96 .TP
97 .B <cookie>
98 an uuid of the socket
99 .RE
100 .TP
101 .B \-m, \-\-memory
102 Show socket memory usage. The output format is:
103 .RS
104 .P
105 skmem:(r<rmem_alloc>,rb<rcv_buf>,t<wmem_alloc>,tb<snd_buf>,
106 .br
107 .RS
108 .RS
109 f<fwd_alloc>,w<wmem_queued>,o<opt_mem>,
110 .RE
111 .RE
112 .br
113 .RS
114 .RS
115 bl<back_log>,d<sock_drop>)
116 .RE
117 .RE
118 .P
119 .TP
120 .B <rmem_alloc>
121 the memory allocated for receiving packet
122 .P
123 .TP
124 .B <rcv_buf>
125 the total memory can be allocated for receiving packet
126 .P
127 .TP
128 .B <wmem_alloc>
129 the memory used for sending packet (which has been sent to layer 3)
130 .P
131 .TP
132 .B <snd_buf>
133 the total memory can be allocated for sending packet
134 .P
135 .TP
136 .B <fwd_alloc>
137 the memory allocated by the socket as cache, but not used for
138 receiving/sending packet yet. If need memory to send/receive packet,
139 the memory in this cache will be used before allocate additional
140 memory.
141 .P
142 .TP
143 .B <wmem_queued>
144 The memory allocated for sending packet (which has not been sent to layer 3)
145 .P
146 .TP
147 .B <opt_mem>
148 The memory used for storing socket option, e.g., the key for TCP MD5 signature
149 .P
150 .TP
151 .B <back_log>
152 The memory used for the sk backlog queue. On a process context, if the
153 process is receiving packet, and a new packet is received, it will be
154 put into the sk backlog queue, so it can be received by the process
155 immediately
156 .P
157 .TP
158 .B <sock_drop>
159 the number of packets dropped before they are de-multiplexed into the socket
160 .RE
161 .TP
162 .B \-p, \-\-processes
163 Show process using socket.
164 .TP
165 .B \-T, \-\-threads
166 Show thread using socket. Implies
167 .BR \-p .
168 .TP
169 .B \-i, \-\-info
170 Show internal TCP information. Below fields may appear:
171 .RS
172 .P
173 .TP
174 .B ts
175 show string "ts" if the timestamp option is set
176 .P
177 .TP
178 .B sack
179 show string "sack" if the sack option is set
180 .P
181 .TP
182 .B ecn
183 show string "ecn" if the explicit congestion notification option is set
184 .P
185 .TP
186 .B ecnseen
187 show string "ecnseen" if the saw ecn flag is found in received packets
188 .P
189 .TP
190 .B fastopen
191 show string "fastopen" if the fastopen option is set
192 .P
193 .TP
194 .B cong_alg
195 the congestion algorithm name, the default congestion algorithm is "cubic"
196 .P
197 .TP
198 .B wscale:<snd_wscale>:<rcv_wscale>
199 if window scale option is used, this field shows the send scale factor
200 and receive scale factor
201 .P
202 .TP
203 .B rto:<icsk_rto>
204 tcp re-transmission timeout value, the unit is millisecond
205 .P
206 .TP
207 .B backoff:<icsk_backoff>
208 used for exponential backoff re-transmission, the actual
209 re-transmission timeout value is icsk_rto << icsk_backoff
210 .P
211 .TP
212 .B rtt:<rtt>/<rttvar>
213 rtt is the average round trip time, rttvar is the mean deviation of
214 rtt, their units are millisecond
215 .P
216 .TP
217 .B ato:<ato>
218 ack timeout, unit is millisecond, used for delay ack mode
219 .P
220 .TP
221 .B mss:<mss>
222 max segment size
223 .P
224 .TP
225 .B cwnd:<cwnd>
226 congestion window size
227 .P
228 .TP
229 .B pmtu:<pmtu>
230 path MTU value
231 .P
232 .TP
233 .B ssthresh:<ssthresh>
234 tcp congestion window slow start threshold
235 .P
236 .TP
237 .B bytes_acked:<bytes_acked>
238 bytes acked
239 .P
240 .TP
241 .B bytes_received:<bytes_received>
242 bytes received
243 .P
244 .TP
245 .B segs_out:<segs_out>
246 segments sent out
247 .P
248 .TP
249 .B segs_in:<segs_in>
250 segments received
251 .P
252 .TP
253 .B send <send_bps>bps
254 egress bps
255 .P
256 .TP
257 .B lastsnd:<lastsnd>
258 how long time since the last packet sent, the unit is millisecond
259 .P
260 .TP
261 .B lastrcv:<lastrcv>
262 how long time since the last packet received, the unit is millisecond
263 .P
264 .TP
265 .B lastack:<lastack>
266 how long time since the last ack received, the unit is millisecond
267 .P
268 .TP
269 .B pacing_rate <pacing_rate>bps/<max_pacing_rate>bps
270 the pacing rate and max pacing rate
271 .P
272 .TP
273 .B rcv_space:<rcv_space>
274 a helper variable for TCP internal auto tuning socket receive buffer
275 .P
276 .TP
277 .B tcp-ulp-mptcp flags:[MmBbJjecv] token:<rem_token(rem_id)/loc_token(loc_id)> seq:<sn> sfseq:<ssn> ssnoff:<off> maplen:<maplen>
278 MPTCP subflow information
279 .P
280 .RE
281 .TP
282 .B \-\-tos
283 Show ToS and priority information. Below fields may appear:
284 .RS
285 .P
286 .TP
287 .B tos
288 IPv4 Type-of-Service byte
289 .P
290 .TP
291 .B tclass
292 IPv6 Traffic Class byte
293 .P
294 .TP
295 .B class_id
296 Class id set by net_cls cgroup. If class is zero this shows priority
297 set by SO_PRIORITY.
298 .RE
299 .TP
300 .B \-\-cgroup
301 Show cgroup information. Below fields may appear:
302 .RS
303 .P
304 .TP
305 .B cgroup
306 Cgroup v2 pathname. This pathname is relative to the mount point of the hierarchy.
307 .RE
308 .TP
309 .B \-\-tipcinfo
310 Show internal tipc socket information.
311 .TP
312 .B \-K, \-\-kill
313 Attempts to forcibly close sockets. This option displays sockets that are
314 successfully closed and silently skips sockets that the kernel does not support
315 closing. It supports IPv4 and IPv6 sockets only.
316 .TP
317 .B \-s, \-\-summary
318 Print summary statistics. This option does not parse socket lists obtaining
319 summary from various sources. It is useful when amount of sockets is so huge
320 that parsing /proc/net/tcp is painful.
321 .TP
322 .B \-E, \-\-events
323 Continually display sockets as they are destroyed
324 .TP
325 .B \-Z, \-\-context
326 As the
327 .B \-p
328 option but also shows process security context. If the
329 .B \-T
330 option is used, also shows thread security context.
331 .sp
332 For
333 .BR netlink (7)
334 sockets the initiating process context is displayed as follows:
335 .RS
336 .RS
337 .IP "1." 4
338 If valid pid show the process context.
339 .IP "2." 4
340 If destination is kernel (pid = 0) show kernel initial context.
341 .IP "3." 4
342 If a unique identifier has been allocated by the kernel or netlink user,
343 show context as "unavailable". This will generally indicate that a
344 process has more than one netlink socket active.
345 .RE
346 .RE
347 .TP
348 .B \-z, \-\-contexts
349 As the
350 .B \-Z
351 option but also shows the socket context. The socket context is
352 taken from the associated inode and is not the actual socket
353 context held by the kernel. Sockets are typically labeled with the
354 context of the creating process, however the context shown will reflect
355 any policy role, type and/or range transition rules applied,
356 and is therefore a useful reference.
357 .TP
358 .B \-N NSNAME, \-\-net=NSNAME
359 Switch to the specified network namespace name.
360 .TP
361 .B \-b, \-\-bpf
362 Show socket classic BPF filters (only administrators are allowed to get these
363 information).
364 .TP
365 .B \-4, \-\-ipv4
366 Display only IP version 4 sockets (alias for -f inet).
367 .TP
368 .B \-6, \-\-ipv6
369 Display only IP version 6 sockets (alias for -f inet6).
370 .TP
371 .B \-0, \-\-packet
372 Display PACKET sockets (alias for -f link).
373 .TP
374 .B \-t, \-\-tcp
375 Display TCP sockets.
376 .TP
377 .B \-u, \-\-udp
378 Display UDP sockets.
379 .TP
380 .B \-d, \-\-dccp
381 Display DCCP sockets.
382 .TP
383 .B \-w, \-\-raw
384 Display RAW sockets.
385 .TP
386 .B \-x, \-\-unix
387 Display Unix domain sockets (alias for -f unix).
388 .TP
389 .B \-S, \-\-sctp
390 Display SCTP sockets.
391 .TP
392 .B \-\-tipc
393 Display tipc sockets (alias for -f tipc).
394 .TP
395 .TP
396 .B \-\-vsock
397 Display vsock sockets (alias for -f vsock).
398 .TP
399 .B \-\-xdp
400 Display XDP sockets (alias for -f xdp).
401 .TP
402 .B \-M, \-\-mptcp
403 Display MPTCP sockets.
404 .TP
405 .B \-\-inet-sockopt
406 Display inet socket options.
407 .TP
408 .B \-f FAMILY, \-\-family=FAMILY
409 Display sockets of type FAMILY. Currently the following families are
410 supported: unix, inet, inet6, link, netlink, vsock, tipc, xdp.
411 .TP
412 .B \-A QUERY, \-\-query=QUERY, \-\-socket=QUERY
413 List of socket tables to dump, separated by commas. The following identifiers
414 are understood: all, inet, tcp, udp, raw, unix, packet, netlink, unix_dgram,
415 unix_stream, unix_seqpacket, packet_raw, packet_dgram, dccp, sctp, tipc,
416 vsock_stream, vsock_dgram, xdp, mptcp. Any item in the list may optionally be
417 prefixed by an exclamation mark
418 .RB ( ! )
419 to exclude that socket table from being dumped.
420 .TP
421 .B \-D FILE, \-\-diag=FILE
422 Do not display anything, just dump raw information about TCP sockets
423 to FILE after applying filters. If FILE is - stdout is used.
424 .TP
425 .B \-F FILE, \-\-filter=FILE
426 Read filter information from FILE. Each line of FILE is interpreted
427 like single command line option. If FILE is - stdin is used.
428 .TP
429 .B \-\-bpf-maps
430 Pretty-print all the BPF socket-local data entries for each socket.
431 .TP
432 .B \-\-bpf-map-id=MAP_ID
433 Pretty-print the BPF socket-local data entries for the requested map ID. Can be used more than once.
434 .TP
435 .B FILTER := [ state STATE-FILTER ] [ EXPRESSION ]
436 Please take a look at the official documentation for details regarding filters.
437
438 .SH STATE-FILTER
439
440 .B STATE-FILTER
441 allows one to construct arbitrary set of states to match. Its syntax is
442 sequence of keywords state and exclude followed by identifier of
443 state.
444 .TP
445 Available identifiers are:
446
447 All standard TCP states:
448 .BR established ", " syn-sent ", " syn-recv ", " fin-wait-1 ", " fin-wait-2 ", " time-wait ", " closed ", " close-wait ", " last-ack ", "
449 .BR listening " and " closing.
450
451 .B all
452 - for all the states
453
454 .B connected
455 - all the states except for
456 .BR listening " and " closed
457
458 .B synchronized
459 - all the
460 .B connected
461 states except for
462 .B syn-sent
463
464 .B bucket
465 - states, which are maintained as minisockets, i.e.
466 .BR time-wait " and " syn-recv
467
468 .B big
469 - opposite to
470 .B bucket
471
472 .B bound-inactive
473 - bound but otherwise inactive sockets (not listening, connecting, etc.)
474
475 .SH EXPRESSION
476
477 .B EXPRESSION
478 allows filtering based on specific criteria.
479 .B EXPRESSION
480 consists of a series of predicates combined by boolean operators. The possible operators in increasing
481 order of precedence are
482 .B or
483 (or | or ||),
484 .B and
485 (or & or &&), and
486 .B not
487 (or !). If no operator is between consecutive predicates, an implicit
488 .B and
489 operator is assumed. Subexpressions can be grouped with "(" and ")".
490 .P
491 The following predicates are supported:
492
493 .TP
494 .B {dst|src} [=] HOST
495 Test if the destination or source matches HOST. See HOST SYNTAX for details.
496 .TP
497 .B {dport|sport} [OP] [FAMILY:]:PORT
498 Compare the destination or source port to PORT. OP can be any of "<", "<=", "=", "!=",
499 ">=" and ">". Following normal arithmetic rules. FAMILY and PORT are as described in
500 HOST SYNTAX below.
501 .TP
502 .B dev [=|!=] DEVICE
503 Match based on the device the connection uses. DEVICE can either be a device name or the
504 index of the interface.
505 .TP
506 .B fwmark [=|!=] MASK
507 Matches based on the fwmark value for the connection. This can either be a specific mark value
508 or a mark value followed by a "/" and a bitmask of which bits to use in the comparison. For example
509 "fwmark = 0x01/0x03" would match if the two least significant bits of the fwmark were 0x01.
510 .TP
511 .B cgroup [=|!=] PATH
512 Match if the connection is part of a cgroup at the given path.
513 .TP
514 .B autobound
515 Match if the port or path of the source address was automatically allocated
516 (rather than explicitly specified).
517 .P
518 Most operators have aliases. If no operator is supplied "=" is assumed.
519 Each of the following groups of operators are all equivalent:
520 .RS
521 .IP \(bu 2
522 = == eq
523 .IP \(bu
524 != ne neq
525 .IP \(bu
526 > gt
527 .IP \(bu
528 < lt
529 .IP \(bu
530 >= ge geq
531 .IP \(bu
532 <= le leq
533 .IP \(bu
534 ! not
535 .IP \(bu
536 | || or
537 .IP \(bu
538 & && and
539 .RE
540 .SH HOST SYNTAX
541 .P
542 The general host syntax is [FAMILY:]ADDRESS[:PORT].
543 .P
544 FAMILY must be one of the families supported by the -f option. If not given
545 it defaults to the family given with the -f option, and if that is also
546 missing, will assume either inet or inet6. Note that all host conditions in the
547 expression should either all be the same family or be only inet and inet6. If there
548 is some other mixture of families, the results will probably be unexpected.
549 .P
550 The form of ADDRESS and PORT depends on the family used. "*" can be used as
551 a wildcard for either the address or port. The details for each family are as
552 follows:
553 .TP
554 .B unix
555 ADDRESS is a glob pattern (see
556 .BR fnmatch (3))
557 that will be matched case-insensitively against the unix socket's address. Both path and abstract
558 names are supported. Unix addresses do not support a port, and "*" cannot be used as a wildcard.
559 .TP
560 .B link
561 ADDRESS is the case-insensitive name of an Ethernet protocol to match. PORT
562 is either a device name or a device index for the desired link device, as seen
563 in the output of ip link.
564 .TP
565 .B netlink
566 ADDRESS is a descriptor of the netlink family. Possible values come from
567 /etc/iproute2/nl_protos. PORT is the port id of the socket, which is usually
568 the same as the owning process id. The value "kernel" can be used to represent
569 the kernel (port id of 0).
570 .TP
571 .B vsock
572 ADDRESS is an integer representing the CID address, and PORT is the port.
573 .TP
574 .BR inet \ and\ inet6
575 ADDRESS is an ip address (either v4 or v6 depending on the family) or a DNS
576 hostname that resolves to an ip address of the required version. An ipv6
577 address must be enclosed in "[" and "]" to disambiguate the port separator. The
578 address may additionally have a prefix length given in CIDR notation (a slash
579 followed by the prefix length in bits). PORT is either the numerical
580 socket port, or the service name for the port to match.
581
582 .SH USAGE EXAMPLES
583 .TP
584 .B ss -t -a
585 Display all TCP sockets.
586 .TP
587 .B ss -t -a -Z
588 Display all TCP sockets with process SELinux security contexts.
589 .TP
590 .B ss -u -a
591 Display all UDP sockets.
592 .TP
593 .B ss -o state established '( dport = :ssh or sport = :ssh )'
594 Display all established ssh connections.
595 .TP
596 .B ss -x src /tmp/.X11-unix/*
597 Find all local processes connected to X server.
598 .TP
599 .B ss -o state fin-wait-1 '( sport = :http or sport = :https )' dst 193.233.7/24
600 List all the tcp sockets in state FIN-WAIT-1 for our apache to network
601 193.233.7/24 and look at their timers.
602 .TP
603 .B ss -a -A 'all,!tcp'
604 List sockets in all states from all socket tables but TCP.
605 .SH SEE ALSO
606 .BR ip (8),
607 .br
608 .BR RFC " 793 "
609 - https://tools.ietf.org/rfc/rfc793.txt (TCP states)
610
611 .SH AUTHOR
612 .I ss
613 was written by Alexey Kuznetsov, <[email protected]>.
614 .PP
615 This manual page was written by Michael Prokop <[email protected]>
616 for the Debian project (but may be used by others).