1wicked(8) Network configuration wicked(8)
2
6 wicked - network management utility
7
9 wicked [global-options] ifup [options] interface
10 wicked [global-options] ifdown [options] interface
11 wicked [global-options] ifreload [options] interface
12 wicked [global-options] ifstatus [options] interface
13 wicked [global-options] ifcheck [options] interface
14 wicked [global-options] show-config [options] [interface]
15 wicked [global-options] convert [options] [file ... ]
16 wicked [global-options] show-xml [options] [interface]
17 wicked [global-options] xpath [options] format...
18 wicked [global-options] getnames [options] device...
19 wicked [global-options] duid [options] <action> ...
20 wicked [global-options] iaid [options] <action> ...
21 wicked [global-options] arp <action> [options] ...
22 wicked [global-options] ethtool [interface] --action [arguments] ...
23
25 wicked offers access to the wicked network managment service from the
26 command line. It can be used to display the current state of network
27 devices, to bring interfaces up or down, or to check their operational
28 status.
29 Conceptually, the wicked network management system deals with two very
31 distinct classes of information. One is the set of configuration files
32 stored somewhere in the system; the other is the current configuration
33 state maintained by the kernel and closely related system daemons like
34 pppd(8) or openvpn(8).
35 Currently, wicked only supports sysconfig style ifcfg- files. Data
37 present in these config files is converted to an internal XML represen‐
38 tation.
39 The server only knows about the latter, but does not parse any configu‐
41 ration files, and does not maintain any state besides what is actually
42 in effect. On the other hand, the client never probes the kernel
43 directly to obtain the current system state. The client's job is to
44 parse the configuration file(s) handed to it by the user, process and
45 convert them to policies, and hand them off to wickedd-nanny. wickedd-
46 nanny then performs device configuration when policy conditions have
47 been met.
48 The client, nanny and server processes communicate with each other over
50 DBus.
51
53 wicked supports a set of options common to all subcommands. These
54 options must precede the subcommand, as in
55 # wicked --dry-run ifup eth0
57 Currently, wicked supports the following list of options:
59 --config filename
61 By default, the daemon reads its configuration from
62 /etc/wicked/common.xml. The --config options allows you to
63 specify a different configuration file.
64 --log-level level
66 Set log level to one of <error|warning|notice|info|debug>.
67 --log-target target
69 Set log target to one of <stderr|syslog>, optionally followed by
70 a colon and target specific details.
71 stderr[:options] with the following options:
73 pid include program pid in each message
74 syslog[:facility[:options]] with following facilities:
76 user, daemon, local0 .. local7
77 and options:
78 perror log the message to stderr as well
79 --debug facility
82 Enable debugging for facility. The list of available facilities
83 can be obtained using "--debug help".
84 --root-directory pathname
86 Specify an alternative root directory from where to load files.
87 This applies to the client's configuration file as well as any
88 interface configuration files.
89 --dry-run
91 skips all calls to wickedd that would modify the current system
92 settings, instead displaying the command that would be sent,
93 along with an XML representation of the XML. Helpful for get‐
94 ting a feel for how the utility and the protocol work, and for
95 debugging.
96 This does not work at the moment.
98 --systemd
100 Forces wicked to use the syslog target for logging.
101 --transient
103 Enables more detailed interface return codes.
104
106 To bring up interfaces, use wicked ifup. This command supports a num‐
107 ber of different modes of operations. In its simplest form, you just
108 give it the name of an interface, and it will bring up the interface
109 using the stored system configuration:
110 # wicked ifup eth0
112 This invocation makes wicked:
114 1. Run the ibft extension to get all firmware type configurations
115 2. Read all sysconfig network configuration files from /etc/sysconfig/network
116 3. Read all XML network configuration files from /etc/wicked/ifconfig
117 For each interface to be configured, wicked will generate a policy and
119 pass this to wickedd-nanny. wickedd-nanny will then kick off applying
120 the configuration to wickedd. wickedd then will perform the necessary
121 steps to configure the interface. These steps include assigning a
122 static address, and starting DHCP and similar address configuration
123 protocols as required.
124 Instead of an interface name, you can also use the special names all or
126 boot, which will tell wicked to bring up all interfaces. The differ‐
127 ence between all and boot is in behavior. When using the latter, wicked
128 will ignore any interfaces that are not configured as boot time inter‐
129 faces.
130 It is also possible to bring up interfaces that do not have a configu‐
132 ration stored in the system; using the --ifconfig option you can pro‐
133 vide a configuration by specifying a path prefixed by a supported
134 schema. Again, you have to specify the name of the interface to bring
135 up, or all to bring up all interfaces described in the file:
136 # wicked ifup --ifconfig compat:/etc/sysconfig/network all
138 # wicked ifup --ifconfig firmware:ibft:ethernet0 all
139 Note that wicked attempts to bring up interfaces in a "reasonable
141 order": for virtual interfaces like VLANs, bridges or bonds, it will
142 always make sure that all subordinate devices are in the required state
143 before bringing up the virtual device itself.
144 The ifup command supports the following options:
146 --ifconfig pathname
148 Specify an alternative source of network configuration, instead
149 of obtaining the system's interface configuration.
150 If the file name starts with the string compat:, wicked is
152 instructed to load the interface configuration from files in the
153 default "ifcfg" syntax, as described by the ifcfg(5) manual
154 page. The string following the compat: prefix is interpreted as
155 a directory name where wicked will scan for files with names
156 matching ifcfg-* and related files, like routes and ifroute-*.
157 The special name firmware: can be used to obtain the interface
159 definition(s) from firmware services like iBFT.
160 --mode identifier
162 This can be used in conjunction with the special interface name
163 all, in order to restrict the set of interfaces that will be
164 brought up. If this option is given, only those interface con‐
165 figurations are considered that have a control <mode> element
166 containing the given identifier.
167 If the interface does not specify a <mode> element in its con‐
169 trol section, then it defaults to boot.
170 --boot-stage identifier
172 This can be used in conjunction with the special interface name
173 all, in order to restrict the set of interfaces that will be
174 brought up. If this option is given, only those interface con‐
175 figurations are considered that have a <boot-stage> element con‐
176 taining the given identifier.
177 If the interface does not specify a <boot-stage> element in its
179 control section, then it defaults to default.
180 --skip-origin configsource
182 This can be used to ignore interfaces that have already been
183 configured. For instance, an interface that has been configured
184 based on a firmware configuration (see option --ifconfig above)
185 will be marked as having a configuration origin of firmware.
186 When bringing up the remaining network interfaces, it is a good
187 idea to not touch these. This can be achieved by running wicked
188 with the option --skip-origin firmware.
189 --skip-active
191 Ignore all interfaces that have already been brought up.
192 --timeout seconds
194 The default timeout for bringing up a network device is 5 sec‐
195 onds. If the interface fails to come up within this time, wicked
196 will fail the device and and exit with an error code. All inter‐
197 faces depending on the failed interface will fail as well.
198 --persistent Set interface into persistent mode (no regular
199 ifdown allowed).
200 Failed interfaces are left in an undefined state.
202
204 This command does the reverse of ifup. Again, you can give it either a
205 specific interface name, or use the special name all to bring down all
206 devices. When bringing down several interfaces, the utility tries to do
207 this in a suitable order.
208 The ifdown command supports the following options:
210 --force state
212 Forcefully put interface into a specified state. This option is
213 applicable whether the interface is persistent or not. State can
214 be one of:
215 device-down
216 device-exists
217 device-setup
218 protocols-up
219 firewall-up
220 device-up
221 link-up
222 link-authenticated
223 lldp-up
224 --delete
226 Attempts to delete an interface. This is equivalent to --force
227 device-down.
228 --no-delete
230 Brings the specified interface to device-exists state. In other
231 words, the interface is down, but not deleted. Persistent inter‐
232 faces are ignored.
233 --timeout seconds
235 The default timeout for bringing down a network device is 5 sec‐
236 onds. If the interface fails to shut down within this time,
237 wicked will fail the device and and exit with an error code. All
238 interfaces that are used by the failed interface will fail as
239 well.
240 Failed interfaces are left in an undefined state.
242
244 ingly.
245 To automatically re-apply changed sections of a configuration for spec‐
246 ified interfaces, use wicked ifreload. This command performs necessary
247 ifdown/ifup operations and attempts to apply detected differences. For
248 additional, see the uses cases below.
249 # wicked ifreload eth0
251 # wicked ifreload all
252 There are 4 potential ifreload use cases:
254 1. Configuration unchanged
256 ifreload does not touch specified interfaces.
257 2. Configuration changed
258 performs ifdown followed by ifup with the new configuration on the
259 specified interfaces.
260 3. Configuration deleted
261 performs ifdown --delete in order to remove the specified interfaces.
262 4. New configuration added
263 performs regular ifup on specified interfaces.
264 This behavior can be fine-tuned using the following options:
266 --ifconfig pathname
268 Specify an alternative source of network configuration, instead
269 of obtaining the system's interface configuration.
270 If the file name starts with the string compat:, wicked is
272 instructed to load the interface configuration from files in the
273 default "ifcfg" syntax, as described by the ifcfg(5) manual
274 page. The string following the compat: prefix is interpreted as
275 a path name. If this path name refers to a directory, wicked
276 will scan it for files with names matching ifcfg-*. If the path
277 name refers to a regular file, it will parse this file, assuming
278 it is an ifcfg file.
279 The special name firmware: can be used to obtain the interface
281 definition(s) from firmware services like iBFT.
282 --persistent
284 Set interface into persistent mode (no regular ifdown allowed).
285
287 To display/diagnose system wide interface network configuration, use
288 wicked ifstatus/show. ifstatus command additionally reads system wide
289 configuration and so is usable by root only. The show variant, on the
290 other hand, deals with runtime configurations of existing interfaces
291 only. Thus, it can be used by users.
292 # wicked ifstatus eth0
294 # wicked ifstatus all
295 Example output for loopback interface:
297 lo up
298 link: #1, state up
299 type: loopback
300 cstate: network-up
301 config: compat:/etc/sysconfig/network/ifcfg-lo
302 leases: ipv4 static granted
303 addr: ipv4 127.0.0.1/8
304 addr: ipv6 ::1/128
305 This behavior can be fine-tuned using the following options:
307 --quiet
309 Used to obtain status return codes only. No information is out‐
310 put, so can be used for scripting.
311 --brief
313 Displays device status for specified interfaces.
314 --ifconfig filename
316 Note that this is ifstatus specfic (ie. root only). Used to
317 alter the source of the specified interface configurations.
318
320 To inspect details such as interface presence, change in interface con‐
321 figuration, internal interface state (cstate) and persistent mode for
322 specified interfaces, use wicked ifcheck. This command can be particu‐
323 larly helpful to script writers.
324 # wicked ifcheck --missed eth0
326 # wicked ifcheck --missed --changed all
327 --ifconfig pathname
329 Specify an alternative source of network configuration, instead
330 of obtaining the system's interface configuration.
331 If the file name starts with the string compat:, wicked is
333 instructed to load the interface configuration from files in the
334 old-style "ifcfg" syntax, as described by the ifcfg(5) manual
335 page. The string following the compat: prefix is interpreted as
336 a path name. If this path name refers to a directory, wicked
337 will scan it for files with names matching ifcfg-*. If the path
338 name refers to a regular file, it will parse this file, assuming
339 it is an ifcfg file.
340 The special name firmware: can be used to obtain the interface
342 definition(s) from firmware services like iBFT.
343 --quiet
345 Used to obtain status return codes only. No information is out‐
346 put, so can be used for scripting.
347 --missed
349 Check if the interface is missed.
350 --changed
352 Check if the interface's configuration is changed.
353 --state state-name
355 Check if the interface is in the given state. Possible states:
356 none
357 device-down
358 device-exists
359 device-setup
360 protocols-up
361 firewall-up
362 device-up
363 link-up
364 link-authenticated
365 lldp-up
366 network-up
367 --persistent
369 Check if the interface is in persistent mode.
370
372 To display all available network configuration files in the internal
374 XML format for specified sources (default is all sources), use wicked
375 show-config. To specify the source, use one of the following:
376 firmware:
377 compat:
378 # wicked show-config
380 # wicked show-config compat:
381 This behavior can be fine-tuned using the following options:
383 --raw Filter from output all config meta-data.
385 --output path
387 By default, wicked will write the XML document to its standard
388 output. Using this option, you can instruct it to write to a
389 different file instead. If the specified path is a directory,
390 the XML document will be split into separate files, one for each
391 interface.
392
394 Wicked currently supports sysconfig ifcfg files, and internally con‐
395 verts them to XML. When invoked without arguments, this command will
396 dump to stdout the XML document representation of all of your ifcfg
397 files.
398 This behavior can be fine-tuned using the following options:
400 --raw Filter from output all config meta-data.
402 --output path
404 By default, wicked will write the XML document to its standard
405 output. Using this option, you can instruct it to write to a
406 different file instead. If the specified path is a directory,
407 the XML document will be split into separate files, one for each
408 interface.
409 Note that convert is a variant is show-config, and is equivalent to:
411 show-config compat:
412
414 wicked can identify network devices via a number of different mecha‐
415 nisms, in addition to the usual interface name. For instance, you can
416 identify an Ethernet device using the permanent MAC address programmed
417 into the card's EEPROM, or via its PCI topology.
418 For the convenience of management applications, wicked provides a func‐
420 tion to retrieve all possible names for an interface names as XML. For
421 each device specified on the command line, a <names> is printed, with
422 zero or more <name> elements.
423 The getnames command supports the following options:
425 --modem
427 Instead of querying network devices, interpret the given inter‐
428 face name as a modem device.
429
431 This command permits to show, get, set or create a new DHCP Unique
432 Identifier (DUID) and store it in wicked's persistent duid file. A
433 DUID is used to identify DHCP clients and servers (hosts), is unique
434 across them and should not change over time if at all possible.
435 For complete description, please refer to
436 https://tools.ietf.org/html/rfc3315#section-9
437 The set, get, create commands also permit to store the duid per-device
439 in the persistent duid file using the --scope <ifname> parameter, which
440 is used when configured to appear with multiple identities to the dhcp
441 servers. See the dhcp6 default-duid and dhcp4 create-cid node descrip‐
442 tions in the wicked-config(5) manual page.
443 create <type> [--scope <ifname>] [--update]
445 Constructs a DUID of a specific type and when requested used
446 with the --update option, also store in wicked's persistent duid
447 file.
448 - DUID type 1, Link-layer address plus time:
450 # wicked duid create llt [ [ifname] | <hwtype> <hwaddr> ]
451 To specify the hardware address type and address (MAC),
453 use e.g.:
454 # wicked duid create llt ethernet 02:00:00:00:00:01
455 To specify to use the hardware address of an interface,
457 use e.g.:
458 # wicked duid create llt eth0
459 Without arguments, wicked will search for an existing
461 interface it can use:
462 # wicked duid create llt
463 Currently supported hardware types are ethernet and
465 infiniband. The time is set to duid creation time (since
466 2001) automatically.
467 - DUID type 2, Vendor Based on IANA Enterprise Number:
469 # wicked duid create en <enterprise-number> <machine-identifier>
470 To create a duid en using for example the enterprise num‐
472 ber assigned to SUSE and an opaque unique machine identi‐
473 fier noted as colon-separated hex bytes, use:
474 # wicked duid create en 7057 02:00:00:00:00:02
475 See also http://www.iana.org/assignments/enterprise-num‐
477 bers.
478 - DUID type 3, Link-layer address:
480 # wicked duid create ll [ [ifname] | <hwtype> <hwaddr> ]
481 Usage is as for type 1 duid llt, the duid does not con‐
483 tain a time.
484 - DUID type 4, UUID-Based Unique Identifier:
486 # wicked duid create uuid [ <uuid> | --machine-id | --product-id ]
487 Creates a DUID using specified UUID in its common format
489 format, by importing the systemd /etc/machine-id file or
490 the DMI product id uuid (problematic), use e.g.:
491 # wicked duid create uuid 35bc57cb-c327-4908-9592-57ad07e8aa77
492 # wicked duid create uuid --machine-id
493 # wicked duid create uuid --product-id
494 set [--scope <ifname>] <duid>
497 Stores duid in colon-separated hex bytes notation to the persis‐
498 tent duid file, e.g.:
499 # wicked duid set 00:04:8b:69:45:16:ce:fb:4a:1d:b0:3a:c0:02:b6:b7:55:36
500 del [--scope <ifname>]
502 Deletes the duid stored in the persistent duid file.
503 get [--scope <ifname>]
505 Retrieves the duid stored in the persistent duid file.
506 dump or show
508 Shows all duid's stored in the persistent duid file.
509
511 This command permits to show, get, set or create a new DHCP Identity
512 Association Identifier (IAID).
513 An IAID is a 32bit number used to associate a collection of addresses
514 (temporary, non-temporary or prefix address) to an interface/device of
515 a client.
516 Wicked automatically maintains one IAID per interface in it's persis‐
517 tent iaid file. This command permits to adjust them when/as needed.
518 For complete description, please refer to
520 https://tools.ietf.org/html/rfc3315#section-10
521 create [--update] <ifname>
523 Constructs an IAID for a given interface and if requested with
524 --update, also stores it in the persistent iaid file.
525 set <ifname> <iaid>
527 Stores the specified 32bit iaid number for an interface in the
528 persistent iaid file.
529 del <ifname>
531 Deletes the IAID of a given interface.
532 get <ifname>
534 Retrieves the IAID of a given interface.
535 dump show
537 Shows all IAID's and interfaces stored in the persistent duid
538 file.
539
542 This command permits to verify/probe IPv4 addresses for duplicates,
543 notify/announce about own IP address use to neighbours and ping neigh‐
544 bours using ARP requests.
545 verify [--count n] [--interval ms] <ifname> <IP address>
547 Sends given number (default 3) of IPv4 duplicate address detec‐
548 tions probes in intervals (default random range 1000..2000ms) to
549 verify, that given IP address is not already in use on the
550 interface. On a reply indicating a duplicate address, status
551 code 4 is returned.
552 notify [--count n] [--interval ms] <ifname> <IP address>
554 Notify about/Announce the use of the IPv4 address to the neigh‐
555 bours on an interface by sending a number (default 2) of gratu‐
556 itous ARP requests in the given interval (default 2000ms)
557 between the packets. When no notify were sent, the status code
558 7 is returned.
559 ping [--count n] [--interval ms] [--replies n] [--timeout ms] [--from-
561 ip ip] <ifname> <IP address>
562 ARP ping a neighbour with specified IP address on an interface
563 with first or the specified source IP address and an interval
564 (default 1000ms) between the packets. To limit the number of
565 pings to send, use the count parameter. The replies parameter
566 permits to specify the number of replies expected in the time
567 given by timeout or the count and interval parameters to report
568 a success status code 0 or status code 7 when the expected
569 replies do not arrive.
570
572 Please read the wicked-ethtool(8) manual page.
573
576 The wickedd server can be enhanced to support new network device types
577 via extension commands — usually shell scripts. When invoking such a
578 script, wickedd will hand it the arguments of the DBus call as an XML
579 document.
580 The xpathP command tries to provide a flexible and convenient interface
582 for extracting individual bits of information from an XML document. To
583 the degree that XML can be convenient to a shell programmer...
584 For this, wicked supports expressions using a (subset of) the XPATH 1.0
586 syntax. These xpath expressions can be embedded into format strings
587 using "%{expression}". Several expressions can be embedded into one
588 format string; this can help to combine pairs of information such as
589 e.g. address and prefix length.
590 The xpath command by default expects an XML document on standard input.
592 You can use the --file option to specify a filename.
593 The xpath command supports the following options:
595 --reference xpath-expr
597 By default, the command will evaluate all XPATH expressions rel‐
598 ative to the document's root node. Using this option allows you
599 to "drill into" the document: the utility will first evaluate
600 the given expression to look up 0 or more XML nodes in the docu‐
601 ment, and then evaluate all format strings relative to these
602 nodes. It is an error for the reference expression to yield data
603 other than XML elements (such as strings).
604 --file filename
606 The file containing the XML document to operate on.
607 This manual page cannot give a full overview of xpath, of course, how‐
609 ever consider the following examples (which assume the input is an XML
610 interface description):
611 # wicked xpath "vlan_tag=%{/interface/vlan/tag}"
613 Given a VLAN interface definition, this will expand to the contents of
615 the <tag> element of the VLAN definition. The "path-like" syntax speci‐
616 fies how to traverse the XML tree to find the desired node. Assuming
617 the tag is 42, the above command will print vlan_tag=42. In case the
618 document contains several VLAN interface definitions, this would of
619 course print several lines of output; one per VLAN tag found.
620 Note that the xpath command considers an empty expansion as error. If
622 an element or expansion is considered optional, you can prefix it with
623 a question mark, as in %{?...}. If the expansion fails, the expression
624 will be replaced with an empty string.
625 As a different example, consider a bridge definition like the follow‐
627 ing:
628 <bridge>
630 <ports>
631 <e>
632 <device>eth0</device>
633 <priority>1</priority>
634 </e>
635 <e>
636 <device>eth1</device>
637 <priority>0</priority>
638 </e>
639 </ports>
640 </bridge>
641 In order to print out a list of device/priority pairs of all ports, you
643 could invoke wicked like this:
644 # wicked xpath --reference "/bridge/ports/e" \
646 "dev=%{device} priority=%{?priority}"
647 By using the --reference option, you instruct wicked to loop over all
649 XML nodes matching this expression - i.e. the two child nodes of the
650 <ports> element. For each of them in turn, the xpath expression is
651 evaluated relative to each node. Note the use of the question mark in
652 the priority term, marking the field as optional.
653
655 wickedd(8), wicked-config(5), wicked-ethtool(8)
656
658 Copyright (C) 2018 SUSE LINUX GmbH, Nuernberg, Germany.
659
661 Please report bugs as described at <http://bugs.opensuse.org>
662
664 Olaf Kirch Pawel Wieczorkiewicz Karol Mroz Nirmoy Das
665wicked June 2018 wicked(8)