source: networking/netutils/networkmanager.xml@ f61c18e

<?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        "009372a92b916412d3fecb1d3b216346">
  <!ENTITY NetworkManager-size          "5.1 MB">
  <!ENTITY NetworkManager-buildsize     "285 MB (with tests)">
  <!ENTITY NetworkManager-time          "0.8 SBU (with tests, using parallelism=4)">
]>

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

  <sect1info>
    <date>$Date$</date>
  </sect1info>

  <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>

    &lfs110_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"/> or
          DHCPCD support is known to be broken with dhcpcd-9 -->
      <xref role="nodep" linkend="dhcp"/> (client only),
      <xref linkend="gobject-introspection"/>,
      <xref linkend="iptables"/>,
      <xref linkend="newt"/> (for <command>nmtui</command>),
      <xref linkend="nss"/>,
      <xref linkend="polkit"/>,
      <xref linkend="pygobject3"/>,
      <phrase revision="sysv"><xref linkend="elogind"/>,</phrase>
      <phrase revision="systemd"><xref linkend="systemd"/>,</phrase>
      <xref linkend="upower"/>,
      <xref linkend="vala"/>, and
      <xref linkend="wpa_supplicant"/> (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"/> (used if <xref linkend="nss"/> is not found),
      <xref linkend="gtk-doc"/>,
      <xref linkend="libpsl"/>,
      <xref linkend="qt5"/> (for examples),
      <xref linkend="ModemManager"/>,
      <xref linkend="valgrind"/>,
      <ulink url="http://www.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>

    <para condition="html" role="usernotes">User Notes:
      <ulink url="&blfs-wiki;/NetworkManager"/>
    </para>
  </sect2>

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

    <para>
      If you wish to run the tests, enable the following options in the
      kernel configuration and 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. -->

<screen><literal>Device Drivers ---&gt;
  [*] Network device support         [CONFIG_NETDEVICES] ---&gt;
    [*] Bonding driver support       [CONFIG_BONDING]
    [*] Dummy net driver support     [CONFIG_DUMMY]
    [*] Ethernet team driver support [CONFIG_NET_TEAM]</literal></screen>

    <indexterm zone="NetworkManager NetworkManager-kernel">
      <primary sortas="d-NetworkManager">NetworkManager</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 --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 --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,
      as the root user, <!-- needs the "ip" command -->
      issue: <command>ninja test</command>. Five tests,
      <filename>platform/test-tc-linux</filename>,
      <!--<filename>platform/test-core</filename>,-->
      <filename>test-l3cfg</filename>,
      <filename>devices/test-acd</filename>,
      <filename>platform/test-route-linux</filename>, and
      <filename>platform/test-link-linux</filename>,
      <!--<filename>platform/test-cleanup-linux</filename>,--> are known to fail.
    </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>

  </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 parameter 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.
    </para>

    <para>
  <!--<parameter>-Djson_validation=false</parameter>, no longer recognized -->
      <parameter>-Dlibpsl=false</parameter> and
      <parameter>-Dovs=false</parameter>: These switches disable building with the
      respective libraries. Remove if you have the needed libraries installed.
    </para>
    
<!--
    <para>
      <parameter>-Dlibpsl=false</parameter>: This switch is required if
      <application>libpsl</application> is not installed. Omit this switch if
      you have built <application>libpsl</application>.
    </para>
-->

    <para>
      <parameter>-Dmodem_manager=false</parameter>: This switch is requried if
      <application>ModemManager</application> is not installed. Omit 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 parameter disables
      <application>PPP</application> support in
      <application>NetworkManager</application>.
    </para>

    <para>
      <parameter>-Dlibaudit=no</parameter> and
      <parameter>-Dselinux=false</parameter>: libaudit and SELinux are not used
      in BLFS.
    </para>

    <para>
      <parameter>-Dqt=false</parameter>: disables the
      <application>QT</application> examples. Omit if you have
      <application>QT</application> available and wish to install the examples.
    </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 dhclient <!--dhcpcd --> or internal):
      </para>

<screen role="nodump"><userinput>cat &gt; /etc/NetworkManager/conf.d/dhcp.conf &lt;&lt; "EOF"
<literal>[main]
dhcp=</literal><replaceable>dhclient</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 configuation 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>
        <!-- A lot of libraries were removed here. We should verify compatibilty. 
        RESTORED AT 1.18.2 -renodr -->
      </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>