General Command Structure

The ip utility has a global syntax structure that will be quite familiar to anyone that has ever configured a Cisco router using IOS. All of the commands start with ip followed by the appropriate object, such as addr or route , then followed by the arguments and information needed to perform the function. All IPv4 addresses and networks are specified using CIDR syntax, for example 127.0.0.1/8 for the loopback interface and network. All IPv6 addresses and network may be specified using collapsed notation (see Chapter 9, "IPv6" ).

This chapter presents a comprehensive description of the ip utility objects that you will be using. You will start by going through most of the ip commands in extreme detail, covering the link, addr, route, rule, neigh, tunnel, multicast , and monitor objects (detailed in Table 4.1). The most important of these are the addr, route , and rule objects because they form the heart of the Policy Routing implementation structure under Linux, the Triad. The other objects are included here for reference ”you will be making use of them in the examples and exercises.

Table 4.1. `ip` Utility Objects

Object	Description
`link`	Network Device
`addr`	IP Address (Triad #1)
`route`	Routes (Triad #2)
`rule`	Rules (Triad #3)
`neigh`	ARP Neighbors Table
`tunnel`	IP Tunnels
`multicast`	IP Multicast
`monitor`	Debug and Tracking

These sections will be different from the style you have seen up to this point because of the nature of the command syntax of the ip command. As of August 2000 there are no man pages for ip , and the documentation is only available in LaTeX format. If you have read the ip-cref.tex document that Kuznetsov has written as included in 1999-03-08 distribution or newer of IPROUTE2, feel free to just skim through most of this section. I have extended the discussion and examples somewhat, but the core is taken from ip-cref.tex . If you have any questions or comments about the examples or statements in this section, please direct them to me.

IP Global Command Syntax

The generic form of the ip command is

 ip  [ options ] object [ command [ arguments ]]

Options

Options is a multivalued set of modifiers that affect the general behavior and output of the ip utility. All options begin with the - character and may be used both in long and abbreviated forms. Currently the following options are available:

-V, -Version ” Print the version of the ip utility and exit.
-s, -stats, -statistics ” Output more information.

This option may be repeated to increase the verbosity level of the output. As a rule, the additional information is device or function statistics or values. In many cases the values output should be considered in the same sense as output from the /proc/ directory, where the name of the value is not directly related to the value itself.
-f, -family { inet, inet6, link} ” Enforce which protocol family to use.

If this option is not present, the protocol family output to use is guessed from the other command-line arguments. If the rest of the command line does not provide sufficient information to guess a protocol family, the ip command falls back to a default family of inet in the case of network protocols. link is a special family identifier meaning that no networking protocol is involved. There are several shortcuts for this option, as listed here:

-4 ” Shortcut for -family inet .

-6 ” Shortcut for -family inet6 .

-0 ” Shortcut for -family link .
-o, -oneline ” Format the output records as single lines by replacing any line feeds with the \ character.

This option is to provide a convenient method for sending the command output through a pipe ”for example, when you want to count the number of output records with wc or you want to grep through the output.
-r, -resolve ” Use system name resolution to output DNS names .

Note that ip itself never uses DNS to resolve names to addresses. This option exists for convenience only.

Object

This is the most important part of the ip command line. Object is the object type on which you want to operate or obtain information. The object types understood by the current ip utility are link, addr, neigh, route, rule, maddr, mroute , and tunnel .

link ” Physical or logical network device.
addr ” Protocol (IPv4 or IPv6) address on a device.
neigh ” ARP or NDISC cache entry.
route ” Routing table entry.
rule ” Rule in routing policy database.
maddr ” Multicast address.
mroute ” Multicast routing cache entry.
tunnel ” Tunnel over IP.

The names of all of the objects may be written in full or abbreviated form. For example, addr may be abbreviated as ad or just a . Within each section as the commands are illustrated the usable abbreviations are shown. However, I strongly recommend that when you use the ip command within scripts, you make it a habit to always use the full command-line specification. Using the abbreviations is easy on the command line but harder to easily read and understand within scripts. Since you may not be the only person who ever has to deal with your scripts, you should strive to make them as complete as possible.

Command

Command specifies the action to perform on the object. The set of possible actions depends on the object type. Typically it is possible to add, delete , and show (list) the object(s), but some objects will not allow all of these operations and many have additional actions and commands. Note that the command syntax help , which is available for all objects, prints out the full list of available commands and argument syntax conventions. If no command is given, a default command is assumed. The default command is usually show (list) but if the objects of the class cannot be listed, the default is to print out the command syntax help.

Arguments

Arguments is the list of command options specific to the command. The arguments depend on the command and the object. There are two types of arguments that can be issued:

Flags ” These are abbreviated with a single keyword.
Parameters ” These consist of a keyword followed by a value.

Each command has a default parameter that is used if the arguments are omitted. For example, the dev parameter is the default for the ip link command; thus ip link list eth0 is equivalent to ip link list dev eth0 . Within all the following command descriptions, I distinguish default parameters with the marker (default) next to the default command.

As previously mentioned for the names of objects, all keywords may be abbreviated with the first or first few unique letters . These shortcuts are convenient when ip is used interactively, but they are not recommended for use in scripts, and please do not use them when reporting bugs or asking for help. Officially allowed abbreviations are listed along with the first mention of the command.

Error Conditions

The ip command most commonly fails for the following reasons:

The command-line syntax is wrong. This is often due to using an unknown keyword, an incorrectly formatted TCP/IP address, a wrong keyword argument for the command, and so on. In that case, the ip command exits without performing any actions and prints out an error message containing information about the reason for failure. In some cases it prints out the command syntax help.

The arguments did not pass self-consistency verification.

ip failed to compile a kernel request from the arguments due to insufficient user -provided information.

The kernel returned an error to a syscall. In that case, ip prints the error message as it was output from perror(3) , prefixed with a comment and the syscall identifier.

The kernel returned an error to a RTNETLINK request. In that case, ip prints the error message as it was output from perror(3) , prefixed with RTNETLINK answers.

Note

Note that all ip command operations are atomic. This means that if the ip command fails, it does not change anything in the system. One harmful exception is the ip link command, which may change only part of the device parameters given on the command line. I will mention this again in the section on ip link usage and recommend that all ip link actions be performed individually. This is actually a preferred use for the ip command in general. If you need to perform many repetitions of the command, use a script loop or a script. Then, any generated error messages can be associated with the appropriate ip command action.

It is difficult to list all possible error messages, especially the syntax errors. As a rule, their meaning should be clear from the context of the command that was issued. For example, if you issue the command ip link sub eth0 with the obvious misspelling of set , you get the error message Command "sub" is unknown, try "ip link help" , which should prompt you to check your command syntax.

In using the ip command there are several facilities that need to be present for the command to perform its functions. The ip command talks to the kernel through the NETLINK interface. This is turned on by the NETLINK and RNETLINK options discussed in the beginning of this chapter. If the ip command does not work or you get an error message, you do not have the needed functions defined or your kernel is not the one you compiled. The most common mistakes are

NETLINK is not configured in the kernel. The error message is Cannot open netlink socket Invalid value .
RTNETLINK is not configured in the kernel. In that case, one of the following messages may be printed, depending on the actual command issued:
```
 Cannot talk to rtnetlink Connection refused Cannot send dump request Connection refused 
```

Now that you have seen the overview of the command syntax it is time to delve into the details. The following sections detail the usage of the command syntax elements and give some examples.

Top