<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE stylesheet [
<!ENTITY % entities SYSTEM "common.ent" >
%entities;
]>
<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <!-- We need to strip whitespaces so that position() function counts correctly.
       http://www.oxygenxml.com/archives/xsl-list/200305/msg00430.html -->
  <xsl:strip-space elements="nm-setting-docs setting" />

  <xsl:output
      method="xml"
      doctype-public="-//OASIS//DTD DocBook XML V4.5//EN"
      doctype-system="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
      />

  <xsl:template match="nm-setting-docs">
    <refentry id="nm-settings-ifcfg-rh">
      <refentryinfo>
        <title>nm-settings-ifcfg-rh</title>
        <author>NetworkManager developers</author>
      </refentryinfo>
      <refmeta>
        <refentrytitle>nm-settings-ifcfg-rh</refentrytitle>
        <manvolnum>5</manvolnum>
        <refmiscinfo class="source">NetworkManager</refmiscinfo>
        <refmiscinfo class="manual">Configuration</refmiscinfo>
        <refmiscinfo class="version">&NM_VERSION;</refmiscinfo>
      </refmeta>
      <refnamediv>
        <refname>nm-settings-ifcfg-rh</refname>
        <refpurpose>Description of <emphasis>ifcfg-rh</emphasis> settings plugin</refpurpose>
      </refnamediv>
      <refsect1 id='description'><title>Description</title>
        <para>
          NetworkManager is based on the concept of connection profiles that contain
          network configuration (see <citerefentry><refentrytitle>nm-settings-nmcli</refentrytitle>
          <manvolnum>5</manvolnum></citerefentry> for details). The profiles can be
          stored in various formats. NetworkManager uses plugins for reading and writing
          the data. The plugins can be configured in <citerefentry>
          <refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
        </para>
        <para>
          The <emphasis>ifcfg-rh</emphasis> plugin is used on the Fedora and Red Hat
          Enterprise Linux distributions to read/write configuration from/to
          the traditional <filename>/etc/sysconfig/network-scripts/ifcfg-*</filename> files.
          Each NetworkManager connection maps to one <filename>ifcfg-*</filename> file, with
          possible usage of <filename>keys-*</filename> for passwords, <filename>route-*</filename>
          for static IPv4 routes and <filename>route6-*</filename> for static IPv6 routes.
          The plugin currently supports reading and writing Ethernet, Wi-Fi, InfiniBand,
          VLAN, Bond, Bridge, and Team connections. Unsupported connection types (such as
          WWAN, PPPoE, VPN, or ADSL) are handled by <emphasis>keyfile</emphasis> plugin
          (<link linkend='nm-settings-keyfile'><citerefentry><refentrytitle>nm-settings-keyfile</refentrytitle><manvolnum>5</manvolnum></citerefentry></link>).
          The main reason for using <emphasis>ifcfg-rh</emphasis> plugin is the compatibility
          with legacy configurations for <emphasis>ifup</emphasis> and <emphasis>ifdown</emphasis>
          (initscripts).
        </para>
      </refsect1>
      <refsect1 id='file_format'><title>File Format</title>
        <para>
          The <emphasis>ifcfg-rh</emphasis> config format is a simple text file containing
          VARIABLE="value" lines. The format is described in <filename>sysconfig.txt</filename>
          of <emphasis>initscripts</emphasis> package. Note that the configuration files
          may be sourced by <emphasis>initscripts</emphasis>, so they must be valid shell
          scripts. That means, for instance, that <literal>#</literal> character can be used
          for comments, strings with spaces must be quoted, special characters must be escaped,
          etc.
        </para>
        <para>
          Users can create or modify the <emphasis>ifcfg-rh</emphasis> connection files
          manually, even if that is not the recommended way of managing the profiles.
          However, if they choose to do that, they must inform NetworkManager about
          their changes (for example via <emphasis>nmcli con (re)load</emphasis>).
        </para>
        <formalpara>
          <title>Some <emphasis>ifcfg-rh</emphasis> configuration examples:</title>
          <para>
            <programlisting>
            <emphasis role="bold">Simple DHCP ethernet configuration:</emphasis>
NAME=ethernet
UUID=1c4ddf70-01bf-46d6-b04f-47e842bd98da
TYPE=Ethernet
BOOTPROTO=dhcp
DEFROUTE=yes
PEERDNS=yes
PEERROUTES=yes
IPV4_FAILURE_FATAL=no
ONBOOT=yes
            </programlisting>
          </para>
          <para>
            <programlisting>
            <emphasis role="bold">Simple ethernet configuration with static IP:</emphasis>
TYPE=Ethernet
BOOTPROTO=none
IPADDR=10.1.0.25
PREFIX=24
GATEWAY=10.1.0.1
DEFROUTE=yes
IPV4_FAILURE_FATAL=no
IPV6INIT=yes
IPV6_AUTOCONF=yes
IPV6_DEFROUTE=yes
IPV6_PEERDNS=yes
IPV6_PEERROUTES=yes
IPV6_FAILURE_FATAL=no
NAME=ethernet-em2
UUID=51bb3904-c0fc-4dfe-83b2-0a71e7928c13
DEVICE=em2
ONBOOT=yes
            </programlisting>
          </para>
          <para>
            <programlisting>
            <emphasis role="bold">WPA2 Enterprise WLAN (TTLS with inner MSCHAPV2 authentication):</emphasis>
ESSID="CompanyWLAN"
MODE=Managed
KEY_MGMT=WPA-EAP
TYPE=Wireless
IEEE_8021X_EAP_METHODS=TTLS
IEEE_8021X_IDENTITY=joe
IEEE_8021X_PASSWORD_FLAGS=ask
IEEE_8021X_INNER_AUTH_METHODS=MSCHAPV2
IEEE_8021X_CA_CERT=/home/joe/.cert/company.crt
BOOTPROTO=dhcp
DEFROUTE=yes
PEERDNS=yes
PEERROUTES=yes
IPV4_FAILURE_FATAL=no
IPV6INIT=no
NAME=MyCompany
UUID=f79848ff-11a6-4810-9e1a-99039dea84c4
ONBOOT=yes
            </programlisting>
          </para>
          <para>
            <programlisting>
            <emphasis role="bold">Bridge and bridge port configuration:</emphasis>
ifcfg-bridge:                                ifcfg-bridge-port:
NAME=bridge                                  NAME=bridge007-port-eth0
UUID=4be99ce0-c5b2-4764-8b77-ec226e440125    UUID=3ad56c4a-47e1-419b-b0d4-8ad86eb967a3
DEVICE=bridge007                             DEVICE=eth0
STP=yes                                      ONBOOT=yes
TYPE=Bridge                                  TYPE=Ethernet
BRIDGING_OPTS=priority=32768                 BRIDGE=bridge007
ONBOOT=yes
BOOTPROTO=dhcp

            </programlisting>
          </para>
          <para>
            <programlisting>
            <emphasis role="bold">Bonding configuration:</emphasis>
ifcfg-BOND:                                  ifcfg-BOND-port:
NAME=BOND                                    NAME=BOND-port
UUID=b41888aa-924c-450c-b0f8-85a4f0a51b4a    UUID=9bb048e4-286a-4cc3-b104-007dbd20decb
DEVICE=bond100                               DEVICE=eth0
BONDING_OPTS="mode=balance-rr miimon=100"    ONBOOT=yes
TYPE=Bond                                    TYPE=Ethernet
BONDING_MASTER=yes                           MASTER=bond100
ONBOOT=yes                                   SLAVE=yes
BOOTPROTO=dhcp

            </programlisting>
          </para>
          <para>
            <programlisting>
            <emphasis role="bold">Team and team port configuration:</emphasis>
ifcfg-my_team0:
DEVICE=team0
TEAM_CONFIG="{ \"device\": \"team0\", \"runner\": {\"name\": \"roundrobin\"}, \"ports\": {\"eth1\": {}, \"eth2\": {}} }"
DEVICETYPE=Team
BOOTPROTO=dhcp
NAME=team0-profile
UUID=1d3460a0-7b37-457f-a300-fe8d92da4807
ONBOOT=yes

ifcfg-my_team0_port1:
NAME=team0-port1
UUID=d5aed298-c567-4cc1-b808-6d38ecef9e64
DEVICE=eth1
ONBOOT=yes
TEAM_MASTER=team0
DEVICETYPE=TeamPort

ifcfg-my_team0_port2:
NAME=team0-port2
UUID=94e75f4e-e5ad-401c-8962-31e0ae5d2215
DEVICE=eth2
ONBOOT=yes
TEAM_MASTER=team0
DEVICETYPE=TeamPort
            </programlisting>
          </para>
          <para>
            The UUID values in the config files must be unique. You can use <emphasis>uuidgen</emphasis>
            command line tool to generate such values. Alternatively, you can leave out UUID
            entirely. In that case NetworkManager will generate a UUID based on the file name.
          </para>
        </formalpara>
      </refsect1>

      <refsect1 id='differences_against_initscripts'><title>Differences against initscripts</title>
        <para>
          The main differences of NetworkManager ifcfg-rh plugin and traditional
          initscripts are:
          <variablelist class="NM-initscripts-differences">
            <varlistentry>
              <term><emphasis role="bold">NM_CONTROLLED=yes|no</emphasis></term>
              <listitem><para>
                NM_CONTROLLED is NetworkManager-specific variable used by NetworkManager
                for determining whether the device of the <emphasis>ifcfg</emphasis> file
                should be managed. NM_CONTROLLED=yes is supposed if the variable is not
                present in the file.
                Note that if you have more <emphasis>ifcfg</emphasis> files for a single
                device, NM_CONTROLLED=no in one of the files will cause the device not
                to be managed. The profile may not even be the active one.
              </para></listitem>
            </varlistentry>
            <varlistentry>
              <term><emphasis role="bold">New variables</emphasis></term>
              <listitem><para>
                NetworkManager has introduced some new variable, not present in initscripts,
                to be able to store data for its new features. The variables are marked
                as extensions in the tables below.
              </para></listitem>
            </varlistentry>
            <varlistentry>
              <term><emphasis role="bold">Semantic change of variables and differences</emphasis></term>
              <listitem>
                <para>
                  NetworkManager changes the semantics for a few variables and there are other behavioral differences.
                <itemizedlist>
                  <listitem>
                    <para><literal>PEERDNS</literal> -
                    initscripts interpret PEERDNS=no to mean "never touch resolv.conf".
                    NetworkManager interprets it to say "never add automatic (DHCP, PPP, VPN, etc.)
                    nameservers to resolv.conf".</para>
                  </listitem>
                  <listitem>
                    <para><literal>ONBOOT</literal> -
                    initscripts use ONBOOT=yes to mark the devices that are to be activated
                    during boot. NetworkManager extends this to also mean that this profile
                    can be used for auto-connecting at any time.</para>
                  </listitem>
                  <listitem>
                    <para><literal>BOOTPROTO</literal> -
                    NetworkManager supports traditional values <emphasis>none</emphasis> (static),
                    <emphasis>dhcp</emphasis>. But it also allows additional values to
                    enable new addressing methods. They are <emphasis>autoip</emphasis> for IPv4
                    link-local addressing using Avahi daemon and <emphasis>shared</emphasis> for
                    connection sharing. When <emphasis>shared</emphasis> is used, NetworkManager
                    assigns the interface 10.42.0.1, or it uses the first static address,
                    if configured.</para>
                  </listitem>
                  <listitem>
                    <para><literal>HWADDR</literal> -
                    initscripts compare the currently set hardware address of a device, while
                    NetworkManager considers the permanent one.</para>
                  </listitem>
                  <listitem>
                    <para><literal>NOZEROCONF</literal> -
                    initscripts add an on-link route to 169.254.0.0/16 for ethernet profiles that don't
                    explicitly opt-out by setting <literal>NOZEROCONF</literal> variable. NetworkManager does
                    not do that. Instead a static, manual route with scope=253 (link) should be added to get
                    that behavior.</para>
                  </listitem>
                </itemizedlist>
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </para>
        <para>
          See the next section for detailed mapping of NetworkManager properties and
          <emphasis>ifcfg-rh</emphasis> variables. Variable names, format and usage
          differences in NetworkManager and initscripts are documented in the tables below.
        </para>
      </refsect1>

      <refsect1 id='details'><title>Details</title>
        <para>
          <emphasis>ifcfg-rh</emphasis> plugin variables marked with <emphasis>(+)</emphasis>
          are NetworkManager specific extensions not understood by traditional initscripts.
        </para>
        <xsl:apply-templates />
        <refsect2 id="secrets-flags">
          <title>Secret flags</title>
          <para>
            Each secret property in a NetworkManager setting has an associated
            <emphasis>flags</emphasis> property that describes how to handle that secret.
            In the <emphasis>ifcfg-rh</emphasis> plugin variables for secret flags have a
            <emphasis>_FLAGS</emphasis> suffix. The variables contain one or more of the
            following values (space separated). Missing (or empty) *_FLAGS variable means
            that the password is owned by NetworkManager.
          </para>
          <itemizedlist>
            <listitem>
              <para><literal>user</literal> - a user-session secret agent is responsible for providing
              and storing this secret; when it is required, agents will be asked to provide it.</para>
            </listitem>
            <listitem>
              <para><literal>ask</literal> - the associated password is not saved but it will be
              requested from the user each time it is required.</para>
            </listitem>
            <listitem>
              <para><literal>unused</literal> - in some situations it cannot be automatically determined
              that a secret is required or not. This flag hints that the secret is not required and should
              not be requested from the user.</para>
            </listitem>
          </itemizedlist>
        </refsect2>
      </refsect1>

      <refsect1 id='files'><title>Files</title>
        <para><filename>/etc/sysconfig/network-scripts/ifcfg-*</filename></para>
        <para><filename>/etc/sysconfig/network-scripts/keys-*</filename></para>
        <para><filename>/etc/sysconfig/network-scripts/route-*</filename></para>
        <para><filename>/etc/sysconfig/network-scripts/route6-*</filename></para>
        <para><filename>/usr/share/doc/initscripts/sysconfig.txt</filename></para>
      </refsect1>
      <refsect1 id='see_also'><title>See Also</title>
        <para><link linkend='nm-settings-nmcli'><citerefentry><refentrytitle>nm-settings-nmcli</refentrytitle><manvolnum>5</manvolnum></citerefentry></link>,
        <link linkend='nm-settings-keyfile'><citerefentry><refentrytitle>nm-settings-keyfile</refentrytitle><manvolnum>5</manvolnum></citerefentry></link>,
        <link linkend='NetworkManager'><citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
        <link linkend='NetworkManager.conf'><citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></link>,
        <link linkend='nmcli'><citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
        <link linkend='nmcli-examples'><citerefentry><refentrytitle>nmcli-examples</refentrytitle><manvolnum>7</manvolnum></citerefentry></link></para>
      </refsect1>
    </refentry>
  </xsl:template>

  <xsl:template match="setting">
    <xsl:variable name="setting_name" select="../@name"/>
    <xsl:variable name="unsupported" select="'6lowpan, 802-11-olpc-mesh, adsl, bluetooth, cdma, dummy, generic, gsm, ip-tunnel, link, loopback, macsec, macvlan, ovs-bridge, ovs-dpdk, ovs-interface, ovs-patch, ovs-port, ppp, pppoe, serial, tun, veth, vpn, vrf, vxlan, wifi-p2p, wimax, wireguard, wpan'"/>
      <xsl:if test="not (contains(concat(' ', $unsupported, ','), concat(' ', @name, ',')))">
        <table>
          <title><xsl:value-of select="@name"/> setting</title>
          <tgroup cols="4">
            <thead>
              <row>
                <entry>Property</entry>
                <entry>Ifcfg-rh Variable</entry>
                <entry>Default</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <xsl:apply-templates/>
            </tbody>
          </tgroup>
        </table>
      </xsl:if>

      <xsl:if test="@name = 'dcb'">
        <para>
          All DCB related configuration is a NetworkManager extension. DCB=yes must be
          used explicitly to enable DCB so that the rest of the DCB_* variables can apply.
        </para>
      </xsl:if>

      <xsl:if test="position() = last()">
        <para>The following settings are not supported by <emphasis>ifcfg-rh</emphasis> plugin:</para>
        <para><xsl:value-of select="$unsupported"/></para>
      </xsl:if>
  </xsl:template>

  <xsl:template match="property">
    <xsl:variable name="setting_name" select="../@name"/>


    <row>
      <entry align="left"><xsl:value-of select="@name"/></entry>
      <entry align="left">
        <xsl:call-template name="string-emphasize-all">
          <xsl:with-param name="text" select="@variable"/>
          <xsl:with-param name="emphasize" select="'(+)'"/>
        </xsl:call-template>
      </entry>
      <entry align="left"><xsl:value-of select="@default"/></entry>
      <entry align="left">
        <xsl:value-of select="description"/><xsl:if test="@format = 'NMSettingSecretFlags'"> (see <xref linkend="secrets-flags"/> for _FLAGS values)</xsl:if>

        <xsl:if test="string-length(@example)">
        <emphasis role="bold">

Example: </emphasis><xsl:value-of select="@example"/>
        </xsl:if>
        <xsl:if test="string-length(@values)">
        <emphasis role="bold">

Allowed values: </emphasis><xsl:value-of select="@values"/>
        </xsl:if>
      </entry>
    </row>
  </xsl:template>

  <xsl:template name="string-emphasize-all">
    <xsl:param name="text"/>
    <xsl:param name="emphasize"/>
    <xsl:choose>
      <xsl:when test="contains($text, $emphasize)">
        <xsl:value-of select="substring-before($text,$emphasize)"/>
        <emphasis><xsl:value-of select="$emphasize"/></emphasis>
        <xsl:call-template name="string-emphasize-all">
          <xsl:with-param name="text" select="substring-after($text,$emphasize)"/>
          <xsl:with-param name="emphasize" select="$emphasize"/>
        </xsl:call-template>
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="$text"/>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

</xsl:stylesheet>
