source: networking/netutils/networkmanager.xml@ c950ae6

11.0 11.1 11.2 11.3 12.0 12.1 kea ken/TL2024 ken/inkscape-core-mods ken/tuningfonts lazarus lxqt plabs/newcss plabs/python-mods python3.11 qt5new rahul/power-profiles-daemon renodr/vulkan-addition trunk upgradedb xry111/intltool xry111/llvm18 xry111/soup3 xry111/test-20220226 xry111/xf86-video-removal
Last change on this file since c950ae6 was 64b1d203, checked in by Pierre Labastie <pierre.labastie@…>, 3 years ago

Tags
  • Property mode set to 100644
File size: 22.6 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY NetworkManager-download-http
8"&gnome-download-http;/NetworkManager/&NetworkManager-minor;/NetworkManager-&NetworkManager-version;.tar.xz">
9 <!ENTITY NetworkManager-download-ftp
10"&gnome-download-ftp;/NetworkManager/&NetworkManager-minor;/NetworkManager-&NetworkManager-version;.tar.xz">
11 <!ENTITY NetworkManager-md5sum "009372a92b916412d3fecb1d3b216346">
12 <!ENTITY NetworkManager-size "5.1 MB">
13 <!ENTITY NetworkManager-buildsize "285 MB (with tests)">
14 <!ENTITY NetworkManager-time "0.8 SBU (with tests, using parallelism=4)">
15]>
16
17<sect1 id="NetworkManager" xreflabel="NetworkManager-&NetworkManager-version;">
18 <?dbhtml filename="networkmanager.html"?>
19
20 <sect1info>
21 <date>$Date$</date>
22 </sect1info>
23
24 <title>NetworkManager-&NetworkManager-version;</title>
25
26 <indexterm zone="NetworkManager">
27 <primary sortas="a-NetworkManager">NetworkManager</primary>
28 </indexterm>
29
30 <sect2 role="package">
31 <title>Introduction to NetworkManager</title>
32
33 <para>
34 <application>NetworkManager</application> is a set of co-operative
35 tools that make networking simple and straightforward. Whether you use WiFi,
36 wired, 3G, or Bluetooth, NetworkManager allows you to quickly move from
37 one network to another: Once a network has been configured and joined
38 once, it can be detected and re-joined automatically the next time it's
39 available.
40 </para>
41
42 &lfs110a_checked;
43
44 <note revision="systemd">
45 <para>
46 Make sure that you disable the <command>systemd-networkd</command>
47 service or configure it not to manage the interfaces you want to manage
48 with <application>NetworkManager</application>.
49 </para>
50 </note>
51
52 <bridgehead renderas="sect3">Package Information</bridgehead>
53 <itemizedlist spacing="compact">
54 <listitem>
55 <para>
56 Download (HTTP): <ulink url="&NetworkManager-download-http;"/>
57 </para>
58 </listitem>
59 <listitem>
60 <para>
61 Download (FTP): <ulink url="&NetworkManager-download-ftp;"/>
62 </para>
63 </listitem>
64 <listitem>
65 <para>
66 Download MD5 sum: &NetworkManager-md5sum;
67 </para>
68 </listitem>
69 <listitem>
70 <para>
71 Download size: &NetworkManager-size;
72 </para>
73 </listitem>
74 <listitem>
75 <para>
76 Estimated disk space required: &NetworkManager-buildsize;
77 </para>
78 </listitem>
79 <listitem>
80 <para>
81 Estimated build time: &NetworkManager-time;
82 </para>
83 </listitem>
84 </itemizedlist>
85
86 <bridgehead renderas="sect3">NetworkManager Dependencies</bridgehead>
87
88 <bridgehead renderas="sect4">Required</bridgehead>
89 <para role="required">
90 <xref linkend="jansson"/> and
91 <xref linkend="libndp"/>
92 </para>
93
94 <bridgehead renderas="sect4">Recommended</bridgehead>
95 <para role="recommended">
96 <xref linkend="curl"/>,
97 <!--<xref linkend="dhcpcd"/> or
98 DHCPCD support is known to be broken with dhcpcd-9 -->
99 <xref role="nodep" linkend="dhcp"/> (client only),
100 <xref linkend="gobject-introspection"/>,
101 <xref linkend="iptables"/>,
102 <xref linkend="newt"/> (for <command>nmtui</command>),
103 <xref linkend="nss"/>,
104 <xref linkend="polkit"/>,
105 <xref linkend="pygobject3"/>,
106 <phrase revision="sysv"><xref linkend="elogind"/>,</phrase>
107 <phrase revision="systemd"><xref linkend="systemd"/>,</phrase>
108 <xref linkend="upower"/>,
109 <xref linkend="vala"/>, and
110 <xref linkend="wpa_supplicant"/> (built with D-Bus support),
111 </para>
112
113 <bridgehead renderas="sect4">Optional</bridgehead>
114 <para role="optional">
115 <xref linkend="bluez"/>,
116 <xref linkend="dbus-python"/> (for the test suite),
117 <!-- <xref linkend="firewalld"/> (For whenever firewalld is reintroduced) -->
118 <xref linkend="gnutls"/> (used if <xref linkend="nss"/> is not found),
119 <xref linkend="gtk-doc"/>,
120 <xref linkend="libpsl"/>,
121 <xref linkend="qt5"/> (for examples),
122 <xref linkend="ModemManager"/>,
123 <xref linkend="valgrind"/>,
124 <ulink url="http://www.thekelleys.org.uk/dnsmasq/doc.html">dnsmasq</ulink>,
125 <ulink url="https://firewalld.org/">firewalld</ulink>,
126 <ulink url="https://github.com/Distrotech/libaudit">libaudit</ulink>,
127 <ulink url="https://github.com/jpirko/libteam">libteam</ulink>,
128 <ulink url="&gnome-download-http;/mobile-broadband-provider-info/">mobile-broadband-provider-info</ulink>,
129 <ulink url="https://www.samba.org/ftp/ppp/">PPP</ulink>, and
130 <ulink url="https://dianne.skoll.ca/projects/rp-pppoe/">RP-PPPoE</ulink>
131 </para>
132
133 <para condition="html" role="usernotes">User Notes:
134 <ulink url="&blfs-wiki;/NetworkManager"/>
135 </para>
136 </sect2>
137
138 <sect2 role="kernel" id="NetworkManager-kernel">
139 <title>Kernel Configuration</title>
140
141 <para>
142 If you wish to run the tests, enable the following options in the
143 kernel configuration and recompile the kernel if necessary:
144 </para>
145
146 <!-- Ethernet Teaming support is potentially optional, but I didn't
147 run the tests again to test that. It was needed to convince one of
148 the Linux Platform tests to move farther along because otherwise
149 RTNETLINK would respond with an Error 95 - unknown device type.
150 This would cause the test to fail early on in the process. -->
151
152<screen><literal>Device Drivers ---&gt;
153 [*] Network device support [CONFIG_NETDEVICES] ---&gt;
154 [*] Bonding driver support [CONFIG_BONDING]
155 [*] Dummy net driver support [CONFIG_DUMMY]
156 [*] Ethernet team driver support [CONFIG_NET_TEAM]</literal></screen>
157
158 <indexterm zone="NetworkManager NetworkManager-kernel">
159 <primary sortas="d-NetworkManager">NetworkManager</primary>
160 </indexterm>
161 </sect2>
162
163 <sect2 role="installation">
164 <title>Installation of NetworkManager</title>
165
166 <para>
167 If <xref linkend="qt5"/> is installed and the Qt based
168 examples are desired, fix two meson.build files:
169 </para>
170
171<screen><userinput>sed -e 's/-qt4/-qt5/' \
172 -e 's/moc_location/host_bins/' \
173 -i examples/C/qt/meson.build &amp;&amp;
174
175sed -e 's/Qt/&amp;5/' \
176 -i meson.build</userinput></screen>
177
178<!--
179 <para>
180 Fix a missing meson.build file for initrd hooks (not used in BLFS):
181 </para>
182
183<screen><userinput>sed '/initrd/d' -i src/core/meson.build</userinput></screen>
184-->
185
186 <para>
187 Fix the python scripts so that they use <application>Python
188 3</application>:
189 </para>
190
191<screen><userinput>grep -rl '^#!.*python$' | xargs sed -i '1s/python/&amp;3/'</userinput></screen>
192
193 <para>
194 Install <application>NetworkManager</application> by running the
195 following commands:
196 </para>
197
198<screen revision="sysv"><userinput>mkdir build &amp;&amp;
199cd build &amp;&amp;
200
201CXXFLAGS+="-O2 -fPIC" \
202meson --prefix=/usr \
203 --buildtype=release \
204 -Dlibaudit=no \
205 -Dlibpsl=false \
206 -Dnmtui=true \
207 -Dovs=false \
208 -Dppp=false \
209 -Dselinux=false \
210 -Dsession_tracking=elogind \
211 -Dmodem_manager=false \
212 -Dsystemdsystemunitdir=no \
213 -Dsystemd_journal=false \
214 -Dqt=false \
215 .. &amp;&amp;
216ninja</userinput></screen>
217
218<screen revision="systemd"><userinput>mkdir build &amp;&amp;
219cd build &amp;&amp;
220
221CXXFLAGS+="-O2 -fPIC" \
222meson --prefix=/usr \
223 --buildtype=release \
224 -Dlibaudit=no \
225 -Dlibpsl=false \
226 -Dnmtui=true \
227 -Dovs=false \
228 -Dppp=false \
229 -Dselinux=false \
230 -Dqt=false \
231 -Dsession_tracking=systemd \
232 -Dmodem_manager=false \
233 .. &amp;&amp;
234ninja</userinput></screen>
235
236 <para>
237 An already active graphical session
238 with a bus address is necessary to run the tests. To test the results,
239 as the root user, <!-- needs the "ip" command -->
240 issue: <command>ninja test</command>. Five tests,
241 <filename>platform/test-tc-linux</filename>,
242 <!--<filename>platform/test-core</filename>,-->
243 <filename>test-l3cfg</filename>,
244 <filename>devices/test-acd</filename>,
245 <filename>platform/test-route-linux</filename>, and
246 <filename>platform/test-link-linux</filename>,
247 <!--<filename>platform/test-cleanup-linux</filename>,--> are known to fail.
248 </para>
249
250 <para>
251 Now, as the <systemitem class="username">root</systemitem> user:
252 </para>
253
254<screen role="root"><userinput>ninja install &amp;&amp;
255mv -v /usr/share/doc/NetworkManager{,-&NetworkManager-version;}</userinput></screen>
256
257 </sect2>
258
259 <sect2 role="commands">
260 <title>Command Explanations</title>
261
262 <para>
263 <envar>CXXFLAGS="-O2 -fPIC"</envar>: These compiler options are
264 necessary to build the Qt5 based examples.
265 </para>
266
267 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
268 href="../../xincludes/meson-buildtype-release.xml"/>
269
270 <para>
271 <option>-Ddocs=true</option>: Use this switch to enable building
272 man pages and documentation if <xref linkend="gtk-doc"/> is installed.
273 </para>
274
275 <para>
276 <parameter>-Dnmtui=true</parameter>: This parameter enables building
277 <command>nmtui</command>.
278 </para>
279
280 <para revision="sysv">
281 <parameter>-Dsystemdsystemunitdir=no</parameter> and
282 <parameter>-Dsystemd_journal=false</parameter>: systemd is not
283 used for sysv init systems.
284 </para>
285
286 <para>
287 <!--<parameter>-Djson_validation=false</parameter>, no longer recognized -->
288 <parameter>-Dlibpsl=false</parameter> and
289 <parameter>-Dovs=false</parameter>: These switches disable building with the
290 respective libraries. Remove if you have the needed libraries installed.
291 </para>
292
293<!--
294 <para>
295 <parameter>-Dlibpsl=false</parameter>: This switch is required if
296 <application>libpsl</application> is not installed. Omit this switch if
297 you have built <application>libpsl</application>.
298 </para>
299-->
300
301 <para>
302 <parameter>-Dmodem_manager=false</parameter>: This switch is requried if
303 <application>ModemManager</application> is not installed. Omit if you
304 have built <application>ModemManager</application> and
305 <application>mobile-broadband-provider-info</application>.
306 </para>
307
308 <para revision="sysv">
309 <parameter>-Dsession_tracking=elogind</parameter>: This switch
310 is used to set <command>elogind</command> as the default
311 program for session tracking.
312 </para>
313
314 <para revision="systemd">
315 <parameter>-Dsession_tracking=systemd</parameter>: This switch
316 is used to set <command>systemd-logind</command> as the default
317 program for session tracking.
318 </para>
319
320 <para revision="systemd">
321 <parameter>-Dsystemdsystemunitdir=/lib/systemd/system</parameter>:
322 This switch is used to set the correct installation directory for
323 systemd units.
324 </para>
325
326 <para>
327 <parameter>-Dppp=false</parameter>: This parameter disables
328 <application>PPP</application> support in
329 <application>NetworkManager</application>.
330 </para>
331
332 <para>
333 <parameter>-Dlibaudit=no</parameter> and
334 <parameter>-Dselinux=false</parameter>: libaudit and SELinux are not used
335 in BLFS.
336 </para>
337
338 <para>
339 <parameter>-Dqt=false</parameter>: disables the
340 <application>QT</application> examples. Omit if you have
341 <application>QT</application> available and wish to install the examples.
342 </para>
343
344 </sect2>
345
346 <sect2 role="configuration">
347 <title>Configuring NetworkManager</title>
348
349 <sect3 id="NetworkManager-config">
350 <title>Config Files</title>
351 <para>
352 <filename>/etc/NetworkManager/NetworkManager.conf</filename>
353 </para>
354
355 <indexterm zone="NetworkManager NetworkManager-config">
356 <primary
357 sortas="e-etc-NetworkManager-NetworkManager.conf">
358 /etc/NetworkManager/NetworkManager.conf</primary>
359 </indexterm>
360
361 </sect3>
362
363 <sect3><title>Configuration Information</title>
364
365 <para>
366 For <application>NetworkManager</application> to work, at least
367 a minimal configuration file must be present. Such a file is not
368 installed with <command>make install</command>. Issue the following
369 command as the <systemitem class="username">root</systemitem> user to
370 create a minimal <filename>NetworkManager.conf</filename> file:
371 </para>
372
373<screen role="root"><userinput>cat &gt;&gt; /etc/NetworkManager/NetworkManager.conf &lt;&lt; "EOF"
374<literal>[main]
375plugins=keyfile</literal>
376EOF</userinput></screen>
377
378 <para>
379 This file should not be modified directly by users of the system.
380 Instead, system specific changes should be made using configuration
381 files in the
382 <filename class="directory">/etc/NetworkManager/conf.d</filename>
383 directory.
384 </para>
385
386 <para>
387 To allow polkit to manage authorizations, add the following
388 configuration file:
389 </para>
390
391<screen role="root"><userinput>cat &gt; /etc/NetworkManager/conf.d/polkit.conf &lt;&lt; "EOF"
392<literal>[main]
393auth-polkit=true</literal>
394EOF</userinput></screen>
395
396 <para>
397 To use something other than the built-in dhcp client (recommended if
398 using only <command>nmcli</command>), use the following configuration
399 (valid values include either dhclient <!--dhcpcd --> or internal):
400 </para>
401
402<screen role="nodump"><userinput>cat &gt; /etc/NetworkManager/conf.d/dhcp.conf &lt;&lt; "EOF"
403<literal>[main]
404dhcp=</literal><replaceable>dhclient</replaceable>
405EOF</userinput></screen>
406
407 <para>
408 To prevent <application>NetworkManager</application> from updating the
409 <filename>/etc/resolv.conf</filename> file, add the following
410 configuration file:
411 </para>
412
413<screen role="nodump"><userinput>cat &gt; /etc/NetworkManager/conf.d/no-dns-update.conf &lt;&lt; "EOF"
414<literal>[main]
415dns=none</literal>
416EOF</userinput></screen>
417
418 <para>
419 For additional configuation options, see
420 <command>man 5 NetworkManager.conf</command>.
421 </para>
422
423 <para>
424 To allow regular users to configure network connections,
425 you should add them to the
426 <systemitem class="groupname">netdev</systemitem>
427 group, and create a <application>polkit</application> rule that grants
428 access. Run the following commands as the
429 <systemitem class="username">root</systemitem> user:
430 </para>
431
432<screen role="root"><userinput>groupadd -fg 86 netdev &amp;&amp;
433/usr/sbin/usermod -a -G netdev <replaceable>&lt;username&gt;</replaceable>
434
435cat &gt; /usr/share/polkit-1/rules.d/org.freedesktop.NetworkManager.rules &lt;&lt; "EOF"
436<literal>polkit.addRule(function(action, subject) {
437 if (action.id.indexOf("org.freedesktop.NetworkManager.") == 0 &amp;&amp; subject.isInGroup("netdev")) {
438 return polkit.Result.YES;
439 }
440});</literal>
441EOF</userinput></screen>
442
443 </sect3>
444
445 <sect3 id="NetworkManager-init">
446 <title><phrase revision="sysv">Boot Script</phrase>
447 <phrase revision="systemd">Systemd Unit</phrase></title>
448
449 <para revision="sysv">
450 To automatically start the <command>NetworkManager</command> daemon
451 when the system is rebooted, install the
452 <filename>/etc/rc.d/init.d/networkmanager</filename>bootscript from the
453 <xref linkend="bootscripts"/> package.
454 </para>
455
456 <para revision="systemd">
457 To start the <command>NetworkManager</command> daemon at boot, enable
458 the previously installed systemd unit by running the following command
459 as the <systemitem class="username">root</systemitem> user:
460 </para>
461
462 <note>
463 <para>
464 If using <application>Network Manager</application> to manage
465 an interface, any previous configuration for that interface should be
466 removed, and the interface brought down prior to starting
467 <application>Network Manager</application>.
468 </para>
469 </note>
470
471 <indexterm zone="NetworkManager NetworkManager-init">
472 <primary sortas="f-NetworkManager">NetworkManager</primary>
473 </indexterm>
474
475<screen role="root" revision="sysv"><userinput>make install-networkmanager</userinput></screen>
476
477<screen role="root" revision="systemd"><userinput>systemctl enable NetworkManager</userinput></screen>
478<!-- The below instruction is obsolete. NetworkManager-wait-online is now
479 enabled by default when enabling NetworkManager. -->
480<!--
481 <para revision="systemd">
482 <application>NetworkManager</application> also ships a systemd unit
483 called <filename>NetworkManager-wait-online.service</filename> which
484 can be used to prevent services that require network connectivity
485 from starting until <application>NetworkManager</application> has
486 established the connection. To enable it, run the following command
487 as the <systemitem class="username">root</systemitem> user:
488 </para>
489
490<screen role="root" revision="systemd"><userinput>systemctl enable NetworkManager-wait-online</userinput></screen>
491 -->
492 <!-- As such, let's now provide instructions on how to disable that
493 behavior, for those who wish to do so. -->
494 <para revision="systemd">
495 Starting in version 1.11.2 of <application>NetworkManager</application>,
496 a systemd unit named <filename>NetworkManager-wait-online.service</filename>
497 is enabled, which is used to prevent services that require network
498 connectivity from starting until <application>NetworkManager</application>
499 establishes a connection. To disable this behavior, run the following
500 command as the <systemitem class="username">root</systemitem> user:
501 </para>
502
503<screen role="root" revision="systemd"><userinput>systemctl disable NetworkManager-wait-online</userinput></screen>
504
505 </sect3>
506
507 </sect2>
508
509 <sect2 role="content">
510 <title>Contents</title>
511
512 <segmentedlist>
513 <segtitle>Installed Programs</segtitle>
514 <segtitle>Installed Libraries</segtitle>
515 <segtitle>Installed Directories</segtitle>
516
517 <seglistitem>
518 <seg>
519 NetworkManager, nmcli, nm-online, nmtui, and, symlinked to nmtui:
520 nmtui-connect, nmtui-edit, and nmtui-hostname
521 </seg>
522 <seg>
523 libnm.so
524 and several modules under /usr/lib/NetworkManager
525 </seg>
526 <seg>
527 /etc/NetworkManager,
528 /usr/include/libnm,
529 /usr/lib/NetworkManager,
530 /usr/share/doc/NetworkManager-&NetworkManager-version;,
531 /usr/share/gtk-doc/html/{libnm,NetworkManager}
532 (if the documentation is built),
533 and
534 /var/lib/NetworkManager
535 </seg>
536 <!-- A lot of libraries were removed here. We should verify compatibilty.
537 RESTORED AT 1.18.2 -renodr -->
538 </seglistitem>
539 </segmentedlist>
540
541 <variablelist>
542 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
543 <?dbfo list-presentation="list"?>
544 <?dbhtml list-presentation="table"?>
545
546 <varlistentry id="nmcli">
547 <term><command>nmcli</command></term>
548 <listitem>
549 <para>
550 is a command-line tool for controlling
551 <application>NetworkManager</application>
552 and getting its status
553 </para>
554 <indexterm zone="NetworkManager nmcli">
555 <primary sortas="b-nmcli">nmcli</primary>
556 </indexterm>
557 </listitem>
558 </varlistentry>
559
560 <varlistentry id="nm-online">
561 <term><command>nm-online</command></term>
562 <listitem>
563 <para>
564 is an utility to determine whether you are online
565 </para>
566 <indexterm zone="NetworkManager nm-online">
567 <primary sortas="b-nm-online">nm-online</primary>
568 </indexterm>
569 </listitem>
570 </varlistentry>
571
572 <varlistentry id="nmtui">
573 <term><command>nmtui</command></term>
574 <listitem>
575 <para>
576 is an interactive ncurses-based user interface for
577 <application>nmcli</application>
578 </para>
579 <indexterm zone="NetworkManager nmtui">
580 <primary sortas="b-nmtui">nmtui</primary>
581 </indexterm>
582 </listitem>
583 </varlistentry>
584
585 <varlistentry id="nmtui-connect">
586 <term><command>nmtui-connect</command></term>
587 <listitem>
588 <para>
589 is an interactive ncurses-based user interface to
590 activate/deactivate connections
591 </para>
592 <indexterm zone="NetworkManager nmtui-connect">
593 <primary sortas="b-nmtui-connect">nmtui-connect</primary>
594 </indexterm>
595 </listitem>
596 </varlistentry>
597
598 <varlistentry id="nmtui-edit">
599 <term><command>nmtui-edit</command></term>
600 <listitem>
601 <para>
602 is an interactive ncurses-based user interface to edit connections
603 </para>
604 <indexterm zone="NetworkManager nmtui-edit">
605 <primary sortas="b-nmtui-edit">nmtui-edit</primary>
606 </indexterm>
607 </listitem>
608 </varlistentry>
609
610 <varlistentry id="nmtui-hostname">
611 <term><command>nmtui-hostname</command></term>
612 <listitem>
613 <para>
614 is an interactive ncurses-based user interface to edit the hostname
615 </para>
616 <indexterm zone="NetworkManager nmtui-hostname">
617 <primary sortas="b-nmtui-hostname">nmtui-hostname</primary>
618 </indexterm>
619 </listitem>
620 </varlistentry>
621
622 <varlistentry id="NetworkManager-prog">
623 <term><command>NetworkManager</command></term>
624 <listitem>
625 <para>
626 is the network management daemon
627 </para>
628 <indexterm zone="NetworkManager NetworkManager-prog">
629 <primary sortas="b-NetworkManager">NetworkManager</primary>
630 </indexterm>
631 </listitem>
632 </varlistentry>
633
634 <varlistentry id="libnm">
635 <term><filename class="libraryfile">libnm.so</filename></term>
636 <listitem>
637 <para>
638 contains functions used by <application>NetworkManager</application>
639 </para>
640 <indexterm zone="NetworkManager libnm">
641 <primary sortas="c-libnm">libnm.so</primary>
642 </indexterm>
643 </listitem>
644 </varlistentry>
645 </variablelist>
646
647 </sect2>
648
649</sect1>
Note: See TracBrowser for help on using the repository browser.