man: generate nm-settings-ifcfg-rh(5) manual page

2 files changed, 375 insertions, 2 deletions

diff --git a/man/Makefile.am b/man/Makefile.am
index 0f4b139afb..376a8b42ac 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -41,6 +41,13 @@ nm-settings-keyfile.xml: nm-settings-keyfile.xsl $(top_builddir)/libnm-util/nm-k
 		--stringparam date "`date +'%d %B %Y'`" \
 		$^
 
+nm-settings-ifcfg-rh.xml: nm-settings-ifcfg-rh.xsl $(top_builddir)/libnm-util/nm-ifcfg-rh-docs.xml
+	$(AM_V_GEN) xsltproc \
+		--output $@ \
+		--stringparam version $(NM_VERSION) \
+		--stringparam date "`date +'%d %B %Y'`" \
+		$^
+
 endif
 
 configure_generated_man_pages =		\
@@ -55,19 +62,23 @@ docbook_generated_man_pages =		\
 
 docbook_autogenerated_man_pages =	\
 	nm-settings.5			\
-	nm-settings-keyfile.5
+	nm-settings-keyfile.5		\
+	nm-settings-ifcfg-rh.5
 
 EXTRA_DIST +=					\
 	nm-settings.xml				\
 	nm-settings.xsl				\
 	nm-settings-keyfile.xml			\
 	nm-settings-keyfile.xsl			\
+	nm-settings-ifcfg-rh.xml		\
+	nm-settings-ifcfg-rh.xsl		\
 	$(docbook_generated_man_pages:.%=.xml)	\
 	$(docbook_autogenerated_man_pages)
 
 DISTCLEANFILES =				\
 	nm-settings.xml				\
-	nm-settings-keyfile.xml
+	nm-settings-keyfile.xml			\
+	nm-settings-ifcfg-rh.xml
 
 man_MANS += $(configure_generated_man_pages)
 
diff --git a/man/nm-settings-ifcfg-rh.xsl b/man/nm-settings-ifcfg-rh.xsl
new file mode 100644
index 0000000000..5c7fbfae15
--- /dev/null
+++ b/man/nm-settings-ifcfg-rh.xsl
@@ -0,0 +1,362 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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-ifcfg-rh-docs setting" />
+
+  <xsl:output
+      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:param name="date"/>
+  <xsl:param name="version"/>
+
+  <xsl:template match="nm-ifcfg-rh-docs">
+    <xsl:variable name="unsupported" select="'adsl, bluetooth, ppp, pppoe, serial, generic, gsm, cdma, 802-11-olpc-mesh, wimax, vpn'"/>
+    <refentry id="nm-settings-ifcfg-rh">
+      <refentryinfo>
+        <date><xsl:value-of select="$date"/></date>
+      </refentryinfo>
+      <refmeta>
+        <refentrytitle>nm-settings-ifcfg-rh</refentrytitle>
+        <manvolnum>5</manvolnum>
+        <refmiscinfo class="source">NetworkManager</refmiscinfo>
+        <refmiscinfo class="manual">Configuration</refmiscinfo>
+        <refmiscinfo class="version"><xsl:value-of select="$version"/></refmiscinfo>
+      </refmeta>
+      <refnamediv>
+        <refname>nm-settings-ifcfg-rh</refname>
+        <refpurpose>Description of <emphasis>ifcfg-rh</emphasis> settings plugin</refpurpose>
+      </refnamediv>
+      <refsect1>
+        <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 standard <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
+          (<citerefentry><refentrytitle>nm-settings-keyfile</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+          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>
+        <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 (see <emphasis>monitor-connection-file</emphasis> in
+          <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum>
+          </citerefentry>, and <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">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=eth0
+ONBOOT=yes
+TEAM_MASTER=team0
+DEVICETYPE=TeamPort
+            </programlisting>
+          </para>
+        </formalpara>
+      </refsect1>
+
+      <refsect1>
+        <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 bellows.
+              </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 extents this to also mean that this profile
+                    can be used for auto-connecting at any time.</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 bellow.
+        </para>
+      </refsect1>
+
+      <refsect1>
+      <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
+            folowing 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>
+        <title>AUTHOR</title>
+        <para>
+          <author>
+            <firstname>NetworkManager developers</firstname>
+          </author>
+        </para>
+      </refsect1>
+      <refsect1>
+        <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>
+        <title>SEE ALSO</title>
+        <para>https://developer.gnome.org/NetworkManager/unstable/ref-settings.html</para>
+        <para>nm-settings(5), nm-settings-keyfile(5), NetworkManager(8), NetworkManager.conf(5), nmcli(1), nmcli-examples(5)</para>
+      </refsect1>
+    </refentry>
+  </xsl:template>
+
+  <xsl:template match="setting">
+    <xsl:variable name="setting_name" select="../@name"/>
+    <xsl:variable name="unsupported" select="'adsl, bluetooth, ppp, pppoe, serial, generic, gsm, cdma, 802-11-olpc-mesh, wimax, vpn'"/>
+      <xsl:if test="not (contains($unsupported, @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 extention. 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="contains(@name,'-flags') and $setting_name != 'dcb'"> (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>