# Task-centered iproute2 user guide Overview of iproute2 [Overview of iproute2](#overview-of-iproute2) About this document [About this document](#about-this-document) Contributing [Contributing](#contributing) Typographic conventions [Typographic conventions](#typographic-conventions) Gener

Task-centered iproute2 user guide

Overview of iproute2

About this document

Contributing

Typographic conventions

General notes

Abbreviating commands

Scripting considerations

IPv4 and IPv6 addresses

Show all addresses

Show addresses for a single interface

Show addresses only for running interfaces

Show only static or dynamic IPv6 addresses

Add an address to an interface

Add an address with a human-readable description

Delete an address from an interface

Remove all addresses from an interface

Change the primary address

IPv4 and IPv6 addresses

Show all addresses

Show addresses for a single interface

Show addresses only for running interfaces

Show only static or dynamic IPv6 addresses

Add an address to an interface

Add an address with a human-readable description

Delete an address from an interface

Remove all addresses from an interface

Change the primary address

Neighbor (ARP and NDP) tables

View neighbor tables

View neighbors for a specific interface

Flush table for an interface

Add a neighbor table entry

Delete a neighbor table entry

Neighbor (ARP and NDP) tables

View neighbor tables

View neighbors for a specific interface

Flush table for an interface

Add a neighbor table entry

Delete a neighbor table entry

Network links

Show information about all links

Show information about a specific link

Bring a link up or down

Set human-readable link description

Add link alternative names

Rename an interface

Change link-layer address (usually MAC address)

Change link MTU

Delete a link

Enable or disable multicast on an interface

Enable or disable ARP on an interface

Create a VLAN interface

Create a QinQ interface (VLAN stacking)

Create a virtual MAC (MACVLAN) interface

Create a dummy interface

Create a bonding interface

Create an intermediate functional block interface

Create a pair of virtual ethernet devices

Network links

Show information about all links

Show information about a specific link

Bring a link up or down

Set human-readable link description

Add link alternative names

Rename an interface

Change link-layer address (usually MAC address)

Change link MTU

Delete a link

Enable or disable multicast on an interface

Enable or disable ARP on an interface

Create a VLAN interface

Create a QinQ interface (VLAN stacking)

Create a virtual MAC (MACVLAN) interface

Create a dummy interface

Create a bonding interface

Create an intermediate functional block interface

Create a pair of virtual ethernet devices

Link groups

Add an interface to a group

Remove an interface from a group

Assign a symbolic name to a group

Perform an operation on a group

View information about links from a specific group

Link groups

Add an interface to a group

Remove an interface from a group

Assign a symbolic name to a group

Perform an operation on a group

View information about links from a specific group

Bridges

Bridge management utilities

Create a bridge

Add a bridge port

Delete a bridge port

View bridge port information

Isolate a bridge port

Create a VLAN-aware bridge

Create a VLAN access port

Create a VLAN trunk port

View bridge VLAN information

View bridge forwarding table

Bridges

Bridge management utilities

Create a bridge

Add a bridge port

Delete a bridge port

View bridge port information

Isolate a bridge port

Create a VLAN-aware bridge

Create a VLAN access port

Create a VLAN trunk port

View bridge VLAN information

View bridge forwarding table

TUN and TAP devices

View TUN/TAP devices

Add a TUN/TAP device useable by the root user

Add a TUN/TAP device usable by an ordinary user

Add a TUN/TAP device using an alternate packet format

Add a TUN/TAP ignoring flow control

Delete a TUN/TAP device

TUN and TAP devices

View TUN/TAP devices

Add a TUN/TAP device useable by the root user

Add a TUN/TAP device usable by an ordinary user

Add a TUN/TAP device using an alternate packet format

Add a TUN/TAP ignoring flow control

Delete a TUN/TAP device

Tunnel interfaces

Create an IPIP tunnel

Create an SIT (6in4) tunnel

Create an IPIP6 tunnel

Create an IP6IP6 tunnel

Create an L2 GRE tunnel device

Create a GRE tunnel

Create multiple GRE tunnels to the same endpoint

Create a point-to-multipoint GRE tunnel

Create a GRE tunnel over IPv6

Delete a tunnel

Modify a tunnel

View tunnel information

Tunnel interfaces

Create an IPIP tunnel

Create an SIT (6in4) tunnel

Create an IPIP6 tunnel

Create an IP6IP6 tunnel

Create an L2 GRE tunnel device

Create a GRE tunnel

Create multiple GRE tunnels to the same endpoint

Create a point-to-multipoint GRE tunnel

Create a GRE tunnel over IPv6

Delete a tunnel

Modify a tunnel

View tunnel information

L2TPv3 pseudowires

Create an L2TPv3 tunnel over UDP

Create an L2TPv3 tunnel over IP

Create an L2TPv3 session

Delete an L2TPv3 session

Delete an L2TPv3 tunnel

View L2TPv3 tunnel information

View L2TPv3 session information

L2TPv3 pseudowires

Create an L2TPv3 tunnel over UDP

Create an L2TPv3 tunnel over IP

Create an L2TPv3 session

Delete an L2TPv3 session

Delete an L2TPv3 tunnel

View L2TPv3 tunnel information

View L2TPv3 session information

VXLAN

Create a unicast VXLAN link

Create a multicast VXLAN link

VXLAN

Create a unicast VXLAN link

Create a multicast VXLAN link

GENEVE

Create a unicast GENEVE link

Create a unicast GENEVE link with a custom UDP port

Create an externally managed GENEVE device

GENEVE

Create a unicast GENEVE link

Create a unicast GENEVE link with a custom UDP port

Create an externally managed GENEVE device

Routing tables

Connected routes

View all routes

View routes to a network and all its subnets

View routes to a network and all supernets

View routes to an exact subnet

View only the route actually used by the kernel

View route cache (pre 3.6 kernels only)

Add a route via a gateway

Add a route via an interface

Add a route without consistency check for gateway reachability

Change or replace a route

Delete a route

Default route

Blackhole routes

Other special routes

Routes with different metrics

Multipath routing

Routing tables

Connected routes

View all routes

View routes to a network and all its subnets

View routes to a network and all supernets

View routes to an exact subnet

View only the route actually used by the kernel

View route cache (pre 3.6 kernels only)

Add a route via a gateway

Add a route via an interface

Add a route without consistency check for gateway reachability

Change or replace a route

Delete a route

Default route

Blackhole routes

Other special routes

Routes with different metrics

Multipath routing

Policy-based routing

Create a policy route

View policy routes

General rule syntax

Create a rule to match a source network

Create a rule to match a destination network

Create a rule to match a ToS field value

Create a rule to match a firewall mark value

Create a rule to match an inbound interface

Create a rule to match an outbound interface

Create a rule to match a user id range

Set rule priority

Show all rules

Delete a rule

Delete all rules

Policy-based routing

Create a policy route

View policy routes

General rule syntax

Create a rule to match a source network

Create a rule to match a destination network

Create a rule to match a ToS field value

Create a rule to match a firewall mark value

Create a rule to match an inbound interface

Create a rule to match an outbound interface

Create a rule to match a user id range

Set rule priority

Show all rules

Delete a rule

Delete all rules

VRF

Create a VRF

View configured VRFs

Bind an interface to a VRF

Remove an interface from a VRF

Run a command inside a VRF

Check if a process is running in a VRF

List processes running in a VRF

VRF

Create a VRF

View configured VRFs

Bind an interface to a VRF

Remove an interface from a VRF

Run a command inside a VRF

Check if a process is running in a VRF

List processes running in a VRF

Network namespaces

Create a namespace

List existing namespaces

Delete a namespace

Run a process inside a namespace

List all processes assigned to a namespace

Identify process' primary namespace

Assign a network interface to a namespace

Connect one namespace to another

Monitor network namespace subsystem events

Network namespaces

Create a namespace

List existing namespaces

Delete a namespace

Run a process inside a namespace

List all processes assigned to a namespace

Identify process' primary namespace

Assign a network interface to a namespace

Connect one namespace to another

Monitor network namespace subsystem events

Multicast groups and routes

View multicast groups

Add a link-layer multicast address

View multicast routes

Multicast groups and routes

View multicast groups

Add a link-layer multicast address

View multicast routes

Network event monitoring

Monitor all events

Monitor specific events

Read a log file produced by rtmon

Network event monitoring

Monitor all events

Monitor specific events

Read a log file produced by rtmon

netconf (sysctl configuration viewing)

View sysctl configuration for all interfaces

View sysctl configuration for specific interface

netconf (sysctl configuration viewing)

View sysctl configuration for all interfaces

View sysctl configuration for specific interface

Contributors

Daniil Baturin

CC-BY-SA License

# Overview of iproute2

iproute2 is the Linux networking toolkit that replaced legacy tools

(ifconfig, vconfig, brctl, route, arp etc.). Those tools are only kept for compatibility with old scripts

and do not provide access to a lot of newer networking features of the Linux kernel.

iproute2

It originally written by Alex Kuznetsov and is now maintained by Stephen Hemminger.

Most of the networking functionality is unified in the ip command. There’s also tc for managing traffic policies (QoS),

bridge for managing software bridge interfaces, and ss (a netstat replacement).

Those commands are usually shipped in a package called iproute2 or iproute.

Most Linux distributions install it by default these days.

The ip command is sometimes installed in /sbin and thus may not be in the $PATH of unprivileged users by default.

# About this document

Historically, documentation has been a weak side of iproute2. The official man pages list available options but don’t give almost any usage examples.

That need has been addressed by third-party documentation.

This document aims to provide a comprehensive but easy to use guide to the ip and bridge commands,

and some information about ss.

Documenting tc in this style would be a separate big project.

The document is task-centered: it tells you how to do different tasks using iproute2 commands instead of listing available subcommands.

# Contributing

This document is maintained by Daniil Baturin and distributed under

CC-BY-SA 4.0 — a strong copyleft, free culture license.

Daniil Baturin

CC-BY-SA 4.0

Contributions are always welcome; you can find the source files at

github.com/dmbaturin/iproute2-cheatsheet.

github.com/dmbaturin/iproute2-cheatsheet

You can also show your support by buying the maintainer a metaphorical coffee.

metaphorical coffee

This document is provided “as is”, without any warranty. The authors are not liable for any damage related to using it.

As usual, think before you type, and think twice before hitting the Enter key.

# Typographic conventions

Metasyntactic variables are written in a shell-like syntax, ${something}. Optional command parts are in square brackets. Mandatory arguments are in angle brackets.

# General notes

All commands that change any settings require root privileges. Commands that just display information generally do not require special privileges.

There are configuration files in /etc/iproute2, mainly for assigning symbolic names to network stack entities such as routing tables.

Those files are re-read every time you run the ip command, so you don’t need to do anything to apply the changes.

# Abbreviating commands

Any ip command can be abbreviated. For example, ip address add 192.0.2.1/24 dev eth0 can be written ip addr a 192.0.2.1/24 dev eth0 or even ip a a 192.0.2.1/24 dev eth0.

In some cases, you can even omit words. For example, show and list words are always fine to omit: ip address is equivalent to ip address show and ip address list.

Note that the abbreviation system is not always consistent. The dev keyword in ip a a 192.0.2.1/24 dev eth0 cannot be abbreviated, even though every other word can be.

This document intentionally gives all commands in their fullest form for better readability.

It’s also a good idea to use full forms in scripts because readers may not be familiar with abbreviations,

and code is read much more often than it’s written.

# Scripting considerations

A common complaint about distributions removing ifconfig is that it forces people to rewrite scripts.

However, iproute2 is better for scripting since it supports machine-readable output.

It provides the following output options:

Here is a comparison of outputs (--json --pretty and --json --brief are omitted to save space):

# IPv4 and IPv6 addresses

iproute2 accepts both dotted decimal masks and prefix length values.

That is, both 192.0.2.10/24 and 192.0.2.10/255.255.255.0 are acceptable formats.

# Show all addresses

All show commands can be used with -4 or -6 options to show only IPv4 or IPv6 addresses.

# Show addresses for a single interface

Examples:

# Show addresses only for running interfaces

# Show only static or dynamic IPv6 addresses

Show only statically configured addresses:

Show only addresses learnt via autoconfiguration:

# Add an address to an interface

Examples:

You can add as many addresses as you want.

If you add more than one address, your machine will accept packets for all of them. The first address you add becomes a “primary address”.

The primary address of an interface it’s used as the source address for outgoing packets by default.

All additional addresses you set will become secondary addresses.

# Add an address with a human-readable description

Examples:

The label must start with the interface name followed by a colon due to some backward compatibility issues, otherwise you’ll get an error.

Keep the label shorter than sixteen characters, or else you’ll get this error: RTNETLINK answers: Numerical result out of range.

Notes

For IPv6 addresses, this command has no effect. It will add the address correctly but will ignore the label.

# Delete an address from an interface

Examples:

An interface name is required—the kernel will not try to automatically guess which interface you want to remove that address from.

Such a guess would not always be unambiguous: Linux does allow the same address to be configured on multiple interfaces, and it has valid use cases

(in the Cisco world, this is known as “unnumbered interfaces”).

# Remove all addresses from an interface

Examples:

By default, this command removes both IPv4 and IPv6 addresses.

If you want to remove only IPv4 or IPv6 addresses, use ip -4 address flush or ip -6 address flush.

# Change the primary address

There is no way to swap primary and secondary IPv4 addresses or explicitly set a new primary IPv4 address. Try to always set the primary address first.

If the sysctl variable net.ipv4.conf.${interface}.promote_secondaries is set to 1, when you delete a primary address, the first secondary address becomes primary.

You can enable this behaviour globally with net.ipv4.conf.default.promote_secondaries=1.

Note that when promote_secondaries is set to 0, removing a primary address will also remove all secondary addresses from its interface.

This setting varies between Linux distributions, so be careful to check it before attempting to change a primary address.

Secondary IPv6 addresses are always promoted to primary if a primary address is deleted.

# Neighbor (ARP and NDP) tables

This command supports both American (ip neighbor) and British (ip neighbour) spelling variants.

# View neighbor tables

All “show” commands support -4 and -6 options to view only IPv4 (ARP) or IPv6 (NDP) neighbors. By default, all neighbors are displayed.

# View neighbors for a specific interface

Examples: ip neighbor show dev eth0

# Flush table for an interface

Examples: ip neighbor flush dev eth1

# Add a neighbor table entry

Examples: ip neighbor add 192.0.2.1 lladdr 22:ce:e0:99:63:6f dev eth0

One use case for it is a form of data link layer security. You can disable ARP on an interface completely

and add MAC addresses of authorized devices by hand.

# Delete a neighbor table entry

Examples: ip neighbor delete 192.0.2.1 lladdr 22:ce:e0:99:63:6f dev eth0

Allows you to delete a static entry or get rid of an automatically learnt entry without flushing the table.

# Network links

“Link” is another term for a network interface. Commands from the ip link family perform operations that are common for all interface types, like viewing link information or changing the MTU.

Historically, the ip link command could not create tunnels (IPIP, GRE etc.), VXLAN links, or L2TPv3 pseudowires.

Starting from at least iproute2 3.16, it could create anything except L2TPv3 interfaces, and this remains true as of iproute2 5.7.

A lot of time, old commands for specific interface types are still more convenient to use, though.

Note that the Linux kernel allows arbitrary, even non-ASCII names for network interfaces.

It’s better to stick with alphanumeric because userspace programs (like iptables) may not be so forgiving.

# Show information about all links

These commands are equivalent.

# Show information about a specific link

Examples:

You can omit the dev word.

# Bring a link up or down

Examples:

Note: virtual links (tunnels, VLANs, etc.) are always created in the “down” state. You need to bring them up to start using them.

# Set human-readable link description

Examples: ip link set dev eth0 alias "LAN interface".

Link aliases show up in the ip link show output, like this:

# Add link alternative names

The kernel limits the length of link names to 15 characters. In order to

overcome this limitation, alternative names can be added to a link.

Examples: ip link property add dev eth0 altname eno1 altname enp3s0

Alternative names can be used to refer to the link in iproute commands.

# Rename an interface

Examples: ip link set dev eth0 name lan

Note that you can’t rename an active interface. You need to bring it down before renaming it.

bring it down

# Change link-layer address (usually MAC address)

A link-layer address is a pretty broad concept. The most known example is the MAC address of an Ethernet device.

To change a MAC address, you would need something like ip link set dev eth0 address 22:ce:e0:99:63:6f.

# Change link MTU

Examples: ip link set dev tun0 mtu 1480

MTU stands for “Maximum Transmission Unit”, the maximum size of a frame an interface can transmit at once.

Apart from reducing fragmentation in tunnels, this is also used to increase the performance of gigabit ethernet links

that support so-called “jumbo frames” (frames up to 9000 bytes large).

If all your equipment supports gigabit ethernet, you may want to do something like ip link set dev eth0 mtu 9000.

Note that you may need to configure it on your L2 switches too, some of them have jumbo frames disabled by default.

# Delete a link

Obviously, only virtual links can be deleted, like VLANs, bridges, or tunnels.

For physical interfaces, this command has no effect.

# Enable or disable multicast on an interface

Unless you really know what you are doing, better don’t touch this option.

# Enable or disable ARP on an interface

One may want to disable ARP to enforce a security policy and allow only specific MACs to communicate with the interface.

In this case, neighbor table entries for whitelisted MACs should be created manually,

or nothing will be able to communicate with that interface.

created manually

In most cases, it’s better to configure MAC policy on an access layer switch, though. Do not change this flag unless you are sure what you are going to do and why.

# Create a VLAN interface

Examples: ip link add name eth0.110 link eth0 type vlan id 110

The only type of VLAN supported by Linux is IEEE 802.1q VLAN; legacy implementations like ISL are not supported.

You can use any name for a VLAN interface. eth0.110 is a traditional format, but it’s not required.

Any Ethernet-like device can be a parent for a VLAN interface: bridge, bonding, L2 tunnels (GRETAP, L2TPv3…).

# Create a QinQ interface (VLAN stacking)

Example:

VLAN stacking (aka 802.1ad QinQ) is a way to transmit VLAN tagged traffic over another VLAN.

The common use case for it is like this: suppose you are a service provider and you have a customer who wants to use your network infrastructure

to connect parts of their network to each other.

They use multiple VLANs in their network, so an ordinary rented VLAN is not an option.

With QinQ you can add a second tag to the customer traffic when it enters your network and remove that tag when it exits,

so there are no conflicts, and you don’t need to waste VLAN numbers.

The service tag is a VLAN tag the provider uses to carry client traffic through their network.

The client tag is a tag set by the customer.

Note that link MTU for the client VLAN interface is not adjusted automatically; you need to take care of it yourself

and either decrease the client interface MTU by at least 4 bytes or increase the parent MTU accordingly.

Standards-compliant QinQ is ava