1wicked(8) Network configuration wicked(8)
2
3
4
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
30 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
36 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
40 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
49 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
56 # wicked --dry-run ifup eth0
57
58 Currently, wicked supports the following list of options:
59
60 --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
65 --log-level level
66 Set log level to one of <error|warning|notice|info|debug>.
67
68 --log-target target
69 Set log target to one of <stderr|syslog>, optionally followed by
70 a colon and target specific details.
71
72 stderr[:options] with the following options:
73 pid include program pid in each message
74
75 syslog[:facility[:options]] with following facilities:
76 user, daemon, local0 .. local7
77 and options:
78 perror log the message to stderr as well
79
80
81 --debug facility
82 Enable debugging for facility. The list of available facilities
83 can be obtained using "--debug help".
84
85 --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
90 --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
97 This does not work at the moment.
98
99 --systemd
100 Forces wicked to use the syslog target for logging.
101
102 --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
111 # wicked ifup eth0
112
113 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
118 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
125 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
131 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
137 # wicked ifup --ifconfig compat:/etc/sysconfig/network all
138 # wicked ifup --ifconfig firmware:ibft:ethernet0 all
139
140 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
145 The ifup command supports the following options:
146
147 --ifconfig pathname
148 Specify an alternative source of network configuration, instead
149 of obtaining the system's interface configuration.
150
151 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
158 The special name firmware: can be used to obtain the interface
159 definition(s) from firmware services like iBFT.
160
161 --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
168 If the interface does not specify a <mode> element in its con‐
169 trol section, then it defaults to boot.
170
171 --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
178 If the interface does not specify a <boot-stage> element in its
179 control section, then it defaults to default.
180
181 --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
190 --skip-active
191 Ignore all interfaces that have already been brought up.
192
193 --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
201 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
209 The ifdown command supports the following options:
210
211 --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
225 --delete
226 Attempts to delete an interface. This is equivalent to --force
227 device-down.
228
229 --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
234 --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
241 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
250 # wicked ifreload eth0
251 # wicked ifreload all
252
253 There are 4 potential ifreload use cases:
254
255 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
265 This behavior can be fine-tuned using the following options:
266
267 --ifconfig pathname
268 Specify an alternative source of network configuration, instead
269 of obtaining the system's interface configuration.
270
271 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
280 The special name firmware: can be used to obtain the interface
281 definition(s) from firmware services like iBFT.
282
283 --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
293 # wicked ifstatus eth0
294 # wicked ifstatus all
295
296 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
306 This behavior can be fine-tuned using the following options:
307
308 --quiet
309 Used to obtain status return codes only. No information is out‐
310 put, so can be used for scripting.
311
312 --brief
313 Displays device status for specified interfaces.
314
315 --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
325 # wicked ifcheck --missed eth0
326 # wicked ifcheck --missed --changed all
327
328 --ifconfig pathname
329 Specify an alternative source of network configuration, instead
330 of obtaining the system's interface configuration.
331
332 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
341 The special name firmware: can be used to obtain the interface
342 definition(s) from firmware services like iBFT.
343
344 --quiet
345 Used to obtain status return codes only. No information is out‐
346 put, so can be used for scripting.
347
348 --missed
349 Check if the interface is missed.
350
351 --changed
352 Check if the interface's configuration is changed.
353
354 --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
368 --persistent
369 Check if the interface is in persistent mode.
370
372
373 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
379 # wicked show-config
380 # wicked show-config compat:
381
382 This behavior can be fine-tuned using the following options:
383
384 --raw Filter from output all config meta-data.
385
386 --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
399 This behavior can be fine-tuned using the following options:
400
401 --raw Filter from output all config meta-data.
402
403 --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
410 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
419 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
424 The getnames command supports the following options:
425
426 --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
438 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
444 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
449 - DUID type 1, Link-layer address plus time:
450 # wicked duid create llt [ [ifname] | <hwtype> <hwaddr> ]
451
452 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
456 To specify to use the hardware address of an interface,
457 use e.g.:
458 # wicked duid create llt eth0
459
460 Without arguments, wicked will search for an existing
461 interface it can use:
462 # wicked duid create llt
463
464 Currently supported hardware types are ethernet and
465 infiniband. The time is set to duid creation time (since
466 2001) automatically.
467
468 - DUID type 2, Vendor Based on IANA Enterprise Number:
469 # wicked duid create en <enterprise-number> <machine-identifier>
470
471 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
476 See also http://www.iana.org/assignments/enterprise-num‐
477 bers.
478
479 - DUID type 3, Link-layer address:
480 # wicked duid create ll [ [ifname] | <hwtype> <hwaddr> ]
481
482 Usage is as for type 1 duid llt, the duid does not con‐
483 tain a time.
484
485 - DUID type 4, UUID-Based Unique Identifier:
486 # wicked duid create uuid [ <uuid> | --machine-id | --product-id ]
487
488 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
495
496 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
501 del [--scope <ifname>]
502 Deletes the duid stored in the persistent duid file.
503
504 get [--scope <ifname>]
505 Retrieves the duid stored in the persistent duid file.
506
507 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
519 For complete description, please refer to
520 https://tools.ietf.org/html/rfc3315#section-10
521
522 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
526 set <ifname> <iaid>
527 Stores the specified 32bit iaid number for an interface in the
528 persistent iaid file.
529
530 del <ifname>
531 Deletes the IAID of a given interface.
532
533 get <ifname>
534 Retrieves the IAID of a given interface.
535
536 dump show
537 Shows all IAID's and interfaces stored in the persistent duid
538 file.
539
540
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
546 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
553 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
560 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
574
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
581 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
585 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
591 The xpath command by default expects an XML document on standard input.
592 You can use the --file option to specify a filename.
593
594 The xpath command supports the following options:
595
596 --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
605 --file filename
606 The file containing the XML document to operate on.
607
608 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
612 # wicked xpath "vlan_tag=%{/interface/vlan/tag}"
613
614 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
621 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
626 As a different example, consider a bridge definition like the follow‐
627 ing:
628
629 <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
642 In order to print out a list of device/priority pairs of all ports, you
643 could invoke wicked like this:
644
645 # wicked xpath --reference "/bridge/ports/e" \
646 "dev=%{device} priority=%{?priority}"
647
648 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
665
666
667
668wicked June 2018 wicked(8)