wicked(8)

📦
version 0.6.80 · 2 versions
, in opensuse-leap 16.0

💅 wicked(8) — Network configuration 💅

hiii bestie 🫶 so this is wicked(8), the manpage for wicked, your friendly neighborhood network management utility. It lives in the Network configuration section of the manual, and honestly? it's giving main character energy. Let's get into it. ✨

🌸 NAME 🌸

wicked — network management utility. that's it, that's the whole name section, we love a concise queen 👑

🦋 SYNOPSIS 🦋

okay so here's every single way you can call her, copy-pasted exactly, don't come for me:

wicked [global-options] ifup [options] interface
wicked [global-options] ifdown [options] interface
wicked [global-options] ifreload [options] interface
wicked [global-options] ifstatus [options] interface
wicked [global-options] ifcheck [options] interface
wicked [global-options] show-config [options] [interface]
wicked [global-options] convert [options] [file ... ]
wicked [global-options] show-xml [options] [interface]
wicked [global-options] xpath [options] format...
wicked [global-options] getnames [options] device...
wicked [global-options] duid [options] <action> ...
wicked [global-options] iaid [options] <action> ...
wicked [global-options] arp <action> [options] ...
wicked [global-options] ethtool [interface] --action [arguments] ...

like yes, that's a lot of subcommands, but she contains multitudes 💜

✨ DESCRIPTION ✨

so wicked gives you access to the wicked network management service from the command line — that's the whole vibe. You can use it to peep the current state of your network devices, to bring interfaces up or down, or to check their operational status. iconic 🔥

conceptually, the wicked network management system deals with two very distinct classes of information:

  1. the set of configuration files stored somewhere in the system
  2. the current configuration state maintained by the kernel and closely related system daemons like pppd(8) or openvpn(8)

literally two different worlds, bestie, don't mix them up.

currently, wicked only supports sysconfig style ifcfg- files. Data present in these config files is converted to an internal XML representation. so it's a glow-up, basically 🦋

the server only knows about the latter — it does not parse any configuration files, and it does not maintain any state besides what is actually in effect. On the other hand, the client never probes the kernel directly to obtain the current system state. The client's job is to parse the configuration file(s) handed to it by the user, process and convert them to policies, and hand them off to wickedd-nanny. Then wickedd-nanny performs device configuration when policy conditions have been met. teamwork, makes the dream work 🤝

The client, nanny and server processes communicate with each other over DBus. periodt. 💅

🎀 OPTIONS 🎀

wicked supports a set of options common to all subcommands. These options must precede the subcommand, like this:

# wicked --dry-run ifup eth0

(yeah, order matters, she's particular about that 🙈)

currently, wicked supports the following list of options:

  • --config filename — By default, the daemon reads its configuration from /usr/etc/wicked/common.xml. The --config option lets you specify a different configuration file. custom vibes only 🎀
  • --log-level level — Set log level to one of <error|warning|notice|info|debug>.
  • --log-target target — Set log target to one of <stderr|syslog>, optionally followed by a colon and target specific details.
    • stderr[:options] with the following options:
      • pid — include program pid in each message
    • syslog[:facility[:options]] with following facilities:
      • user, daemon, local0 .. local7
    • and options:
      • perror — log the message to stderr as well
  • --debug facility — Enable debugging for facility. The list of available facilities can be obtained using "--debug help". (she tells you herself, we stan a self-aware queen 👑)
  • --root-directory pathname — Specify an alternative root directory from where to load files. This applies to the client's configuration file as well as any interface configuration files. 🗂️
  • --dry-run — skips all calls to wickedd that would modify the current system settings, instead displaying the command that would be sent, along with an XML representation of the XML. Helpful for getting a feel for how the utility and the protocol work, and for debugging.
⚠️ okay important, bestie: This does not work at the moment. 😭 so like, it's a vibe in theory only. don't rely on it.
  • --systemd — Forces wicked to use the syslog target for logging.
  • --transient — Enables more detailed interface return codes.

💖 ifup — bring up one or more interfaces 💖

to bring up interfaces, use wicked ifup. This command supports a number of different modes of operations. In its simplest form, you just give it the name of an interface, and it will bring up the interface using the stored system configuration:

# wicked ifup eth0

This invocation makes wicked:

  1. Run the ibft extension to get all firmware type configurations
  2. Read all sysconfig network configuration files from /etc/sysconfig/network
  3. Read all XML network configuration files from /usr/etc/wicked/ifconfig

For each interface to be configured, wicked will generate a policy and pass this to wickedd-nanny. wickedd-nanny will then kick off applying the configuration to wickedd. wickedd then will perform the necessary steps to configure the interface. These steps include assigning a static address, and starting DHCP and similar address configuration protocols as required. she's doing the most, honestly 💅

instead of an interface name, you can also use the special names all or boot, which will tell wicked to bring up all interfaces. The difference between all and boot is in behavior: when using the latter, wicked will ignore any interfaces that are not configured as boot time interfaces. lowkey a subtle distinction but it matters 👀

it is also possible to bring up interfaces that do not have a configuration stored in the system; using the --ifconfig option you can provide a configuration by specifying a path prefixed by a supported schema. Again, you have to specify the name of the interface to bring up, or all to bring up all interfaces described in the file:

# wicked ifup --ifconfig compat:/etc/sysconfig/network all
# wicked ifup --ifconfig firmware:ibft:ethernet0 all

note that wicked attempts to bring up interfaces in a "reasonable order": for virtual interfaces like VLANs, bridges or bonds, it will always make sure that all subordinate devices are in the required state before bringing up the virtual device itself. she's organized like that 🧚

The ifup command supports the following options:

  • --ifconfig pathname — Specify an alternative source of network configuration, instead of obtaining the system's interface configuration.
    • If the file name starts with the string compat:, wicked is instructed to load the interface configuration from files in the default "ifcfg" syntax, as described by the ifcfg(5) manual page. The string following the compat: prefix is interpreted as a directory name where wicked will scan for files with names matching ifcfg-* and related files, like routes and ifroute-*.
    • The special name firmware: can be used to obtain the interface definition(s) from firmware services like iBFT.
  • --mode identifier — This can be used in conjunction with the special interface name all, in order to restrict the set of interfaces that will be brought up. If this option is given, only those interface configurations are considered that have a control <mode> element containing the given identifier.
    • If the interface does not specify a <mode> element in its control section, then it defaults to boot.
  • --boot-stage identifier — This can be used in conjunction with the special interface name all, in order to restrict the set of interfaces that will be brought up. If this option is given, only those interface configurations are considered that have a <boot-stage> element containing the given identifier.
    • If the interface does not specify a <boot-stage> element in its control section, then it defaults to default.
  • --skip-origin configsource — This can be used to ignore interfaces that have already been configured. For instance, an interface that has been configured based on a firmware configuration (see option --ifconfig above) will be marked as having a configuration origin of firmware. When bringing up the remaining network interfaces, it is a good idea to not touch these. This can be achieved by running wicked with the option --skip-origin firmware. 💡
  • --skip-active — Ignore all interfaces that have already been brought up.
  • --timeout seconds — The default timeout for bringing up a network device is 5 seconds. If the interface fails to come up within this time, wicked will fail the device and and exit with an error code. All interfaces depending on the failed interface will fail as well.

--persistent — Set interface into persistent mode (no regular ifdown allowed).

💀 heads up: Failed interfaces are left in an undefined state. that's it, that's the warning, no cap.

🍓 ifdown — bring down one or more interfaces 🍓

This command does the reverse of ifup. Again, you can give it either a specific interface name, or use the special name all to bring down all devices. When bringing down several interfaces, the utility tries to do this in a suitable order. reverse glow-down, still organized ✨

The ifdown command supports the following options:

  • --force state — Forcefully put interface into a specified state. This option is applicable whether the interface is persistent or not. State can be one of:
    • device-down
    • device-exists
    • device-setup
    • protocols-up
    • firewall-up
    • device-up
    • link-up
    • link-authenticated
    • lldp-up
  • --delete — Attempts to delete an interface. This is equivalent to --force device-down.
  • --no-delete — Brings the specified interface to device-exists state. In other words, the interface is down, but not deleted. Persistent interfaces are ignored.
  • --release — Overrides active configuration to force a lease release.
  • --no-release — Overrides active configuration to skip a lease release.
  • --timeout seconds — The default timeout for bringing down a network device is 5 seconds. If the interface fails to shut down within this time, wicked will fail the device and and exit with an error code. All interfaces that are used by the failed interface will fail as well.
😭 same warning as before, bestie: Failed interfaces are left in an undefined state.

ifreload — checks whether a configuration has changed, and applies accordingly 💅

okay so this one is genuinely the main character of config reloading. wicked ifreload automatically re-applies the changed sections of a configuration for the interfaces you name. Basically it does the necessary ifdown/ifup dance for you and attempts to apply detected differences. If you wanna go deeper, the use cases are right below bestie 🫶

# wicked ifreload eth0
# wicked ifreload all

There are 4 potential ifreload use cases, and ngl they're lowkey elegant:

  1. Configuration unchanged — ifreload does not touch specified interfaces. it literally does not perceive you ✨
  2. Configuration changed — performs ifdown followed by ifup with the new configuration on the specified interfaces.
  3. Configuration deleted — performs ifdown in order to shut down the specified interfaces. it's giving closure 💀
  4. New configuration added — performs regular ifup on specified interfaces.

This behavior can be fine-tuned using the following options:

  • --ifconfig pathname — Specify an alternative source of network configuration, instead of obtaining the system's interface configuration. <br>If the file name starts with the string compat:, wicked is instructed to load the interface configuration from files in the default "ifcfg" syntax, as described by the ifcfg(5) manual page. The string following the compat: prefix is interpreted as a path name. If this path name refers to a directory, wicked will scan it for files with names matching ifcfg-*. If the path name refers to a regular file, it will parse this file, assuming it is an ifcfg file. <br>The special name firmware: can be used to obtain the interface definition(s) from firmware services like iBFT. 🧚
  • --persistent — Set interface into persistent mode (no regular ifdown allowed) in ifup run. she's ✨committed✨
  • --release — Overrides active configuration to force a lease release for interfaces being shut down.
  • --no-release — Overrides active configuration to skip a lease release for interfaces being shut down.

ifstatus/show — displays detailed interface information 🔍

wanna display/diagnose the system wide interface network configuration? that's wicked ifstatus/show bestie. heads up tho: the ifstatus command additionally reads system wide configuration and so is usable by root only. The show variant, on the other hand, deals with runtime configurations of existing interfaces only — so it can be used by users. iykyk 👑

# wicked ifstatus eth0
# wicked ifstatus all

Example output for loopback interface:

lo              up
      link:     #1, state up
      type:     loopback
      cstate:   network-up
      config:   compat:/etc/sysconfig/network/ifcfg-lo
      leases:   ipv4 static granted
      addr:     ipv4 127.0.0.1/8
      addr:     ipv6 ::1/128

This behavior can be fine-tuned using the following options:

  • --quiet — Used to obtain status return codes only. No information is output, so can be used for scripting. silent but deadly fr 🤫
  • --brief — Displays device status for specified interfaces.
  • --ifconfig filename — Note that this is ifstatus specific (ie. root only). Used to alter the source of the specified interface configurations.

ifcheck — inspects particular interface details 🕵️‍♀️

need to inspect details like interface presence, change in interface configuration, internal interface state (cstate) and persistent mode for specified interfaces? wicked ifcheck said say less. This command can be particularly helpful to script writers — she's the bestie of anyone writing automation 💖

# wicked ifcheck --missed eth0
# wicked ifcheck --missed --changed all
  • --ifconfig pathname — Specify an alternative source of network configuration, instead of obtaining the system's interface configuration. <br>If the file name starts with the string compat:, wicked is instructed to load the interface configuration from files in the old-style "ifcfg" syntax, as described by the ifcfg(5) manual page. The string following the compat: prefix is interpreted as a path name. If this path name refers to a directory, wicked will scan it for files with names matching ifcfg-*. If the path name refers to a regular file, it will parse this file, assuming it is an ifcfg file. <br>The special name firmware: can be used to obtain the interface definition(s) from firmware services like iBFT.
  • --quiet — Used to obtain status return codes only. No information is output, so can be used for scripting.
  • --missed — Check if the interface is missed. where did she GO 😭
  • --changed — Check if the interface's configuration is changed.
  • --state state-name — Check if the interface is in the given state. Possible states:
none
device-down
device-exists
device-setup
protocols-up
firewall-up
device-up
link-up
link-authenticated
lldp-up
network-up
  • --persistent — Check if the interface is in persistent mode.

show-config — reads, converts and displays all available configuration files 🌈

(yes the original manpage typo'd that, we're not gonna talk about it 💀)

To display all available network configuration files in the internal XML format for specified sources (default is all sources), use wicked show-config. To specify the source, use one of the following:

firmware:
compat:
# wicked show-config
# wicked show-config compat:

This behavior can be fine-tuned using the following options:

  • --raw — Filter from output all config meta-data. just the vibes, no commentary ✨
  • --output path — By default, wicked will write the XML document to its standard output. Using this option, you can instruct it to write to a different file instead. If the specified path is a directory, the XML document will be split into separate files, one for each interface.

convert — convert configuration files to internal XML 🔄

Wicked currently supports sysconfig ifcfg files, and internally converts them to XML. When invoked without arguments, this command will dump to stdout the XML document representation of all of your ifcfg files. it's giving translator era 🎀

This behavior can be fine-tuned using the following options:

  • --raw — Filter from output all config meta-data.
  • --output path — By default, wicked will write the XML document to its standard output. Using this option, you can instruct it to write to a different file instead. If the specified path is a directory, the XML document will be split into separate files, one for each interface.
Note that convert is a variant of show-config, and is equivalent to:
show-config compat:

getnames — obtain different names for an interface 🏷️

wicked can identify network devices via a number of different mechanisms, in addition to the usual interface name. For instance, you can identify an Ethernet device using the permanent MAC address programmed into the card's EEPROM, or via its PCI topology. she contains multitudes 💅

For the convenience of management applications, wicked provides a function to retrieve all possible names for an interface names as XML. For each device specified on the command line, a <names> is printed, with zero or more <name> elements.

The getnames command supports the following options:

  • --modem — Instead of querying network devices, interpret the given interface name as a modem device. 📞

💖 duid - set, get, create a new DUID 💖

okay bestie, this command is literally your DHCP identity station 💅 It lets you show, get, set, or create a new DHCP Unique Identifier (DUID) and stash it in wicked's persistent duid file. A DUID is used to identify DHCP clients and servers (hosts), it's unique across them, and it should not change over time if at all possible. For the complete lore, please refer to https://tools.ietf.org/html/rfc3315#section-9 — yes, RFC 3315 section 9, no cap ✨

The set, get, and create commands also let you store the duid per-device in the persistent duid file using the --scope <ifname> parameter, which is used when configured to appear with multiple identities to the DHCP servers. See the dhcp6 default-duid and dhcp4 create-cid node descriptions in the wicked-config(5) manual page. iykyk 🫶

  • create <type> [--scope <ifname>] [--update] — constructs a DUID of a specific type, and when you request it with the --update option, it also stores it in wicked's persistent duid file.
  • DUID type 1, Link-layer address plus time:
# wicked duid create llt [ [ifname] | <hwtype> <hwaddr> ]

To specify the hardware address type and address (MAC), use e.g.:

# wicked duid create llt ethernet 02:00:00:00:00:01

To specify to use the hardware address of an interface, use e.g.:

# wicked duid create llt eth0

Without arguments, wicked will search for an existing interface it can use:

# wicked duid create llt

Currently supported hardware types are ethernet and infiniband. The time is set to duid creation time (since 2001) automatically. ⏰

  • DUID type 2, Vendor Based on IANA Enterprise Number:
# wicked duid create en <enterprise-number> <machine-identifier>

To create a duid en using for example the enterprise number assigned to SUSE and an opaque unique machine identifier noted as colon-separated hex bytes, use:

# wicked duid create en 7057 02:00:00:00:00:02

See also http://www.iana.org/assignments/enterprise-numbers.

  • DUID type 3, Link-layer address:
# wicked duid create ll [ [ifname] | <hwtype> <hwaddr> ]

Usage is as for type 1 duid llt, but the duid does not contain a time. 🕰️❌

  • DUID type 4, UUID-Based Unique Identifier:
# wicked duid create uuid [ <uuid> | --machine-id | --product-id ]

Creates a DUID using the specified UUID in its common format, by importing the systemd /etc/machine-id file or the DMI product id uuid (problematic), use e.g.:

# wicked duid create uuid 35bc57cb-c327-4908-9592-57ad07e8aa77
# wicked duid create uuid --machine-id
# wicked duid create uuid --product-id
  • set [--scope <ifname>] <duid> — stores duid in colon-separated hex bytes notation to the persistent duid file, e.g.:
# wicked duid set 00:04:8b:69:45:16:ce:fb:4a:1d:b0:3a:c0:02:b6:b7:55:36
  • del [--scope <ifname>] — deletes the duid stored in the persistent duid file. bye-bye 👋
  • get [--scope <ifname>] — retrieves the duid stored in the persistent duid file.
  • dump or show — shows all the DUIDs stored in the persistent duid file.

🆔 iaid - set, get, create a new IAID ✨

This command lets you show, get, set, or create a new DHCP Identity Association Identifier (IAID). An IAID is a 32bit number used to associate a collection of addresses (temporary, non-temporary, or prefix address) to an interface/device of a client. Wicked automatically maintains one IAID per interface in its persistent iaid file. This command lets you adjust them when/as needed. 🛠️

For the complete description, please refer to https://tools.ietf.org/html/rfc3315#section-10.

  • create [--update] <ifname> — constructs an IAID for a given interface and, if requested with --update, also stores it in the persistent iaid file.
  • set <ifname> <iaid> — stores the specified 32bit iaid number for an interface in the persistent iaid file.
  • del <ifname> — deletes the IAID of a given interface.
  • get <ifname> — retrieves the IAID of a given interface.
  • dump show — shows all IAID's and interfaces stored in the persistent duid file.

📡 arp - send ARP requests 📡

This command lets you verify/probe IPv4 addresses for duplicates, notify/announce about your own IP address use to neighbours, and ping neighbours using ARP requests. It's giving network detective energy 🔎

  • verify [--count n] [--interval ms] <ifname> <IP address> — sends the given number (default 3) of IPv4 duplicate address detection probes in intervals (default random range 1000..2000ms) to verify that the given IP address is not already in use on the interface. On a reply indicating a duplicate address, status code 4 is returned. 🚨
  • notify [--count n] [--interval ms] <ifname> <IP address> — notifies about/announces the use of the IPv4 address to the neighbours on an interface by sending a number (default 2) of gratuitous ARP requests in the given interval (default 2000ms) between the packets. When no notify were sent, status code 7 is returned. 📣
  • ping [--count n] [--interval ms] [--replies n] [--timeout ms] [--from-ip ip] <ifname> <IP address> — ARP pings a neighbour with the specified IP address on an interface with the first or the specified source IP address and an interval (default 1000ms) between the packets. To limit the number of pings to send, use the count parameter. The replies parameter lets you specify the number of replies expected in the time given by timeout or the count and interval parameters to report a success status code 0 or status code 7 when the expected replies do not arrive. 🫡

🛠️ ethtool - Show and modify ethtool options 🛠️

Please read the wicked-ethtool(8) manual page. That's the whole assignment, bestie — go read it 💅

🔎 xpath - retrieve data from an XML blob 🔎

The wickedd server can be enhanced to support new network device types via extension commands — usually shell scripts. When invoking such a script, wickedd will hand it the arguments of the DBus call as an XML document.

The xpathP command tries to provide a flexible and convenient interface for extracting individual bits of information from an XML document. To the degree that XML can be convenient to a shell programmer... sure, bestie 💀

For this, wicked supports expressions using a (subset of) the XPATH 1.0 syntax. These xpath expressions can be embedded into format strings using "%{expression}". Several expressions can be embedded into one format string; this can help to combine pairs of information such as e.g. address and prefix length.

The xpath command by default expects an XML document on standard input. You can use the --file option to specify a filename.

The xpath command supports the following options:

  • --reference xpath-expr — by default, the command will evaluate all XPATH expressions relative to the document's root node. Using this option lets you "drill into" the document: the utility will first evaluate the given expression to look up 0 or more XML nodes in the document, and then evaluate all format strings relative to these nodes. It is an error for the reference expression to yield data other than XML elements (such as strings).
  • --file filename — the file containing the XML document to operate on.

This manual page cannot give a full overview of xpath, of course, however consider the following examples (which assume the input is an XML interface description):

# wicked xpath "vlan_tag=%{/interface/vlan/tag}"

Given a VLAN interface definition, this will expand to the contents of the <tag> element of the VLAN definition. The "path-like" syntax specifies how to traverse the XML tree to find the desired node. Assuming the tag is 42, the above command will print vlan_tag=42. In case the document contains several VLAN interface definitions, this would of course print several lines of output; one per VLAN tag found. 🌸

Note that the xpath command considers an empty expansion as error. If an element or expansion is considered optional, you can prefix it with a question mark, as in %{?...}. If the expansion fails, the expression will be replaced with an empty string.

As a different example, consider a bridge definition like the following:

<bridge>
  <ports>
    <e>
     <device>eth0</device>
     <priority>1</priority>
    </e>
    <e>
     <device>eth1</device>
     <priority>0</priority>
    </e>
  </ports>
</bridge>

In order to print out a list of device/priority pairs of all ports, you could invoke wicked like this:

# wicked xpath --reference "/bridge/ports/e" \
          "dev=%{device} priority=%{?priority}"

By using the --reference option, you instruct wicked to loop over all XML nodes matching this expression — i.e. the two child nodes of the <ports> element. For each of them in turn, the xpath expression is evaluated relative to each node. Note the use of the question mark in the priority term, marking the field as optional. ✨

✨ SEE ALSO ✨

wickedd(8), wicked-config(5), wicked-ethtool(8)

Copyright (C) 2018 SUSE LINUX GmbH, Nuernberg, Germany.

🐛 BUGS 🐛

Please report bugs as described at <https://bugs.opensuse.org>

👑 AUTHORS 👑

Olaf Kirch Pawel Wieczorkiewicz Karol Mroz Nirmoy Das

Final vibe check: this is the wicked source/version page, dated June 2018, and yes, it's wicked(8). Periodt. 💅✨

📦 where this page comes from