1wicked(8)                    Network configuration                   wicked(8)
2
3
4

NAME

6       wicked - network management utility
7

SYNOPSIS

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

DESCRIPTION

25       wicked  offers access to the wicked network management 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  di‐
43       rectly to obtain the current system state. The client's job is to parse
44       the configuration file(s) handed to it by the user, process and convert
45       them  to  policies,  and hand them off to wickedd-nanny.  wickedd-nanny
46       then performs device configuration when  policy  conditions  have  been
47       met.
48
49       The client, nanny and server processes communicate with each other over
50       DBus.
51

OPTIONS

53       wicked supports a set of options common to all subcommands.  These  op‐
54       tions 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

ifup - bring up one or more interfaces

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 or‐
141       der": for virtual interfaces like VLANs, bridges or bonds, it will  al‐
142       ways  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 in‐
152              structed 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 if‐
199              down allowed).
200
201              Failed interfaces are left in an undefined state.
202

ifdown - bring down one or more interfaces

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

ifreload - checks whether a configuration has changed, and applies accord‐

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 in‐
272              structed 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

ifstatus/show - displays detailed interface information.

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 specific (ie. root  only).   Used  to
317              alter the source of the specified interface configurations.
318

ifcheck - inspects particular interface details

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 in‐
333              structed 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

show-config - reads, conversts and displays all available configuration files.

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

convert - convert configuration files to internal XML

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

getnames - obtain different names for an interface

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

duid - set, get, create a new DUID

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 in‐
461                     terface it can use:
462                                # wicked duid create llt
463
464                     Currently  supported  hardware types are ethernet and in‐
465                     finiband.  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

iaid - set, get, create a new IAID

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

arp - send ARP requests

542       This command permits to verify/probe IPv4 addresses for duplicates, no‐
543       tify/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  in‐
550              terface.  On a reply indicating a duplicate address, status code
551              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)  be‐
557              tween  the packets.  When no notify were sent, the status code 7
558              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

ethtool - Show and modify ethtool options

572       Please read the wicked-ethtool(8) manual page.
573
574

xpath - retrieve data from an XML blob

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 us‐
587       ing "%{expression}".  Several expressions can be embedded into one for‐
588       mat string; this can help to combine pairs of information such as  e.g.
589       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

SEE ALSO

655       wickedd(8), wicked-config(5), wicked-ethtool(8)
656
658       Copyright (C) 2018 SUSE LINUX GmbH, Nuernberg, Germany.
659

BUGS

661       Please report bugs as described at <http://bugs.opensuse.org>
662

AUTHORS

664       Olaf Kirch Pawel Wieczorkiewicz Karol Mroz Nirmoy Das
665
666
667
668wicked                             June 2018                         wicked(8)
Impressum