diff options
| -rw-r--r-- | man/Makefile.am | 15 | ||||
| -rw-r--r-- | man/nm-settings-keyfile.xsl | 308 |
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> |