netstat.tproj/netstat.1

   1 .\" Copyright (c) 2012 Apple Inc. All rights reserved.
   2 .\"
   3 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   4 .\"
   5 .\" This file contains Original Code and/or Modifications of Original Code
   6 .\" as defined in and that are subject to the Apple Public Source License
   7 .\" Version 2.0 (the 'License'). You may not use this file except in
   8 .\" compliance with the License. The rights granted to you under the License
   9 .\" may not be used to create, or enable the creation or redistribution of,
  10 .\" unlawful or unlicensed copies of an Apple operating system, or to
  11 .\" circumvent, violate, or enable the circumvention or violation of, any
  12 .\" terms of an Apple operating system software license agreement.
  13 .\"
  14 .\" Please obtain a copy of the License at
  15 .\" http://www.opensource.apple.com/apsl/ and read it before using this file.
  16 .\"
  17 .\" The Original Code and all software distributed under the License are
  18 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  19 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  20 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  21 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  22 .\" Please see the License for the specific language governing rights and
  23 .\" limitations under the License.
  24 .\"
  25 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  26 .\"
  27 .\" Copyright (c) 1983, 1990, 1992, 1993
  28 .\"     The Regents of the University of California.  All rights reserved.
  29 .\"
  30 .\" Redistribution and use in source and binary forms, with or without
  31 .\" modification, are permitted provided that the following conditions
  32 .\" are met:
  33 .\" 1. Redistributions of source code must retain the above copyright
  34 .\"    notice, this list of conditions and the following disclaimer.
  35 .\" 2. Redistributions in binary form must reproduce the above copyright
  36 .\"    notice, this list of conditions and the following disclaimer in the
  37 .\"    documentation and/or other materials provided with the distribution.
  38 .\" 3. All advertising materials mentioning features or use of this software
  39 .\"    must display the following acknowledgement:
  40 .\"     This product includes software developed by the University of
  41 .\"     California, Berkeley and its contributors.
  42 .\" 4. Neither the name of the University nor the names of its contributors
  43 .\"    may be used to endorse or promote products derived from this software
  44 .\"    without specific prior written permission.
  45 .\"
  46 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  47 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  48 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  49 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  50 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  51 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  52 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  53 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  54 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  55 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  56 .\" SUCH DAMAGE.
  57 .\"
  58 .\"     @(#)netstat.1   8.8 (Berkeley) 4/18/94
  59 .\" $FreeBSD: src/usr.bin/netstat/netstat.1,v 1.22.2.7 2001/08/10 09:07:09 ru Exp $
  60 .\"
  61 .Dd June 15, 2001
  62 .Dt NETSTAT 1
  63 .Os Darwin
  64 .Sh NAME
  65 .Nm netstat
  66 .Nd show network status
  67 .Sh SYNOPSIS
  68 .Nm
  69 .Op Fl AaLlnW
  70 .Op Fl f Ar address_family | Fl p Ar protocol
  71 .Nm
  72 .Op Fl gilns
  73 .Op Fl v
  74 .Op Fl f Ar address_family
  75 .Op Fl I Ar interface
  76 .Nm
  77 .Fl i | I Ar interface
  78 .Op Fl w Ar wait
  79 .Op Fl c Ar queue
  80 .Op Fl abdgqRt
  81 .Nm
  82 .Fl s Op Fl s
  83 .Op Fl f Ar address_family | Fl p Ar protocol
  84 .Op Fl w Ar wait
  85 .Nm
  86 .Fl i | I Ar interface Fl s
  87 .Op Fl f Ar address_family | Fl p Ar protocol
  88 .Nm
  89 .Fl m
  90 .Op Fl m
  91 .Nm
  92 .Fl r
  93 .Op Fl Aaln
  94 .Op Fl f Ar address_family
  95 .Nm
  96 .Fl rs
  97 .Op Fl s
  98 .\"-----------------------------------------------------------------------------------------
  99 .Sh DESCRIPTION
 100 .\"-----------------------------------------------------------------------------------------
 101 The
 102 .Nm
 103 command symbolically displays the contents of various network-related data structures.
 104 There are a number of output formats, depending on the options for the information presented.
 105 The first form of the command displays a list of active sockets for each protocol.
 106 The second form presents the contents of one of the other network data structures according
 107 to the option selected. Using the third form, with a
 108 .Ar wait
 109 interval specified,
 110 .Nm
 111 will continuously display the information regarding packet traffic on the configured network
 112 interfaces.  The fourth form displays statistics for the specified protocol or address family. If a
 113 .Ar wait
 114 interval is specified, the protocol information over the last interval seconds will be displayed.
 115 The fifth form displays per-interface statistics for the specified protocol or address family.
 116 The sixth form displays
 117 .Xr mbuf 9
 118 statistics.  The seventh form displays routing table for the specified address family.  The
 119 eighth form displays routing statistics.
 120 .Pp
 121 The options have the following meaning:
 122 .Bl -tag -width flag
 123 .It Fl A
 124 With the default display, show the address of any protocol control blocks associated with
 125 sockets and the flow hash; used for debugging.
 126 .It Fl a
 127 With the default display, show the state of all sockets; normally sockets used by server
 128 processes are not shown. With the routing table display (option
 129 .Fl r ,
 130 as described below), show protocol-cloned routes (routes generated by a
 131 .Dv RTF_PRCLONING
 132 parent route); normally these routes are not shown.
 133 .It Fl b
 134 With the interface display (option
 135 .Fl i ,
 136 as described below), show the number of bytes in and out.
 137 .It Fl c Ar queue
 138 With the queue statistics (option
 139 .Fl q ,
 140 as described below), show only those for the specified
 141 .Ar queue .
 142 .It Fl d
 143 With either interface display (option
 144 .Fl i
 145 or an interval, as described below), show the number of dropped packets.
 146 .It Fl f Ar address_family
 147 Limit statistics or address control block reports to those of the specified
 148 .Ar address family  .
 149 The following address families are recognized:
 150 .Ar inet  ,
 151 for
 152 .Dv AF_INET  ,
 153 .Ar inet6  ,
 154 for
 155 .Dv AF_INET6
 156 and
 157 .Ar unix  ,
 158 for
 159 .Dv AF_UNIX  .
 160 .It Fl g
 161 Show information related to multicast (group address) membership.  If the
 162 .Fl s
 163 option is also present, show extended interface group management statistics.  If the
 164 .Fl v
 165 option is specified, show link-layer memberships; they are suppressed by default.
 166 Source lists for each group will also be printed.  Specifiying
 167 .Fl v
 168 twice will print the control plane timers for each interface and the source list counters
 169 for each group.  If the
 170 .Fl i
 171 is specified, only that interface will be shown.  If the
 172 .Fl f
 173 is specified, only information for the address family will be displayed.
 174 .It Fl I Ar interface
 175 Show information about the specified interface; used with a
 176 .Ar wait
 177 interval as described below.
 178 If the
 179 .Fl s
 180 option is present, show per-interface protocol statistics on the
 181 .Ar interface
 182 for the specified
 183 .Ar address_family
 184 or
 185 .Ar protocol ,
 186 or for all protocol families.
 187 .It Fl i
 188 Show the state of interfaces which have been auto-configured (interfaces statically
 189 configured into a system, but not located at boot time are not shown).  If the
 190 .Fl a
 191 options is also present, multicast addresses currently in use are shown for each
 192 Ethernet interface and for each IP interface address.  Multicast addresses are shown
 193 on separate lines following the interface address with which they are associated.
 194 If the
 195 .Fl s
 196 option is present, show per-interface statistics on all interfaces for the specified
 197 .Ar address_family
 198 or
 199 .Ar protocol ,
 200 or for all protocol families.
 201 .It Fl L
 202 Show the size of the various listen queues.  The first count shows the number of
 203 unaccepted connections.  The second count shows the amount of unaccepted incomplete
 204 connections.  The third count is the maximum number of queued connections.
 205 .It Fl l
 206 Print full IPv6 address.
 207 .It Fl m
 208 Show statistics recorded by the memory management routines (the network stack manages a private pool of memory buffers). More detailed information about the buffers, which includes their cache related statistics, can be obtained by using
 209 .Fl mm
 210 or
 211 .Fl m
 212 .Fl m
 213 option.
 214 .It Fl n
 215 Show network addresses as numbers (normally
 216 .Nm
 217 interprets addresses and attempts to display them symbolically).  This option may be
 218 used with any of the display formats.
 219 .It Fl p Ar protocol
 220 Show statistics about
 221 .Ar protocol ,
 222 which is either a well-known name for a protocol or an alias for it.  Some protocol
 223 names and aliases are listed in the file
 224 .Pa /etc/protocols .
 225 The special protocol name
 226 .Dq bdg
 227 is used to show bridging statistics.  A null response typically means that there are
 228 no interesting numbers to report.  The program will complain if
 229 .Ar protocol
 230 is unknown or if there is no statistics routine for it.
 231 .It Fl q
 232 Show network interface send queue statistics.  By default all queues are displayed, unless
 233 specified with
 234 .Fl c .
 235 This option requires specifying an interface with
 236 .Fl I
 237 option.  More detailed information about the queues, which includes their queueing algorithm related statistics, can be obtained by using
 238 .Fl qq
 239 or
 240 .Fl q
 241 .Fl q
 242 option.
 243 .It Fl r
 244 Show the routing tables.  Use with
 245 .Fl a
 246 to show protocol-cloned routes.  When
 247 .Fl s
 248 is also present, show routing statistics instead.  When
 249 .Fl l
 250 is also present,
 251 .Nm
 252 assumes more columns are there and the maximum transmission unit
 253 .Pq Dq mtu
 254 are also displayed.
 255 .It Fl R
 256 Show reachability information.  Use with
 257 .Fl i
 258 to show link-layer reachability information for a given interface.
 259 .It Fl s
 260 Show per-protocol statistics.  If this option is repeated, counters with a value of
 261 zero are suppressed.
 262 .It Fl v
 263 Increase verbosity level.
 264 .It Fl W
 265 In certain displays, avoid truncating addresses even if this causes some fields to
 266 overflow.
 267 .It Fl w Ar wait
 268 Show network interface or protocol statistics at intervals of
 269 .Ar wait
 270 seconds.
 271 .It Fl x
 272 Show extended link-layer reachability information in addition to that shown by
 273 the
 274 .Fl R
 275 flag.
 276 .El
 277 .Pp
 278 .\"-------------------------------------------------------------------------------
 279 .Sh OUTPUT
 280 .\"-------------------------------------------------------------------------------
 281 The default display, for active sockets, shows the local and remote addresses,
 282 send and receive queue sizes (in bytes), protocol, and the internal state of
 283 the protocol.  Address formats are of the form
 284 .Dq host.port
 285 or
 286 .Dq network.port
 287 if a socket's address specifies a network but no specific host address.
 288 If known, the host and network addresses are displayed symbolically
 289 according to the databases
 290 .Pa /etc/hosts
 291 and
 292 .Pa /etc/networks ,
 293 respectively.  If a symbolic name for an address is unknown, or if the
 294 .Fl n
 295 option is specified, the address is printed numerically, according to the
 296 address family.  For more information regarding the Internet
 297 .Dq dot format ,
 298 refer to
 299 .Xr inet 3 ) .
 300 Unspecified,
 301 or
 302 .Dq wildcard ,
 303 addresses and ports appear as
 304 .Dq * .
 305 .Pp
 306 Internet domain socket states:
 307 .Bl -column X LISTEN
 308 CLOSED:  The socket is not in use.
 309 .Pp
 310 LISTEN:  The socket is listening for incoming connections.  Unconnected
 311 listening sockets like these are only displayed when using the -a option.
 312 .Pp
 313 SYN_SENT:  The socket is actively trying to establish a connection to a
 314 remote peer.
 315 .Pp
 316 SYN_RCVD:  The socket has passively received a connection request from a
 317 remote peer.
 318 .Pp
 319 ESTABLISHED:  The socket has an established connection between a local
 320 application and a remote peer.
 321 .Pp
 322 CLOSE_WAIT:  The socket connection has been closed by the remote peer,
 323 and the system is waiting for the local application to close its half of
 324 the connection.
 325 .Pp
 326 LAST_ACK:  The socket connection has been closed by the remote peer, the
 327 local application has closed its half of the connection, and the system
 328 is waiting for the remote peer to acknowledge the close.
 329 .Pp
 330 FIN_WAIT_1:  The socket connection has been closed by the local
 331 application, the remote peer has not yet acknowledged the close, and the
 332 system is waiting for it to close its half of the connection.
 333 .Pp
 334 FIN_WAIT_2:  The socket connection has been closed by the local
 335 application, the remote peer has acknowledged the close, and the system
 336 is waiting for it to close its half of the connection.
 337 .Pp
 338 CLOSING:  The socket connection has been closed by the local application
 339 and the remote peer simultaneously, and the remote peer has not yet
 340 acknowledged the close attempt of the local application.
 341 .Pp
 342 TIME_WAIT:  The socket connection has been closed by the local
 343 application, the remote peer has closed its half of the connection, and
 344 the system is waiting to be sure that the remote peer received the last
 345 acknowledgement.
 346 .El
 347 .Pp
 348 The interface display provides a table of cumulative statistics regarding
 349 packets transferred, errors, and collisions.  The network addresses of the
 350 interface and the maximum transmission unit
 351 .Pq Dq mtu
 352 are also displayed.
 353 .Pp
 354 The routing table display indicates the available routes and their status.
 355 Each route consists of a destination host or network and a gateway to use
 356 in forwarding packets.  The flags field shows a collection of information
 357 about the route stored as binary choices.  The individual flags are discussed
 358 in more detail in the
 359 .Xr route 8
 360 and
 361 .Xr route 4
 362 manual pages.  The mapping between letters and flags is:
 363 .Bl -column XXXX RTF_BLACKHOLE
 364 1       RTF_PROTO1      Protocol specific routing flag #1
 365 2       RTF_PROTO2      Protocol specific routing flag #2
 366 3       RTF_PROTO3      Protocol specific routing flag #3
 367 B       RTF_BLACKHOLE   Just discard packets (during updates)
 368 b       RTF_BROADCAST   The route represents a broadcast address
 369 C       RTF_CLONING     Generate new routes on use
 370 c       RTF_PRCLONING   Protocol-specified generate new routes on use
 371 D       RTF_DYNAMIC     Created dynamically (by redirect)
 372 G       RTF_GATEWAY     Destination requires forwarding by intermediary
 373 H       RTF_HOST        Host entry (net otherwise)
 374 I       RTF_IFSCOPE     Route is associated with an interface scope
 375 i       RTF_IFREF       Route is holding a reference to the interface
 376 L       RTF_LLINFO      Valid protocol to link address translation
 377 M       RTF_MODIFIED    Modified dynamically (by redirect)
 378 m       RTF_MULTICAST   The route represents a multicast address
 379 R       RTF_REJECT      Host or net unreachable
 380 r       RTF_ROUTER      Host is a default router
 381 S       RTF_STATIC      Manually added
 382 U       RTF_UP          Route usable
 383 W       RTF_WASCLONED   Route was generated as a result of cloning
 384 X       RTF_XRESOLVE    External daemon translates proto to link address
 385 Y       RTF_PROXY       Proxying; cloned routes will not be scoped
 386 .El
 387 .Pp
 388 Direct routes are created for each interface attached to the local host;
 389 the gateway field for such entries shows the address of the outgoing
 390 interface.  The refcnt field gives the current number of active uses of
 391 the route.  Connection oriented protocols normally hold on to a single
 392 route for the duration of a connection while connectionless protocols
 393 obtain a route while sending to the same destination.  The use field
 394 provides a count of the number of packets sent using that route.  The
 395 interface entry indicates the network interface utilized for the route.
 396 A route which is marked with the RTF_IFSCOPE flag is instantiated for
 397 the corresponding interface.  A cloning route which is marked with the
 398 RTF_PROXY flag will not generate new routes that are associated
 399 with its interface scope.
 400 .Pp
 401 When
 402 .Nm netstat
 403 is invoked with the
 404 .Fl w
 405 option and a
 406 .Ar wait
 407 interval argument, it displays a running count of statistics related to
 408 network interfaces or protocols.  An obsolete version of this option used a numeric
 409 parameter with no option, and is currently supported for backward
 410 compatibility.  By default, this display summarizes information for all
 411 interfaces.  Information for a specific interface may be displayed with the
 412 .Fl I
 413 option.
 414 .Sh SEE ALSO
 415 .Xr fstat 1 ,
 416 .Xr nfsstat 1 ,
 417 .Xr ps 1 ,
 418 .Xr inet 4 ,
 419 .Xr unix 4 ,
 420 .Xr hosts 5 ,
 421 .Xr networks 5 ,
 422 .Xr protocols 5 ,
 423 .Xr route 8 ,
 424 .Xr services 5 ,
 425 .Xr iostat 8 ,
 426 .Xr trpt 8 ,
 427 .Xr vmstat 8
 428 .Sh HISTORY
 429 The
 430 .Nm netstat
 431 command appeared in
 432 .Bx 4.2 .
 433 .Pp
 434 IPv6 support was added by WIDE/KAME project.
 435 .Sh BUGS
 436 The notion of errors is ill-defined.