source: networking/netutils/networkmanager.xml@ e4c821e2

12.0 12.1 ken/TL2024 ken/tuningfonts lazarus plabs/newcss python3.11 rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18
Last change on this file since e4c821e2 was e4c821e2, checked in by Xi Ruoyao <xry111@…>, 10 months ago

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