mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager
synced 2024-10-06 16:21:50 +00:00
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.
This commit is contained in:
parent
1c2174a802
commit
24edee2772
|
@ -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)
|
||||
|
||||
|
|
308
man/nm-settings-keyfile.xsl
Normal file
308
man/nm-settings-keyfile.xsl
Normal file
|
@ -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>
|
Loading…
Reference in a new issue