source: networking/netutils/networkmanager.xml@ a3c24ab

trunk
Last change on this file since a3c24ab was a3c24ab, checked in by Rahul Chandra <rahul@…>, 2 weeks ago

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