man/man8/ip.8

   1 .TH IP 8 "20 Dec 2011" "iproute2" "Linux"
   2 .SH NAME
   3 ip \- show / manipulate routing, network devices, interfaces and tunnels
   4 .SH SYNOPSIS
   5
   6 .ad l
   7 .in +8
   8 .ti -8
   9 .B ip
  10 .RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | "
  11 .BR help " }"
  12 .sp
  13
  14 .ti -8
  15 .B ip
  16 .RB "[ " -force " ] "
  17 .BI "-batch " filename
  18 .sp
  19
  20 .ti -8
  21 .IR OBJECT " := { "
  22 .BR link " | " address " | " addrlabel " | " route " | " rule " | " neigh " | "\
  23  ntable " | " tunnel " | " tuntap " | " maddress " | "  mroute " | " mrule " | "\
  24  monitor " | " xfrm " | " netns " | "  l2tp " | "  tcp_metrics " | " token " | "\
  25  macsec " }"
  26 .sp
  27
  28 .ti -8
  29 .IR OPTIONS " := { "
  30 \fB\-V\fR[\fIersion\fR] |
  31 \fB\-h\fR[\fIuman-readable\fR] |
  32 \fB\-s\fR[\fItatistics\fR] |
  33 \fB\-d\fR[\fIetails\fR] |
  34 \fB\-r\fR[\fIesolve\fR] |
  35 \fB\-iec\fR |
  36 \fB\-f\fR[\fIamily\fR] {
  37 .BR inet " | " inet6 " | " link " } | "
  38 \fB-4\fR |
  39 \fB-6\fR |
  40 \fB-I\fR |
  41 \fB-D\fR |
  42 \fB-B\fR |
  43 \fB-0\fR |
  44 \fB-l\fR[\fIoops\fR] { \fBmaximum-addr-flush-attempts\fR } |
  45 \fB\-o\fR[\fIneline\fR] |
  46 \fB\-rc\fR[\fIvbuf\fR] [\fBsize\fR] |
  47 \fB\-t\fR[\fIimestamp\fR] |
  48 \fB\-ts\fR[\fIhort\fR] |
  49 \fB\-n\fR[\fIetns\fR] name |
  50 \fB\-a\fR[\fIll\fR] |
  51 \fB\-c\fR[\fIolor\fR] |
  52 \fB\-br\fR[\fIief\fR] |
  53 \fB\-j\fR[son\fR] |
  54 \fB\-p\fR[retty\fR] }
  55
  56 .SH OPTIONS
  57
  58 .TP
  59 .BR "\-V" , " -Version"
  60 Print the version of the
  61 .B ip
  62 utility and exit.
  63
  64 .TP
  65 .BR "\-h", " \-human", " \-human-readable"
  66 output statistics with human readable values followed by suffix.
  67
  68 .TP
  69 .BR "\-b", " \-batch " <FILENAME>
  70 Read commands from provided file or standard input and invoke them.
  71 First failure will cause termination of ip.
  72
  73 .TP
  74 .BR "\-force"
  75 Don't terminate ip on errors in batch mode.
  76 If there were any errors during execution of the commands, the application return code will be non zero.
  77
  78 .TP
  79 .BR "\-s" , " \-stats" , " \-statistics"
  80 Output more information. If the option
  81 appears twice or more, the amount of information increases.
  82 As a rule, the information is statistics or some time values.
  83
  84 .TP
  85 .BR "\-d" , " \-details"
  86 Output more detailed information.
  87
  88 .TP
  89 .BR "\-l" , " \-loops " <COUNT>
  90 Specify maximum number of loops the 'ip address flush' logic
  91 will attempt before giving up. The default is 10.
  92 Zero (0) means loop until all addresses are removed.
  93
  94 .TP
  95 .BR "\-f" , " \-family " <FAMILY>
  96 Specifies the protocol family to use. The protocol family identifier can be one of
  97 .BR "inet" , " inet6" , " bridge" ,  " mpls"
  98 or
  99 .BR link .
 100 If this option is not present,
 101 the protocol family is guessed from other arguments. If the rest
 102 of the command line does not give enough information to guess the
 103 family,
 104 .B ip
 105 falls back to the default one, usually
 106 .B inet
 107 or
 108 .BR "any" .
 109 .B link
 110 is a special family identifier meaning that no networking protocol
 111 is involved.
 112
 113 .TP
 114 .B \-4
 115 shortcut for
 116 .BR "-family inet" .
 117
 118 .TP
 119 .B \-6
 120 shortcut for
 121 .BR "\-family inet6" .
 122
 123 .TP
 124 .B \-B
 125 shortcut for
 126 .BR "\-family bridge" .
 127
 128 .TP
 129 .B \-M
 130 shortcut for
 131 .BR "\-family mpls" .
 132
 133 .TP
 134 .B \-0
 135 shortcut for
 136 .BR "\-family link" .
 137
 138 .TP
 139 .BR "\-o" , " \-oneline"
 140 output each record on a single line, replacing line feeds
 141 with the
 142 .B '\e'
 143 character. This is convenient when you want to count records
 144 with
 145 .BR wc (1)
 146 or to
 147 .BR grep (1)
 148 the output.
 149
 150 .TP
 151 .BR "\-r" , " \-resolve"
 152 use the system's name resolver to print DNS names instead of
 153 host addresses.
 154
 155 .TP
 156 .BR "\-n" , " \-netns " <NETNS>
 157 switches
 158 .B ip
 159 to the specified network namespace
 160 .IR NETNS .
 161 Actually it just simplifies executing of:
 162
 163 .B ip netns exec
 164 .IR NETNS
 165 .B ip
 166 .RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | "
 167 .BR help " }"
 168
 169 to
 170
 171 .B ip
 172 .RI "-n[etns] " NETNS " [ " OPTIONS " ] " OBJECT " { " COMMAND " | "
 173 .BR help " }"
 174
 175 .TP
 176 .BR "\-a" , " \-all"
 177 executes specified command over all objects, it depends if command supports this option.
 178
 179 .TP
 180 .BR \-c [ color ][ = { always | auto | never }
 181 Configure color output. If parameter is omitted or
 182 .BR always ,
 183 color output is enabled regardless of stdout state. If parameter is
 184 .BR auto ,
 185 stdout is checked to be a terminal before enabling color output. If parameter is
 186 .BR never ,
 187 color output is disabled. If specified multiple times, the last one takes
 188 precedence. This flag is ignored if
 189 .B \-json
 190 is also given.
 191
 192 Used color palette can be influenced by
 193 .BR COLORFGBG
 194 environment variable
 195 (see
 196 .BR ENVIRONMENT ).
 197
 198 .TP
 199 .BR "\-t" , " \-timestamp"
 200 display current time when using monitor option.
 201
 202 .TP
 203 .BR "\-ts" , " \-tshort"
 204 Like
 205 .BR \-timestamp ,
 206 but use shorter format.
 207
 208 .TP
 209 .BR "\-rc" , " \-rcvbuf" <SIZE>
 210 Set the netlink socket receive buffer size, defaults to 1MB.
 211
 212 .TP
 213 .BR "\-iec"
 214 print human readable rates in IEC units (e.g. 1Ki = 1024).
 215
 216 .TP
 217 .BR "\-br" , " \-brief"
 218 Print only basic information in a tabular format for better readability. This option is currently only supported by
 219 .BR "ip addr show " and " ip link show " commands.
 220
 221 .TP
 222 .BR "\-j", " \-json"
 223 Output results in JavaScript Object Notation (JSON).
 224
 225 .TP
 226 .BR "\-p", " \-pretty"
 227 The default JSON format is compact and more efficient to parse but hard for most users to read.
 228 This flag adds indentation for readability.
 229
 230 .SH IP - COMMAND SYNTAX
 231
 232 .SS
 233 .I OBJECT
 234
 235 .TP
 236 .B address
 237 - protocol (IP or IPv6) address on a device.
 238
 239 .TP
 240 .B addrlabel
 241 - label configuration for protocol address selection.
 242
 243 .TP
 244 .B l2tp
 245 - tunnel ethernet over IP (L2TPv3).
 246
 247 .TP
 248 .B link
 249 - network device.
 250
 251 .TP
 252 .B maddress
 253 - multicast address.
 254
 255 .TP
 256 .B monitor
 257 - watch for netlink messages.
 258
 259 .TP
 260 .B mroute
 261 - multicast routing cache entry.
 262
 263 .TP
 264 .B mrule
 265 - rule in multicast routing policy database.
 266
 267 .TP
 268 .B neighbour
 269 - manage ARP or NDISC cache entries.
 270
 271 .TP
 272 .B netns
 273 - manage network namespaces.
 274
 275 .TP
 276 .B ntable
 277 - manage the neighbor cache's operation.
 278
 279 .TP
 280 .B route
 281 - routing table entry.
 282
 283 .TP
 284 .B rule
 285 - rule in routing policy database.
 286
 287 .TP
 288 .B tcp_metrics/tcpmetrics
 289 - manage TCP Metrics
 290
 291 .TP
 292 .B token
 293 - manage tokenized interface identifiers.
 294
 295 .TP
 296 .B tunnel
 297 - tunnel over IP.
 298
 299 .TP
 300 .B tuntap
 301 - manage TUN/TAP devices.
 302
 303 .TP
 304 .B xfrm
 305 - manage IPSec policies.
 306
 307 .PP
 308 The names of all objects may be written in full or
 309 abbreviated form, for example
 310 .B address
 311 can be abbreviated as
 312 .B addr
 313 or just
 314 .B a.
 315
 316 .SS
 317 .I COMMAND
 318
 319 Specifies the action to perform on the object.
 320 The set of possible actions depends on the object type.
 321 As a rule, it is possible to
 322 .BR "add" , " delete"
 323 and
 324 .B show
 325 (or
 326 .B list
 327 ) objects, but some objects do not allow all of these operations
 328 or have some additional commands. The
 329 .B help
 330 command is available for all objects. It prints
 331 out a list of available commands and argument syntax conventions.
 332 .sp
 333 If no command is given, some default command is assumed.
 334 Usually it is
 335 .B list
 336 or, if the objects of this class cannot be listed,
 337 .BR "help" .
 338
 339 .SH ENVIRONMENT
 340 .TP
 341 .B COLORFGBG
 342 If set, it's value is used for detection whether background is dark or light and use contrast colors for it.
 343
 344 COLORFGBG environment variable usually contains either two or three
 345 values separated by semicolons; we want the last value in either case.
 346 If this value is 0-6 or 8, chose colors suitable for dark background:
 347
 348 COLORFGBG=";0" ip -c a
 349
 350 .SH EXIT STATUS
 351 Exit status is 0 if command was successful, and 1 if there is a syntax error.
 352 If an error was reported by the kernel exit status is 2.
 353
 354 .SH "EXAMPLES"
 355 .PP
 356 ip addr
 357 .RS 4
 358 Shows addresses assigned to all network interfaces.
 359 .RE
 360 .PP
 361 ip neigh
 362 .RS 4
 363 Shows the current neighbour table in kernel.
 364 .RE
 365 .PP
 366 ip link set x up
 367 .RS 4
 368 Bring up interface x.
 369 .RE
 370 .PP
 371 ip link set x down
 372 .RE
 373 .RS 4
 374 Bring down interface x.
 375 .RE
 376 .PP
 377 ip route
 378 .RS 4
 379 Show table routes.
 380 .RE
 381
 382 .SH HISTORY
 383 .B ip
 384 was written by Alexey N. Kuznetsov and added in Linux 2.2.
 385 .SH SEE ALSO
 386 .BR ip-address (8),
 387 .BR ip-addrlabel (8),
 388 .BR ip-l2tp (8),
 389 .BR ip-link (8),
 390 .BR ip-maddress (8),
 391 .BR ip-monitor (8),
 392 .BR ip-mroute (8),
 393 .BR ip-neighbour (8),
 394 .BR ip-netns (8),
 395 .BR ip-ntable (8),
 396 .BR ip-route (8),
 397 .BR ip-rule (8),
 398 .BR ip-tcp_metrics (8),
 399 .BR ip-token (8),
 400 .BR ip-tunnel (8),
 401 .BR ip-xfrm (8)
 402 .br
 403 .RB "IP Command reference " ip-cref.ps
 404 .SH REPORTING BUGS
 405 Report any bugs to the Network Developers mailing list
 406 .B <netdev@vger.kernel.org>
 407 where the development and maintenance is primarily done.
 408 You do not have to be subscribed to the list to send a message there.
 409
 410 .SH AUTHOR
 411 Original Manpage by Michail Litvak <mci@owl.openwall.com>