wicked(8)

NAME
wicked - network management utility

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

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

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

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

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.

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.

    Failed interfaces are left in an undefined state.

ifreload - checks whether a configuration has changed, and applies accordingly.
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 in order to shut down 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) in ifup run.

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

ifcheck - inspects particular interface details
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.

show-config - reads, conversts and displays all available configuration files.
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.

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.

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:

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.

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

iaid - set, get, create a new IAID
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.

arp - send ARP requests
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.

ethtool - Show and modify ethtool options
Please read the wicked-ethtool(8) manual page.

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

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.

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

COPYRIGHT
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