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+ -->
   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 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 introspect 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>Options</title>
  46
  47     <para>The following options are understood:</para>
  48
  49     <variablelist>
  50       <varlistentry>
  51         <term>
  52           <option>-a</option>
  53           <option>--all</option>
  54         </term>
  55
  56         <listitem>
  57           <para>Show all links with <command>status</command>.</para>
  58         </listitem>
  59       </varlistentry>
  60
  61       <varlistentry>
  62         <term>
  63           <option>-s</option>
  64           <option>--stats</option>
  65         </term>
  66
  67         <listitem>
  68           <para>Show link statistics with <command>status</command>.</para>
  69         </listitem>
  70       </varlistentry>
  71
  72       <xi:include href="standard-options.xml" xpointer="help" />
  73       <xi:include href="standard-options.xml" xpointer="version" />
  74       <xi:include href="standard-options.xml" xpointer="no-legend" />
  75       <xi:include href="standard-options.xml" xpointer="no-pager" />
  76
  77     </variablelist>
  78   </refsect1>
  79
  80   <refsect1>
  81     <title>Commands</title>
  82
  83     <para>The following commands are understood:</para>
  84
  85     <variablelist>
  86       <varlistentry>
  87         <term>
  88           <command>list</command>
  89           <optional><replaceable>PATTERN…</replaceable></optional>
  90         </term>
  91
  92         <listitem>
  93           <para>Show a list of existing links and their status. If one ore more
  94           <replaceable>PATTERN</replaceable>s are specified, only links matching one of them are shown.
  95           If no further arguments are specified shows all links,
  96           otherwise just the specified links. Produces output similar to:
  97
  98           <programlisting>IDX LINK         TYPE     OPERATIONAL SETUP
  99   1 lo           loopback carrier     unmanaged
 100   2 eth0         ether    routable    configured
 101   3 virbr0       ether    no-carrier  unmanaged
 102   4 virbr0-nic   ether    off         unmanaged
 103
 104 4 links listed.</programlisting></para>
 105
 106         <para>The operational status is one of the following:
 107             <variablelist>
 108               <varlistentry>
 109                 <term>off</term>
 110                 <listitem>
 111                   <para>the device is powered down</para>
 112                 </listitem>
 113               </varlistentry>
 114               <varlistentry>
 115                 <term>no-carrier</term>
 116                 <listitem>
 117                   <para>the device is powered up, but it does not yet have a carrier</para>
 118                 </listitem>
 119               </varlistentry>
 120               <varlistentry>
 121                 <term>dormant</term>
 122                 <listitem>
 123                   <para>the device has a carrier, but is not yet ready for normal traffic</para>
 124                 </listitem>
 125               </varlistentry>
 126               <varlistentry>
 127                 <term>degraded-carrier</term>
 128                 <listitem>
 129                   <para>for bond or bridge master, one of the bonding or bridge slave network interfaces is
 130                   in off, no-carrier, or dormant state</para>
 131                 </listitem>
 132               </varlistentry>
 133               <varlistentry>
 134                 <term>carrier</term>
 135                 <listitem>
 136                   <para>the link has a carrier, or for bond or bridge master, all bonding or bridge slave
 137                   network interfaces are enslaved to the master.</para>
 138                 </listitem>
 139               </varlistentry>
 140               <varlistentry>
 141                 <term>degraded</term>
 142                 <listitem>
 143                   <para>the link has carrier and addresses valid on the local link configured</para>
 144                 </listitem>
 145               </varlistentry>
 146               <varlistentry>
 147                 <term>enslaved</term>
 148                 <listitem>
 149                   <para>the link has carrier and is enslaved to bond or bridge master network interface</para>
 150                 </listitem>
 151               </varlistentry>
 152               <varlistentry>
 153                 <term>routable</term>
 154                 <listitem>
 155                   <para>the link has carrier and routable address configured</para>
 156                 </listitem>
 157               </varlistentry>
 158             </variablelist>
 159         </para>
 160
 161         <para>The setup status is one of the following:
 162             <variablelist>
 163               <varlistentry>
 164                 <term>pending</term>
 165                 <listitem>
 166                   <para>udev is still processing the link, we don't yet know if we will manage it</para>
 167                 </listitem>
 168               </varlistentry>
 169               <varlistentry>
 170                 <term>failed</term>
 171                 <listitem>
 172                   <para>networkd failed to manage the link</para>
 173                 </listitem>
 174               </varlistentry>
 175               <varlistentry>
 176                 <term>configuring</term>
 177                 <listitem>
 178                   <para>in the process of retrieving configuration or configuring the link</para>
 179                 </listitem>
 180               </varlistentry>
 181               <varlistentry>
 182                 <term>configured</term>
 183                 <listitem>
 184                   <para>link configured successfully</para>
 185                 </listitem>
 186               </varlistentry>
 187               <varlistentry>
 188                 <term>unmanaged</term>
 189                 <listitem>
 190                   <para>networkd is not handling the link</para>
 191                 </listitem>
 192               </varlistentry>
 193               <varlistentry>
 194                 <term>linger</term>
 195                 <listitem>
 196                   <para>the link is gone, but has not yet been dropped by networkd</para>
 197                 </listitem>
 198               </varlistentry>
 199             </variablelist>
 200         </para>
 201         </listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term>
 206           <command>status</command>
 207           <optional><replaceable>PATTERN…</replaceable></optional>
 208         </term>
 209
 210         <listitem>
 211           <para>Show information about the specified links: type, state, kernel module driver, hardware and
 212           IP address, configured DNS servers, etc. If one ore more <replaceable>PATTERN</replaceable>s are
 213           specified, only links matching one of them are shown.</para>
 214
 215           <para>When no links are specified, an overall network status is shown. Also see the option
 216           <option>--all</option>.</para>
 217
 218           <para>Produces output similar to:
 219           <programlisting>
 220 ●      State: routable
 221      Address: 10.193.76.5 on eth0
 222               192.168.122.1 on virbr0
 223               169.254.190.105 on eth0
 224               fe80::5054:aa:bbbb:cccc on eth0
 225      Gateway: 10.193.11.1 (CISCO SYSTEMS, INC.) on eth0
 226          DNS: 8.8.8.8
 227               8.8.4.4</programlisting></para>
 228         </listitem>
 229
 230       </varlistentry>
 231
 232       <varlistentry>
 233         <term>
 234           <command>lldp</command>
 235           <optional><replaceable>PATTERN…</replaceable></optional>
 236         </term>
 237
 238         <listitem>
 239           <para>Show discovered LLDP (Link Layer Discovery Protocol) neighbors. If one or more
 240           <replaceable>PATTERN</replaceable>s are specified only neighbors on those interfaces are shown.
 241           Otherwise shows discovered neighbors on all interfaces. Note that for this feature to work,
 242           <varname>LLDP=</varname> must be turned on for the specific interface, see
 243           <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 244           details.</para>
 245
 246           <para>Produces output similar to:
 247           <programlisting>LINK             CHASSIS ID        SYSTEM NAME      CAPS        PORT ID           PORT DESCRIPTION
 248 enp0s25          00:e0:4c:00:00:00 GS1900           ..b........ 2                 Port #2
 249
 250 Capability Flags:
 251 o - Other; p - Repeater;  b - Bridge; w - WLAN Access Point; r - Router;
 252 t - Telephone; d - DOCSIS cable device; a - Station; c - Customer VLAN;
 253 s - Service VLAN, m - Two-port MAC Relay (TPMR)
 254
 255 1 neighbors listed.</programlisting></para>
 256         </listitem>
 257       </varlistentry>
 258
 259       <varlistentry>
 260         <term>
 261           <command>label</command>
 262         </term>
 263
 264         <listitem><para>Show numerical address labels that can be used for address selection.
 265         This is the same information that
 266         <citerefentry><refentrytitle>ip-addrlabel</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 267         shows. See <ulink url="https://tools.ietf.org/html/rfc3484">RFC 3484</ulink>
 268         for a discussion of address labels.</para>
 269
 270         <para>Produces output similar to:
 271         <programlisting>Prefix/Prefixlen                          Label
 272         ::/0                                  1
 273     fc00::/7                                  5
 274     fec0::/10                                11
 275     2002::/16                                 2
 276     3ffe::/16                                12
 277  2001:10::/28                                 7
 278     2001::/32                                 6
 279 ::ffff:0.0.0.0/96                             4
 280         ::/96                                 3
 281        ::1/128                                0</programlisting></para>
 282         </listitem>
 283       </varlistentry>
 284
 285        <varlistentry>
 286         <term>
 287           <command>delete</command>
 288         </term>
 289         <listitem><para>Deletes virtual netdevs. Takes interface name or index number.</para></listitem>
 290       </varlistentry>
 291
 292     </variablelist>
 293   </refsect1>
 294
 295   <refsect1>
 296     <title>Exit status</title>
 297
 298     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 299   </refsect1>
 300
 301   <refsect1>
 302     <title>See Also</title>
 303     <para>
 304       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 305       <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 306       <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 307       <citerefentry project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 308     </para>
 309   </refsect1>
 310 </refentry>