source: networking/netutils/networkmanager.xml@ fc09938

12.2 lazarus trunk
Last change on this file since fc09938 was fc09938, checked in by Bruce Dubbs <bdubbs@…>, 4 weeks ago

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