glfs/networking/netutils/networkmanager.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY NetworkManager-download-http
"&gnome-download-http;/NetworkManager/&NetworkManager-minor;/NetworkManager-&NetworkManager-version;.tar.xz">
  <!ENTITY NetworkManager-download-ftp
"&gnome-download-ftp;/NetworkManager/&NetworkManager-minor;/NetworkManager-&NetworkManager-version;.tar.xz">
  <!ENTITY NetworkManager-md5sum        "bd6c9cb0ecd0fb7f516cde7bf4dee3fb">
  <!ENTITY NetworkManager-size          "6.6 MB">
  <!ENTITY NetworkManager-buildsize     "904 MB (with tests and documentation)">
  <!ENTITY NetworkManager-time          "1.2 SBU (with tests, using parallelism=4)">
]>

<sect1 id="NetworkManager" xreflabel="NetworkManager-&NetworkManager-version;">
  <?dbhtml filename="networkmanager.html"?>


  <title>NetworkManager-&NetworkManager-version;</title>

  <indexterm zone="NetworkManager">
    <primary sortas="a-NetworkManager">NetworkManager</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to NetworkManager</title>

    <para>
      <application>NetworkManager</application> is a set of co-operative
      tools that make networking simple and straightforward. Whether you use WiFi,
      wired, 3G, or Bluetooth, NetworkManager allows you to quickly move from
      one network to another: Once a network has been configured and joined
      once, it can be detected and re-joined automatically the next time it's
      available.
    </para>

    &lfs120_checked;

    <note revision="systemd">
      <para>
        Make sure that you disable the <command>systemd-networkd</command>
        service or configure it not to manage the interfaces you want to manage
        with <application>NetworkManager</application>.
      </para>
    </note>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&NetworkManager-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&NetworkManager-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &NetworkManager-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &NetworkManager-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &NetworkManager-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &NetworkManager-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">NetworkManager Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="jansson"/> and
      <xref linkend="libndp"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="curl"/>,
      <xref linkend="dhcpcd"/>,
      <xref linkend="gobject-introspection"/>,
      <xref linkend="iptables"/>,
      <xref linkend="newt"/> (for <command>nmtui</command>),
      <xref linkend="nss"/>,
      <xref role='runtime' linkend="polkit"/> (runtime),
      <xref linkend="pygobject3"/>,
      <phrase revision="sysv"><xref linkend="elogind"/>,</phrase>
      <phrase revision="systemd"><xref linkend="systemd"/>,</phrase>
      <xref linkend="vala"/>, and
      <xref linkend="wpa_supplicant"/> (runtime, built with D-Bus support)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="bluez"/>,
      <xref linkend="dbus-python"/> (for the test suite),
      <!-- <xref linkend="firewalld"/> (For whenever firewalld is reintroduced) -->
      <xref linkend="gnutls"/> (can be used instead of <xref linkend="nss"/>),
      <xref linkend="gtk-doc"/>,
      <xref linkend="libpsl"/>,
      (<xref linkend="qt5"/> or
       <xref role="node" linkend="qt5-components"/> with qtdoc) (for examples),
      <xref linkend="ModemManager"/>,
      <xref linkend="upower"/>,
      <xref linkend="valgrind"/>,
      <ulink url="https://thekelleys.org.uk/dnsmasq/doc.html">dnsmasq</ulink>,
      <ulink url="https://firewalld.org/">firewalld</ulink>,
      <ulink url="https://github.com/Distrotech/libaudit">libaudit</ulink>,
      <ulink url="https://github.com/jpirko/libteam">libteam</ulink>,
      <ulink url="&gnome-download-http;/mobile-broadband-provider-info/">mobile-broadband-provider-info</ulink>,
      <ulink url="https://www.samba.org/ftp/ppp/">PPP</ulink>, and
      <ulink url="https://dianne.skoll.ca/projects/rp-pppoe/">RP-PPPoE</ulink>
    </para>

  </sect2>

  <sect2 role="kernel" id="NetworkManager-kernel">
    <title>Kernel Configuration</title>

    <para>
      If you wish to run the tests, check that at least the following options
      are enabled in the kernel configuration. Those options have been
      determined to be necessary, but may not be sufficient. Recompile the
      kernel if necessary:
    </para>

    <!-- Ethernet Teaming support is potentially optional, but I didn't
         run the tests again to test that. It was needed to convince one of
         the Linux Platform tests to move farther along because otherwise
         RTNETLINK would respond with an Error 95 - unknown device type.
         This would cause the test to fail early on in the process.

         [pierre, Nov 2022]: I cannot tell whether these options are
         the only ones that are needed. They are the options I had to add
         in order to have some tests pass. But I already had some other
         options set for packet filtering (iptables), that may not be
         available by default and may be necessary. Even with the options
         below still one test (test-route) fails.-->

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="networkmanager-test-kernel.xml"/>

    <indexterm zone="NetworkManager NetworkManager-kernel">
      <primary sortas="d-NetworkManager">NetworkManager (test)</primary>
    </indexterm>
  </sect2>

  <sect2 role="installation">
    <title>Installation of NetworkManager</title>

    <para>
      If <xref linkend="qt5"/> is installed and the Qt based
      examples are desired, fix two meson.build files:
    </para>

<screen><userinput>sed -e 's/-qt4/-qt5/'              \
    -e 's/moc_location/host_bins/' \
    -i examples/C/qt/meson.build   &amp;&amp;

sed -e 's/Qt/&amp;5/'                  \
    -i meson.build</userinput></screen>

<!--
    <para>
      Fix a missing meson.build file for initrd hooks (not used in BLFS):
    </para>

<screen><userinput>sed '/initrd/d' -i src/core/meson.build</userinput></screen>
-->

    <para>
      Fix the python scripts so that they use <application>Python
      3</application>:
    </para>

<screen><userinput>grep -rl '^#!.*python$' | xargs sed -i '1s/python/&amp;3/'</userinput></screen>

    <para>
      Install <application>NetworkManager</application> by running the
      following commands:
    </para>

<screen revision="sysv"><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

CXXFLAGS+="-O2 -fPIC"            \
meson setup ..                   \
      --prefix=/usr              \
      --buildtype=release        \
      -Dlibaudit=no              \
      -Dlibpsl=false             \
      -Dnmtui=true               \
      -Dovs=false                \
      -Dppp=false                \
      -Dselinux=false            \
      -Dsession_tracking=elogind \
      -Dmodem_manager=false      \
      -Dsystemdsystemunitdir=no  \
      -Dsystemd_journal=false    \
      -Dqt=false                 &amp;&amp;
ninja</userinput></screen>

<screen revision="systemd"><userinput>mkdir build &amp;&amp;
cd    build    &amp;&amp;

CXXFLAGS+="-O2 -fPIC"            \
meson setup ..                   \
      --prefix=/usr              \
      --buildtype=release        \
      -Dlibaudit=no              \
      -Dlibpsl=false             \
      -Dnmtui=true               \
      -Dovs=false                \
      -Dppp=false                \
      -Dselinux=false            \
      -Dqt=false                 \
      -Dsession_tracking=systemd \
      -Dmodem_manager=false      &amp;&amp;
ninja</userinput></screen>

    <para>
      An already active graphical session with a bus address is necessary
      to run the tests. To test the results, issue
      <command>ninja test</command>.
    </para>

    <para>
      A few tests may fail, depending on enabled kernel options.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>ninja install &amp;&amp;
mv -v /usr/share/doc/NetworkManager{,-&NetworkManager-version;}</userinput></screen>

    <para>
      If you have not passed the <option>-Ddocs=true</option> option to
      <command>meson</command>, you can install the pregenerated manual pages
      with (as the &root; user):
    </para>

<screen role="root"><userinput>for file in $(echo ../man/*.[1578]); do
    section=${file##*.} &amp;&amp;
    install -vdm 755 /usr/share/man/man$section
    install -vm 644 $file /usr/share/man/man$section/
done</userinput></screen>

    <para>
      If you have not used <option>-Ddocs=true</option>, the
      pregenerated HTML documentation can also be installed with (as
      the &root; user):
    </para>

<screen role="root"
        remap="doc"><userinput>cp -Rv ../docs/{api,libnm} /usr/share/doc/NetworkManager-&NetworkManager-version;</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <envar>CXXFLAGS="-O2 -fPIC"</envar>: These compiler options are
      necessary to build the Qt5 based examples.
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/meson-buildtype-release.xml"/>

    <para>
      <option>-Ddocs=true</option>: Use this switch to enable building
      man pages and documentation if <xref linkend="gtk-doc"/> is installed.
    </para>

    <para>
      <parameter>-Dnmtui=true</parameter>: This switch enables building
      <command>nmtui</command>.
    </para>

    <para revision="sysv">
      <parameter>-Dsystemdsystemunitdir=no</parameter> and
      <parameter>-Dsystemd_journal=false</parameter>: systemd is not
      used for sysv init systems, so prevent installing units and using the
      systemd journal.
    </para>

    <para>
      <parameter>-Dlibpsl=false</parameter> and
      <parameter>-Dovs=false</parameter>: These switches disable building with
      the respective libraries. Remove these if you have the needed libraries
      installed on your system.
    </para>

    <para>
      <parameter>-Dmodem_manager=false</parameter>: This switch is required if
      <application>ModemManager</application> is not installed. Omit this switch
      if you have built <application>ModemManager</application> and
      <application>mobile-broadband-provider-info</application>.
    </para>

    <para revision="sysv">
      <parameter>-Dsession_tracking=elogind</parameter>: This switch
      is used to set <command>elogind</command> as the default
      program for session tracking.
    </para>

    <para revision="systemd">
      <parameter>-Dsession_tracking=systemd</parameter>: This switch
      is used to set <command>systemd-logind</command> as the default
      program for session tracking.
    </para>

    <para revision="systemd">
      <parameter>-Dsystemdsystemunitdir=/lib/systemd/system</parameter>:
      This switch is used to set the correct installation directory for
      systemd units.
    </para>

    <para>
      <parameter>-Dppp=false</parameter>: This switch disables
      <application>PPP</application> support in
      <application>NetworkManager</application> since the programs necessary
      for it are not installed. Remove this switch if you need PPP support and
      have <application>PPP</application> installed.
    </para>

    <para>
      <parameter>-Dlibaudit=no</parameter> and
      <parameter>-Dselinux=false</parameter>: This switch disables support for
      libaudit and SELinux since they are not used in BLFS.
    </para>

    <para>
      <parameter>-Dqt=false</parameter>: This switch disables the
      <application>Qt</application> examples. Omit if you have
      <application>Qt</application> available and wish to install the examples.
    </para>

    <para>
      <option>-Dcrypto=gnutls</option>: Use this switch if you have GnuTLS
      installed and want to use it for certificate and key operations in
      NetworkManager, instead of using NSS (the default).
    </para>

    <para>
      <option>-Dcrypto=null</option>: Use this switch if neither NSS nor
      GnuTLS is installed but you want to build NetworkManager anyway.  This
      switch will make NetworkManager lack some features (for example
      802.1X).
    </para>

    <para>
      <option>-Dsuspend_resume=upower</option>: Use this switch if
      you have <xref linkend='upower'/> installed and want to use it
      (instead of &logind;) for suspend and resume support.
    </para>
  </sect2>

  <sect2 role="configuration">
    <title>Configuring NetworkManager</title>

    <sect3 id="NetworkManager-config">
      <title>Config Files</title>
      <para>
        <filename>/etc/NetworkManager/NetworkManager.conf</filename>
      </para>

      <indexterm zone="NetworkManager NetworkManager-config">
        <primary
        sortas="e-etc-NetworkManager-NetworkManager.conf">
        /etc/NetworkManager/NetworkManager.conf</primary>
      </indexterm>

    </sect3>

    <sect3><title>Configuration Information</title>

      <para>
        For <application>NetworkManager</application> to work, at least
        a minimal configuration file must be present. Such a file is not
        installed with <command>make install</command>. Issue the following
        command as the <systemitem class="username">root</systemitem> user to
        create a minimal <filename>NetworkManager.conf</filename> file:
      </para>

<screen role="root"><userinput>cat &gt;&gt; /etc/NetworkManager/NetworkManager.conf &lt;&lt; "EOF"
<literal>[main]
plugins=keyfile</literal>
EOF</userinput></screen>

      <para>
        This file should not be modified directly by users of the system.
        Instead, system specific changes should be made using configuration
        files in the
        <filename class="directory">/etc/NetworkManager/conf.d</filename>
        directory.
      </para>

      <para>
        To allow polkit to manage authorizations, add the following
        configuration file:
      </para>

<screen role="root"><userinput>cat &gt; /etc/NetworkManager/conf.d/polkit.conf &lt;&lt; "EOF"
<literal>[main]
auth-polkit=true</literal>
EOF</userinput></screen>

      <para>
        To use something other than the built-in dhcp client (recommended if
        using only <command>nmcli</command>), use the following configuration
        (valid values include either dhcpcd or internal):
      </para>

<screen role="nodump"><userinput>cat &gt; /etc/NetworkManager/conf.d/dhcp.conf &lt;&lt; "EOF"
<literal>[main]
dhcp=</literal><replaceable>dhcpcd</replaceable>
EOF</userinput></screen>

      <para>
        To prevent <application>NetworkManager</application> from updating the
        <filename>/etc/resolv.conf</filename> file, add the following
        configuration file:
      </para>

<screen role="nodump"><userinput>cat &gt; /etc/NetworkManager/conf.d/no-dns-update.conf &lt;&lt; "EOF"
<literal>[main]
dns=none</literal>
EOF</userinput></screen>

      <para>
        For additional configuration options, see
        <command>man 5 NetworkManager.conf</command>.
      </para>

      <para>
        To allow regular users to configure network connections,
        you should add them to the
        <systemitem class="groupname">netdev</systemitem>
        group, and create a <application>polkit</application> rule that grants
        access. Run the following commands as the
        <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>groupadd -fg 86 netdev &amp;&amp;
/usr/sbin/usermod -a -G netdev <replaceable>&lt;username&gt;</replaceable>

cat &gt; /usr/share/polkit-1/rules.d/org.freedesktop.NetworkManager.rules &lt;&lt; "EOF"
<literal>polkit.addRule(function(action, subject) {
    if (action.id.indexOf("org.freedesktop.NetworkManager.") == 0 &amp;&amp; subject.isInGroup("netdev")) {
        return polkit.Result.YES;
    }
});</literal>
EOF</userinput></screen>

    </sect3>

    <sect3 id="NetworkManager-init">
      <title><phrase revision="sysv">Boot Script</phrase>
             <phrase revision="systemd">Systemd Unit</phrase></title>

      <para revision="sysv">
        To automatically start the <command>NetworkManager</command> daemon
        when the system is rebooted, install the
        <filename>/etc/rc.d/init.d/networkmanager</filename>bootscript from the
        <xref linkend="bootscripts"/> package.
      </para>

      <para revision="systemd">
        To start the <command>NetworkManager</command> daemon at boot, enable
        the previously installed systemd unit by running the following command
        as the <systemitem class="username">root</systemitem> user:
      </para>

      <note>
        <para>
          If using <application>Network Manager</application> to manage
          an interface, any previous configuration for that interface should be
          removed, and the interface brought down prior to starting
          <application>Network Manager</application>.
        </para>
      </note>

      <indexterm zone="NetworkManager NetworkManager-init">
        <primary sortas="f-NetworkManager">NetworkManager</primary>
      </indexterm>

<screen role="root" revision="sysv"><userinput>make install-networkmanager</userinput></screen>

<screen role="root" revision="systemd"><userinput>systemctl enable NetworkManager</userinput></screen>
<!-- The below instruction is obsolete. NetworkManager-wait-online is now
     enabled by default when enabling NetworkManager. -->
<!--
      <para revision="systemd">
        <application>NetworkManager</application> also ships a systemd unit
        called <filename>NetworkManager-wait-online.service</filename> which
        can be used to prevent services that require network connectivity
        from starting until <application>NetworkManager</application> has
        established the connection. To enable it, run the following command
        as the <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root" revision="systemd"><userinput>systemctl enable NetworkManager-wait-online</userinput></screen>
   -->
      <!-- As such, let's now provide instructions on how to disable that
           behavior, for those who wish to do so. -->
      <para revision="systemd">
        Starting in version 1.11.2 of <application>NetworkManager</application>,
        a systemd unit named <filename>NetworkManager-wait-online.service</filename>
        is enabled, which is used to prevent services that require network
        connectivity from starting until <application>NetworkManager</application>
        establishes a connection. To disable this behavior, run the following
        command as the <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root" revision="systemd"><userinput>systemctl disable NetworkManager-wait-online</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          NetworkManager, nmcli, nm-online, nmtui, and, symlinked to nmtui:
          nmtui-connect, nmtui-edit, and nmtui-hostname
        </seg>
        <seg>
          libnm.so
          and several modules under /usr/lib/NetworkManager
        </seg>
        <seg>
          /etc/NetworkManager,
          /usr/include/libnm,
          /usr/lib/NetworkManager,
          /usr/share/doc/NetworkManager-&NetworkManager-version;,
          /usr/share/gtk-doc/html/{libnm,NetworkManager}
          (if the documentation is built),
          and
          /var/lib/NetworkManager
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="nmcli">
        <term><command>nmcli</command></term>
        <listitem>
          <para>
            is a command-line tool for controlling
            <application>NetworkManager</application>
            and getting its status
          </para>
          <indexterm zone="NetworkManager nmcli">
            <primary sortas="b-nmcli">nmcli</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="nm-online">
        <term><command>nm-online</command></term>
        <listitem>
          <para>
            is an utility to determine whether you are online
          </para>
          <indexterm zone="NetworkManager nm-online">
            <primary sortas="b-nm-online">nm-online</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="nmtui">
        <term><command>nmtui</command></term>
        <listitem>
          <para>
            is an interactive ncurses-based user interface for
            <application>nmcli</application>
          </para>
          <indexterm zone="NetworkManager nmtui">
            <primary sortas="b-nmtui">nmtui</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="nmtui-connect">
        <term><command>nmtui-connect</command></term>
        <listitem>
          <para>
            is an interactive ncurses-based user interface to
            activate/deactivate connections
          </para>
          <indexterm zone="NetworkManager nmtui-connect">
            <primary sortas="b-nmtui-connect">nmtui-connect</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="nmtui-edit">
        <term><command>nmtui-edit</command></term>
        <listitem>
          <para>
            is an interactive ncurses-based user interface to edit connections
          </para>
          <indexterm zone="NetworkManager nmtui-edit">
            <primary sortas="b-nmtui-edit">nmtui-edit</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="nmtui-hostname">
        <term><command>nmtui-hostname</command></term>
        <listitem>
          <para>
            is an interactive ncurses-based user interface to edit the hostname
          </para>
          <indexterm zone="NetworkManager nmtui-hostname">
            <primary sortas="b-nmtui-hostname">nmtui-hostname</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="NetworkManager-prog">
        <term><command>NetworkManager</command></term>
        <listitem>
          <para>
            is the network management daemon
          </para>
          <indexterm zone="NetworkManager NetworkManager-prog">
            <primary sortas="b-NetworkManager">NetworkManager</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libnm">
        <term><filename class="libraryfile">libnm.so</filename></term>
        <listitem>
          <para>
            contains functions used by <application>NetworkManager</application>
          </para>
          <indexterm zone="NetworkManager libnm">
            <primary sortas="c-libnm">libnm.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>
    </variablelist>

  </sect2>

</sect1>