%entities;

]>

                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

       http://www.oxygenxml.com/archives/xsl-list/200305/msg00430.html -->

  <xsl:strip-space elements="nm-setting-docs setting" />

      method="xml"

      doctype-public="-//OASIS//DTD DocBook XML V4.3//EN"

      doctype-system="http://www.oasis-open.org/docbook/xml/4.3/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</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-slave:

NAME=BOND                                    NAME=BOND-slave

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_slave1:

NAME=team0-slave1

UUID=d5aed298-c567-4cc1-b808-6d38ecef9e64

DEVICE=eth1

ONBOOT=yes

TEAM_MASTER=team0

DEVICETYPE=TeamPort

ifcfg-my_team0_slave2:

NAME=team0-slave2

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</emphasis></term>

              <listitem><para>

                NetworkManager had to slightly change the semantic for a few variables.

                <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>

                </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>fcfg-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'><citerefentry><refentrytitle>nm-settings</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="'802-11-olpc-mesh, adsl, bluetooth, cdma, dummy, generic, gsm, ip-tunnel, macsec, macvlan, ppp, pppoe, serial, tun, vpn, vxlan, wimax'"/>

      <xsl:if test="not (contains(concat(' ', $unsupported, ','), concat(' ', @name, ',')))">

          <title><xsl:value-of select="@name"/> setting</title>

          <tgroup cols="4">

              <row>

                <entry>Property</entry>

                <entry>Ifcfg-rh Variable</entry>

                <entry>Default</entry>

                <entry>Description</entry>

              </row>

              <xsl:apply-templates/>

          </tgroup>

      </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>