glfs/networking/netutils/networkmanager.xml
2022-12-08 14:50:23 -06:00

700 lines
26 KiB
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 "4ee43fe4068b058f4c2f1f0ddbedc24f">
<!ENTITY NetworkManager-size "6.3 MB">
<!ENTITY NetworkManager-buildsize "244 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"?>
<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>
&lfs112_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="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>
<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, 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.-->
<screen><literal>
[*] Networking support---&gt; [CONFIG_NET]
Networking options---&gt;
[*] TCP/IP networking [CONFIG_INET]
&lt;*/M&gt; IP: tunelling [CONFIG_NET_IPIP]
&lt;*/M&gt; IP: GRE demultiplexer [CONFIG_NET_IPGRE_DEMUX]
&lt;*/M&gt; IP: GRE tunnels over IP [CONFIG_NET_IPGRE]
&lt;*&gt; The IPv6 protocol ---&gt; [CONFIG_IPV6]
&lt;*/M&gt; IPv6: IPv6-in-IPv4 tunnel (SIT driver) [CONFIG_IPV6_SIT]
&lt;*/M&gt; IPv6: GRE tunnel [CONFIG_IPV6_GRE]
[*] IPv6: Multiple Routing Tables [CONFIG_IPV6_MULTIPLE_TABLES]
[*] MPTCP: Multipath TCP [CONFIG_MPTCP]
[*] MPTCP: IPv6 support for Multipath TCP [CONFIG_MPTCP_IPV6]
&lt;*/M&gt; 802.1Q/802.1ad VLAN Support [CONFIG_VLAN_8021Q]
[*] QoS and/or fair queueing ---&gt; [CONFIG_NET_SCHED]
&lt;*/M&gt; Stochastic Fairness Queueing (SFQ) [CONFIG_NET_SCH_SFQ]
&lt;*/M&gt; Token Bucket Filter (TBF) [CONFIG_NET_SCH_TBF]
&lt;*/M&gt; Fair Queue Controlled Delay AQM (FQ_CODEL) [CONFIG_NET_SCH_FQ_CODEL]
&lt;*/M&gt; Ingress/classifier-action Qdisc [CONFIG_NET_SCH_INGRESS]
Device Drivers ---&gt;
[*] Network device support ---&gt; [CONFIG_NETDEVICES]
[*] Network core driver support [CONFIG_NET_CORE]
&lt;*&gt; Bonding driver support [CONFIG_BONDING]
&lt;*&gt; Dummy net driver support [CONFIG_DUMMY]
&lt;*&gt; Ethernet team driver support ---&gt; [CONFIG_NET_TEAM]
&lt;*&gt; MAC-VLAN support [CONFIG_MACVLAN]
&lt;*&gt; MAC-VLAN based tap driver [CONFIG_MACVTAP]
&lt;*&gt; IP-VLAN support [CONFIG_IPVLAN]
&lt;*&gt; Virtual eXtensible Local Area Network (VXLAN) [CONFIG_VXLAN]
&lt;*&gt; Virtual ethernet pair device [CONFIG_VETH]
&lt;*&gt; Virtual Routing and Forwarding (Lite) [CONFIG_VRF]
</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, 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>
Still in case 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 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 required 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 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>
<!-- A lot of libraries were removed here. We should verify compatibility.
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>