1 <?xml version="1.0" encoding="UTF-8"?>
2 <xsl:stylesheet version="1.0"
3 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
5 <!-- We need to strip whitespaces so that position() function counts correctly.
6 http://www.oxygenxml.com/archives/xsl-list/200305/msg00430.html -->
7 <xsl:strip-space elements="nm-ifcfg-rh-docs setting" />
11 doctype-public="-//OASIS//DTD DocBook XML V4.3//EN"
12 doctype-system="http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
15 <xsl:param name="date"/>
16 <xsl:param name="version"/>
18 <xsl:template match="nm-ifcfg-rh-docs">
19 <xsl:variable name="unsupported" select="'adsl, bluetooth, ppp, pppoe, serial, generic, gsm, cdma, 802-11-olpc-mesh, wimax, vpn'"/>
20 <refentry id="nm-settings-ifcfg-rh">
22 <date><xsl:value-of select="$date"/></date>
25 <refentrytitle>nm-settings-ifcfg-rh</refentrytitle>
26 <manvolnum>5</manvolnum>
27 <refmiscinfo class="source">NetworkManager</refmiscinfo>
28 <refmiscinfo class="manual">Configuration</refmiscinfo>
29 <refmiscinfo class="version"><xsl:value-of select="$version"/></refmiscinfo>
32 <refname>nm-settings-ifcfg-rh</refname>
33 <refpurpose>Description of <emphasis>ifcfg-rh</emphasis> settings plugin</refpurpose>
36 <title>DESCRIPTION</title>
38 NetworkManager is based on the concept of connection profiles that contain
39 network configuration (see <citerefentry><refentrytitle>nm-settings</refentrytitle>
40 <manvolnum>5</manvolnum></citerefentry> for details). The profiles can be
41 stored in various formats. NetworkManager uses plugins for reading and writing
42 the data. The plugins can be configured in <citerefentry>
43 <refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
46 The <emphasis>ifcfg-rh</emphasis> plugin is used on the Fedora and Red Hat
47 Enterprise Linux distributions to read/write configuration from/to
48 the traditional <filename>/etc/sysconfig/network-scripts/ifcfg-*</filename> files.
49 Each NetworkManager connection maps to one <filename>ifcfg-*</filename> file, with
50 possible usage of <filename>keys-*</filename> for passwords, <filename>route-*</filename>
51 for static IPv4 routes and <filename>route6-*</filename> for static IPv6 routes.
52 The plugin currently supports reading and writing Ethernet, Wi-Fi, InfiniBand,
53 VLAN, Bond, Bridge, and Team connections. Unsupported connection types (such as
54 WWAN, PPPoE, VPN, or ADSL) are handled by <emphasis>keyfile</emphasis> plugin
55 (<citerefentry><refentrytitle>nm-settings-keyfile</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
56 The main reason for using <emphasis>ifcfg-rh</emphasis> plugin is the compatibility
57 with legacy configurations for <emphasis>ifup</emphasis> and <emphasis>ifdown</emphasis>
62 <title>File Format</title>
64 The <emphasis>ifcfg-rh</emphasis> config format is a simple text file containing
65 VARIABLE="value" lines. The format is described in <filename>sysconfig.txt</filename>
66 of <emphasis>initscripts</emphasis> package. Note that the configuration files
67 may be sourced by <emphasis>initscripts</emphasis>, so they must be valid shell
68 scripts. That means, for instance, that <literal>#</literal> character can be used
69 for comments, strings with spaces must be quoted, special characters must be escaped,
73 Users can create or modify the <emphasis>ifcfg-rh</emphasis> connection files
74 manually, even if that is not the recommended way of managing the profiles.
75 However, if they choose to do that, they must inform NetworkManager about
76 their changes (see <emphasis>monitor-connection-file</emphasis> in
77 <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum>
78 </citerefentry>, and <emphasis>nmcli con (re)load</emphasis>).
81 <title>Some <emphasis>ifcfg-rh</emphasis> configuration examples:</title>
84 <emphasis role="bold">Simple DHCP ethernet configuration:</emphasis>
86 UUID=1c4ddf70-01bf-46d6-b04f-47e842bd98da
98 <emphasis role="bold">Simple ethernet configuration with static IP:</emphasis>
105 IPV4_FAILURE_FATAL=no
111 IPV6_FAILURE_FATAL=no
113 UUID=51bb3904-c0fc-4dfe-83b2-0a71e7928c13
120 <emphasis role="bold">WPA2 Enterprise WLAN (TTLS with inner MSCHAPV2 authentication):</emphasis>
125 IEEE_8021X_EAP_METHODS=TTLS
126 IEEE_8021X_IDENTITY=joe
127 IEEE_8021X_PASSWORD_FLAGS=ask
128 IEEE_8021X_INNER_AUTH_METHODS=MSCHAPV2
129 IEEE_8021X_CA_CERT=/home/joe/.cert/company.crt
134 IPV4_FAILURE_FATAL=no
137 UUID=f79848ff-11a6-4810-9e1a-99039dea84c4
143 <emphasis role="bold">Bridge and bridge port configuration:</emphasis>
144 ifcfg-bridge: ifcfg-bridge-port:
145 NAME=bridge NAME=bridge007-port-eth0
146 UUID=4be99ce0-c5b2-4764-8b77-ec226e440125 UUID=3ad56c4a-47e1-419b-b0d4-8ad86eb967a3
147 DEVICE=bridge007 DEVICE=eth0
149 TYPE=Bridge TYPE=Ethernet
150 BRIDGING_OPTS=priority=32768 BRIDGE=bridge007
158 <emphasis role="bold">Bonding configuration:</emphasis>
159 ifcfg-BOND: ifcfg-BOND-slave:
160 NAME=BOND NAME=BOND-slave
161 UUID=b41888aa-924c-450c-b0f8-85a4f0a51b4a UUID=9bb048e4-286a-4cc3-b104-007dbd20decb
162 DEVICE=bond100 DEVICE=eth0
163 BONDING_OPTS="mode=balance-rr miimon=100" ONBOOT=yes
164 TYPE=Bond TYPE=Ethernet
165 BONDING_MASTER=yes MASTER=bond100
173 <emphasis role="bold">Team and team port configuration:</emphasis>
176 TEAM_CONFIG="{ \"device\": \"team0\", \"runner\": {\"name\": \"roundrobin\"}, \"ports\": {\"eth1\": {}, \"eth2\": {}} }"
180 UUID=1d3460a0-7b37-457f-a300-fe8d92da4807
183 ifcfg-my_team0_slave1:
185 UUID=d5aed298-c567-4cc1-b808-6d38ecef9e64
191 ifcfg-my_team0_slave2:
193 UUID=94e75f4e-e5ad-401c-8962-31e0ae5d2215
201 The UUID values in the config files must be unique. You can use <emphasis>uuidgen</emphasis>
202 command line tool to generate such values. Alternatively, you can leave out UUID
203 entirely. In that case NetworkManager will generate a UUID based on the file name.
209 <title>Differences against initscripts</title>
211 The main differences of NetworkManager ifcfg-rh plugin and traditional
213 <variablelist class="NM-initscripts-differences">
215 <term><emphasis role="bold">NM_CONTROLLED=yes|no</emphasis></term>
217 NM_CONTROLLED is NetworkManager-specific variable used by NetworkManager
218 for determining whether the device of the <emphasis>ifcfg</emphasis> file
219 should be managed. NM_CONTROLLED=yes is supposed if the variable is not
221 Note that if you have more <emphasis>ifcfg</emphasis> files for a single
222 device, NM_CONTROLLED=no in one of the files will cause the device not
223 to be managed. The profile may not even be the active one.
227 <term><emphasis role="bold">New variables</emphasis></term>
229 NetworkManager has introduced some new variable, not present in initscripts,
230 to be able to store data for its new features. The variables are marked
231 as extensions in the tables below.
235 <term><emphasis role="bold">Semantic change of variables</emphasis></term>
237 NetworkManager had to slightly change the semantic for a few variables.
240 <para><literal>PEERDNS</literal> -
241 initscripts interpret PEERDNS=no to mean "never touch resolv.conf".
242 NetworkManager interprets it to say "never add automatic (DHCP, PPP, VPN, etc.)
243 nameservers to resolv.conf".</para>
246 <para><literal>ONBOOT</literal> -
247 initscripts use ONBOOT=yes to mark the devices that are to be activated
248 during boot. NetworkManager extents this to also mean that this profile
249 can be used for auto-connecting at any time.</para>
252 <para><literal>BOOTPROTO</literal> -
253 NetworkManager supports traditional values <emphasis>none</emphasis> (static),
254 <emphasis>dhcp</emphasis>. But it also allows additional values to
255 enable new addressing methods. They are <emphasis>autoip</emphasis> for IPv4
256 link-local addressing using Avahi daemon and <emphasis>shared</emphasis> for
257 connection sharing. When <emphasis>shared</emphasis> is used, NetworkManager
258 assigns the interface 10.42.0.1, or it uses the first static address,
259 if configured.</para>
267 See the next section for detailed mapping of NetworkManager properties and
268 <emphasis>ifcfg-rh</emphasis> variables. Variable names, format and usage
269 differences in NetworkManager and initscripts are documented in the tables bellow.
274 <title>DETAILS</title>
276 <emphasis>ifcfg-rh</emphasis> plugin variables marked with <emphasis>(+)</emphasis>
277 are NetworkManager specific extensions not understood by traditional initscripts.
279 <xsl:apply-templates />
280 <refsect2 id="secrets-flags">
281 <title>Secret flags</title>
283 Each secret property in a NetworkManager setting has an associated
284 <emphasis>flags</emphasis> property that describes how to handle that secret.
285 In the <emphasis>fcfg-rh</emphasis> plugin variables for secret flags have a
286 <emphasis>_FLAGS</emphasis> suffix. The variables contain one or more of the
287 following values (space separated). Missing (or empty) *_FLAGS variable means
288 that the password is owned by NetworkManager.
292 <para><literal>user</literal> - a user-session secret agent is responsible for providing
293 and storing this secret; when it is required, agents will be asked to provide it.</para>
296 <para><literal>ask</literal> - the associated password is not saved but it will be
297 requested from the user each time it is required.</para>
300 <para><literal>unused</literal> - in some situations it cannot be automatically determined
301 that a secret is required or not. This flag hints that the secret is not required and should
302 not be requested from the user.</para>
309 <title>AUTHOR</title>
312 <firstname>NetworkManager developers</firstname>
318 <para><filename>/etc/sysconfig/network-scripts/ifcfg-*</filename></para>
319 <para><filename>/etc/sysconfig/network-scripts/keys-*</filename></para>
320 <para><filename>/etc/sysconfig/network-scripts/route-*</filename></para>
321 <para><filename>/etc/sysconfig/network-scripts/route6-*</filename></para>
322 <para><filename>/usr/share/doc/initscripts/sysconfig.txt</filename></para>
325 <title>SEE ALSO</title>
326 <para>https://developer.gnome.org/NetworkManager/unstable/ref-settings.html</para>
327 <para>nm-settings(5), nm-settings-keyfile(5), NetworkManager(8), NetworkManager.conf(5), nmcli(1), nmcli-examples(5)</para>
332 <xsl:template match="setting">
333 <xsl:variable name="setting_name" select="../@name"/>
334 <xsl:variable name="unsupported" select="'adsl, bluetooth, ppp, pppoe, serial, generic, gsm, cdma, 802-11-olpc-mesh, wimax, vpn'"/>
335 <xsl:if test="not (contains($unsupported, @name))">
337 <title><xsl:value-of select="@name"/> setting</title>
341 <entry>Property</entry>
342 <entry>Ifcfg-rh Variable</entry>
343 <entry>Default</entry>
344 <entry>Description</entry>
348 <xsl:apply-templates/>
354 <xsl:if test="@name = 'dcb'">
356 All DCB related configuration is a NetworkManager extension. DCB=yes must be
357 used explicitly to enable DCB so that the rest of the DCB_* variables can apply.
361 <xsl:if test="position() = last()">
362 <para>The following settings are not supported by <emphasis>ifcfg-rh</emphasis> plugin:</para>
363 <para><xsl:value-of select="$unsupported"/></para>
367 <xsl:template match="property">
368 <xsl:variable name="setting_name" select="../@name"/>
372 <entry align="left"><xsl:value-of select="@name"/></entry>
374 <xsl:call-template name="string-emphasize-all">
375 <xsl:with-param name="text" select="@variable"/>
376 <xsl:with-param name="emphasize" select="'(+)'"/>
379 <entry align="left"><xsl:value-of select="@default"/></entry>
381 <xsl:value-of select="@description"/><xsl:if test="@format = 'NMSettingSecretFlags'"> (see <xref linkend="secrets-flags"/> for _FLAGS values)</xsl:if>
383 <xsl:if test="string-length(@example)">
384 <emphasis role="bold">
386 Example: </emphasis><xsl:value-of select="@example"/>
388 <xsl:if test="string-length(@values)">
389 <emphasis role="bold">
391 Allowed values: </emphasis><xsl:value-of select="@values"/>
397 <xsl:template name="string-emphasize-all">
398 <xsl:param name="text"/>
399 <xsl:param name="emphasize"/>
401 <xsl:when test="contains($text, $emphasize)">
402 <xsl:value-of select="substring-before($text,$emphasize)"/>
403 <emphasis><xsl:value-of select="$emphasize"/></emphasis>
404 <xsl:call-template name="string-emphasize-all">
405 <xsl:with-param name="text" select="substring-after($text,$emphasize)"/>
406 <xsl:with-param name="emphasize" select="$emphasize"/>
410 <xsl:value-of select="$text"/>