SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

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

WICKED

Section: Maintenance Commands (8)
Updated: 16 July 2012
Index 

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] [command] ...
wicked [global-options] iaid [options] [command] ...

 

DESCRIPTION

wicked offers access to the wicked network managment service from thecommand 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 verydistinct classes of information. One is the set of configurationfiles stored somewhere in the system; the other is the currentconfiguration state maintained by the kernel and closely relatedsystem daemons like pppd(8) or openvpn(8).

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

The server only knows about the latter, but does not parse any configurationfiles, and does not maintain any state besides what is actually ineffect. On the other hand, the client never probes the kernel directlyto obtain the current system state. The client'sjob 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 conditionshave been met.

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

OPTIONS

wickedsupports a set of options common to all subcommands. These optionsmust 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--configoptions 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:pidinclude program pid in each message

syslog[:facility[:options]]with following facilities:user, daemon, local0 .. local7and options:perrorlog 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 anyinterface configuration files.
--dry-run
skips all calls to wickedd that would modify the current systemsettings, instead displaying the command that would be sent, along withan 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, andit 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 configurations2. 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 passthis to wickedd-nanny. wickedd-nanny will then kick off applying the configurationto wickedd. wickedd then will perform the necessary steps to configure the interface.These steps include assigning a static address, and starting DHCP and similaraddress configuration protocols as required.

Instead of an interface name, you can also use the special names allor boot, which will tell wicked to bring up all interfaces.The difference between all and boot is in behavior. Whenusing the latter, wicked will ignore any interfaces that are notconfigured as boot time interfaces.

It is also possible to bring up interfaces that do not have aconfiguration stored in the system; using the --ifconfigoption you can provide a configuration by specifying a pathprefixed by a supported schema. Again, you have to specifythe name of the interface to bring up, or allto 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 "reasonableorder": for virtual interfaces like VLANs, bridges or bonds, it willalways make sure that all subordinate devices are in the required statebefore bringing up the virtual device itself.

The ifup command supports the following options:

--ifconfig pathname
Specify an alternative source of network configuration, instead ofobtaining the system's interface configuration.
If the file name starts with the string compat:, wicked isinstructed to load the interface configuration from files in thedefault "ifcfg" syntax, as described by the ifcfg(5) manual page.The string following the compat: prefix is interpreted as adirectory name where wicked will scan for files with names matchingifcfg-* and related files, like routes and ifroute-*.
The special name firmware: can be used to obtain the interfacedefinition(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 consideredthat have a control <mode> element containing the given identifier.
If the interface does not specify a <mode> element in its controlsection, 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 consideredthat have a <boot-stage> element containing the given identifier.
If the interface does not specify a <boot-stage> element in its controlsection, 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 firmwareconfiguration (see option --ifconfig above) will be marked ashaving a configuration origin of firmware. When bringing up theremaining 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. Ifthe interface fails to come up within this time, wicked will failthe device and and exit with an error code. All interfaces dependingon the failed interface will fail as well.--persistentSet 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 usethe special name all to bring down all devices. Whenbringing down several interfaces, the utility tries to do thisin a suitable order.

The ifdown command supports the following options:

--force state
Forcefully put interface into a specified state. This optionis applicable whether the interface is persistent or not. Statecan 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 otherwords, the interface is down, but not deleted. Persistentinterfaces are ignored.
--timeout seconds
The default timeout for bringing down a network device is 5 seconds. Ifthe interface fails to shut down within this time, wicked will failthe device and and exit with an error code. All interfaces that areused 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 operationsand 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 ofobtaining the system's interface configuration.
If the file name starts with the string compat:, wicked isinstructed to load the interface configuration from files in thedefault "ifcfg" syntax, as described by the ifcfg(5) manual page.The string following the compat: prefix is interpreted as apath 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, assumingit is an ifcfg file.
The special name firmware: can be used to obtain the interfacedefinition(s) from firmware services like iBFT.
--persistent
Set interface into persistent mode (no regular ifdown allowed).

 

ifstatus/show - displays detailed interface information.

To display/diagnose system wide interface network configuration, usewicked ifstatus/show. ifstatus command additionally readssystem wide configuration and so is usable by root only. The showvariant, on the other hand, deals with runtime configurations ofexisting 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 scrpiting.
--brief
Displays device status for specified interfaces.
--ifconfig filenam
Note that this is ifstatus specfic (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 interfaceconfiguration, internal interface state (cstate) and persistent modefor specified interfaces, use wicked ifcheck. This commandcan 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 ofobtaining the system's interface configuration.
If the file name starts with the string compat:, wicked isinstructed to load the interface configuration from files in theold-style "ifcfg" syntax, as described by the ifcfg(5) manual page.The string following the compat: prefix is interpreted as apath 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, assumingit is an ifcfg file.
The special name firmware: can be used to obtain the interfacedefinition(s) from firmware services like iBFT.
--quiet
Used to obtain status return codes only. No information is output,so can be used for scrpiting.
--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 forspecified sources (default is all sources), use wicked show-config. To specifythe 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. Usingthis option, you can instruct it to write to a different file instead. If the specifiedpath is a directory, the XML document will be split into separate files, one foreach interface.

 

convert - convert configuration files to internal XML

Wicked currently supports sysconfig ifcfg files, and internally convertsthem to XML. When invoked without arguments, this command will dump to stdout theXML 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. Usingthis option, you can instruct it to write to a different file instead. If the specifiedpath is a directory, the XML document will be split into separate files, one foreach 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 differentmechanisms, in addition to the usual interface name. For instance,you can identify an Ethernet device using the permanent MAC addressprogrammed into the card's EEPROM, or via its PCI topology.

For the convenience of management applications, wicked providesa function to retrieve all possible names for an interface names asXML. 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 nameas 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 acrossthem 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 thepersistent duid file using the --scope <ifname> parameter, which is usedwhen configured to appear with multiple identities to the dhcp servers.See the dhcp6 default-duid and dhcp4 create-cid node descriptionsin 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 SUSEand 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 importingthe 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 AssociationIdentifier (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.

 

xpath - retrieve data from an XML blob

The wickedd server can be enhanced to support new network device typesvia 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 extractingindividual bits of information from an XML document. To the degree that XMLcan be convenient to a shell programmer...

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

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 tothe document's root node. Using this option allows you to "drill into"the document: the utility will first evaluate the given expression tolook up 0 or more XML nodes in the document, and then evaluate allformat strings relative to these nodes. It is an error for thereference expression to yield data other than XML elements (such asstrings).
--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 isan XML interface description):

# wicked xpath dqvlan_tag=%{/interface/vlan/tag}dq

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

Note that the xpath command considers an empty expansion as error.If an element or expansion is considered optional, you can prefix itwith a question mark, as in %{?...}. If the expansion fails, theexpression 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 couldinvoke wicked like this:

# wicked xpath --reference dq/bridge/ports/edq rs          dqdev=%{device} priority=%{?priority}dq

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

SEE ALSO

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

COPYRIGHT

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

BUGS

Please report bugs at <https://bugzilla.novell.com/index.cgi> 

AUTHORS

Olaf KirchPawel WieczorkiewiczKarol Mroz

 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
ifup - bring up one or more interfaces
ifdown - bring down one or more interfaces
ifreload - checks whether a configuration has changed, and applies accordingly.
ifstatus/show - displays detailed interface information.
ifcheck - inspects particular interface details
show-config - reads, conversts and displays all available configuration files.
convert - convert configuration files to internal XML
getnames - obtain different names for an interface
duid - set, get, create a new DUID
iaid - set, get, create a new IAID
xpath - retrieve data from an XML blob
SEE ALSO
COPYRIGHT
BUGS
AUTHORS
This document was created byman2html,using the manual pages.