networkctl - Man Page

• List existing links with their status: networkctl
• Show an overall network status: networkctl status
• Bring network devices up: sudo networkctl up interface1 interface2 ...
• Bring network devices down: sudo networkctl down interface1 interface2 ...
• Renew dynamic configurations (e.g. IP addresses received from a DHCP server): sudo networkctl renew interface1 interface2 ...
• Reload configuration files (.netdev and .network): sudo networkctl reload
• Reconfigure network interfaces (if you edited the config, you need to call networkctl reload first): sudo networkctl reconfigure interface1 interface2 ...

tldr.sh

networkctl [Options...] COMMAND [LINK...]

networkctl may be used to query or modify the state of the network links as seen by systemd-networkd​. Please refer to systemd-networkd.service(8) for an introduction to the basic concepts, functionality, and configuration syntax​.

The following commands are understood:

list [PATTERN​...]

Show a list of existing links and their status​. If one or more PATTERNs are specified, only links matching one of them are shown​. If no further arguments are specified shows all links, otherwise just the specified links​. Produces output similar to:

IDX LINK         TYPE     OPERATIONAL SETUP
  1 lo           loopback carrier     unmanaged
  2 eth0         ether    routable    configured
  3 virbr0       ether    no-carrier  unmanaged
  4 virbr0-nic   ether    off         unmanaged

4 links listed​.

The operational status is one of the following:

missing

The device is missing​.

Added in version 245​.

off

The device is powered down​.

Added in version 240​.

no-carrier

The device is powered up, but does not yet have a carrier​.

Added in version 240​.

dormant

The device has a carrier, but is not yet ready for normal traffic​.

Added in version 240​.

degraded-carrier

One of the bonding or bridge slave network interfaces is in off, no-carrier, or dormant state, and the master interface has no address​.

Added in version 242​.

carrier

The link has carrier, or for bond or bridge master, all bonding or bridge slave network interfaces are enslaved to the master​.

Added in version 240​.

degraded

The link has carrier and addresses valid on the local link configured​. For bond or bridge master this means that not all slave network interfaces have carrier but at least one does​.

Added in version 240​.

enslaved

The link has carrier and is enslaved to bond or bridge master network interface​.

Added in version 242​.

routable

The link has carrier and routable address configured​. For bond or bridge master it is not necessary for all slave network interfaces to have carrier, but at least one must​.

Added in version 240​.

The setup status is one of the following:

pending

systemd-udevd(8) is still processing the link, we do not yet know if we will manage it​.

Added in version 240​.

initialized

systemd-udevd(8) has processed the link, but we do not yet know if we will manage it​.

Added in version 251​.

configuring

Configuration for the link is being retrieved or the link is being configured​.

Added in version 240​.

configured

Link has been configured successfully​.

Added in version 240​.

unmanaged

systemd-networkd is not handling the link​.

Added in version 240​.

failed

systemd-networkd failed to configure the link​.

Added in version 240​.

linger

The link is gone, but has not yet been dropped by systemd-networkd​.

Added in version 240​.

Added in version 219​.

status [PATTERN​...]

Show information about the specified links: type, state, kernel module driver, hardware and IP address, configured DNS servers, etc​. If one or more PATTERNs are specified, only links matching one of them are shown​.

When no links are specified, an overall network status is shown​. Also see the option --all​.

Produces output similar to:

●        State: routable
  Online state: online
       Address: 10​.193​.76​.5 on eth0
                192​.168​.122​.1 on virbr0
                169​.254​.190​.105 on eth0
                fe80::5054:aa:bbbb:cccc on eth0
       Gateway: 10​.193​.11​.1 (CISCO SYSTEMS, INC​.) on eth0
           DNS: 8​.8​.8​.8
                8​.8​.4​.4

In the overall network status, the online state depends on the individual online state of all required links​. Managed links are required for online by default​. In this case, the online state is one of the following:

unknown

All links have unknown online status (i​.e​. there are no required links)​.

Added in version 249​.

offline

All required links are offline​.

Added in version 249​.

partial

Some, but not all, required links are online​.

Added in version 249​.

online

All required links are online​.

Added in version 249​.

Added in version 219​.

dhcp-lease INTERFACE [CODE[:FORMAT]] ​...

Show the DHCP message of the acquired lease (i​.e​. the received DHCPACK message)​. Takes an interface name and optional DHCP option codes​. If no option code is specified, both the DHCP message header and all options are shown​. If one or more option codes are specified, only the specified options are shown​.

When called with the --json= option, the entire DHCP message is shown in JSON format​. In that case, any specified option codes are ignored​.

By default, each option is displayed in a human-readable format, depending on the option​. For example, DNS server addresses are shown as a list of IP addresses (e​.g​. "192​.0​.2​.1"), and the lease time is shown as a human-readable duration (e​.g​. "8h")​.

Each option code may optionally be followed by a formatter, separated by a colon (e​.g​. "42:address")​. This can be useful if the default formatting is not appropriate​.

The following formatters are supported:

auto

Use the default formatting​.

hex

Show the raw bytes in hexadecimal, separated by colons​.

flag

Treat the option as having zero-length data and display "yes"​.

bool

Treat the option as a 1-byte boolean and display "yes" or "no"​.

uint8

Treat the option as a 1-byte unsigned integer​.

uint16

Treat the option as a 2-byte unsigned integer​.

time

Treat the option as a 4-byte time value in seconds and display it as a human-readable duration​.

string

Treat the option as a string​.

address

Treat the option as one or more IPv4 addresses and display them in human-readable form​.

Produces output similar to:

$ networkctl dhcp-lease eth0
Header:
              KEY VALUE
   Hardware Type: ETHER
Hardware Address: 41:42:43:31:32:33
  Client Address: 192​.0​.2​.123
  Server Address: 192​.0​.2​.1

Options:
CODE NAME               DATA
   1 subnet mask        255​.255​.255​.0
   3 router             192​.0​.2​.1
   6 domain name server 192​.0​.2​.1
  12 hostname           test-node
  15 domain name        lan
  28 broadcast address  192​.0​.2​.255
  42 NTP server         192​.0​.2​.11
                        192​.0​.2​.12
  51 lease time         1d
  53 message type       5
  54 server identifier  192​.0​.2​.1
  58 renewal time       11h 5min 38s
  59 rebinding time     20h 5min 38s
 119 domain search      hoge​.example​.com
                        foo​.example​.com

Added in version 261​.

lldp [PATTERN​...]

Show discovered LLDP (Link Layer Discovery Protocol) neighbors​. If one or more PATTERNs are specified only neighbors on those interfaces are shown​. Otherwise, shows discovered neighbors on all interfaces​. Note that for this feature to work, LLDP= must be turned on for the specific interface, see systemd.network(5) for details​.

Produces output similar to:

LINK    SYSTEM-NAME SYSTEM-DESCRIPTION CHASSIS-ID        PORT-ID PORT-DESCRIPTION CAPS
enp0s25 GS1900      -                  00:e0:4c:00:00:00 2       Port #2           ​.​.b​.​.​.​.​.​.​.​.

Capability Flags:
o - Other; p - Repeater;  b - Bridge; w - WLAN Access Point; r - Router;
t - Telephone; d - DOCSIS cable device; a - Station; c - Customer VLAN;
s - Service VLAN, m - Two-port MAC Relay (TPMR)

1 neighbor(s) listed​.

Added in version 219​.

label

Show numerical address labels that can be used for address selection​. This is the same information that ip-addrlabel(8) shows​. See RFC 3484​^[1] for a discussion of address labels​.

Produces output similar to:

Prefix/Prefixlen                          Label
        ::/0                                  1
    fc00::/7                                  5
    fec0::/10                                11
    2002::/16                                 2
    3ffe::/16                                12
 2001:10::/28                                 7
    2001::/32                                 6
::ffff:0​.0​.0​.0/96                             4
        ::/96                                 3
       ::1/128                                0

Added in version 234​.

delete DEVICE​...

Deletes virtual netdevs​. Takes interface name or index number​.

Added in version 243​.

up DEVICE​...

Bring devices up​. Takes interface name or index number​.

Added in version 246​.

down DEVICE​...

Bring devices down​. Takes interface name or index number​.

Added in version 246​.

renew DEVICE​...

Renew dynamic configurations e​.g​. addresses received from DHCP server​. Takes interface name or index number​.

Added in version 244​.

forcerenew DEVICE​...

Send a FORCERENEW message to all connected clients, triggering DHCP reconfiguration​. Takes interface name or index number​.

Added in version 246​.

reconfigure DEVICE​...

Reconfigure network interfaces​. Takes interface name or index number​. Note that this does not reload ​.netdev or ​.network corresponding to the specified interface​. So, if you edit config files, it is necessary to call networkctl reload first to apply new settings​.

Added in version 244​.

reload

Reload ​.netdev and ​.network files​.

If a new or modified ​.netdev file is found, then the corresponding netdev is created or updated, respectively​. Note, if the corresponding interface already exists, then some of new settings may not be applied​. E​.g​., VLAN ID cannot be changed after the interface was created, so changing [VLAN] Id= will not take effect if the matching VLAN interface already exists​. To apply such settings, the interfaces need to be removed manually before reload​. Also note that even if a ​.netdev file is removed, systemd-networkd(8) does not remove the existing netdev corresponding to the file​.

If a new, modified, or removed ​.network file is found, then all interfaces that matched the file are reconfigured​. This reconfiguration step can be skipped by passing --no-reconfigure, in which case only config files are reloaded from disk without reconfiguring any network interfaces​. Use networkctl reconfigure afterwards to selectively apply config changes per interface​.

Added in version 244​.

edit FILE|@DEVICE​...

Edit network configuration files, which include ​.network, ​.netdev, and ​.link files​. If no network config file matching the given name is found, a new one will be created under /etc/ or /run/, depending on whether --runtime is specified​. Specially, if the name is prefixed by "@", it will be treated as a network interface, and editing will be performed on the network config files associated with it​. Additionally, the interface name can be suffixed with ":network" (default), ":link", or ":netdev", in order to choose the type of network config to operate on​.

If --drop-in= is specified, edit the drop-in file instead of the main configuration file​. Unless --no-reload is specified, systemd-networkd(8) will be reloaded after the edit of the ​.network or ​.netdev files finishes​. The same applies for ​.link files and systemd-udevd(8)​. Note that the changed link settings are not automatically applied after reloading​. To achieve that, trigger uevents for the corresponding interface​. Refer to systemd.link(5) for more information​.

If --stdin is specified, the new content will be read from standard input​. In this mode, the old content of the file is discarded​.

Added in version 254​.

cat [FILE|@DEVICE​...]

Show network configuration files​. This command honors the "@" prefix in a similar way as edit, with support for an additional suffix ":all" for showing all types of configuration files associated with the interface at once​. When no argument is specified, networkd.conf(5) and its drop-in files will be shown​.

Added in version 254​.

mask FILE​...

Mask network configuration files, which include ​.network, ​.netdev, and ​.link files​. A symlink of the given name will be created under /etc/ or /run/, depending on whether --runtime is specified, that points to /dev/null​. If a non-empty config file with the specified name exists under the target directory or a directory with higher priority (e​.g​. --runtime is used while an existing config resides in /etc/), the operation is aborted​.

This command honors --no-reload in the same way as edit​.

Added in version 256​.

unmask FILE​...

Unmask network configuration files, i​.e​. reverting the effect of mask​. Note that this command operates regardless of the scope of the directory, i​.e​. --runtime is of no effect​.

This command honors --no-reload in the same way as edit and mask​.

Added in version 256​.

persistent-storage BOOL

Notify systemd-networkd.service(8) that the persistent storage for the service is ready​. This is called by systemd-networkd-persistent-storage​.service​. Usually, this command should not be called manually by users or administrators​.

Added in version 256​.

The following options are understood:

-a --all

Show all links with status​.

Added in version 219​.

-s --stats

Show link statistics with status​.

Added in version 243​.

-l,  --full

Do not ellipsize the output​.

Added in version 245​.

-n,  --lines=

When used with status, controls the number of journal lines to show, counting from the most recent ones​. Takes a positive integer argument​. Defaults to 10​.

Added in version 245​.

--drop-in=NAME

When used with edit, edit the drop-in file NAME instead of the main configuration file​.

Added in version 254​.

--no-reload

When used with edit, mask, or unmask, systemd-networkd.service(8) or systemd-udevd.service(8) will not be reloaded after the operation finishes​.

Added in version 254​.

--no-reconfigure

When used with reload, only reload config files from disk without reconfiguring any network interfaces​. This may be useful to avoid reconfiguring multiple interfaces simultaneously when multiple ​.network files are updated, or when an updated ​.network file is applied to multiple interfaces​. Use networkctl reconfigure afterwards to apply changes selectively per interface​.

Added in version 262​.

--runtime

When used with edit or mask, operate on the file under /run/ instead of /etc/​.

Added in version 256​.

--stdin

When used with edit, the contents of the file will be read from standard input and the editor will not be launched​. In this mode, the old contents of the file are automatically replaced​. This is useful to "edit" configuration from scripts, especially so that drop-in directories are created and populated in one go​.

Multiple drop-ins may be "edited" in this mode with --drop-in=, and the same contents will be written to all of them​. Otherwise, exactly one main configuration file is expected​.

Added in version 257​.

--no-ask-password

Do not query the user for authentication for privileged operations​.

--json=MODE

Shows output formatted as JSON​. Expects one of "short" (for the shortest possible output without any redundant whitespace or line breaks), "pretty" (for a pretty version of the same, with indentation and line breaks) or "off" (to turn off JSON output, the default)​.

-h,  --help

Print a short help text and exit​.

--version

Print a short version string and exit​.

--no-legend

Do not print the legend, i​.e​. column headers and the footer with hints​.

--no-pager

Do not pipe output into a pager​.

On success, 0 is returned, a non-zero failure code otherwise​.

systemd-networkd.service(8), systemd.network(5), systemd.netdev(5), ip(8)

1.

RFC 3484
https://tools.ietf.org/html/rfc3484

org.freedesktop.network1(5), systemd.directives(7), systemd.index(7), systemd.netdev(5), systemd.network(5), systemd-networkd.service(8), systemd-networkd-wait-online.service(8).