source: networking/netutils/networkmanager.xml@ 4da49b9

10.1 11.0 qt5new trunk xry111/git-date xry111/git-date-for-trunk xry111/git-date-test
Last change on this file since 4da49b9 was 4da49b9, checked in by Pierre Labastie <pieere@…>, 7 months ago

Fix "sed" in NetworkManager

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@24284 af4574ff-66df-0310-9fd7-8a98e5e911e0

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