Imported Upstream version 220

[systemd.git] / man / systemd.netdev.5

'\" t
.TH "SYSTEMD\&.NETDEV" "5" "" "systemd 220" "systemd.network"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd.netdev \- Virtual Network Device configuration
.SH "SYNOPSIS"
.PP
\fInetdev\fR\&.netdev
.SH "DESCRIPTION"
.PP
Network setup is performed by
\fBsystemd-networkd\fR(8)\&.
.PP
Virtual Network Device files must have the extension
\&.netdev; other extensions are ignored\&. Virtual network devices are created as soon as networkd is started\&. If a netdev with the specified name already exists, networkd will use that as\-is rather than create its own\&. Note that the settings of the pre\-existing netdev will not be changed by networkd\&.
.PP
The
\&.netdev
files are read from the files located in the system network directory
/usr/lib/systemd/network, the volatile runtime network directory
/run/systemd/network
and the local administration network directory
/etc/systemd/network\&. All configuration files are collectively sorted and processed in lexical order, regardless of the directories in which they live\&. However, files with identical filenames replace each other\&. Files in
/etc
have the highest priority, files in
/run
take precedence over files with the same name in
/usr/lib\&. This can be used to override a system\-supplied configuration file with a local file if needed; a symlink in
/etc
with the same name as a configuration file in
/usr/lib, pointing to
/dev/null, disables the configuration file entirely\&.
.SH "SUPPORTED NETDEV KINDS"
.PP
The following kinds of virtual network devices may be configured in
\&.netdev
files:
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table\ \&1.\ \&Supported kinds of virtual network devices
.TS
allbox tab(:);
lB lB.
T{
Kind
T}:T{
Description
T}
.T&
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l.
T{
\fIbond\fR
T}:T{
A bond device is an aggregation of all its slave devices\&. See \m[blue]\fBLinux Ethernet Bonding Driver HOWTO\fR\m[]\&\s-2\u[1]\d\s+2 for details\&.Local configuration
T}
T{
\fIbridge\fR
T}:T{
A bridge device is a software switch, each of its slave devices and the bridge itself are ports of the switch\&.
T}
T{
\fIdummy\fR
T}:T{
A dummy device drops all packets sent to it\&.
T}
T{
\fIgre\fR
T}:T{
A Level 3 GRE tunnel over IPv4\&. See \m[blue]\fBRFC 2784\fR\m[]\&\s-2\u[2]\d\s+2 for details\&.
T}
T{
\fIgretap\fR
T}:T{
A Level 2 GRE tunnel over IPv4\&.
T}
T{
\fIip6gre\fR
T}:T{
A Level 3 GRE tunnel over IPv6\&.
T}
T{
\fIip6tnl\fR
T}:T{
An IPv4 or IPv6 tunnel over IPv6
T}
T{
\fIip6gretap\fR
T}:T{
An Level 2 GRE tunnel over IPv6\&.
T}
T{
\fIipip\fR
T}:T{
An IPv4 over IPv4 tunnel\&.
T}
T{
\fIipvlan\fR
T}:T{
An ipvlan device is a stacked device which receives packets from its underlying device based on IP address filtering\&.
T}
T{
\fImacvlan\fR
T}:T{
A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering\&.
T}
T{
\fIsit\fR
T}:T{
An IPv6 over IPv4 tunnel\&.
T}
T{
\fItap\fR
T}:T{
A persistent Level 2 tunnel between a network device and a device node\&.
T}
T{
\fItun\fR
T}:T{
A persistent Level 3 tunnel between a network device and a device node\&.
T}
T{
\fIveth\fR
T}:T{
An ethernet tunnel between a pair of network devices\&.
T}
T{
\fIvlan\fR
T}:T{
A VLAN is a stacked device which receives packets from its underlying device based on VLAN tagging\&. See \m[blue]\fBIEEE 802\&.1Q\fR\m[]\&\s-2\u[3]\d\s+2 for details\&.
T}
T{
\fIvti\fR
T}:T{
An IPv4 over IPSec tunnel\&.
T}
T{
\fIvti6\fR
T}:T{
An IPv6 over IPSec tunnel\&.
T}
T{
\fIvxlan\fR
T}:T{
A virtual extensible LAN (vxlan), for connecting Cloud computing deployments\&.
T}
.TE
.sp 1
.SH "[MATCH] SECTION OPTIONS"
.PP
A virtual network device is only created if the
"[Match]"
section matches the current environment, or if the section is empty\&. The following keys are accepted:
.PP
\fIHost=\fR
.RS 4
Matches against the hostname or machine ID of the host\&. See
"ConditionHost="
in
\fBsystemd.unit\fR(5)
for details\&.
.RE
.PP
\fIVirtualization=\fR
.RS 4
Checks whether the system is executed in a virtualized environment and optionally test whether it is a specific implementation\&. See
"ConditionVirtualization="
in
\fBsystemd.unit\fR(5)
for details\&.
.RE
.PP
\fIKernelCommandLine=\fR
.RS 4
Checks whether a specific kernel command line option is set (or if prefixed with the exclamation mark unset)\&. See
"ConditionKernelCommandLine="
in
\fBsystemd.unit\fR(5)
for details\&.
.RE
.PP
\fIArchitecture=\fR
.RS 4
Checks whether the system is running on a specific architecture\&. See
"ConditionArchitecture="
in
\fBsystemd.unit\fR(5)
for details\&.
.RE
.SH "[NETDEV] SECTION OPTIONS"
.PP
The
"[NetDev]"
section accepts the following keys:
.PP
\fIDescription=\fR
.RS 4
A free\-form description of the netdev\&.
.RE
.PP
\fIName=\fR
.RS 4
The interface name used when creating the netdev\&. This option is compulsory\&.
.RE
.PP
\fIKind=\fR
.RS 4
The netdev kind\&. This option is compulsory\&. See the
"Supported netdev kinds"
section for the valid keys\&.
.RE
.PP
\fIMTUBytes=\fR
.RS 4
The maximum transmission unit in bytes to set for the device\&. The usual suffixes K, M, G, are supported and are understood to the base of 1024\&. This key is not currently supported for
"tun"
or
"tap"
devices\&.
.RE
.PP
\fIMACAddress=\fR
.RS 4
The MAC address to use for the device\&. If none is given, one is generated based on the interface name and the
\fBmachine-id\fR(5)\&. This key is not currently supported for
"tun"
or
"tap"
devices\&.
.RE
.SH "[VLAN] SECTION OPTIONS"
.PP
The
"[VLAN]"
section only applies for netdevs of kind
"vlan", and accepts the following key:
.PP
\fIId=\fR
.RS 4
The VLAN ID to use\&. An integer in the range 0\(en4094\&. This option is compulsory\&.
.RE
.SH "[MACVLAN] SECTION OPTIONS"
.PP
The
"[MACVLAN]"
section only applies for netdevs of kind
"macvlan", and accepts the following key:
.PP
\fIMode=\fR
.RS 4
The MACVLAN mode to use\&. The supported options are
"private",
"vepa",
"bridge", and
"passthru"\&.
.RE
.SH "[IPVLAN] SECTION OPTIONS"
.PP
The
"[IPVLAN]"
section only applies for netdevs of kind
"ipvlan", and accepts the following key:
.PP
\fIMode=\fR
.RS 4
The IPVLAN mode to use\&. The supported options are
"L2"
and
"L3"\&.
.RE
.SH "[VXLAN] SECTION OPTIONS"
.PP
The
"[VXLAN]"
section only applies for netdevs of kind
"vxlan", and accepts the following keys:
.PP
\fIId=\fR
.RS 4
The VXLAN ID to use\&.
.RE
.PP
\fIGroup=\fR
.RS 4
An assigned multicast group IP address\&.
.RE
.PP
\fITOS=\fR
.RS 4
The Type Of Service byte value for a vxlan interface\&.
.RE
.PP
\fITTL=\fR
.RS 4
A fixed Time To Live N on Virtual eXtensible Local Area Network packets\&. N is a number in the range 1\-255\&. 0 is a special value meaning that packets inherit the TTL value\&.
.RE
.PP
\fIMacLearning=\fR
.RS 4
A boolean\&. When true, enables dynamic MAC learning to discover remote MAC addresses\&.
.RE
.PP
\fIFDBAgeingSec=\fR
.RS 4
The lifetime of Forwarding Database entry learnt by the kernel in seconds\&.
.RE
.PP
\fIARPProxy=\fR
.RS 4
A boolean\&. When true, enables ARP proxy\&.
.RE
.PP
\fIL2MissNotification=\fR
.RS 4
A boolean\&. When true, enables netlink LLADDR miss notifications\&.
.RE
.PP
\fIL3MissNotification=\fR
.RS 4
A boolean\&. When true, enables netlink IP ADDR miss notifications\&.
.RE
.PP
\fIRouteShortCircuit=\fR
.RS 4
A boolean\&. When true route short circuit is turned on\&.
.RE
.PP
\fIUDPCheckSum=\fR
.RS 4
A boolean\&. When true transmitting UDP checksums when doing VXLAN/IPv4 is turned on\&.
.RE
.PP
\fIUDP6ZeroChecksumTx=\fR
.RS 4
A boolean\&. When true sending zero checksums in VXLAN/IPv6 is turned on\&.
.RE
.PP
\fIUDP6ZeroCheckSumRx=\fR
.RS 4
A boolean\&. When true receiving zero checksums in VXLAN/IPv6 is turned on\&.
.RE
.SH "[TUNNEL] SECTION OPTIONS"
.PP
The
"[Tunnel]"
section only applies for netdevs of kind
"ipip",
"sit",
"gre",
"gretap",
"ip6gre",
"ip6gretap",
"vti",
"vti6", and
"ip6tnl"
and accepts the following keys:
.PP
\fILocal=\fR
.RS 4
A static local address for tunneled packets\&. It must be an address on another interface of this host\&.
.RE
.PP
\fIRemote=\fR
.RS 4
The remote endpoint of the tunnel\&.
.RE
.PP
\fITOS=\fR
.RS 4
The Type Of Service byte value for a tunnel interface\&. For details about the TOS see the
\m[blue]\fBType of Service in the Internet Protocol Suite\fR\m[]\&\s-2\u[4]\d\s+2
document\&.
.RE
.PP
\fITTL=\fR
.RS 4
A fixed Time To Live N on tunneled packets\&. N is a number in the range 1\-255\&. 0 is a special value meaning that packets inherit the TTL value\&. The default value for IPv4 tunnels is: inherit\&. The default value for IPv6 tunnels is: 64\&.
.RE
.PP
\fIDiscoverPathMTU=\fR
.RS 4
A boolean\&. When true, enables Path MTU Discovery on the tunnel\&.
.RE
.PP
\fIMode=\fR
.RS 4
An
"ip6tnl"
tunnels can have three modes
"ip6ip6"
for IPv6 over IPv6,
"ipip6"
for IPv4 over IPv6 or
"any"
for either\&.
.RE
.SH "[PEER] SECTION OPTIONS"
.PP
The
"[Peer]"
section only applies for netdevs of kind
"veth"
and accepts the following key:
.PP
\fIName=\fR
.RS 4
The interface name used when creating the netdev\&. This option is compulsory\&.
.RE
.PP
\fIMACAddress=\fR
.RS 4
The peer MACAddress, if not set it is generated in the same way as the MAC address of the main interface\&.
.RE
.SH "[TUN] SECTION OPTIONS"
.PP
The
"[Tun]"
section only applies for netdevs of kind
"tun", and accepts the following keys:
.PP
\fIOneQueue=\fR
.RS 4
Takes a boolean argument\&. Configures whether all packets are queued at the device (enabled), or a fixed number of packets are queued at the device and the rest at the
"qdisc"\&. Defaults to
"no"\&.
.RE
.PP
\fIMultiQueue=\fR
.RS 4
Takes a boolean argument\&. Configures whether to use multiple file descriptors (queues) to parallelize packets sending and receiving\&. Defaults to
"no"\&.
.RE
.PP
\fIPacketInfo=\fR
.RS 4
Takes a boolean argument\&. Configures whether packets should be prepended with four extra bytes (two flag bytes and two protocol bytes)\&. If disabled it indicates that the packets will be pure IP packets\&. Defaults to
"no"\&.
.RE
.PP
\fIUser=\fR
.RS 4
User to grant access to the
/dev/net/tun
device\&.
.RE
.PP
\fIGroup=\fR
.RS 4
Group to grant access to the
/dev/net/tun
device\&.
.RE
.SH "[TAP] SECTION OPTIONS"
.PP
The
"[Tap]"
section only applies for netdevs of kind
"tap", and accepts the same keys as the
"[Tun]"
section\&.
.SH "[BOND] SECTION OPTIONS"
.PP
The
"[Bond]"
section accepts the following key:
.PP
\fIMode=\fR
.RS 4
Specifies one of the bonding policies\&. The default is
"balance\-rr"
(round robin)\&. Possible values are
"balance\-rr",
"active\-backup",
"balance\-xor",
"broadcast",
"802\&.3ad",
"balance\-tlb", and
"balance\-alb"\&.
.RE
.PP
\fITransmitHashPolicy=\fR
.RS 4
Selects the transmit hash policy to use for slave selection in balance\-xor, 802\&.3ad, and tlb modes\&. Possible values are
"layer2",
"layer3+4",
"layer2+3",
"encap2+3",
"802\&.3ad", and
"encap3+4"\&.
.RE
.PP
\fILACPTransmitRate=\fR
.RS 4
Specifies the rate with which link partner transmits Link Aggregation Control Protocol Data Unit packets in 802\&.3ad mode\&. Possible values are
"slow", which requests partner to transmit LACPDUs every 30 seconds, and
"fast", which requests partner to transmit LACPDUs every second\&. The default value is
"slow"\&.
.RE
.PP
\fIMIIMonitorSec=\fR
.RS 4
Specifies the frequency that Media Independent Interface link monitoring will occur\&. A value of zero disables MII link monitoring\&. This values is rounded down to the nearest millisecond\&. The default value is 0\&.
.RE
.PP
\fIUpDelaySec=\fR
.RS 4
Specifies the delay before a link is enabled after a link up status has been detected\&. This value is rounded down to a multiple of MIIMonitorSec\&. The default value is 0\&.
.RE
.PP
\fIDownDelaySec=\fR
.RS 4
Specifies the delay before a link is disabled after a link down status has been detected\&. This value is rounded down to a multiple of MIIMonitorSec\&. The default value is 0\&.
.RE
.PP
\fILearnPacketIntervalSec=\fR
.RS 4
Specifies the number of seconds between instances where the bonding driver sends learning packets to each slaves peer switch\&. The valid range is 1 \- 0x7fffffff; the default value is 1\&. This Option has effect only in balance\-tlb and balance\-alb modes\&.
.RE
.PP
\fIAdSelect=\fR
.RS 4
Specifies the 802\&.3ad aggregation selection logic to use\&. Possible values are
"stable",
"bandwidth",
"count"
.RE
.PP
\fIFailOverMACPolicy=\fR
.RS 4
Specifies whether active\-backup mode should set all slaves to the same MAC address at enslavement or, when enabled, perform special handling of the bond\*(Aqs MAC address in accordance with the selected policy\&. The default policy is none\&. Possible values are
"none",
"active",
"follow"
.RE
.PP
\fIARPValidate=\fR
.RS 4
Specifies whether or not ARP probes and replies should be validated in any mode that supports ARP monitoring, or whether non\-ARP traffic should be filtered (disregarded) for link monitoring purposes\&. Possible values are
"none",
"active",
"backup",
"all"
.RE
.PP
\fIARPIntervalSec=\fR
.RS 4
Specifies the ARP link monitoring frequency in milliseconds\&. A value of 0 disables ARP monitoring\&. The default value is 0\&.
.RE
.PP
\fIARPIPTargets=\fR
.RS 4
Specifies the IP addresses to use as ARP monitoring peers when ARPIntervalSec is greater than 0\&. These are the targets of the ARP request sent to determine the health of the link to the targets\&. Specify these values in ipv4 dotted decimal format\&. At least one IP address must be given for ARP monitoring to function\&. The maximum number of targets that can be specified is 16\&. The default value is no IP addresses\&.
.RE
.PP
\fIARPAllTargets=\fR
.RS 4
Specifies the quantity of ARPIPTargets that must be reachable in order for the ARP monitor to consider a slave as being up\&. This option affects only active\-backup mode for slaves with ARPValidate enabled\&. Possible values are
"any",
"all"
.RE
.PP
\fIPrimaryReselectPolicy=\fR
.RS 4
Specifies the reselection policy for the primary slave\&. This affects how the primary slave is chosen to become the active slave when failure of the active slave or recovery of the primary slave occurs\&. This option is designed to prevent flip\-flopping between the primary slave and other slaves\&. Possible values are
"always",
"better",
"failure"
.RE
.PP
\fIResendIGMP=\fR
.RS 4
Specifies the number of IGMP membership reports to be issued after a failover event\&. One membership report is issued immediately after the failover, subsequent packets are sent in each 200ms interval\&. The valid range is (0 \- 255)\&. Defaults to 1\&. A value of 0 prevents the IGMP membership report from being issued in response to the failover event\&.
.RE
.PP
\fIPacketsPerSlave=\fR
.RS 4
Specify the number of packets to transmit through a slave before moving to the next one\&. When set to 0 then a slave is chosen at random\&.The valid range is (0 \- 65535)\&. Defaults to 1\&. This option has effect only in balance\-rr mode\&.
.RE
.PP
\fIGratuitousARP=\fR
.RS 4
Specify the number of peer notifications (gratuitous ARPs and unsolicited IPv6 Neighbor Advertisements) to be issued after a failover event\&. As soon as the link is up on the new slave a peer notification is sent on the bonding device and each VLAN sub\-device\&. This is repeated at each link monitor interval (ARPIntervalSec or MIIMonitorSec, whichever is active) if the number is greater than 1\&. The valid range is (0 \- 255)\&. Default value is 1\&. These options affect only the active\-backup mode\&.
.RE
.PP
\fIAllSlavesActive=\fR
.RS 4
A boolean\&. Specifies that duplicate frames (received on inactive ports) should be dropped false or delivered true\&. Normally, bonding will drop duplicate frames (received on inactive ports), which is desirable for most users\&. But there are some times it is nice to allow duplicate frames to be delivered\&. The default value is false (drop duplicate frames received on inactive ports)\&.
.RE
.PP
\fIMinLinks=\fR
.RS 4
Specifies the minimum number of links that must be active before asserting carrier\&. The default value is 0\&.
.RE
.PP
For more detail information see
\m[blue]\fBLinux Ethernet Bonding Driver HOWTO\fR\m[]\&\s-2\u[1]\d\s+2
.SH "EXAMPLE"
.PP
\fBExample\ \&1.\ \&/etc/systemd/network/bridge.netdev\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[NetDev]
Name=bridge0
Kind=bridge
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&2.\ \&/etc/systemd/network/vlan1.netdev\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[Match]
Virtualization=no

[NetDev]
Name=vlan1
Kind=vlan

[VLAN]
Id=1
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&3.\ \&/etc/systemd/network/ipip.netdev\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[NetDev]
Name=ipip\-tun
Kind=ipip
MTUBytes=1480

[Tunnel]
Local=192\&.168\&.223\&.238
Remote=192\&.169\&.224\&.239
TTL=64
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&4.\ \&/etc/systemd/network/tap.netdev\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[NetDev]
Name=tap\-test
Kind=tap

[Tap]
MultiQueue=true
PacketInfo=true
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&5.\ \&/etc/systemd/network/sit.netdev\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[NetDev]
Name=sit\-tun
Kind=sit
MTUBytes=1480

[Tunnel]
Local=10\&.65\&.223\&.238
Remote=10\&.65\&.223\&.239
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&6.\ \&/etc/systemd/network/gre.netdev\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[NetDev]
Name=gre\-tun
Kind=gre
MTUBytes=1480

[Tunnel]
Local=10\&.65\&.223\&.238
Remote=10\&.65\&.223\&.239
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&7.\ \&/etc/systemd/network/vti.netdev\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[NetDev]
Name=vti\-tun
Kind=vti
MTUBytes=1480

[Tunnel]
Local=10\&.65\&.223\&.238
Remote=10\&.65\&.223\&.239
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&8.\ \&/etc/systemd/network/veth.netdev\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[NetDev]
Name=veth\-test
Kind=veth

[Peer]
Name=veth\-peer
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&9.\ \&/etc/systemd/network/dummy.netdev\fR
.sp
.if n \{\
.RS 4
.\}
.nf
[NetDev]
Name=dummy\-test
Kind=dummy
MACAddress=12:34:56:78:9a:bc
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsystemd-networkd\fR(8),
\fBsystemd.link\fR(5),
\fBsystemd.network\fR(5)
.SH "NOTES"
.IP " 1." 4
Linux Ethernet Bonding Driver HOWTO
.RS 4
\%https://www.kernel.org/doc/Documentation/networking/bonding.txt
.RE
.IP " 2." 4
RFC 2784
.RS 4
\%https://tools.ietf.org/html/rfc2784
.RE
.IP " 3." 4
IEEE 802.1Q
.RS 4
\%http://www.ieee802.org/1/pages/802.1Q.html
.RE
.IP " 4." 4
Type of Service in the Internet Protocol Suite
.RS 4
\%http://tools.ietf.org/html/rfc1349
.RE