man/nm-settings-ifcfg-rh.xsl

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <xsl:stylesheet version="1.0"
   3                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
   4
   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" />
   8
   9   <xsl:output
  10       method="xml"
  11       doctype-public="-//OASIS//DTD DocBook XML V4.3//EN"
  12       doctype-system="http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
  13       />
  14
  15   <xsl:param name="date"/>
  16   <xsl:param name="version"/>
  17
  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">
  21       <refentryinfo>
  22         <date><xsl:value-of select="$date"/></date>
  23       </refentryinfo>
  24       <refmeta>
  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>
  30       </refmeta>
  31       <refnamediv>
  32         <refname>nm-settings-ifcfg-rh</refname>
  33         <refpurpose>Description of <emphasis>ifcfg-rh</emphasis> settings plugin</refpurpose>
  34       </refnamediv>
  35       <refsect1>
  36         <title>DESCRIPTION</title>
  37         <para>
  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>.
  44         </para>
  45         <para>
  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>
  58           (initscripts).
  59         </para>
  60       </refsect1>
  61       <refsect1>
  62         <title>File Format</title>
  63         <para>
  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,
  70           etc.
  71         </para>
  72         <para>
  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>).
  79         </para>
  80         <formalpara>
  81           <title>Some <emphasis>ifcfg-rh</emphasis> configuration examples:</title>
  82           <para>
  83             <programlisting>
  84             <emphasis role="bold">Simple DHCP ethernet configuration:</emphasis>
  85 NAME=ethernet
  86 UUID=1c4ddf70-01bf-46d6-b04f-47e842bd98da
  87 TYPE=Ethernet
  88 BOOTPROTO=dhcp
  89 DEFROUTE=yes
  90 PEERDNS=yes
  91 PEERROUTES=yes
  92 IPV4_FAILURE_FATAL=no
  93 ONBOOT=yes
  94             </programlisting>
  95           </para>
  96           <para>
  97             <programlisting>
  98             <emphasis role="bold">Simple ethernet configuration with static IP:</emphasis>
  99 TYPE=Ethernet
 100 BOOTPROTO=none
 101 IPADDR=10.1.0.25
 102 PREFIX=24
 103 GATEWAY=10.1.0.1
 104 DEFROUTE=yes
 105 IPV4_FAILURE_FATAL=no
 106 IPV6INIT=yes
 107 IPV6_AUTOCONF=yes
 108 IPV6_DEFROUTE=yes
 109 IPV6_PEERDNS=yes
 110 IPV6_PEERROUTES=yes
 111 IPV6_FAILURE_FATAL=no
 112 NAME=ethernet-em2
 113 UUID=51bb3904-c0fc-4dfe-83b2-0a71e7928c13
 114 DEVICE=em2
 115 ONBOOT=yes
 116             </programlisting>
 117           </para>
 118           <para>
 119             <programlisting>
 120             <emphasis role="bold">WPA2 Enterprise WLAN (TTLS with inner MSCHAPV2 authentication):</emphasis>
 121 ESSID="CompanyWLAN"
 122 MODE=Managed
 123 KEY_MGMT=WPA-EAP
 124 TYPE=Wireless
 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
 130 BOOTPROTO=dhcp
 131 DEFROUTE=yes
 132 PEERDNS=yes
 133 PEERROUTES=yes
 134 IPV4_FAILURE_FATAL=no
 135 IPV6INIT=no
 136 NAME=MyCompany
 137 UUID=f79848ff-11a6-4810-9e1a-99039dea84c4
 138 ONBOOT=yes
 139             </programlisting>
 140           </para>
 141           <para>
 142             <programlisting>
 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
 148 STP=yes                                      ONBOOT=yes
 149 TYPE=Bridge                                  TYPE=Ethernet
 150 BRIDGING_OPTS=priority=32768                 BRIDGE=bridge007
 151 ONBOOT=yes
 152 BOOTPROTO=dhcp
 153
 154             </programlisting>
 155           </para>
 156           <para>
 157             <programlisting>
 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
 166 ONBOOT=yes                                   SLAVE=yes
 167 BOOTPROTO=dhcp
 168
 169             </programlisting>
 170           </para>
 171           <para>
 172             <programlisting>
 173             <emphasis role="bold">Team and team port configuration:</emphasis>
 174 ifcfg-my_team0:
 175 DEVICE=team0
 176 TEAM_CONFIG="{ \"device\": \"team0\", \"runner\": {\"name\": \"roundrobin\"}, \"ports\": {\"eth1\": {}, \"eth2\": {}} }"
 177 DEVICETYPE=Team
 178 BOOTPROTO=dhcp
 179 NAME=team0-profile
 180 UUID=1d3460a0-7b37-457f-a300-fe8d92da4807
 181 ONBOOT=yes
 182
 183 ifcfg-my_team0_slave1:
 184 NAME=team0-slave1
 185 UUID=d5aed298-c567-4cc1-b808-6d38ecef9e64
 186 DEVICE=eth1
 187 ONBOOT=yes
 188 TEAM_MASTER=team0
 189 DEVICETYPE=TeamPort
 190
 191 ifcfg-my_team0_slave2:
 192 NAME=team0-slave2
 193 UUID=94e75f4e-e5ad-401c-8962-31e0ae5d2215
 194 DEVICE=eth2
 195 ONBOOT=yes
 196 TEAM_MASTER=team0
 197 DEVICETYPE=TeamPort
 198             </programlisting>
 199           </para>
 200           <para>
 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.
 204           </para>
 205         </formalpara>
 206       </refsect1>
 207
 208       <refsect1>
 209         <title>Differences against initscripts</title>
 210         <para>
 211           The main differences of NetworkManager ifcfg-rh plugin and traditional
 212           initscripts are:
 213           <variablelist class="NM-initscripts-differences">
 214             <varlistentry>
 215               <term><emphasis role="bold">NM_CONTROLLED=yes|no</emphasis></term>
 216               <listitem><para>
 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
 220                 present in the file.
 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.
 224               </para></listitem>
 225             </varlistentry>
 226             <varlistentry>
 227               <term><emphasis role="bold">New variables</emphasis></term>
 228               <listitem><para>
 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.
 232               </para></listitem>
 233             </varlistentry>
 234             <varlistentry>
 235               <term><emphasis role="bold">Semantic change of variables</emphasis></term>
 236               <listitem><para>
 237                 NetworkManager had to slightly change the semantic for a few variables.
 238                 <itemizedlist>
 239                   <listitem>
 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>
 244                   </listitem>
 245                   <listitem>
 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>
 250                   </listitem>
 251                   <listitem>
 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>
 260                  </listitem>
 261                 </itemizedlist>
 262               </para></listitem>
 263             </varlistentry>
 264           </variablelist>
 265         </para>
 266         <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 below.
 270         </para>
 271       </refsect1>
 272
 273       <refsect1>
 274       <title>DETAILS</title>
 275         <para>
 276           <emphasis>ifcfg-rh</emphasis> plugin variables marked with <emphasis>(+)</emphasis>
 277           are NetworkManager specific extensions not understood by traditional initscripts.
 278         </para>
 279         <xsl:apply-templates />
 280         <refsect2 id="secrets-flags">
 281           <title>Secret flags</title>
 282           <para>
 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.
 289           </para>
 290           <itemizedlist>
 291             <listitem>
 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>
 294             </listitem>
 295             <listitem>
 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>
 298             </listitem>
 299             <listitem>
 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>
 303             </listitem>
 304           </itemizedlist>
 305         </refsect2>
 306       </refsect1>
 307
 308       <refsect1>
 309         <title>AUTHOR</title>
 310         <para>
 311           <author>
 312             <firstname>NetworkManager developers</firstname>
 313           </author>
 314         </para>
 315       </refsect1>
 316       <refsect1>
 317         <title>FILES</title>
 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>
 323       </refsect1>
 324       <refsect1>
 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>
 328       </refsect1>
 329     </refentry>
 330   </xsl:template>
 331
 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))">
 336         <table>
 337           <title><xsl:value-of select="@name"/> setting</title>
 338           <tgroup cols="4">
 339             <thead>
 340               <row>
 341                 <entry>Property</entry>
 342                 <entry>Ifcfg-rh Variable</entry>
 343                 <entry>Default</entry>
 344                 <entry>Description</entry>
 345               </row>
 346             </thead>
 347             <tbody>
 348               <xsl:apply-templates/>
 349             </tbody>
 350           </tgroup>
 351         </table>
 352       </xsl:if>
 353
 354       <xsl:if test="@name = 'dcb'">
 355         <para>
 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.
 358         </para>
 359       </xsl:if>
 360
 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>
 364       </xsl:if>
 365   </xsl:template>
 366
 367   <xsl:template match="property">
 368     <xsl:variable name="setting_name" select="../@name"/>
 369
 370
 371     <row>
 372       <entry align="left"><xsl:value-of select="@name"/></entry>
 373       <entry align="left">
 374         <xsl:call-template name="string-emphasize-all">
 375           <xsl:with-param name="text" select="@variable"/>
 376           <xsl:with-param name="emphasize" select="'(+)'"/>
 377         </xsl:call-template>
 378       </entry>
 379       <entry align="left"><xsl:value-of select="@default"/></entry>
 380       <entry align="left">
 381         <xsl:value-of select="@description"/><xsl:if test="@format = 'NMSettingSecretFlags'"> (see <xref linkend="secrets-flags"/> for _FLAGS values)</xsl:if>
 382
 383         <xsl:if test="string-length(@example)">
 384         <emphasis role="bold">
 385
 386 Example: </emphasis><xsl:value-of select="@example"/>
 387         </xsl:if>
 388         <xsl:if test="string-length(@values)">
 389         <emphasis role="bold">
 390
 391 Allowed values: </emphasis><xsl:value-of select="@values"/>
 392         </xsl:if>
 393       </entry>
 394     </row>
 395   </xsl:template>
 396
 397   <xsl:template name="string-emphasize-all">
 398     <xsl:param name="text"/>
 399     <xsl:param name="emphasize"/>
 400     <xsl:choose>
 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"/>
 407         </xsl:call-template>
 408       </xsl:when>
 409       <xsl:otherwise>
 410         <xsl:value-of select="$text"/>
 411       </xsl:otherwise>
 412     </xsl:choose>
 413   </xsl:template>
 414
 415 </xsl:stylesheet>