wicked-config - Man Page

/etc/wicked/common.xml
/etc/wicked/server.xml
/etc/wicked/client.xml
/etc/wicked/nanny.xml

These files contain the global configuration options for the wicked network management service. All files follow the same XML schema.

common.xml contains common definitions that should be used by all applications. It is sourced by the other configuration files. It can be used to enable debugging across all wicked components, for instance.

Different components of wicked will load different files on startup; for instance, the wickedd server process will try to load server.xml. If that file does not exist, it will fall back to common.xml and try to read that directly.

The following table shows which wicked commands use which configuration file:

The configuration file is an XML document; its root node must be called <config>.

include

This element can be used to refer to an additional XML configuration file. When parsing a configuration file, wicked will traverse the XML hierarchy once, in the order in which elements occur in the file. The file referenced by an <include> element is loaded and parsed at the time the <include> element is encountered.

Note that the contents of the file will not be "included" in the way you would expect this from e.g. a macro preprocessor. Instead, the referenced file must be a proper XML document, and its top node must also be a config element.

  <dbus>
    <service name="org.opensuse.Network" />
    <schema name="/usr/share/wicked/schema/wicked.xml" />
  </dbus>

sources

This specifies a list of sources that the wicked client will pick up interface configurations from, and their load order. Child elements of <sources> must be called ifconfig, and are expected to specify a location attribute.

The location attribute takes the form type:string, where string may be empty.

Type	Description
firmware	Get configuration from firmware, usually iBFT
compat	Load interface description using legacy ifcfg files
wicked	Load interface description using native wicked XML

The firmware type takes no additional string parameter. When specifying either wicked, you can optionally specify a directory where to look for XML interface configurations. If no directory is given, the path defaults to /etc/wicked/ifconfig. When specifying either compat, you can optionally specify the ifcfg flavor, which can be either suse or redhat. If no flavor is specified, the result is implementation dependent - but usually, it will pick the platform default it was compiled on.

The default configuration is this:

  <sources>
    <ifconfig location="firmware:" />
    <ifconfig location="compat:" />
    <ifconfig location="wicked:" />
  </sources>

The <addrconf> element is evaluated by server applications only, and controls the behavior of dynamic address configuration protocols such as DHCP. This options to blacklist e.g. certain DHCP servers, and which information provided by address configuration to apply.

default-allow-update

Most dynamic address configuration protocols, including DHCP, do not just provide a list of addresses and routes to install for the managed network interface, but can be used to provide information such as a list of DNS servers, directory information (for e.g. NIS), etc. A system receiving that information is free to reconfigure some of its services based on this information. For instance, it makes a lot of sense to configure the resolver library to use the DNS servers specified by a DHCP server. On the other hand, you may want to ignore any NIS information received via DHCP.

The <default-allow-update> is applied to static and intrinsic leases, which do not have an own, type and address family specific <allow-update> element as available under the <dhcp6>, <dhcp4>, <auto6> and <auto4> sub-elements, which support a sub-set of the possible facilities listed here. The <default-allow-update> and the type specific <allow-update> elements enable you to control which system services wicked will (request and) consider to update in the system.

It contains a list of either empty XML elements e.g. (<dns/><ntp/>) naming system the facilities or alternatively, a space separated string list (dns ntp) with the facility names. The special elements default, none and all enable and disable the default, none and all updates, respectively. A no- or a - in the front of a facility name permits to remove/disable a facility from the currently applied set and enable further supported facilities, e.g. default,-nis,slp is applying a modified default set with disabled nis and the optional slp facility enabled additionally.

The following updater facilities are currently defined:

Name	Description
default-route	system default route (IPv4 or IPv6)
hostname	system hostname
dns	update resolv.conf or dns server (via netconfig)
nis	NIS client (via netconfig)
ntp	NTP servers (via netconfig)
smb	SMB settings (no netconfig module implemented)
nds	NDS servers (no netconfig module implemented)
slp	SLP client (no netconfig module implemented)
sip	SIP client (no netconfig module implemented)
log	syslog servers (no netconfig module implemented)
lpr	print servers (no netconfig module implemented)
tz	posix time zone (no netconfig module implemented)
mtu	adjust interface mtu (dhcp4)
boot	root-path (dhcp4)/boot-url (dhcp6) used in the initrd

Note that administrators wishing to support currently unimplemented updaters can do so by configuring external updaters using the <system-updater> extensions described below.

dhcp4

This element can be used to control the behavior of the DHCP4 supplicant. See below for a list of options.

dhcp6

This element can be used to control the behavior of the DHCP6 supplicant. See below for a list of options.

auto6

This element can be used to control the behavior of AUTO6 processing.

The DHCP4 client can be configured through the options listed below. All of them must be nested in the config node like this:

  <addrconf>
    <dhcp4>
      ...
    </dhcp4>
  </addrconf>

or inside a device name context like:

  <addrconf>
    <dhcp4>
      <device name="eth0" >
        ...
      </device>
    </dhcp4>
  </addrconf>

create-cid

Specifies the standard client-id type to use:

Type	Alias	Description
rfc4361	dhcp6	use 0xff as type, followed by DHCPv6 IAID and DUID
rfc2132	hwaddr	use hardware/link layer type, followed by the address
disable	none	disables creation (custom client-id is send if given)

When the interface configuration does not provide an explicit client-id (DHCLIENT_CLIENT_ID in ifcfg files or <client-id> xml config/policy node), wicked will generate a DHCPv4 client-id as specified in this option.

When set to rfc4361, wicked will create a DHCPv4 client-id using the DHCPv6 IAID and DUID (see <dhcp6><default-duid> option). This new rfc4361 client-id is required to perform DDNS updates for ipv4 (A) and ipv6 (AAAA) address records in the same DNS zone (domain) and mandatory to use on infiniband interfaces.

When set to rfc2132, wicked will create a DHCPv4 client-id using the network interface hardware-type and address. This may be needed to maintain compatibility to e.g. DHCPv4 servers with static leases explicitly bound to a rfc2132 client-id or having trouble to provide a lease to a dhcp4 client using the new and longer rfc4361 client-id.

When set to disable, no client-id is created and send by default (except when the interface config request to acquire a lease contains a custom/explicit one).

When unspecified, the default behavior depends on the --enable-dhcp4-rfc4361-cid (default) and --disable-dhcp4-rfc4361-cid configure options, allowing to revert to use the old rfc2132 client-id at compile time, i.e. to prereserve behavior like in older releases, but permit to change to enable the new rfc4361 client-id default at runtime.

Note, that a change of the client-id usually causes to disassociate the lease and/or DNS records, because it is used in the DHCID DNS record (see rfc4701).

vendor-class

Specifies the string to be used as the vendor-class option in the DHCP request. By default, no vendor-class option is sent.

lease-time

Specifies the lease time to request in the DHCP request, in seconds. This also caps the lease time that can be requested in an interface configuration; any lease-time specified there will be silently limited to what was specified in the global configuration file. The following will set the default lease time to one hour:

 <lease-time>3600</lease-time>

ignore-server

Using the ip attribute of this element, you can specify the IP or HW address (currently ethernet devices only) of a faulty DHCP server that should be ignored:

 <ignore-server ip="192.168.8.1" />  <ignore-server mac="52:54:00:02:c2:67" />

prefer-server

Specify a preferred DHCP server, together with a numeric value indicating its preference. Again, the address of the server is specified using the ip or mac attribute.

The numeric preference value is given by the weight, and should range from -1 to 100. Higher numbers indicate a higher preference. A negative value will cause the server to be ignored. If a response from a server with a weight of 100 is received, it will be selected immediately. Otherwise, the supplicant will wait for about one second, and select the server with the highest preference afterwards.

The special keywords never and always correspond to -1 and 100, respectively. If no weight attribute is given, it defaults to always (100).

The following example will ignore 192.168.8.1, always use the information from 192.168.8.10 if available, and fall back to 192.168.8.7 if not:

  <prefer-server ip="192.168.8.1"  weight="never" />
  <prefer-server mac="02:03:04:05:06:07" weight="always" />
  <prefer-server ip="192.168.8.7"  weight="50" />

allow-update

Specify the list of system services that wicked will configure based on the DHCP lease received. For the syntax of this element, please refer to the description of default-allow-update above. dhcp4 supports all update facilities.

route-options

Specify a space separated list of routing options to request from dhcp4 server.

Name		AliasDescription
classless	csr	RFC 3442 classless static route option 121
ms-classless	mscsr	MS classless static route option code 249 (pre RFC 3442)
static-routes	class	Obsolete option 33 requesting static class routes

The RFC 3442 classless static route option provides all routes with a netmask, includes the default routers and has priority over other routing options. By default, wicked requests classless (121) as well as class static routes (33) and the default routers option (3) (when enabled in allow-update) to be compatible to old servers or servers not configured to provide classless, but only a default router option.

define

Permits to define list of custom dhcp options not covered by wicked yet. The dhcp4 option codes are 8-bit (1..254) bytes.

For non-standard options, it is recommended is to use the DHCPv4 private option code range 224 to 254, see RFC3942 (section 4), RFC 2939 and www.iana.org/assignments/bootp-dhcp-parameters to avoid conflicts with options that are or may be defined and implemented later.

To request support for a specific standard option, issue a feature request at https://fate.suse.com/ or https://features.opensuse.org/ (hermes). See Custom DHCP Options section for more details.

The DHCP6 client can be configured through the options listed below. All of them must be nested in the config node like this:

  <addrconf>
    <dhcp6>
      ...
    </dhcp6>
  </addrconf>

or inside a device name context like:

  <addrconf>
    <dhcp6>
      <device name="eth0" >
        ...
      </device>
    </dhcp6>
  </addrconf>

default-duid

DHCPv6 uses a so-called DUID to identify a DHCP client and an IAID, that refers to an interface.
DHCPv4 now also defaults to construct its client-id using the DHCPv6 IAID and DUID as well (see <dhcp4><create-cid> option).
By default, wickedd-dhcp6 will try to generate a DUID based on the link layer address (MAC) of the device and time (DUID-LLT).

The default-duid element permits to override this behavior and either specify an explicit DUID as a string of colon separated hex octets, e.g.:

      <default-duid>00:03:00:01:02:00:00:00:00:02</default-duid>

or an advise which duid type to construct or import expressed in a child element:

      <default-duid><duid type element/></default-duid>

using one of the following duid type elements:

llt, DUID type 1, Link-layer address plus time:

Permits to specify the link/hardware type and address in its hardware and address elements, e.g.:

        <llt>
          <hardware>ethernet</hardware><address>02:00:00:00:00:02</address>
        </llt>

Without arguments, wicked will create the duid-llt using the hardware type and address of the actual device that requests a duid first. The time inside of the DUID is set automatically to the duid creation time.

en, DUID type 2, Vendor Based on IANA Enterprise Number:

Permits to specify a vendor type DUID-EN based on the IANA assigned enterprise number and an machine identifier specified in the enterprise-number and identifier elements, e.g. using IANA number 7057 assigned to SUSE:

        <en>
          <enterprise-number>7057</enterprise-number>
          <identifier>02:00:00:00:00:02</identifier>
        </en>

ll, DUID type 3, Link-layer address (without time):

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

uuid, DUID type 4, UUID-Based Unique Identifier:

Permits to specify the effective UUID to use, e.g.:

        <uuid>80d732e7-b8dc-45ef-bdae-f9f5e6925cef</uuid>

or import it from /etc/machine-id file:

        <uuid><machine-id/></uuid>
or using an explicit path to the machine-id file:
        <uuid><machine-id>/etc/machine-id</machine-id></uuid>

or the DMI product id (problematic, may be not available or not unique):

        <uuid><dmi-product-id/></uuid>

Without arguments, wicked will try to import the machine-id with a fallback to the DMI product id when no machine-id file exists.

Additionally, the default-duid element supports a per-device attribute. When enabled via <default-duid per-device="true"/>, wicked changes to a non-standard behavior and maintains a separate duid for each device instead of the same ("default") DUID for all interfaces and a per device/interface IAID.

This permits to workaround some special cases, where the hosts should appear to the server using multiple identities, that is to behave as multiple machines instead as one with multiple interfaces.

The wickedd daemons store the generated DUIDs in /run/wicked/duid.xml file. The wicked duid utility command permits to review and modify the duid as needed.

Note: When you change the DUID, make sure to restart the wickedd service.

lease-time

Specifies the lease time to request in the DHCP request, in seconds. This also caps the lease time that can be requested in an interface configuration; any lease-time specified there will be silently limited to what was specified in the global configuration file. The following will set the default lease time to one hour:

 <lease-time>3600</lease-time>

release-retransmits

Specifies the number of lease release retransmissions in the range 1..5. Default is to send up to 5 (REL_MAX_RC) retransmissions.

info-refresh-time

Specifies a different default for the RFC4242 info refresh time used when the dhcp6 server does not provide any and permits also to adjust the acceptable time range in the min and max attributes, e.g.:

 <info-refresh-time min= 600" max="604800">86400</info-refresh-time>

prefer-server

Specify a preferred DHCP server, together with a numeric value indicating its preference. The server is identified using its DUID, which has to be specified via the id attribute.

The numeric preference value is given by the weight, and should range from -1 to 255. Higher numbers indicate a higher preference. A negative value will cause the server to be ignored. If a response from a server with a weight of 255 is received, it will be selected immediately. Otherwise, the supplicant will wait for about one second, and select the server providing an offer with the best request match and the highest preference afterwards.

The special keywords never and always correspond to -1 and 255, respectively. If no weight attribute is given, it defaults to always (255).

The following example will ignore DHCP offers from the first server, always use the information from the second (if available), and fall back to the third if not:

  <prefer-server id="00:03:00:01:02:03:04:05:06:07" weight="never" />
  <prefer-server ip="2001:DB8::1" weight="always" />
  <prefer-server ip="2001:DB8::2" weight="50" />

allow-update

Specify the list of system services that wicked will configure based on the DHCP lease received. For the syntax of this element, please refer to the description of default-allow-update above. DHCPv6 allows the following update facilities:

Name	Description
hostname	system hostname (fqdn)
dns	update resolv.conf or dns server (via netconfig)
ntp	NTP servers (via netconfig)
sip	SIP client (optional, no netconfig module implemented)
nis	NIS client (optional, no netconfig module, not supported by ypbind)
tz	posix time zone (no netconfig module implemented)
boot	boot-url used in the initrd

Note: DHCPv6 protocol does not provide any options to request routing settings, which are applied via a router advertisement (IPv6 RA).

define

Permits to define list of custom dhcp options not covered by wicked yet. The dhcp6 option codes are 16-bit (1..65534) integers.

See http://www.iana.org/assignments/dhcpv6-parameters and RFC7227.

To request support for a specific standard option, issue a feature request at https://fate.suse.com/ or https://features.opensuse.org/ (hermes). See Custom DHCP Options section for more details.

Note:

The DHCPv6 protocol does not define any routing options, which are applied by IPv6 Router Advertisement (RA) or require static configuration. The current NIS / ypbind implementation on linux does supported IPv6 at all.

A custom option defines a name for a dhcp option code and a format how to interpret raw data of the dhcp option. This option definition is used to parse and format lease-xml files, (format) leaseinfo dump files and the name can be used to request options (oro alias option-request-option).

The name has to be a valid keyword and is restricted to a word of 1..63 alphanumeric and "-" characters (same to a hostname without any dots).

The current implementation supports the following simple types (scalars):

opaque [fixed-length="<length in bytes>" | embedded-length="1|2|uint8|uint16"]

Opaque data or not printable string formatted as a hex-string (xx:xx:xx) with variable length. The fixed-length attribute permits adjust it to a \0 padded fixed-length data field and the embedded-length attribute to interpret the initial 1 (uint8) or 2 (uint16) bytes as data length (RFC7227).

string [fixed-length="<length in bytes>" | embedded-length="1|2|uint8|uint16"]

A printable variable-length string (without a \0 null-termination). The fixed-length attribute permits to adjust it to a \0 padded fixed-length string and the embedded-length attribute to interpret the initial 1 (uint8) or 2 (uint16) bytes as the string length (RFC7227).

bool

A single byte value interpreted as boolean (0 is "false", otherwise "true").

int8 | int16 | int32 | int64 uint8 | uint16 | uint32 | uint64 [notation="hex"]

A signed or unsigned integer in decimal or optionally, in a 0x.. hex notation.

ipv4-address | ipv6-address

IPv4 and IPv6 address types

ipv4-prefix | ipv6-prefix

An RFC3442 / RFC7227 prefix (destination descriptor) with compact encoded prefix-length byte followed by the significant octets of the network address.

These simple types can be combined together in structs and arrays.

A structs consists of one or more members, which contain a name and a member type, struct or array. The last member in a struct is allowed to contain be variable length type. An array contains an element name and fixed-length type or struct.

A simple type can be specified in the node name (<string/>) or in the data of the type node (<type>string</type>).

Examples:

  <!--
       global or device specific definitions of dhcp4/dhcp6 options
       under <config><addrconf><dhcp4> or <config><addrconf><dhcp6>
  -->
  <define>
    <option>
      <code>224</code>
      <name>foo-server</name>
      <type>ipv4-address</type>
    </option>
    <option>
      <code>225</code>
      <name>foo-path</name>
      <string/>
    </option>
    <option>
      <code>250</code>
      <name>test-cls-routes</name> <!-- RFC3442 classless route format -->
      <array>
        <name>route</name>
        <struct>
          <member>
            <name>destination</name>
            <ipv4-prefix/>
          </member>
          <member>
            <name>gateway</name>
            <ipv4-address/>
          </member>
        </struct>
      </array>
    </option>
    <option>
      <code>251</code>
      <name>six-addresses</code>
      <array>
        <name>ip</name>
        <ipv6-address/>
      </array>
    </option>
  </define>

To test the option definition, the "wicked test" call can be used:

 wicked test dhcp4 --request - eth1 <<EOF
  <request type= offer">
    <request-options>
      <option>224</option>
      <option>test-cls-routes</option>
    </request-options>
  </request>
 EOF

before adding the option requests to the ifcfg or xml configuration and restarting wickedd ("rcwickedd restart") to apply to the supplicant.

teamd

The <teamd> element permits to enable or disable teamd support (inclusive discovery of team device details) in its <enable> sub-element. Disabled by default, server.xml config enables it. Further, it permits to specify the control interface to communicate with teamd in the <ctl> sub-element, using the following options:

Option	Description
detect-once	detect the control interface to use, once (default)
detect	detect the control interface to use in each call
dbus	communicate directly with teamd via dbus
unix	use unix socket control interface via teamdctl tool

bonding

The <bonding> element permits to specify whether to use netlink or sysfs to configure the bonding in its <ctl> sub-element:

Option	Description
netlink	configure bonding via netlink (default)
sysfs	configure bonding via sysfs (the old way)

The functionality of wickedd can be extended through external commands and shell scripts. All of these extensions are declared in server.xml, and all of them follow the same pattern.

Script extensions

Scripts are specified via the <script> element, which needs to provide a name attribute and a command attribute. Again, the name serves as an identifier, while the command specifies the command to be invoked. wicked comes with a (simple) parser for this, which splits up this command into a argument array which is passed to execve(2) eventually.

An example would look like this:

  <script name="install"
          command="/etc/wicked/extensions/hostname install"/>

When defining script extensions, it is possible to define additional environment variables that get passed to the script. This mechanism is explained in more detail below.

Extensions are always grouped under a parent element. The following configuration elements can contain extensions:

  <system-updater name= hostname">
    <script name="backup" command="/etc/wicked/extensions/hostname backup"/>
    <script name="restore" command="/etc/wicked/extensions/hostname restore"/>
    <script name="install" command="/etc/wicked/extensions/hostname install"/>
    <script name="install" command="/etc/wicked/extensions/hostname remove"/>
  </system-updater>

  <netif-firmware-discovery>
    <script name= ibft" command="/etc/wicked/extensions/ibft" />
  </netif-firmware-discovery>

wickedd(8), netconfig(8), RFC3942

Copyright (C) 2014-2016 SUSE LINUX GmbH, Nuernberg, Germany.

Please report bugs at <https://bugzilla.suse.com/>

Olaf Kirch

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