wicked - Man Page

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] ...

wicked offers access to the wicked network management service from the command line. It can be used to display the current state of network devices, to bring interfaces up or down, or to check their operational status.

Conceptually, the wicked network management system deals with two very distinct classes of information. One is the set of configuration files stored somewhere in the system; the other is the current configuration state maintained by the kernel and closely related system daemons like pppd(8) or openvpn(8).

Currently, wicked only supports sysconfig style ifcfg- files. Data present in these config files is converted to an internal XML representation.

The server only knows about the latter, but does not parse any configuration files, and 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. wickedd-nanny then performs device configuration when policy conditions have been met.

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

wicked supports a set of options common to all subcommands. These options must precede the subcommand, as in

     # wicked --dry-run ifup eth0

Currently, wicked supports the following list of options:

--config filename

By default, the daemon reads its configuration from /etc/wicked/common.xml. The --config options allows you to specify a different configuration file.

--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".

--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.

This does not work at the moment.

--systemd

Forces wicked to use the syslog target for logging.

--transient

Enables more detailed interface return codes.

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 /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.

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.

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.

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).

Failed interfaces are left in an undefined state.

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.

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.

--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.

Failed interfaces are left in an undefined state.

To automatically re-apply changed sections of a configuration for specified interfaces, use wicked ifreload. This command performs necessary ifdown/ifup operations and attempts to apply detected differences. For additional, see the uses cases below.

    # wicked ifreload eth0
    # wicked ifreload all

There are 4 potential ifreload use cases:

1. Configuration unchanged
    ifreload does not touch specified interfaces.
2. Configuration changed
    performs ifdown followed by ifup with the new configuration on the 
    specified interfaces.
3. Configuration deleted
    performs ifdown --delete in order to remove the specified interfaces.
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.

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.

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).

To display/diagnose system wide interface network configuration, use wicked ifstatus/show. 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. Thus, it can be used by users.

    # 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.

--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.

To inspect details such as interface presence, change in interface configuration, internal interface state (cstate) and persistent mode for specified interfaces, use wicked ifcheck. This command can be particularly helpful to script writers.

    # 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.

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.

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.

--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.

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.

--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.

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.

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 is show-config, and is equivalent to: show-config compat:

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.

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.

This command permits to show, get, set or create a new DHCP Unique Identifier (DUID) and store it in wicked's persistent duid file. A DUID is used to identify DHCP clients and servers (hosts), is unique across them and should not change over time if at all possible.
For complete description, please refer to https://tools.ietf.org/html/rfc3315#section-9

The set, get, create commands also permit to 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.

create <type> [--scope <ifname>] [--update]

Constructs a DUID of a specific type and when requested used with the --update option, also store 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, 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 specified UUID in its common format 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.

get [--scope <ifname>]

Retrieves the duid stored in the persistent duid file.

dump or show

Shows all duid's stored in the persistent duid file.

This command permits to 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 it's persistent iaid file. This command permits to adjust them when/as needed.

For 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.

This command permits to verify/probe IPv4 addresses for duplicates, notify/announce about own IP address use to neighbours and ping neighbours using ARP requests.

verify [--count n] [--interval ms] <ifname> <IP address>

Sends given number (default 3) of IPv4 duplicate address detections probes in intervals (default random range 1000..2000ms) to verify, that 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>

Notify about/Announce 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, the status code 7 is returned.

ping [--count n] [--interval ms] [--replies n] [--timeout ms] [--from-ip ip] <ifname> <IP address>

ARP ping a neighbour with specified IP address on an interface with 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 permits to 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.

Please read the wicked-ethtool(8) manual page.

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...

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 allows you to "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.

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

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

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

Olaf Kirch Pawel Wieczorkiewicz Karol Mroz Nirmoy Das

wicked(7), wickedd(8), wicked-ethtool(8), wicked-redfish(8).