summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
authorJiří Klimeš <jklimes@redhat.com>2014-07-04 09:20:48 +0200
committerJiří Klimeš <jklimes@redhat.com>2014-08-29 13:59:54 +0200
commit24edee2772b8acac74ddbc72578fe0168e1c105a (patch)
tree5fcae15ace35bd6667a3ed24bf97b0a7ca35db43 /man
parent1c2174a80296a38416fc6b5c1009035c5f7e6dbf (diff)
downloadNetworkManager-24edee2772b8acac74ddbc72578fe0168e1c105a.tar.gz
man: generate nm-settings-keyfile(5) manual page
man/nm-settings-keyfile.xml is generated via an XSLT stylesheet applied to libnm-util/nm-keyfile-docs.xml. Then a manual page is generated from the XML.
Diffstat (limited to 'man')
-rw-r--r--man/Makefile.am15
-rw-r--r--man/nm-settings-keyfile.xsl308
2 files changed, 321 insertions, 2 deletions
diff --git a/man/Makefile.am b/man/Makefile.am
index 014e737971..0f4b139afb 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -34,6 +34,13 @@ nm-settings.xml: nm-settings.xsl $(top_builddir)/libnm-util/nm-setting-docs.xml
--stringparam date "`date +'%d %B %Y'`" \
$^
+nm-settings-keyfile.xml: nm-settings-keyfile.xsl $(top_builddir)/libnm-util/nm-keyfile-docs.xml
+ $(AM_V_GEN) xsltproc \
+ --output $@ \
+ --stringparam version $(NM_VERSION) \
+ --stringparam date "`date +'%d %B %Y'`" \
+ $^
+
endif
configure_generated_man_pages = \
@@ -47,16 +54,20 @@ docbook_generated_man_pages = \
nmcli-examples.5
docbook_autogenerated_man_pages = \
- nm-settings.5
+ nm-settings.5 \
+ nm-settings-keyfile.5
EXTRA_DIST += \
nm-settings.xml \
nm-settings.xsl \
+ nm-settings-keyfile.xml \
+ nm-settings-keyfile.xsl \
$(docbook_generated_man_pages:.%=.xml) \
$(docbook_autogenerated_man_pages)
DISTCLEANFILES = \
- nm-settings.xml
+ nm-settings.xml \
+ nm-settings-keyfile.xml
man_MANS += $(configure_generated_man_pages)
diff --git a/man/nm-settings-keyfile.xsl b/man/nm-settings-keyfile.xsl
new file mode 100644
index 0000000000..b6e01a2389
--- /dev/null
+++ b/man/nm-settings-keyfile.xsl
@@ -0,0 +1,308 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet version="1.0"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+ <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-keyfile-docs">
+ <refentry id="nm-settings-keyfile">
+ <refentryinfo>
+ <date><xsl:value-of select="$date"/></date>
+ </refentryinfo>
+ <refmeta>
+ <refentrytitle>nm-settings-keyfile</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-keyfile</refname>
+ <refpurpose>Description of <emphasis>keyfile</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>keyfile</emphasis> plugin is the generic plugin that supports all
+ the connection types and capabilities that NetworkManager has. It writes files
+ out in a .ini-style format in <filename>/etc/NetworkManager/system-connections/</filename>.
+ This plugin is always enabled and will automatically be used to store
+ any connections that are not supported by any other active plugin.
+ For security, it will ignore files that are readable or writeable by any user
+ or group other than 'root' since private keys and passphrases may be stored
+ in plaintext inside the file.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>File Format</title>
+ <para>
+ The <emphasis>keyfile</emphasis> config format is a simple .ini-style
+ format. It consists of sections (groups) of key-value pairs. Each section
+ corresponds to a setting name as described in the settings specification
+ (<citerefentry><refentrytitle>nm-settings</refentrytitle>
+ <manvolnum>5</manvolnum></citerefentry>). Each configuration key/value
+ pair in the section is one of the properties listed in the settings
+ specification. The majority of properties of the specification is written
+ in the same format into the <emphasis>keyfile</emphasis> too. However
+ some values are inconvenient for people to use. These are stored in the
+ files in more readable ways. These properties are described bellow.
+ An example could be IP addresses that are not written as integer arrays,
+ but more reasonably as "1.2.3.4/12 1.2.3.254".
+ More information of the generic key file format can be found at
+ <ulink url="https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html#glib-Key-value-file-parser.description">
+ GLib key file format</ulink> (Lines beginning with a '#' are comments,
+ lists are separated by character <literal>;</literal> etc.).
+ </para>
+ <para>
+ Users can create or modify the <emphasis>keyfile</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>Examples of <emphasis>keyfile</emphasis> configuration</title>
+ <para>
+ <programlisting>
+ <emphasis role="bold">A sample configuration for an ethernet network:</emphasis>
+[connection]
+id=Main eth0
+uuid=27afa607-ee36-43f0-b8c3-9d245cdc4bb3
+type=802-3-ethernet
+autoconnect=true
+
+[ipv4]
+method=auto
+
+[802-3-ethernet]
+mac-address=00:23:5a:47:1f:71
+ </programlisting>
+ </para>
+ <para>
+ <programlisting>
+ <emphasis role="bold">A sample configuration for WPA-EAP (PEAP with MSCHAPv2) and always-ask secret:</emphasis>
+[connection]
+id=CompanyWIFI
+uuid=cdac6154-a33b-4b15-9904-666772cfa5ee
+type=wifi
+autoconnect=false
+
+[wifi]
+ssid=CorpWLAN
+mode=infrastructure
+security=802-11-wireless-security
+
+[wifi-security]
+key-mgmt=wpa-eap
+
+[ipv4]
+method=auto
+
+[ipv6]
+method=auto
+
+[802-1x]
+eap=peap;
+identity=joe
+ca-cert=/home/joe/.cert/corp.crt
+phase1-peapver=1
+phase2-auth=mschapv2
+password-flags=2
+ </programlisting>
+ </para>
+ <para>
+ <programlisting>
+ <emphasis role="bold">A sample configuration for openvpn:</emphasis>
+[connection]
+id=RedHat-openvpn
+uuid=7f9b3356-b210-4c0e-8123-bd116c9c280f
+type=vpn
+timestamp=1385401165
+
+[vpn]
+service-type=org.freedesktop.NetworkManager.openvpn
+connection-type=password
+password-flags=3
+remote=ovpn.my-company.com
+cipher=AES-256-CBC
+reneg-seconds=0
+port=443
+username=joe
+ca=/etc/openvpn/ISCA.pem
+tls-remote=ovpn.my-company.com
+
+[ipv6]
+method=auto
+
+[ipv4]
+method=auto
+ignore-auto-dns=true
+never-default=true
+ </programlisting>
+ </para>
+ <para>
+ <programlisting>
+ <emphasis role="bold">A sample configuration for a bridge and a bridge port:</emphasis>
+[connection] [connection]
+id=MainBridge id=br-port-1
+uuid=171ae855-a0ab-42b6-bd0c-60f5812eea9d uuid=d6e8ae98-71f8-4b3d-9d2d-2e26048fe794
+interface-name=MainBridge interface-name=em1
+type=bridge type=ethernet
+ master=MainBridge
+[bridge] slave-type=bridge
+interface-name=MainBridge
+ </programlisting>
+ </para>
+ <para>
+ <programlisting>
+ <emphasis role="bold">A sample configuration for a VLAN:</emphasis>
+[connection]
+id=VLAN for building 4A
+uuid=8ce1c9e0-ce7a-4d2c-aa28-077dda09dd7e
+interface-name=VLAN-4A
+type=vlan
+
+[vlan]
+interface-name=VLAN-4A
+parent=eth0
+id=4
+ </programlisting>
+ </para>
+ </formalpara>
+ </refsect1>
+
+ <refsect1>
+ <title>DETAILS</title>
+ <para>
+ <emphasis>keyfile</emphasis> plugin variables for the majority of NetworkManager
+ properties have one-to-one mapping. It means a NetworkManager property is stored
+ in the keyfile as a variable of the same name and in the same format.
+ There are several exceptions to this rule, mainly for making keyfile syntax easier
+ for humans. The exceptions handled specially by <emphasis>keyfile</emphasis>
+ plugin are listed bellow. Refer to
+ <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for all available settings and properties and their description.
+ </para>
+ <formalpara><title>Name aliases</title>
+ <para>
+ Some of the NetworkManager setting names are somewhat hard to type or remember. Therefore
+ <emphasis>keyfile</emphasis> introduces aliases that can be used instead of the names.
+ <!-- Hmm, why doesn't <simplelist type='horiz' columns='2'> create two columns? -->
+ <simplelist type='horiz' columns='1'>
+ <member><emphasis>setting name keyfile alias</emphasis></member>
+ <member>802-3-ethernet = ethernet</member>
+ <member>802-11-wireless = wifi</member>
+ <member>802-11-wireless-security = wifi-security</member>
+ </simplelist>
+ </para>
+ </formalpara>
+ <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>keyfile</emphasis> plugin,
+ the value of <emphasis>-flags</emphasis> variable is a decimal number (0 - 7) defined as a sum
+ of the following values:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>0 - (NM owned) - the system is responsible for providing and storing this secret.</para>
+ </listitem>
+ <listitem>
+ <para>1 - (agent-owned) - 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>2 - (not-saved) - this secret should not be saved but should be requested
+ from the user each time it is required.</para>
+ </listitem>
+ <listitem>
+ <para>4 - (not-required) - 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/NetworkManager/system-connections/*</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-ifcfg-rh(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:if test="property/@name != ''">
+ <table>
+ <title><xsl:value-of select="@name"/> setting (section)</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Property</entry>
+ <entry>Keyfile Variable</entry>
+ <entry>Format</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <xsl:apply-templates/>
+ </tbody>
+ </tgroup>
+ </table>
+ </xsl:if>
+ </xsl:template>
+
+ <xsl:template match="property">
+ <row>
+ <entry align="left"><xsl:value-of select="@name"/></entry>
+ <entry align="left"><xsl:value-of select="@variable"/></entry>
+ <entry align="left"><xsl:value-of select="@format"/></entry>
+ <entry align="left">
+ <xsl:value-of select="@description"/>
+ <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:stylesheet>