man/networkctl.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="networkctl" conditional='ENABLE_NETWORKD'
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>networkctl</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>networkctl</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>networkctl</refname>
  21     <refpurpose>Query or modify the status of network links</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>networkctl</command>
  27       <arg choice="opt" rep="repeat">OPTIONS</arg>
  28       <arg choice="plain">COMMAND</arg>
  29       <arg choice="opt" rep="repeat">LINK</arg>
  30     </cmdsynopsis>
  31   </refsynopsisdiv>
  32
  33   <refsect1>
  34     <title>Description</title>
  35
  36     <para><command>networkctl</command> may be used to query or modify the
  37     state of the network links as seen by
  38     <command>systemd-networkd</command>.  Please refer to
  39     <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  40     for an introduction to the basic concepts, functionality, and
  41     configuration syntax.</para>
  42   </refsect1>
  43
  44   <refsect1>
  45     <title>Commands</title>
  46
  47     <para>The following commands are understood:</para>
  48
  49     <variablelist>
  50       <varlistentry>
  51         <term>
  52           <command>list</command>
  53           <optional><replaceable>PATTERN…</replaceable></optional>
  54         </term>
  55
  56         <listitem>
  57           <para>Show a list of existing links and their status. If one or more
  58           <replaceable>PATTERN</replaceable>s are specified, only links matching one of them are shown.
  59           If no further arguments are specified shows all links,
  60           otherwise just the specified links. Produces output similar to:
  61
  62           <programlisting>IDX LINK         TYPE     OPERATIONAL SETUP
  63   1 lo           loopback carrier     unmanaged
  64   2 eth0         ether    routable    configured
  65   3 virbr0       ether    no-carrier  unmanaged
  66   4 virbr0-nic   ether    off         unmanaged
  67
  68 4 links listed.</programlisting></para>
  69
  70         <para>The operational status is one of the following:
  71             <variablelist>
  72               <varlistentry>
  73                 <term>missing</term>
  74                 <listitem>
  75                     <para>the device is missing</para>
  76
  77                     <xi:include href="version-info.xml" xpointer="v245"/>
  78                 </listitem>
  79               </varlistentry>
  80               <varlistentry>
  81                 <term>off</term>
  82                 <listitem>
  83                   <para>the device is powered down</para>
  84
  85                   <xi:include href="version-info.xml" xpointer="v240"/>
  86                 </listitem>
  87               </varlistentry>
  88               <varlistentry>
  89                 <term>no-carrier</term>
  90                 <listitem>
  91                   <para>the device is powered up, but it does not yet have a carrier</para>
  92
  93                   <xi:include href="version-info.xml" xpointer="v240"/>
  94                 </listitem>
  95               </varlistentry>
  96               <varlistentry>
  97                 <term>dormant</term>
  98                 <listitem>
  99                   <para>the device has a carrier, but is not yet ready for normal traffic</para>
 100
 101                   <xi:include href="version-info.xml" xpointer="v240"/>
 102                 </listitem>
 103               </varlistentry>
 104               <varlistentry>
 105                 <term>degraded-carrier</term>
 106                 <listitem>
 107                   <para>one of the bonding or bridge slave network interfaces is in off, no-carrier, or dormant state, and the master interface has no address.</para>
 108
 109                   <xi:include href="version-info.xml" xpointer="v242"/>
 110                 </listitem>
 111               </varlistentry>
 112               <varlistentry>
 113                 <term>carrier</term>
 114                 <listitem>
 115                   <para>the link has a carrier, or for bond or bridge master, all bonding or bridge slave
 116                   network interfaces are enslaved to the master</para>
 117
 118                   <xi:include href="version-info.xml" xpointer="v240"/>
 119                 </listitem>
 120               </varlistentry>
 121               <varlistentry>
 122                 <term>degraded</term>
 123                 <listitem>
 124                   <para>the link has carrier and addresses valid on the local link configured. For bond or
 125                   bridge master this means that not all slave network interfaces have carrier but at least
 126                   one does.</para>
 127
 128                   <xi:include href="version-info.xml" xpointer="v240"/>
 129                 </listitem>
 130               </varlistentry>
 131               <varlistentry>
 132                 <term>enslaved</term>
 133                 <listitem>
 134                   <para>the link has carrier and is enslaved to bond or bridge master network interface</para>
 135
 136                   <xi:include href="version-info.xml" xpointer="v242"/>
 137                 </listitem>
 138               </varlistentry>
 139               <varlistentry>
 140                 <term>routable</term>
 141                 <listitem>
 142                   <para>the link has carrier and routable address configured. For bond or bridge master it is
 143                   not necessary for all slave network interfaces to have carrier, but at least one must.</para>
 144
 145                   <xi:include href="version-info.xml" xpointer="v240"/>
 146                 </listitem>
 147               </varlistentry>
 148             </variablelist>
 149         </para>
 150
 151         <para>The setup status is one of the following:
 152             <variablelist>
 153               <varlistentry>
 154                 <term>pending</term>
 155                 <listitem>
 156                   <para>udev is still processing the link, we don't yet know if we will manage it</para>
 157
 158                   <xi:include href="version-info.xml" xpointer="v240"/>
 159                 </listitem>
 160               </varlistentry>
 161               <varlistentry>
 162                 <term>initialized</term>
 163                 <listitem>
 164                   <para>udev has processed the link, but we don't yet know if we will manage it</para>
 165
 166                   <xi:include href="version-info.xml" xpointer="v251"/>
 167                 </listitem>
 168               </varlistentry>
 169               <varlistentry>
 170                 <term>configuring</term>
 171                 <listitem>
 172                   <para>in the process of retrieving configuration or configuring the link</para>
 173
 174                   <xi:include href="version-info.xml" xpointer="v240"/>
 175                 </listitem>
 176               </varlistentry>
 177               <varlistentry>
 178                 <term>configured</term>
 179                 <listitem>
 180                   <para>link configured successfully</para>
 181
 182                   <xi:include href="version-info.xml" xpointer="v240"/>
 183                 </listitem>
 184               </varlistentry>
 185               <varlistentry>
 186                 <term>unmanaged</term>
 187                 <listitem>
 188                   <para>networkd is not handling the link</para>
 189
 190                   <xi:include href="version-info.xml" xpointer="v240"/>
 191                 </listitem>
 192               </varlistentry>
 193               <varlistentry>
 194                 <term>failed</term>
 195                 <listitem>
 196                   <para>networkd failed to manage the link</para>
 197
 198                   <xi:include href="version-info.xml" xpointer="v240"/>
 199                 </listitem>
 200               </varlistentry>
 201               <varlistentry>
 202                 <term>linger</term>
 203                 <listitem>
 204                   <para>the link is gone, but has not yet been dropped by networkd</para>
 205
 206                   <xi:include href="version-info.xml" xpointer="v240"/>
 207                 </listitem>
 208               </varlistentry>
 209             </variablelist>
 210         </para>
 211
 212         <xi:include href="version-info.xml" xpointer="v219"/>
 213         </listitem>
 214       </varlistentry>
 215
 216       <varlistentry>
 217         <term>
 218           <command>status</command>
 219           <optional><replaceable>PATTERN…</replaceable></optional>
 220         </term>
 221
 222         <listitem>
 223           <para>Show information about the specified links: type, state, kernel module driver, hardware and
 224           IP address, configured DNS servers, etc. If one or more <replaceable>PATTERN</replaceable>s are
 225           specified, only links matching one of them are shown.</para>
 226
 227           <para>When no links are specified, an overall network status is shown. Also see the option
 228           <option>--all</option>.</para>
 229
 230           <para>Produces output similar to:
 231           <programlisting>
 232 ●        State: routable
 233   Online state: online
 234        Address: 10.193.76.5 on eth0
 235                 192.168.122.1 on virbr0
 236                 169.254.190.105 on eth0
 237                 fe80::5054:aa:bbbb:cccc on eth0
 238        Gateway: 10.193.11.1 (CISCO SYSTEMS, INC.) on eth0
 239            DNS: 8.8.8.8
 240                 8.8.4.4</programlisting></para>
 241
 242           <para>In the overall network status, the online state depends on the individual online state of all
 243           required links. Managed links are required for online by default. In this case, the online state is
 244           one of the following:
 245           <variablelist>
 246             <varlistentry>
 247               <term>unknown</term>
 248               <listitem>
 249                 <para>all links have unknown online status (i.e. there are no required links)</para>
 250
 251                 <xi:include href="version-info.xml" xpointer="v249"/>
 252               </listitem>
 253             </varlistentry>
 254             <varlistentry>
 255               <term>offline</term>
 256               <listitem>
 257                 <para>all required links are offline</para>
 258
 259                 <xi:include href="version-info.xml" xpointer="v249"/>
 260               </listitem>
 261             </varlistentry>
 262             <varlistentry>
 263               <term>partial</term>
 264               <listitem>
 265                 <para>some, but not all, required links are online</para>
 266
 267                 <xi:include href="version-info.xml" xpointer="v249"/>
 268               </listitem>
 269             </varlistentry>
 270             <varlistentry>
 271               <term>online</term>
 272               <listitem>
 273                 <para>all required links are online</para>
 274
 275                 <xi:include href="version-info.xml" xpointer="v249"/>
 276               </listitem>
 277             </varlistentry>
 278           </variablelist>
 279           </para>
 280
 281           <xi:include href="version-info.xml" xpointer="v219"/>
 282         </listitem>
 283
 284       </varlistentry>
 285
 286       <varlistentry>
 287         <term>
 288           <command>lldp</command>
 289           <optional><replaceable>PATTERN…</replaceable></optional>
 290         </term>
 291
 292         <listitem>
 293           <para>Show discovered LLDP (Link Layer Discovery Protocol) neighbors. If one or more
 294           <replaceable>PATTERN</replaceable>s are specified only neighbors on those interfaces are shown.
 295           Otherwise shows discovered neighbors on all interfaces. Note that for this feature to work,
 296           <varname>LLDP=</varname> must be turned on for the specific interface, see
 297           <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 298           details.</para>
 299
 300           <para>Produces output similar to:
 301           <programlisting>LINK             CHASSIS ID        SYSTEM NAME      CAPS        PORT ID           PORT DESCRIPTION
 302 enp0s25          00:e0:4c:00:00:00 GS1900           ..b........ 2                 Port #2
 303
 304 Capability Flags:
 305 o - Other; p - Repeater;  b - Bridge; w - WLAN Access Point; r - Router;
 306 t - Telephone; d - DOCSIS cable device; a - Station; c - Customer VLAN;
 307 s - Service VLAN, m - Two-port MAC Relay (TPMR)
 308
 309 1 neighbors listed.</programlisting></para>
 310
 311           <xi:include href="version-info.xml" xpointer="v219"/>
 312         </listitem>
 313       </varlistentry>
 314
 315       <varlistentry>
 316         <term>
 317           <command>label</command>
 318         </term>
 319
 320         <listitem><para>Show numerical address labels that can be used for address selection.
 321         This is the same information that
 322         <citerefentry project='die-net'><refentrytitle>ip-addrlabel</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 323         shows. See <ulink url="https://tools.ietf.org/html/rfc3484">RFC 3484</ulink>
 324         for a discussion of address labels.</para>
 325
 326         <para>Produces output similar to:
 327         <programlisting>Prefix/Prefixlen                          Label
 328         ::/0                                  1
 329     fc00::/7                                  5
 330     fec0::/10                                11
 331     2002::/16                                 2
 332     3ffe::/16                                12
 333  2001:10::/28                                 7
 334     2001::/32                                 6
 335 ::ffff:0.0.0.0/96                             4
 336         ::/96                                 3
 337        ::1/128                                0</programlisting></para>
 338
 339         <xi:include href="version-info.xml" xpointer="v234"/>
 340         </listitem>
 341       </varlistentry>
 342
 343        <varlistentry>
 344         <term>
 345           <command>delete</command>
 346           <replaceable>DEVICE…</replaceable>
 347         </term>
 348         <listitem><para>Deletes virtual netdevs. Takes interface name or index number.</para>
 349
 350         <xi:include href="version-info.xml" xpointer="v243"/></listitem>
 351       </varlistentry>
 352
 353        <varlistentry>
 354         <term>
 355           <command>up</command>
 356           <replaceable>DEVICE…</replaceable>
 357         </term>
 358         <listitem><para>Bring devices up. Takes interface name or index number.</para>
 359
 360         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 361       </varlistentry>
 362
 363        <varlistentry>
 364         <term>
 365           <command>down</command>
 366           <replaceable>DEVICE…</replaceable>
 367         </term>
 368         <listitem><para>Bring devices down. Takes interface name or index number.</para>
 369
 370         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 371       </varlistentry>
 372
 373        <varlistentry>
 374         <term>
 375           <command>renew</command>
 376           <replaceable>DEVICE…</replaceable>
 377         </term>
 378         <listitem><para>Renew dynamic configurations e.g. addresses received from DHCP server.
 379         Takes interface name or index number.</para>
 380
 381         <xi:include href="version-info.xml" xpointer="v244"/></listitem>
 382       </varlistentry>
 383
 384       <varlistentry>
 385         <term>
 386           <command>forcerenew</command>
 387           <replaceable>DEVICE…</replaceable>
 388         </term>
 389         <listitem><para>Send a FORCERENEW message to all connected clients, triggering DHCP reconfiguration.
 390         Takes interface name or index number.</para>
 391
 392         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 393       </varlistentry>
 394
 395       <varlistentry>
 396         <term>
 397           <command>reconfigure</command>
 398           <replaceable>DEVICE…</replaceable>
 399         </term>
 400         <listitem><para>Reconfigure network interfaces. Takes interface name or index number. Note that
 401         this does not reload <filename>.netdev</filename> or <filename>.network</filename>
 402         corresponding to the specified interface. So, if you edit config files, it is necessary to call
 403         <command>networkctl reload</command> first to apply new settings.</para>
 404
 405         <xi:include href="version-info.xml" xpointer="v244"/></listitem>
 406       </varlistentry>
 407
 408       <varlistentry>
 409         <term>
 410           <command>reload</command>
 411         </term>
 412         <listitem><para>Reload <filename>.netdev</filename> and <filename>.network</filename> files.
 413         If a new <filename>.netdev</filename> file is found, then the corresponding netdev is created.
 414         Note that even if an existing <filename>.netdev</filename> is modified or removed,
 415         <command>systemd-networkd</command> does not update or remove the netdev.
 416         If a new, modified or removed <filename>.network</filename> file is found, then all interfaces
 417         which match the file are reconfigured.</para>
 418
 419         <xi:include href="version-info.xml" xpointer="v244"/></listitem>
 420       </varlistentry>
 421
 422       <varlistentry>
 423         <term>
 424           <command>edit</command>
 425           <replaceable>FILE</replaceable>|<replaceable>@DEVICE</replaceable>…
 426         </term>
 427         <listitem><para>Edit network configuration files, which include <filename>.network</filename>,
 428         <filename>.netdev</filename>, and <filename>.link</filename> files. If no network config file
 429         matching the given name is found, a new one will be created under <filename>/etc/</filename>.
 430         Specially, if the name is prefixed by <literal>@</literal>, it will be treated as
 431         a network interface, and editing will be performed on the network config files associated
 432         with it. Additionally, the interface name can be suffixed with <literal>:network</literal> (default)
 433         or <literal>:link</literal>, in order to choose the type of network config to operate on.</para>
 434
 435         <para>If <option>--drop-in=</option> is specified, edit the drop-in file instead of
 436         the main configuration file. Unless <option>--no-reload</option> is specified,
 437         <command>systemd-networkd</command> will be reloaded after the edit of the
 438         <filename>.network</filename> or <filename>.netdev</filename> files finishes.
 439         The same applies for <filename>.link</filename> files and
 440         <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 441         Note that the changed link settings are not automatically applied after reloading.
 442         To achieve that, trigger uevents for the corresponding interface. Refer to
 443         <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 444         for more information.</para>
 445
 446         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 447       </varlistentry>
 448
 449       <varlistentry>
 450         <term>
 451           <command>cat</command>
 452           <replaceable>FILE</replaceable>|<replaceable>@DEVICE</replaceable>…
 453         </term>
 454         <listitem><para>Show network configuration files. This command honors
 455         the <literal>@</literal> prefix in the same way as <command>edit</command>.</para>
 456
 457         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 458       </varlistentry>
 459     </variablelist>
 460   </refsect1>
 461
 462   <refsect1>
 463     <title>Options</title>
 464
 465     <para>The following options are understood:</para>
 466
 467     <variablelist>
 468       <varlistentry>
 469         <term>
 470           <option>-a</option>
 471           <option>--all</option>
 472         </term>
 473
 474         <listitem>
 475           <para>Show all links with <command>status</command>.</para>
 476
 477           <xi:include href="version-info.xml" xpointer="v219"/>
 478         </listitem>
 479       </varlistentry>
 480
 481       <varlistentry>
 482         <term>
 483           <option>-s</option>
 484           <option>--stats</option>
 485         </term>
 486
 487         <listitem>
 488           <para>Show link statistics with <command>status</command>.</para>
 489
 490           <xi:include href="version-info.xml" xpointer="v243"/>
 491         </listitem>
 492       </varlistentry>
 493
 494       <varlistentry>
 495         <term><option>-l</option></term>
 496         <term><option>--full</option></term>
 497
 498         <listitem>
 499           <para>Do not ellipsize the output.</para>
 500
 501           <xi:include href="version-info.xml" xpointer="v245"/>
 502         </listitem>
 503       </varlistentry>
 504
 505       <varlistentry>
 506         <term><option>-n</option></term>
 507         <term><option>--lines=</option></term>
 508
 509         <listitem>
 510           <para>When used with <command>status</command>, controls the number of journal lines to show,
 511           counting from the most recent ones. Takes a positive integer argument. Defaults to 10.</para>
 512
 513           <xi:include href="version-info.xml" xpointer="v245"/>
 514         </listitem>
 515       </varlistentry>
 516
 517       <varlistentry>
 518         <term><option>--drop-in=</option><replaceable>NAME</replaceable></term>
 519
 520         <listitem>
 521           <para>When used with <command>edit</command>, edit the drop-in file <replaceable>NAME</replaceable>
 522           instead of the main configuration file.</para>
 523
 524           <xi:include href="version-info.xml" xpointer="v254"/>
 525         </listitem>
 526       </varlistentry>
 527
 528       <varlistentry>
 529         <term><option>--no-reload</option></term>
 530
 531         <listitem>
 532           <para>When used with <command>edit</command>,
 533           <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 534           or
 535           <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 536           will not be reloaded after the editing finishes.</para>
 537
 538         <xi:include href="version-info.xml" xpointer="v254"/>
 539         </listitem>
 540       </varlistentry>
 541
 542       <xi:include href="standard-options.xml" xpointer="json" />
 543       <xi:include href="standard-options.xml" xpointer="help" />
 544       <xi:include href="standard-options.xml" xpointer="version" />
 545       <xi:include href="standard-options.xml" xpointer="no-legend" />
 546       <xi:include href="standard-options.xml" xpointer="no-pager" />
 547
 548     </variablelist>
 549   </refsect1>
 550
 551   <refsect1>
 552     <title>Exit status</title>
 553
 554     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 555   </refsect1>
 556
 557   <refsect1>
 558     <title>See Also</title>
 559     <para>
 560       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 561       <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 562       <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 563       <citerefentry project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 564     </para>
 565   </refsect1>
 566 </refentry>