Adding upstream version 255.4.upstream/255.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 570 insertions, 0 deletions

diff --git a/man/networkctl.xml b/man/networkctl.xml
new file mode 100644
index 0000000..68b1d97
--- /dev/null
+++ b/man/networkctl.xml
@@ -0,0 +1,570 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<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 or modify 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 query or modify 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>Commands</title>
+
+    <para>The following commands are understood:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>
+          <command>list</command>
+          <optional><replaceable>PATTERN…</replaceable></optional>
+        </term>
+
+        <listitem>
+          <para>Show a list of existing links and their status. If one or more
+          <replaceable>PATTERN</replaceable>s are specified, only links matching one of them are shown.
+          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>missing</term>
+                <listitem>
+                    <para>The device is missing.</para>
+
+                    <xi:include href="version-info.xml" xpointer="v245"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>off</term>
+                <listitem>
+                  <para>The device is powered down.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v240"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>no-carrier</term>
+                <listitem>
+                  <para>The device is powered up, but does not yet have a carrier.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v240"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>dormant</term>
+                <listitem>
+                  <para>The device has a carrier, but is not yet ready for normal traffic.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v240"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>degraded-carrier</term>
+                <listitem>
+                  <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>
+
+                  <xi:include href="version-info.xml" xpointer="v242"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>carrier</term>
+                <listitem>
+                  <para>The link has carrier, or for bond or bridge master, all bonding or bridge slave
+                  network interfaces are enslaved to the master.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v240"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>degraded</term>
+                <listitem>
+                  <para>The link has carrier and addresses valid on the local link configured. For bond or
+                  bridge master this means that not all slave network interfaces have carrier but at least
+                  one does.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v240"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>enslaved</term>
+                <listitem>
+                  <para>The link has carrier and is enslaved to bond or bridge master network interface.
+                  </para>
+
+                  <xi:include href="version-info.xml" xpointer="v242"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>routable</term>
+                <listitem>
+                  <para>The link has carrier and routable address configured. For bond or bridge master it is
+                  not necessary for all slave network interfaces to have carrier, but at least one must.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v240"/>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+        </para>
+
+        <para>The setup status is one of the following:
+            <variablelist>
+              <varlistentry>
+                <term>pending</term>
+                <listitem>
+                  <para><citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+                  is still processing the link, we don't yet know if we will manage it.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v240"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>initialized</term>
+                <listitem>
+                  <para><citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+                  has processed the link, but we don't yet know if we will manage it.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v251"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>configuring</term>
+                <listitem>
+                  <para>Configuration for the link is being retrieved or the link is being configured.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v240"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>configured</term>
+                <listitem>
+                  <para>Link has been configured successfully.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v240"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>unmanaged</term>
+                <listitem>
+                  <para><command>systemd-networkd</command> is not handling the link.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v240"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>failed</term>
+                <listitem>
+                  <para><command>systemd-networkd</command> failed to configure the link.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v240"/>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>linger</term>
+                <listitem>
+                  <para>The link is gone, but has not yet been dropped by <command>systemd-networkd</command>.</para>
+
+                  <xi:include href="version-info.xml" xpointer="v240"/>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+        </para>
+
+        <xi:include href="version-info.xml" xpointer="v219"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>status</command>
+          <optional><replaceable>PATTERN…</replaceable></optional>
+        </term>
+
+        <listitem>
+          <para>Show information about the specified links: type, state, kernel module driver, hardware and
+          IP address, configured DNS servers, etc. If one or more <replaceable>PATTERN</replaceable>s are
+          specified, only links matching one of them are shown.</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
+  Online state: online
+       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>
+
+          <para>In the overall network status, the online state depends on the individual online state of all
+          required links. Managed links are required for online by default. In this case, the online state is
+          one of the following:
+          <variablelist>
+            <varlistentry>
+              <term>unknown</term>
+              <listitem>
+                <para>All links have unknown online status (i.e. there are no required links).</para>
+
+                <xi:include href="version-info.xml" xpointer="v249"/>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>offline</term>
+              <listitem>
+                <para>All required links are offline.</para>
+
+                <xi:include href="version-info.xml" xpointer="v249"/>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>partial</term>
+              <listitem>
+                <para>Some, but not all, required links are online.</para>
+
+                <xi:include href="version-info.xml" xpointer="v249"/>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>online</term>
+              <listitem>
+                <para>All required links are online.</para>
+
+                <xi:include href="version-info.xml" xpointer="v249"/>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+          </para>
+
+          <xi:include href="version-info.xml" xpointer="v219"/>
+        </listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>lldp</command>
+          <optional><replaceable>PATTERN…</replaceable></optional>
+        </term>
+
+        <listitem>
+          <para>Show discovered LLDP (Link Layer Discovery Protocol) neighbors. If one or more
+          <replaceable>PATTERN</replaceable>s 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>
+
+          <xi:include href="version-info.xml" xpointer="v219"/>
+        </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 project='die-net'><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>
+
+        <xi:include href="version-info.xml" xpointer="v234"/>
+        </listitem>
+      </varlistentry>
+
+       <varlistentry>
+        <term>
+          <command>delete</command>
+          <replaceable>DEVICE…</replaceable>
+        </term>
+        <listitem><para>Deletes virtual netdevs. Takes interface name or index number.</para>
+
+        <xi:include href="version-info.xml" xpointer="v243"/></listitem>
+      </varlistentry>
+
+       <varlistentry>
+        <term>
+          <command>up</command>
+          <replaceable>DEVICE…</replaceable>
+        </term>
+        <listitem><para>Bring devices up. Takes interface name or index number.</para>
+
+        <xi:include href="version-info.xml" xpointer="v246"/></listitem>
+      </varlistentry>
+
+       <varlistentry>
+        <term>
+          <command>down</command>
+          <replaceable>DEVICE…</replaceable>
+        </term>
+        <listitem><para>Bring devices down. Takes interface name or index number.</para>
+
+        <xi:include href="version-info.xml" xpointer="v246"/></listitem>
+      </varlistentry>
+
+       <varlistentry>
+        <term>
+          <command>renew</command>
+          <replaceable>DEVICE…</replaceable>
+        </term>
+        <listitem><para>Renew dynamic configurations e.g. addresses received from DHCP server.
+        Takes interface name or index number.</para>
+
+        <xi:include href="version-info.xml" xpointer="v244"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>forcerenew</command>
+          <replaceable>DEVICE…</replaceable>
+        </term>
+        <listitem><para>Send a FORCERENEW message to all connected clients, triggering DHCP reconfiguration.
+        Takes interface name or index number.</para>
+
+        <xi:include href="version-info.xml" xpointer="v246"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>reconfigure</command>
+          <replaceable>DEVICE…</replaceable>
+        </term>
+        <listitem><para>Reconfigure network interfaces. Takes interface name or index number. Note that
+        this does not reload <filename>.netdev</filename> or <filename>.network</filename>
+        corresponding to the specified interface. So, if you edit config files, it is necessary to call
+        <command>networkctl reload</command> first to apply new settings.</para>
+
+        <xi:include href="version-info.xml" xpointer="v244"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>reload</command>
+        </term>
+        <listitem><para>Reload <filename>.netdev</filename> and <filename>.network</filename> files.
+        If a new <filename>.netdev</filename> file is found, then the corresponding netdev is created.
+        Note that even if an existing <filename>.netdev</filename> is modified or removed,
+        <command>systemd-networkd</command> does not update or remove the netdev.
+        If a new, modified or removed <filename>.network</filename> file is found, then all interfaces
+        which match the file are reconfigured.</para>
+
+        <xi:include href="version-info.xml" xpointer="v244"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>edit</command>
+          <replaceable>FILE</replaceable>|<replaceable>@DEVICE</replaceable>…
+        </term>
+        <listitem><para>Edit network configuration files, which include <filename>.network</filename>,
+        <filename>.netdev</filename>, and <filename>.link</filename> files. If no network config file
+        matching the given name is found, a new one will be created under <filename>/etc/</filename>.
+        Specially, if the name is prefixed by <literal>@</literal>, it will be treated as
+        a network interface, and editing will be performed on the network config files associated
+        with it. Additionally, the interface name can be suffixed with <literal>:network</literal> (default)
+        or <literal>:link</literal>, in order to choose the type of network config to operate on.</para>
+
+        <para>If <option>--drop-in=</option> is specified, edit the drop-in file instead of
+        the main configuration file. Unless <option>--no-reload</option> is specified,
+        <command>systemd-networkd</command> will be reloaded after the edit of the
+        <filename>.network</filename> or <filename>.netdev</filename> files finishes.
+        The same applies for <filename>.link</filename> files and
+        <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+        Note that the changed link settings are not automatically applied after reloading.
+        To achieve that, trigger uevents for the corresponding interface. Refer to
+        <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        for more information.</para>
+
+        <xi:include href="version-info.xml" xpointer="v254"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>cat</command>
+          <replaceable>FILE</replaceable>|<replaceable>@DEVICE</replaceable>…
+        </term>
+        <listitem><para>Show network configuration files. This command honors
+        the <literal>@</literal> prefix in the same way as <command>edit</command>.</para>
+
+        <xi:include href="version-info.xml" xpointer="v254"/></listitem>
+      </varlistentry>
+    </variablelist>
+  </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>
+
+          <xi:include href="version-info.xml" xpointer="v219"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>-s</option>
+          <option>--stats</option>
+        </term>
+
+        <listitem>
+          <para>Show link statistics with <command>status</command>.</para>
+
+          <xi:include href="version-info.xml" xpointer="v243"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-l</option></term>
+        <term><option>--full</option></term>
+
+        <listitem>
+          <para>Do not ellipsize the output.</para>
+
+          <xi:include href="version-info.xml" xpointer="v245"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-n</option></term>
+        <term><option>--lines=</option></term>
+
+        <listitem>
+          <para>When used with <command>status</command>, controls the number of journal lines to show,
+          counting from the most recent ones. Takes a positive integer argument. Defaults to 10.</para>
+
+          <xi:include href="version-info.xml" xpointer="v245"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--drop-in=</option><replaceable>NAME</replaceable></term>
+
+        <listitem>
+          <para>When used with <command>edit</command>, edit the drop-in file <replaceable>NAME</replaceable>
+          instead of the main configuration file.</para>
+
+          <xi:include href="version-info.xml" xpointer="v254"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--no-reload</option></term>
+
+        <listitem>
+          <para>When used with <command>edit</command>,
+          <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+          or
+          <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+          will not be reloaded after the editing finishes.</para>
+
+        <xi:include href="version-info.xml" xpointer="v254"/>
+        </listitem>
+      </varlistentry>
+
+      <xi:include href="standard-options.xml" xpointer="json" />
+      <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>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>