man/nm-settings-keyfile.xsl

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <xsl:stylesheet version="1.0"
   3                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
   4
   5   <xsl:output
   6       method="xml"
   7       doctype-public="-//OASIS//DTD DocBook XML V4.3//EN"
   8       doctype-system="http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
   9       />
  10
  11   <xsl:param name="date"/>
  12   <xsl:param name="version"/>
  13
  14   <xsl:template match="nm-keyfile-docs">
  15     <refentry id="nm-settings-keyfile">
  16       <refentryinfo>
  17         <date><xsl:value-of select="$date"/></date>
  18       </refentryinfo>
  19       <refmeta>
  20         <refentrytitle>nm-settings-keyfile</refentrytitle>
  21         <manvolnum>5</manvolnum>
  22         <refmiscinfo class="source">NetworkManager</refmiscinfo>
  23         <refmiscinfo class="manual">Configuration</refmiscinfo>
  24         <refmiscinfo class="version"><xsl:value-of select="$version"/></refmiscinfo>
  25       </refmeta>
  26       <refnamediv>
  27         <refname>nm-settings-keyfile</refname>
  28         <refpurpose>Description of <emphasis>keyfile</emphasis> settings plugin</refpurpose>
  29       </refnamediv>
  30       <refsect1>
  31         <title>DESCRIPTION</title>
  32         <para>
  33           NetworkManager is based on the concept of connection profiles that contain
  34           network configuration (see <citerefentry><refentrytitle>nm-settings</refentrytitle>
  35           <manvolnum>5</manvolnum></citerefentry> for details). The profiles can be
  36           stored in various formats. NetworkManager uses plugins for reading and writing
  37           the data. The plugins can be configured in <citerefentry>
  38           <refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  39         </para>
  40         <para>
  41           The <emphasis>keyfile</emphasis> plugin is the generic plugin that supports all
  42           the connection types and capabilities that NetworkManager has. It writes files
  43           out in a .ini-style format in <filename>/etc/NetworkManager/system-connections/</filename>.
  44           This plugin is always enabled and will automatically be used to store
  45           any connections that are not supported by any other active plugin.
  46           For security, it will ignore files that are readable or writable by any user
  47           or group other than 'root' since private keys and passphrases may be stored
  48           in plaintext inside the file.
  49         </para>
  50       </refsect1>
  51       <refsect1>
  52         <title>File Format</title>
  53         <para>
  54           The <emphasis>keyfile</emphasis> config format is a simple .ini-style
  55           format. It consists of sections (groups) of key-value pairs. Each section
  56           corresponds to a setting name as described in the settings specification
  57           (<citerefentry><refentrytitle>nm-settings</refentrytitle>
  58           <manvolnum>5</manvolnum></citerefentry>). Each configuration key/value
  59           pair in the section is one of the properties listed in the settings
  60           specification. The majority of properties of the specification is written
  61           in the same format into the <emphasis>keyfile</emphasis> too. However
  62           some values are inconvenient for people to use. These are stored in the
  63           files in more readable ways. These properties are described bellow.
  64           An example could be IP addresses that are not written as integer arrays,
  65           but more reasonably as "1.2.3.4/12 1.2.3.254".
  66           More information of the generic key file format can be found at
  67           <ulink url="https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html#glib-Key-value-file-parser.description">
  68           GLib key file format</ulink> (Lines beginning with a '#' are comments,
  69           lists are separated by character <literal>;</literal> etc.).
  70         </para>
  71         <para>
  72           Users can create or modify the <emphasis>keyfile</emphasis> connection files
  73           manually, even if that is not the recommended way of managing the profiles.
  74           However, if they choose to do that, they must inform NetworkManager about
  75           their changes (see <emphasis>monitor-connection-file</emphasis> in
  76           <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum>
  77           </citerefentry> and <emphasis>nmcli con (re)load</emphasis>).
  78         </para>
  79         <formalpara>
  80           <title>Examples of <emphasis>keyfile</emphasis> configuration</title>
  81           <para>
  82             <programlisting>
  83             <emphasis role="bold">A sample configuration for an ethernet network:</emphasis>
  84 [connection]
  85 id=Main eth0
  86 uuid=27afa607-ee36-43f0-b8c3-9d245cdc4bb3
  87 type=802-3-ethernet
  88 autoconnect=true
  89
  90 [ipv4]
  91 method=auto
  92
  93 [802-3-ethernet]
  94 mac-address=00:23:5a:47:1f:71
  95             </programlisting>
  96           </para>
  97           <para>
  98             <programlisting>
  99             <emphasis role="bold">A sample configuration for WPA-EAP (PEAP with MSCHAPv2) and always-ask secret:</emphasis>
 100 [connection]
 101 id=CompanyWIFI
 102 uuid=cdac6154-a33b-4b15-9904-666772cfa5ee
 103 type=wifi
 104 autoconnect=false
 105
 106 [wifi]
 107 ssid=CorpWLAN
 108 mode=infrastructure
 109 security=802-11-wireless-security
 110
 111 [wifi-security]
 112 key-mgmt=wpa-eap
 113
 114 [ipv4]
 115 method=auto
 116
 117 [ipv6]
 118 method=auto
 119
 120 [802-1x]
 121 eap=peap;
 122 identity=joe
 123 ca-cert=/home/joe/.cert/corp.crt
 124 phase1-peapver=1
 125 phase2-auth=mschapv2
 126 password-flags=2
 127             </programlisting>
 128           </para>
 129           <para>
 130             <programlisting>
 131             <emphasis role="bold">A sample configuration for openvpn:</emphasis>
 132 [connection]
 133 id=RedHat-openvpn
 134 uuid=7f9b3356-b210-4c0e-8123-bd116c9c280f
 135 type=vpn
 136 timestamp=1385401165
 137
 138 [vpn]
 139 service-type=org.freedesktop.NetworkManager.openvpn
 140 connection-type=password
 141 password-flags=3
 142 remote=ovpn.my-company.com
 143 cipher=AES-256-CBC
 144 reneg-seconds=0
 145 port=443
 146 username=joe
 147 ca=/etc/openvpn/ISCA.pem
 148 tls-remote=ovpn.my-company.com
 149
 150 [ipv6]
 151 method=auto
 152
 153 [ipv4]
 154 method=auto
 155 ignore-auto-dns=true
 156 never-default=true
 157             </programlisting>
 158           </para>
 159           <para>
 160             <programlisting>
 161             <emphasis role="bold">A sample configuration for a bridge and a bridge port:</emphasis>
 162 [connection]                                 [connection]
 163 id=MainBridge                                id=br-port-1
 164 uuid=171ae855-a0ab-42b6-bd0c-60f5812eea9d    uuid=d6e8ae98-71f8-4b3d-9d2d-2e26048fe794
 165 interface-name=MainBridge                    interface-name=em1
 166 type=bridge                                  type=ethernet
 167                                              master=MainBridge
 168 [bridge]                                     slave-type=bridge
 169 interface-name=MainBridge
 170             </programlisting>
 171           </para>
 172           <para>
 173             <programlisting>
 174             <emphasis role="bold">A sample configuration for a VLAN:</emphasis>
 175 [connection]
 176 id=VLAN for building 4A
 177 uuid=8ce1c9e0-ce7a-4d2c-aa28-077dda09dd7e
 178 interface-name=VLAN-4A
 179 type=vlan
 180
 181 [vlan]
 182 interface-name=VLAN-4A
 183 parent=eth0
 184 id=4
 185             </programlisting>
 186           </para>
 187         </formalpara>
 188       </refsect1>
 189
 190       <refsect1>
 191         <title>DETAILS</title>
 192         <para>
 193           <emphasis>keyfile</emphasis> plugin variables for the majority of NetworkManager
 194           properties have one-to-one mapping. It means a NetworkManager property is stored
 195           in the keyfile as a variable of the same name and in the same format.
 196           There are several exceptions to this rule, mainly for making keyfile syntax easier
 197           for humans. The exceptions handled specially by <emphasis>keyfile</emphasis>
 198           plugin are listed bellow. Refer to
 199           <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 200           for all available settings and properties and their description.
 201         </para>
 202         <formalpara><title>Name aliases</title>
 203           <para>
 204             Some of the NetworkManager setting names are somewhat hard to type or remember. Therefore
 205             <emphasis>keyfile</emphasis> introduces aliases that can be used instead of the names.
 206             <!-- Hmm, why doesn't <simplelist type='horiz' columns='2'> create two columns? -->
 207             <simplelist type='horiz' columns='1'>
 208               <member><emphasis>setting name                 keyfile alias</emphasis></member>
 209               <member>802-3-ethernet            =  ethernet</member>
 210               <member>802-11-wireless           =  wifi</member>
 211               <member>802-11-wireless-security  =  wifi-security</member>
 212             </simplelist>
 213           </para>
 214         </formalpara>
 215         <xsl:apply-templates/>
 216         <refsect2 id="secrets-flags">
 217           <title>Secret flags</title>
 218           <para>
 219             Each secret property in a NetworkManager setting has an associated <emphasis>flags</emphasis>
 220             property that describes how to handle that secret. In the <emphasis>keyfile</emphasis> plugin,
 221             the value of <emphasis>-flags</emphasis> variable is a decimal number (0 - 7) defined as a sum
 222             of the following values:
 223           </para>
 224           <itemizedlist>
 225             <listitem>
 226               <para>0 - (NM owned) - the system is responsible for providing and storing this secret.</para>
 227             </listitem>
 228             <listitem>
 229               <para>1 - (agent-owned) - a user-session secret agent is responsible for providing
 230               and storing this secret; when it is required, agents will be asked to provide it.</para>
 231             </listitem>
 232             <listitem>
 233               <para>2 - (not-saved) - this secret should not be saved but should be requested
 234               from the user each time it is required.</para>
 235             </listitem>
 236             <listitem>
 237               <para>4 - (not-required) - in some situations it cannot be automatically determined
 238               that a secret is required or not. This flag hints that the secret is not required
 239               and should not be requested from the user.</para>
 240             </listitem>
 241           </itemizedlist>
 242         </refsect2>
 243       </refsect1>
 244
 245       <refsect1>
 246         <title>AUTHOR</title>
 247         <para>
 248           <author>
 249             <firstname>NetworkManager developers</firstname>
 250           </author>
 251         </para>
 252       </refsect1>
 253       <refsect1>
 254         <title>FILES</title>
 255         <para><filename>/etc/NetworkManager/system-connections/*</filename></para>
 256       </refsect1>
 257       <refsect1>
 258         <title>SEE ALSO</title>
 259         <para>https://developer.gnome.org/NetworkManager/unstable/ref-settings.html</para>
 260         <para>nm-settings(5), nm-settings-ifcfg-rh(5), NetworkManager(8), NetworkManager.conf(5), nmcli(1), nmcli-examples(5)</para>
 261       </refsect1>
 262     </refentry>
 263   </xsl:template>
 264
 265   <xsl:template match="setting">
 266     <xsl:variable name="setting_name" select="../@name"/>
 267     <xsl:if test="property/@name != ''">
 268       <table>
 269         <title><xsl:value-of select="@name"/> setting (section)</title>
 270         <tgroup cols="4">
 271           <thead>
 272             <row>
 273               <entry>Property</entry>
 274               <entry>Keyfile Variable</entry>
 275               <entry>Format</entry>
 276               <entry>Description</entry>
 277             </row>
 278           </thead>
 279           <tbody>
 280             <xsl:apply-templates/>
 281           </tbody>
 282         </tgroup>
 283       </table>
 284     </xsl:if>
 285   </xsl:template>
 286
 287   <xsl:template match="property">
 288     <row>
 289       <entry align="left"><xsl:value-of select="@name"/></entry>
 290       <entry align="left"><xsl:value-of select="@variable"/></entry>
 291       <entry align="left"><xsl:value-of select="@format"/></entry>
 292       <entry align="left">
 293         <xsl:value-of select="@description"/>
 294         <xsl:if test="string-length(@example)">
 295           <emphasis role="bold">
 296
 297 Example: </emphasis><xsl:value-of select="@example"/>
 298         </xsl:if>
 299         <xsl:if test="string-length(@values)">
 300           <emphasis role="bold">
 301
 302 Allowed values: </emphasis><xsl:value-of select="@values"/>
 303         </xsl:if>
 304       </entry>
 305     </row>
 306   </xsl:template>
 307
 308 </xsl:stylesheet>