mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager
synced 2024-09-06 09:04:55 +00:00
man: generate nm-settings-ifcfg-rh(5) manual page
This commit is contained in:
parent
24edee2772
commit
f27fac5109
|
@ -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)
|
||||
|
||||
|
|
362
man/nm-settings-ifcfg-rh.xsl
Normal file
362
man/nm-settings-ifcfg-rh.xsl
Normal file
|
@ -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>
|
Loading…
Reference in a new issue