[thirdparty/systemd.git] / man / networkctl.xml

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  SPDX-License-Identifier: LGPL-2.1+
-->

<refentry id="networkctl" conditional='ENABLE_NETWORKD'
          xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>networkctl</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>networkctl</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>networkctl</refname>
    <refpurpose>Query the status of network links</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>networkctl</command>
      <arg choice="opt" rep="repeat">OPTIONS</arg>
      <arg choice="plain">COMMAND</arg>
      <arg choice="opt" rep="repeat">LINK</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><command>networkctl</command> may be used to introspect the
    state of the network links as seen by
    <command>systemd-networkd</command>.  Please refer to
    <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    for an introduction to the basic concepts, functionality, and
    configuration syntax.</para>
  </refsect1>

  <refsect1>
    <title>Options</title>

    <para>The following options are understood:</para>

    <variablelist>
      <varlistentry>
        <term>
          <option>-a</option>
          <option>--all</option>
        </term>

        <listitem>
          <para>Show all links with <command>status</command>.</para>
        </listitem>
      </varlistentry>

      <xi:include href="standard-options.xml" xpointer="help" />
      <xi:include href="standard-options.xml" xpointer="version" />
      <xi:include href="standard-options.xml" xpointer="no-legend" />
      <xi:include href="standard-options.xml" xpointer="no-pager" />

    </variablelist>
  </refsect1>

  <refsect1>
    <title>Commands</title>

    <para>The following commands are understood:</para>

    <variablelist>
      <varlistentry>
        <term>
          <command>list</command>
          <optional><replaceable>LINK…</replaceable></optional>
        </term>

        <listitem>
          <para>Show a list of existing links and their status. If no further arguments are specified shows all links,
          otherwise just the specified links. Produces output similar to:

          <programlisting>IDX LINK         TYPE     OPERATIONAL SETUP
  1 lo           loopback carrier     unmanaged
  2 eth0         ether    routable    configured
  3 virbr0       ether    no-carrier  unmanaged
  4 virbr0-nic   ether    off         unmanaged

4 links listed.</programlisting></para>

        <para>The operational status is one of the following:
            <variablelist>
              <varlistentry>
                <term>off</term>
                <listitem>
                  <para>the device is powered down</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>no-carrier</term>
                <listitem>
                  <para>the device is powered up, but it does not yet have a carrier</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>dormant</term>
                <listitem>
                  <para>the device has a carrier, but is not yet ready for normal traffic</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>carrier</term>
                <listitem>
                  <para>the link has a carrier</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>degraded</term>
                <listitem>
                  <para>the link has carrier and addresses valid on the local link configured</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>routable</term>
                <listitem>
                  <para>the link has carrier and routable address configured</para>
                </listitem>
              </varlistentry>
            </variablelist>
        </para>

        <para>The setup status is one of the following:
            <variablelist>
              <varlistentry>
                <term>pending</term>
                <listitem>
                  <para>udev is still processing the link, we don't yet know if we will manage it</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>failed</term>
                <listitem>
                  <para>networkd failed to manage the link</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>configuring</term>
                <listitem>
                  <para>in the process of retrieving configuration or configuring the link</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>configured</term>
                <listitem>
                  <para>link configured successfully</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>unmanaged</term>
                <listitem>
                  <para>networkd is not handling the link</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>linger</term>
                <listitem>
                  <para>the link is gone, but has not yet been dropped by networkd</para>
                </listitem>
              </varlistentry>
            </variablelist>
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <command>status</command>
          <optional><replaceable>LINK…</replaceable></optional>
        </term>

        <listitem>
          <para>Show information about the specified links: type,
          state, kernel module driver, hardware and IP address,
          configured DNS servers, etc.</para>

          <para>When no links are specified, an overall network status is shown. Also see the option
          <option>--all</option>.</para>

          <para>Produces output similar to:
          <programlisting>
●      State: routable
     Address: 10.193.76.5 on eth0
              192.168.122.1 on virbr0
              169.254.190.105 on eth0
              fe80::5054:aa:bbbb:cccc on eth0
     Gateway: 10.193.11.1 (CISCO SYSTEMS, INC.) on eth0
         DNS: 8.8.8.8
              8.8.4.4</programlisting></para>
        </listitem>

      </varlistentry>

      <varlistentry>
        <term>
          <command>lldp</command>
          <optional><replaceable>LINK…</replaceable></optional>
        </term>

        <listitem>
          <para>Show discovered LLDP (Link Layer Discovery Protocol) neighbors. If one or more link names are specified
          only neighbors on those interfaces are shown. Otherwise shows discovered neighbors on all interfaces. Note
          that for this feature to work, <varname>LLDP=</varname> must be turned on for the specific interface, see
          <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
          details.</para>

          <para>Produces output similar to:
          <programlisting>LINK             CHASSIS ID        SYSTEM NAME      CAPS        PORT ID           PORT DESCRIPTION
enp0s25          00:e0:4c:00:00:00 GS1900           ..b........ 2                 Port #2

Capability Flags:
o - Other; p - Repeater;  b - Bridge; w - WLAN Access Point; r - Router;
t - Telephone; d - DOCSIS cable device; a - Station; c - Customer VLAN;
s - Service VLAN, m - Two-port MAC Relay (TPMR)

1 neighbors listed.</programlisting></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <command>label</command>
        </term>

        <listitem><para>Show numerical address labels that can be used for address selection.
        This is the same information that
        <citerefentry><refentrytitle>ip-addrlabel</refentrytitle><manvolnum>8</manvolnum></citerefentry>
        shows. See <ulink url="https://tools.ietf.org/html/rfc3484">RFC 3484</ulink>
        for a discussion of address labels.</para>

        <para>Produces output similar to:
        <programlisting>Prefix/Prefixlen                          Label
        ::/0                                  1
    fc00::/7                                  5
    fec0::/10                                11
    2002::/16                                 2
    3ffe::/16                                12
 2001:10::/28                                 7
    2001::/32                                 6
::ffff:0.0.0.0/96                             4
        ::/96                                 3
       ::1/128                                0</programlisting></para>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>Exit status</title>

    <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    </para>
  </refsect1>
</refentry>
Commit	Line	Data
514094f9	1	<?xml version='1.0'?>
d9000fd3	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76	3	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
d9000fd3 ZJS	4
d9000fd3 ZJS	5	<!--
572eb058	6	SPDX-License-Identifier: LGPL-2.1+
d9000fd3 ZJS	7	-->
d9000fd3 ZJS	8
e6de49ab	9	<refentry id="networkctl" conditional='ENABLE_NETWORKD'
d9000fd3 ZJS	10	xmlns:xi="http://www.w3.org/2001/XInclude">
	11
	12	<refentryinfo>
	13	<title>networkctl</title>
	14	<productname>systemd</productname>
d9000fd3 ZJS	15	</refentryinfo>
	16
	17	<refmeta>
	18	<refentrytitle>networkctl</refentrytitle>
	19	<manvolnum>1</manvolnum>
	20	</refmeta>
	21
	22	<refnamediv>
	23	<refname>networkctl</refname>
cc98b302	24	<refpurpose>Query the status of network links</refpurpose>
d9000fd3 ZJS	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>
1d3eaa93	43	for an introduction to the basic concepts, functionality, and
d9000fd3 ZJS	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" />
400f73d9	66	<xi:include href="standard-options.xml" xpointer="no-legend" />
d9000fd3 ZJS	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>
1eecafb8	81	<optional><replaceable>LINK…</replaceable></optional>
d9000fd3 ZJS	82	</term>
	83
	84	<listitem>
e997c4b0 LP	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
d9000fd3 ZJS	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>
abcf95e9 JAK	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>
d9000fd3 ZJS	177	</listitem>
	178	</varlistentry>
	179
	180	<varlistentry>
	181	<term>
	182	<command>status</command>
1eecafb8	183	<optional><replaceable>LINK…</replaceable></optional>
d9000fd3 ZJS	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
e997c4b0 LP	191	<para>When no links are specified, an overall network status is shown. Also see the option
e997c4b0 LP	192	<option>--all</option>.</para>
d9000fd3	193
e997c4b0	194	<para>Produces output similar to:
d9000fd3 ZJS	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>
1eecafb8	211	<optional><replaceable>LINK…</replaceable></optional>
d9000fd3 ZJS	212	</term>
	213
	214	<listitem>
e997c4b0 LP	215	<para>Show discovered LLDP (Link Layer Discovery Protocol) neighbors. If one or more link names are specified
e997c4b0 LP	216	only neighbors on those interfaces are shown. Otherwise shows discovered neighbors on all interfaces. Note
1b2ad5d9	217	that for this feature to work, <varname>LLDP=</varname> must be turned on for the specific interface, see
e997c4b0 LP	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>
d9000fd3 ZJS	231	</listitem>
d9000fd3 ZJS	232	</varlistentry>
a5be8dab ZJS	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
d9000fd3 ZJS	260	</variablelist>
	261	</refsect1>
	262
	263	<refsect1>
	264	<title>Exit status</title>
	265
a5be8dab	266	<para>On success, 0 is returned, a non-zero failure code otherwise.</para>
d9000fd3 ZJS	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>,
a5be8dab ZJS	274	<citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
a5be8dab ZJS	275	<citerefentry project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>8</manvolnum></citerefentry>
d9000fd3 ZJS	276	</para>
	277	</refsect1>
	278	</refentry>