xref: /freebsd/usr.bin/sockstat/sockstat.1 (revision c66ec88fed842fbaad62c30d510644ceb7bd2d71)
1.\"-
2.\" Copyright (c) 1999 Dag-Erling Coïdan Smørgrav
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer
10.\"    in this position and unchanged.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. The name of the author may not be used to endorse or promote products
15.\"    derived from this software without specific prior written permission.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27.\"
28.\" $FreeBSD$
29.\"
30.Dd December 30, 2020
31.Dt SOCKSTAT 1
32.Os
33.Sh NAME
34.Nm sockstat
35.Nd list open sockets
36.Sh SYNOPSIS
37.Nm
38.Op Fl 46CcLlnSsUuvw
39.Op Fl j Ar jid
40.Op Fl p Ar ports
41.Op Fl P Ar protocols
42.Sh DESCRIPTION
43The
44.Nm
45command lists open Internet or
46.Ux
47domain sockets.
48.Pp
49The following options are available:
50.Bl -tag -width Fl
51.It Fl 4
52Show
53.Dv AF_INET
54(IPv4) sockets.
55.It Fl 6
56Show
57.Dv AF_INET6
58(IPv6) sockets.
59.It Fl C
60Display the congestion control module, if applicable.
61This is currently only implemented for TCP.
62.It Fl c
63Show connected sockets.
64.It Fl j Ar jail
65Show only sockets belonging to the specified jail ID or name.
66.It Fl L
67Only show Internet sockets if the local and foreign addresses are not
68in the loopback network prefix
69.Li 127.0.0.0/8 ,
70or do not contain the IPv6 loopback address
71.Li ::1 .
72.It Fl l
73Show listening sockets.
74.It Fl n
75Do not resolve numeric UIDs to user names.
76.It Fl p Ar ports
77Only show Internet sockets if the local or foreign port number
78is on the specified list.
79The
80.Ar ports
81argument is a comma-separated list of port numbers and ranges
82specified as first and last port separated by a dash.
83.It Fl P Ar protocols
84Only show sockets of the specified
85.Ar protocols .
86The
87.Ar protocols
88argument is a comma-separated list of protocol names,
89as they are defined in
90.Xr protocols 5 .
91.It Fl q
92Quiet mode, do not print the header line.
93.It Fl S
94Display the protocol stack, if applicable.
95This is currently only implemented for TCP.
96.It Fl s
97Display the protocol state, if applicable.
98This is currently only implemented for SCTP and TCP.
99.It Fl U
100Display the remote UDP encapsulation port number, if applicable.
101This is currently only implemented for SCTP.
102.It Fl u
103Show
104.Dv AF_LOCAL
105.Pq Ux
106sockets.
107.It Fl v
108Verbose mode.
109.It Fl w
110Use wider field size for displaying addresses.
111.El
112.Pp
113If neither
114.Fl 4 , 6
115or
116.Fl u
117is specified,
118.Nm
119will list sockets in all three domains.
120.Pp
121If neither
122.Fl c
123or
124.Fl l
125is specified,
126.Nm
127will list both listening and connected sockets.
128.Pp
129The information listed for each
130socket is:
131.Bl -tag -width "FOREIGN ADDRESS"
132.It Li USER
133The user who owns the socket.
134.It Li COMMAND
135The command which holds the socket.
136.It Li PID
137The process ID of the command which holds the socket.
138.It Li FD
139The file descriptor number of the socket.
140.It Li PROTO
141The transport protocol associated with the socket for Internet
142sockets, or the type of socket
143.Pq stream, datagram, or seqpacket
144for
145.Ux
146sockets.
147.It Li LOCAL ADDRESS
148For Internet sockets, this is the address the local end of the socket
149is bound to (see
150.Xr getsockname 2 ) .
151For bound
152.Ux
153sockets, it is the socket's filename.
154For other
155.Ux
156sockets, it is a right arrow followed by the endpoint's filename, or
157.Dq Li ??
158if the endpoint could not be determined.
159.It Li FOREIGN ADDRESS
160(Internet sockets only)
161The address the foreign end of the socket is bound to (see
162.Xr getpeername 2 ) .
163.It Li ENCAPS
164The remote UDP encapsulation port number if
165.Fl U
166is specified (only for SCTP).
167.It Li PATH STATE
168The path state if
169.Fl s
170is specified (only for SCTP).
171.It Li CONN STATE
172The connection state if
173.Fl s
174is specified (only for SCTP or TCP).
175.It Li STACK
176The protocol stack if
177.Fl S
178is specified (only for TCP).
179.It Li CC
180The congestion control if
181.Fl C
182is specified (only for TCP).
183.El
184.Pp
185If a socket is associated with more than one file descriptor,
186it is shown multiple times.
187If a socket is not associated with any file descriptor,
188the first four columns have no meaning.
189.Sh EXAMPLES
190Show information for IPv4 sockets listening on port 22 using protocol
191TCP:
192.Bd -literal -offset indent
193$ sockstat -4 -l -P tcp -p 22
194.Ed
195.Pp
196Show information for sockets using either TCP or UDP, if neither, the local nor
197the foreign addresses are in the loopback network:
198.Bd -literal -offset indent
199$ sockstat -L -P tcp,udp
200.Ed
201.Pp
202Show TCP IPv6 sockets which are listening and connected (default):
203.Bd -literal -offset indent
204$ sockstat -6 -P tcp
205.Ed
206.Sh SEE ALSO
207.Xr fstat 1 ,
208.Xr netstat 1 ,
209.Xr procstat 1 ,
210.Xr inet 4 ,
211.Xr inet6 4 ,
212.Xr protocols 5
213.Sh HISTORY
214The
215.Nm
216command appeared in
217.Fx 3.1 .
218.Sh AUTHORS
219The
220.Nm
221command and this manual page were written by
222.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .
223