MAN page from openSUSE Tumbleweed wicked-0.6.45-1.1.i586.rpm

WICKED-CONFIG

Section: File Formats (5)
Updated: 16 July 2012
Index

NAME

wicked-config.xml - wicked configuration file

SYNOPSIS

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

DESCRIPTION

These files contain the global configuration options for the wickednetwork 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 enabledebugging across all wicked components, for instance.

Different components of wicked will load different files on startup; forinstance, the wickedd server process will try to load server.xml. Ifthat file does not exist, it will fall back to common.xml and try to read thatdirectly.

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

Application Filename
wicked client.xml
wickedd server.xml
wickedd-nanny nanny.xml
wickedd-auto4 auto4.xml
wickedd-dhcp4 dhcp4.xml
wickedd-dhcp6 dhcp6.xml

GENERAL OPTIONS

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 configurationfile. When parsing a configuration file, wicked will traverse theXML hierarchy once, in the order in which elements occur in the file.The file referenced by an <include> element is loaded and parsedat the time the <include> element is encountered.
: Note that the contents of the file will not be dqincludeddq in theway you would expect this from e.g. a macro preprocessor. Instead, thereferenced file must be a proper XML document, and its top node must alsobe a config element.

Common pathnames

piddir

This element specifies the directory used to write pid files.

The path attribute of this element contains the path to thisdirectory. The optional mode attribute can be used to specifythe permissions of this directory.

The default is to use /run/wicked, mode 0755.

  <statedir path=dq/run/wickeddq mode=dq0755dq />

statedir

This element specifies the location of the directory containing variousfiles relating to the state of the server. For instance, temporary filesare stored here when starting external programs like pppd(8).

The path attribute of this element contains the path to thisdirectory. The optional mode attribute can be used to specifythe permissions of this directory.

The default is to use /run/wicked, mode 0755.

  <statedir path=dq/run/wickeddq mode=dq0755dq />

storedir

This element specifies the location of the directory containing various(reboot) persistent data. For instance, the DHCP DUID and lease filesare is stored in this directory.

The path attribute of this element contains the path to thisdirectory. The optional mode attribute can be used to specifythe permissions of this directory.

The default is to use /var/lib/wicked, mode 0755.

  <statedir path=dq/var/lib/wickeddq mode=dq0755dq />

Nanny enablement

use-nanny: This element controls whether the client will try to apply configurationchanges immediately (one shot ifup), or whether it will forward theconfiguration to nanny.
: When applying an interface configuration immediately to wickedd, it mayfail or not complete in the specified time for a variety of transient reasons,such as an Ethernet cable not being plugged in.
: When managing an interface through nanny, the configuration will beapplied to nanny, which will apply it to wickedd when certainconditions are met such as when the device appears (interface hotplugging)or continue with IP setup, when the link detection was successful for adevice.Nanny will also reapply the configurations to wickedd after restart(e.g. update) and trigger lease confirmations.
: The <use-nanny> element controls the default behavior. When set totrue, wicked will manage all interfaces through nanny.If set to false, all interface changes will be applied directly.The default value is false.
: To enable nanny at installation time, use the nanny=1 installer(linuxrc) boot parameter.

Miscellaneous

debug: This element specifies the default debug facilities to be enabled.Allowed is a comma separated list of supported facility names, includingset names such as all and most and names with a "-" prependedfor negated facilities, e.g. "all,-xpath".
The 'wicked --debug help' command shows valid facility names.If a debug level is specified on the command line or via the WICKED_DEBUGenvironment variable, the setting from the XML configuration file will beignored.

DBus service parameters

All configuration options related to the DBus service are grouped belowthe <dbus> element. Currently, the following child elements arerecognized:

service: This element specifies the DBus service name used, and must be a validDBus API name.The default is "org.opensuse.Network".
schema: This element specifies the location of the schema files.The schema defines the various DBus APIs offered by the server,and how portions of an interface XML description map to theirarguments. The schema files do not contain user-serviceable parts,so it's best to leave this option untouched.

Here's what the default configuration looks like:

  <dbus>    <service name=dqorg.opensuse.Networkdq />    <schema name=dq/usr/share/wicked/schema/wicked.xmldq />  </dbus>

CLIENT ONLY OPTIONS

sources

This specifies a list of sources that the wicked client will pickup interface configurations from, and their load order. Child elementsof <sources> must be called ifconfig, and are expected tospecify a location attribute.

The location attribute takes the form type:string, wherestring 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 adirectory where to look for XML interface configurations. If nodirectory is given, the path defaults to /etc/wicked/ifconfig.When specifying either compat, you can optionally specify theifcfg flavor, which can be either suse or redhat. If noflavor is specified, the result is implementation dependent - butusually, it will pick the platform default it was compiled on.

The default configuration is this:

  <sources>    <ifconfig location=dqfirmware:dq />    <ifconfig location=dqcompat:dq />    <ifconfig location=dqwicked:dq />  </sources>

ADDRESS CONFIGURATION OPTIONS

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

default-allow-update

Most dynamic address configuration protocols, including DHCP, do not just providea 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, directoryinformation (for e.g. NIS), etc. A system receiving that information is free toreconfigure some of its services based on this information.For instance, it makes a lot of sense to configure the resolver library to usethe DNS servers specified by a DHCP server. On the other hand, you may want toignore any NIS information received via DHCP.

The <default-allow-update> is applied to static and intrinsic leases, whichdo not have an own, type and address family specific <allow-update> elementas 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> elementsenable you to control which system services wicked will (request and) considerto update in the system.

It contains a list of either empty XML elements e.g. (<dns/><ntp/>) naming systemthe facilities or alternatively, a space separated string list (dns ntp) with thefacility names.The special elements default, none and all enable and disablethe default, none and all updates, respectively. A no- or a - in thefront of a facility name permits to remove/disable a facility from the currentlyapplied set and enable further supported facilities, e.g. default,-nis,slpis applying a modified default set with disabled nis and the optionalslp 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 unimplementedupdaters 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 DHCP4supplicant. See below for a list of options.

dhcp6

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

auto6

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

DHCP4 SUPPLICANT OPTIONS

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=dqeth0dq >        ...      </device>    </dhcp4>  </addrconf>

create-cid

Specifies the standard client-id type to use:

Type	Alias	Description

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

By default, wickedd-dhcp4 is using the most common rfc2132 on ethernetto maintain compatibility with existing installations and a rfc4361 oninfiniband, where it is mandated by the infiniband dhcp rfc4390.Later versions may change to use the rfc4361 client-id also for ethernet.

When set to disable, no client-id is created and send by default, exceptwhen the interface config request to acquire a lease contains a custom one.

The new rfc4361 client-id is required to perform DDNS updates for ipv4 (A) andipv6 (AAAA) address records in the same DNS zone (domain).Note, that a change of the client-id usually causes to disassociate the leaseand/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 DHCPrequest. By default, no vendor-class option is sent.
lease-time: Specifies the lease time to request in the DHCP request, in seconds. This alsocaps the lease time that can be requested in an interface configuration;any lease-time specified there will be silently limited to what wasspecified in the global configuration file. The following will set the defaultlease time to one hour:
: <lease-time>3600</lease-time>

ignore-server

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

<ignore-server ip=dq192.168.8.1dq /> <ignore-server mac=dq52:54:00:02:c2:67dq />

prefer-server

Specify a preferred DHCP server, together with a numeric value indicating itspreference. Again, the address of the server is specified using theip 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 froma server with a weight of 100 is received, it will be selected immediately.Otherwise, the supplicant will wait for about one minute, and select theserver with the highest preference afterwards.

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

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

  <prefer-server ip=dq192.168.8.1dq  weight=dqneverdq />  <prefer-server ip=dq192.168.8.10dq weight=dq100dq />  <prefer-server ip=dq192.168.8.7dq  weight=dq50dq />

allow-update

Specify the list of system services that wicked will configure basedon the DHCP lease received. For the syntax of this element, please referto the description of default-allow-update above. dhcp4 supportsall update facilities.

route-options

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

Name		Alias

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 becompatible 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 optioncode range 224 to 254, see RFC3942 (section 4), RFC 2939 andwww.iana.org/assignments/bootp-dhcp-parameters to avoid conflicts withoptions that are or may be defined and implemented later.

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

DHCP6 SUPPLICANT OPTIONS

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=dqeth0dq >        ...      </device>    </dhcp6>  </addrconf>

default-duid

DHCPv6 uses a so-called DUID to identify a DHCP client and an IAID, thatrefers to an interface.
DHCPv4 constructs its client-id using the IAID and DUID as well, whenenabled to use a rfc4361 client-id in the <dhcp4><create-cid>config option.
By default, wickedd-dhcp6 will try to generate a DUID based on thelink layer address (MAC) of the device and time (DUID-LLT).

The default-duid element permits to override this behavior and eitherspecify 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 childelement:

      <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 hardwareand 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 typeand 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 enterprisenumber and an machine identifier specified in the enterprise-number andidentifier 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 fallbackto 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 anon-standard behavior and maintains a separate duid for each device instead of thesame ("default") DUID for all interfaces and a per device/interface IAID.

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

The wickedd daemons store the generated DUIDs in /run/wicked/duid.xmlfile. The wicked duid utility command permits to review and modify the duid asneeded.

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 alsocaps the lease time that can be requested in an interface configuration;any lease-time specified there will be silently limited to what wasspecified in the global configuration file. The following will set the defaultlease 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.

ignore-server

Using the ip attribute of this element, you can specify theIP address of a faulty DHCP server that should be ignored:

prefer-server

Specify a preferred DHCP server, together with a numeric value indicating itspreference. The server is identified using its DUID, which has to be specifiedvia the id 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 froma server with a weight of 100 is received, it will be selected immediately.Otherwise, the supplicant will wait for about one minute, and select theserver with the highest preference afterwards.

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

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

  <prefer-server id=dq00:44:01:02:04:00dq weight=dqneverdq />  <prefer-server id=dq00:44:01:02:04:01dq weight=dq100dq />  <prefer-server id=dq00:44:01:02:04:02dq weight=dq50dq />

allow-update

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 routingsettings, 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 requestat 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 appliedby IPv6 Router Advertisement (RA) or require static configuration.The current NIS / ypbind implementation on linux does supported IPv6 at all.

CUSTOM DHCP OPTIONS

A custom option defines a name for a dhcp option code anda format how to interpret raw data of the dhcp option. This option definition isused to parse and format lease-xml files, (format) leaseinfo dump files and thename 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..63alphanumeric and dq-dq characters (same to a hostname without any dots).

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

opaque [fixed-length=dq<length in bytes>dq | embedded-length=dq1|2|uint8|uint16dq]: Opaque data or not printable string formatted as a hex-string (xx:xx:xx) withvariable length. The fixed-length attribute permits adjust it to a \0padded fixed-length data field and the embedded-length attribute tointerpret the initial 1 (uint8) or 2 (uint16) bytes as data length (RFC7227).
string [fixed-length=dq<length in bytes>dq | embedded-length=dq1|2|uint8|uint16dq]: A printable variable-length string (without a \0 null-termination).The fixed-length attribute permits to adjust it to a \0 paddedfixed-length string and the embedded-length attribute to interpretthe initial 1 (uint8) or 2 (uint16) bytes as the string length (RFC7227).
bool: A single byte value interpreted as boolean (0 is dqfalsedq, otherwise dqtruedq).
int8 | int16 | int32 | int64 uint8 | uint16 | uint32 | uint64 [notation=dqhexdq]: 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 encodedprefix-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 nameand a member type, struct or array. The last member in a structis 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 typenode (<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 dqwicked testdq 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 andrestarting wickedd (dqrcwickedd restartdq) to apply to the supplicant.

SERVER ONLY OPTIONS

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 communicatewith 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 orsysfs 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)

EXTENSIONS

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

Script extensions

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

An example would look like this:

  <script name=dqinstalldq          command=dq/etc/wicked/extensions/hostname installdq/>

When defining script extensions, it is possible to define additional environmentvariables that get passed to the script. This mechanism is explained in moredetail below.

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

System updaters

These specify extensions for managing files like resolv.conf, or the systemhostname, based on information contained through an address configuration protocollike DHCP. The configuration element must have a name attribute that specifiesthe system service to configure, and include extensions for backing up the currentconfiguration, for installing new settings, and for restoring the backup.

The configuration for the hostname updater might look like this:

  <system-updater name=hostname>    <script name=dqbackupdq command=dq/etc/wicked/extensions/hostname backupdq/>    <script name=dqrestoredq command=dq/etc/wicked/extensions/hostname restoredq/>    <script name=dqinstalldq command=dq/etc/wicked/extensions/hostname installdq/>    <script name=dqinstalldq command=dq/etc/wicked/extensions/hostname removedq/>  </system-updater>

Currently, wicked supports generic and hostname system updaters.The generic updater operates on data which can be set via netconfig (referto netconfig(7). The hostname updater sets the system hostname.

This extension class supports shell scripts only.

Firmware discovery

Some platforms support iBFT or similar mechanisms to provide the configuration fora network device through the firmware (so that it's possible to boot off that device).In order to support these mechanisms, wicked supports extensions to discover suchconfiguration through firmware discovery extensions.

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

When looking for firmware interface configuration, wicked will invoke all these scriptsin turn and parse their output. Scripts are expected to return XML documents that containzero or more <interface> elements describing the configuration.

This extension class supports shell scripts only.