man/networkctl.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="networkctl" conditional='ENABLE_NETWORKD'
  10           xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>networkctl</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>networkctl</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>networkctl</refname>
  24     <refpurpose>Query the status of network links</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  29       <command>networkctl</command>
  30       <arg choice="opt" rep="repeat">OPTIONS</arg>
  31       <arg choice="plain">COMMAND</arg>
  32       <arg choice="opt" rep="repeat">LINK</arg>
  33     </cmdsynopsis>
  34   </refsynopsisdiv>
  35
  36   <refsect1>
  37     <title>Description</title>
  38
  39     <para><command>networkctl</command> may be used to introspect the
  40     state of the network links as seen by
  41     <command>systemd-networkd</command>.  Please refer to
  42     <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  43     for an introduction to the basic concepts, functionality, and
  44     configuration syntax.</para>
  45   </refsect1>
  46
  47   <refsect1>
  48     <title>Options</title>
  49
  50     <para>The following options are understood:</para>
  51
  52     <variablelist>
  53       <varlistentry>
  54         <term>
  55           <option>-a</option>
  56           <option>--all</option>
  57         </term>
  58
  59         <listitem>
  60           <para>Show all links with <command>status</command>.</para>
  61         </listitem>
  62       </varlistentry>
  63
  64       <xi:include href="standard-options.xml" xpointer="help" />
  65       <xi:include href="standard-options.xml" xpointer="version" />
  66       <xi:include href="standard-options.xml" xpointer="no-legend" />
  67       <xi:include href="standard-options.xml" xpointer="no-pager" />
  68
  69     </variablelist>
  70   </refsect1>
  71
  72   <refsect1>
  73     <title>Commands</title>
  74
  75     <para>The following commands are understood:</para>
  76
  77     <variablelist>
  78       <varlistentry>
  79         <term>
  80           <command>list</command>
  81           <optional><replaceable>LINK…</replaceable></optional>
  82         </term>
  83
  84         <listitem>
  85           <para>Show a list of existing links and their status. If no further arguments are specified shows all links,
  86           otherwise just the specified links. Produces output similar to:
  87
  88           <programlisting>IDX LINK         TYPE     OPERATIONAL SETUP
  89   1 lo           loopback carrier     unmanaged
  90   2 eth0         ether    routable    configured
  91   3 virbr0       ether    no-carrier  unmanaged
  92   4 virbr0-nic   ether    off         unmanaged
  93
  94 4 links listed.</programlisting></para>
  95
  96         <para>The operational status is one of the following:
  97             <variablelist>
  98               <varlistentry>
  99                 <term>off</term>
 100                 <listitem>
 101                   <para>the device is powered down</para>
 102                 </listitem>
 103               </varlistentry>
 104               <varlistentry>
 105                 <term>no-carrier</term>
 106                 <listitem>
 107                   <para>the device is powered up, but it does not yet have a carrier</para>
 108                 </listitem>
 109               </varlistentry>
 110               <varlistentry>
 111                 <term>dormant</term>
 112                 <listitem>
 113                   <para>the device has a carrier, but is not yet ready for normal traffic</para>
 114                 </listitem>
 115               </varlistentry>
 116               <varlistentry>
 117                 <term>carrier</term>
 118                 <listitem>
 119                   <para>the link has a carrier</para>
 120                 </listitem>
 121               </varlistentry>
 122               <varlistentry>
 123                 <term>degraded</term>
 124                 <listitem>
 125                   <para>the link has carrier and addresses valid on the local link configured</para>
 126                 </listitem>
 127               </varlistentry>
 128               <varlistentry>
 129                 <term>routable</term>
 130                 <listitem>
 131                   <para>the link has carrier and routable address configured</para>
 132                 </listitem>
 133               </varlistentry>
 134             </variablelist>
 135         </para>
 136
 137         <para>The setup status is one of the following:
 138             <variablelist>
 139               <varlistentry>
 140                 <term>pending</term>
 141                 <listitem>
 142                   <para>udev is still processing the link, we don't yet know if we will manage it</para>
 143                 </listitem>
 144               </varlistentry>
 145               <varlistentry>
 146                 <term>failed</term>
 147                 <listitem>
 148                   <para>networkd failed to manage the link</para>
 149                 </listitem>
 150               </varlistentry>
 151               <varlistentry>
 152                 <term>configuring</term>
 153                 <listitem>
 154                   <para>in the process of retrieving configuration or configuring the link</para>
 155                 </listitem>
 156               </varlistentry>
 157               <varlistentry>
 158                 <term>configured</term>
 159                 <listitem>
 160                   <para>link configured successfully</para>
 161                 </listitem>
 162               </varlistentry>
 163               <varlistentry>
 164                 <term>unmanaged</term>
 165                 <listitem>
 166                   <para>networkd is not handling the link</para>
 167                 </listitem>
 168               </varlistentry>
 169               <varlistentry>
 170                 <term>linger</term>
 171                 <listitem>
 172                   <para>the link is gone, but has not yet been dropped by networkd</para>
 173                 </listitem>
 174               </varlistentry>
 175             </variablelist>
 176         </para>
 177         </listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term>
 182           <command>status</command>
 183           <optional><replaceable>LINK…</replaceable></optional>
 184         </term>
 185
 186         <listitem>
 187           <para>Show information about the specified links: type,
 188           state, kernel module driver, hardware and IP address,
 189           configured DNS servers, etc.</para>
 190
 191           <para>When no links are specified, an overall network status is shown. Also see the option
 192           <option>--all</option>.</para>
 193
 194           <para>Produces output similar to:
 195           <programlisting>
 196 ●      State: routable
 197      Address: 10.193.76.5 on eth0
 198               192.168.122.1 on virbr0
 199               169.254.190.105 on eth0
 200               fe80::5054:aa:bbbb:cccc on eth0
 201      Gateway: 10.193.11.1 (CISCO SYSTEMS, INC.) on eth0
 202          DNS: 8.8.8.8
 203               8.8.4.4</programlisting></para>
 204         </listitem>
 205
 206       </varlistentry>
 207
 208       <varlistentry>
 209         <term>
 210           <command>lldp</command>
 211           <optional><replaceable>LINK…</replaceable></optional>
 212         </term>
 213
 214         <listitem>
 215           <para>Show discovered LLDP (Link Layer Discovery Protocol) neighbors. If one or more link names are specified
 216           only neighbors on those interfaces are shown. Otherwise shows discovered neighbors on all interfaces. Note
 217           that for this feature to work, <varname>LLDP=</varname> must be turned on for the specific interface, see
 218           <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 219           details.</para>
 220
 221           <para>Produces output similar to:
 222           <programlisting>LINK             CHASSIS ID        SYSTEM NAME      CAPS        PORT ID           PORT DESCRIPTION
 223 enp0s25          00:e0:4c:00:00:00 GS1900           ..b........ 2                 Port #2
 224
 225 Capability Flags:
 226 o - Other; p - Repeater;  b - Bridge; w - WLAN Access Point; r - Router;
 227 t - Telephone; d - DOCSIS cable device; a - Station; c - Customer VLAN;
 228 s - Service VLAN, m - Two-port MAC Relay (TPMR)
 229
 230 1 neighbors listed.</programlisting></para>
 231         </listitem>
 232       </varlistentry>
 233
 234       <varlistentry>
 235         <term>
 236           <command>label</command>
 237         </term>
 238
 239         <listitem><para>Show numerical address labels that can be used for address selection.
 240         This is the same information that
 241         <citerefentry><refentrytitle>ip-addrlabel</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 242         shows. See <ulink url="https://tools.ietf.org/html/rfc3484">RFC 3484</ulink>
 243         for a discussion of address labels.</para>
 244
 245         <para>Produces output similar to:
 246         <programlisting>Prefix/Prefixlen                          Label
 247         ::/0                                  1
 248     fc00::/7                                  5
 249     fec0::/10                                11
 250     2002::/16                                 2
 251     3ffe::/16                                12
 252  2001:10::/28                                 7
 253     2001::/32                                 6
 254 ::ffff:0.0.0.0/96                             4
 255         ::/96                                 3
 256        ::1/128                                0</programlisting></para>
 257         </listitem>
 258       </varlistentry>
 259
 260     </variablelist>
 261   </refsect1>
 262
 263   <refsect1>
 264     <title>Exit status</title>
 265
 266     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 267   </refsect1>
 268
 269   <refsect1>
 270     <title>See Also</title>
 271     <para>
 272       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 273       <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 274       <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 275       <citerefentry project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 276     </para>
 277   </refsect1>
 278 </refentry>