diff options
Diffstat (limited to 'man/networkctl.xml')
| -rw-r--r-- | man/networkctl.xml | 570 |
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> |