Debian Codegraph @

upstream/debian-unstable/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 connections.
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 values.
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 kinds 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 until the timer will expire
76 .P
77 .TP
78 .B <retrans>
79 how many times retransmissions have 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 a 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 packets
122 .P
123 .TP
124 .B <rcv_buf>
125 the total memory that can be allocated for receiving packets
126 .P
127 .TP
128 .B <wmem_alloc>
129 the memory used for sending packets (which has been sent to layer 3)
130 .P
131 .TP
132 .B <snd_buf>
133 the total memory that can be allocated for sending packets
134 .P
135 .TP
136 .B <fwd_alloc>
137 the memory allocated by the socket as cache, but not used for
138 receiving/sending packets yet. If memory is needed to send/receive packets,
139 the memory in this cache will be used before allocating additional
140 memory.
141 .P
142 .TP
143 .B <wmem_queued>
144 The memory allocated for sending packets (which has not been sent to layer 3)
145 .P
146 .TP
147 .B <opt_mem>
148 The memory used for storing socket options, 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 packets, 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 processes using sockets.
164 .TP
165 .B \-T, \-\-threads
166 Show threads using sockets. 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 it has been since the last packet sent, the unit is millisecond
259 .P
260 .TP
261 .B lastrcv:<lastrcv>
262 how long it has been since the last packet received, the unit is millisecond
263 .P
264 .TP
265 .B lastack:<lastack>
266 how long it has been 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 this
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 .B \-\-vsock
396 Display vsock sockets (alias for -f vsock).
397 .TP
398 .B \-\-xdp
399 Display XDP sockets (alias for -f xdp).
400 .TP
401 .B \-M, \-\-mptcp
402 Display MPTCP sockets.
403 .TP
404 .B \-\-inet-sockopt
405 Display inet socket options.
406 .TP
407 .B \-f FAMILY, \-\-family=FAMILY
408 Display sockets of type FAMILY. Currently the following families are
409 supported: unix, inet, inet6, link, netlink, vsock, tipc, xdp.
410 .TP
411 .B \-A QUERY, \-\-query=QUERY, \-\-socket=QUERY
412 List of socket tables to dump, separated by commas. The following identifiers
413 are understood: all, inet, tcp, udp, raw, unix, packet, netlink, unix_dgram,
414 unix_stream, unix_seqpacket, packet_raw, packet_dgram, dccp, sctp, tipc,
415 vsock_stream, vsock_dgram, xdp, mptcp. Any item in the list may optionally be
416 prefixed by an exclamation mark
417 .RB ( ! )
418 to exclude that socket table from being dumped.
419 .TP
420 .B \-D FILE, \-\-diag=FILE
421 Do not display anything, just dump raw information about TCP sockets
422 to FILE after applying filters. If FILE is - stdout is used.
423 .TP
424 .B \-F FILE, \-\-filter=FILE
425 Read filter information from FILE. Each line of FILE is interpreted
426 like single command line option. If FILE is - stdin is used.
427 .TP
428 .B \-\-bpf-maps
429 Pretty-print all the BPF socket-local data entries for each socket.
430 .TP
431 .B \-\-bpf-map-id=MAP_ID
432 Pretty-print the BPF socket-local data entries for the requested map ID. Can be used more than once.
433 .TP
434 .B FILTER := [ state STATE-FILTER ] [ EXPRESSION ]
435 Please take a look at the official documentation for details regarding filters.
436
437 .SH STATE-FILTER
438
439 .B STATE-FILTER
440 allows one to construct an arbitrary set of states to match. Its syntax is
441 sequence of keywords state and exclude followed by identifier of
442 state.
443 .TP
444 Available identifiers are:
445
446 All standard TCP states:
447 .BR established ", " syn-sent ", " syn-recv ", " fin-wait-1 ", " fin-wait-2 ", " time-wait ", " closed ", " close-wait ", " last-ack ", "
448 .BR listening " and " closing.
449
450 .B all
451 - for all the states
452
453 .B connected
454 - all the states except for
455 .BR listening " and " closed
456
457 .B synchronized
458 - all the
459 .B connected
460 states except for
461 .B syn-sent
462
463 .B bucket
464 - states, which are maintained as minisockets, i.e.
465 .BR time-wait " and " syn-recv
466
467 .B big
468 - opposite to
469 .B bucket
470
471 .B bound-inactive
472 - bound but otherwise inactive sockets (not listening, connecting, etc.)
473
474 .SH EXPRESSION
475
476 .B EXPRESSION
477 allows filtering based on specific criteria.
478 .B EXPRESSION
479 consists of a series of predicates combined by boolean operators. The possible operators in increasing
480 order of precedence are
481 .B or
482 (or | or ||),
483 .B and
484 (or & or &&), and
485 .B not
486 (or !). If no operator is between consecutive predicates, an implicit
487 .B and
488 operator is assumed. Subexpressions can be grouped with "(" and ")".
489 .P
490 The following predicates are supported:
491
492 .TP
493 .B {dst|src} [=] HOST
494 Test if the destination or source matches HOST. See HOST SYNTAX for details.
495 .TP
496 .B {dport|sport} [OP] [FAMILY:]:PORT
497 Compare the destination or source port to PORT. OP can be any of "<", "<=", "=", "!=",
498 ">=" and ">", following normal arithmetic rules. FAMILY and PORT are as described in
499 HOST SYNTAX below.
500 .TP
501 .B dev [=|!=] DEVICE
502 Match based on the device the connection uses. DEVICE can either be a device name or the
503 index of the interface.
504 .TP
505 .B fwmark [=|!=] MASK
506 Matches based on the fwmark value for the connection. This can either be a specific mark value
507 or a mark value followed by a "/" and a bitmask of which bits to use in the comparison. For example
508 "fwmark = 0x01/0x03" would match if the two least significant bits of the fwmark were 0x01.
509 .TP
510 .B cgroup [=|!=] PATH
511 Match if the connection is part of a cgroup at the given path.
512 .TP
513 .B autobound
514 Match if the port or path of the source address was automatically allocated
515 (rather than explicitly specified).
516 .P
517 Most operators have aliases. If no operator is supplied "=" is assumed.
518 Each of the following groups of operators are all equivalent:
519 .RS
520 .IP \(bu 2
521 = == eq
522 .IP \(bu
523 != ne neq
524 .IP \(bu
525 > gt
526 .IP \(bu
527 < lt
528 .IP \(bu
529 >= ge geq
530 .IP \(bu
531 <= le leq
532 .IP \(bu
533 ! not
534 .IP \(bu
535 | || or
536 .IP \(bu
537 & && and
538 .RE
539 .SH HOST SYNTAX
540 .P
541 The general host syntax is [FAMILY:]ADDRESS[:PORT].
542 .P
543 FAMILY must be one of the families supported by the -f option. If not given
544 it defaults to the family given with the -f option, and if that is also
545 missing, will assume either inet or inet6. Note that all host conditions in the
546 expression should either all be the same family or be only inet and inet6. If there
547 is some other mixture of families, the results will probably be unexpected.
548 .P
549 The form of ADDRESS and PORT depends on the family used. "*" can be used as
550 a wildcard for either the address or port. The details for each family are as
551 follows:
552 .TP
553 .B unix
554 ADDRESS is a glob pattern (see
555 .BR fnmatch (3))
556 that will be matched case-insensitively against the unix socket's address. Both path and abstract
557 names are supported. Unix addresses do not support a port, and "*" cannot be used as a wildcard.
558 .TP
559 .B link
560 ADDRESS is the case-insensitive name of an Ethernet protocol to match. PORT
561 is either a device name or a device index for the desired link device, as seen
562 in the output of ip link.
563 .TP
564 .B netlink
565 ADDRESS is a descriptor of the netlink family. Possible values come from
566 /etc/iproute2/nl_protos. PORT is the port id of the socket, which is usually
567 the same as the owning process id. The value "kernel" can be used to represent
568 the kernel (port id of 0).
569 .TP
570 .B vsock
571 ADDRESS is an integer representing the CID address, and PORT is the port.
572 .TP
573 .BR inet \ and\ inet6
574 ADDRESS is an ip address (either v4 or v6 depending on the family) or a DNS
575 hostname that resolves to an ip address of the required version. An ipv6
576 address must be enclosed in "[" and "]" to disambiguate the port separator. The
577 address may additionally have a prefix length given in CIDR notation (a slash
578 followed by the prefix length in bits). PORT is either the numerical
579 socket port, or the service name for the port to match.
580
581 .SH USAGE EXAMPLES
582 .TP
583 .B ss -t -a
584 Display all TCP sockets.
585 .TP
586 .B ss -t -a -Z
587 Display all TCP sockets with process SELinux security contexts.
588 .TP
589 .B ss -u -a
590 Display all UDP sockets.
591 .TP
592 .B ss -o state established '( dport = :ssh or sport = :ssh )'
593 Display all established ssh connections.
594 .TP
595 .B ss -x src /tmp/.X11-unix/*
596 Find all local processes connected to X server.
597 .TP
598 .B ss -o state fin-wait-1 '( sport = :http or sport = :https )' dst 193.233.7/24
599 List all the tcp sockets in state FIN-WAIT-1 for our apache to network
600 193.233.7/24 and look at their timers.
601 .TP
602 .B ss -a -A 'all,!tcp'
603 List sockets in all states from all socket tables but TCP.
604 .SH SEE ALSO
605 .BR ip (8),
606 .br
607 .BR RFC " 793 "
608 - https://tools.ietf.org/rfc/rfc793.txt (TCP states)
609
610 .SH AUTHOR
611 .I ss
612 was written by Alexey Kuznetsov, <[email protected]>.
613 .PP
614 This manual page was written by Michael Prokop <[email protected]>
615 for the Debian project (but may be used by others).