man/nm-settings.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-setting-docs">
  15     <refentry id="nm-settings">
  16       <refentryinfo>
  17         <date><xsl:value-of select="$date"/></date>
  18       </refentryinfo>
  19       <refmeta>
  20         <refentrytitle>nm-settings</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</refname>
  28         <refpurpose>Description of settings and properties of NetworkManager connection profiles</refpurpose>
  29       </refnamediv>
  30       <refsect1>
  31         <title>DESCRIPTION</title>
  32         <para>
  33           NetworkManager is based on a concept of connection profiles, sometimes referred to as
  34           connections only. These connection profiles contain a network configuration. When
  35           NetworkManager activates a connection profile on a network device the configuration will
  36           be applied and an active network connection will be established. Users are free to create
  37           as many connection profiles as they see fit. Thus they are flexible in having various network
  38           configurations for different networking needs. The connection profiles are handled by
  39           NetworkManager via <emphasis>settings service</emphasis> and are exported on D-Bus
  40           (<emphasis>/org/freedesktop/NetworkManager/Settings/&lt;num&gt;</emphasis> objects).
  41           The conceptual objects can be described as follows:
  42           <variablelist>
  43             <varlistentry>
  44               <term>Connection (profile)</term>
  45               <listitem>
  46                 <para>
  47                   A specific, encapsulated, independent group of settings describing
  48                   all the configuration required to connect to a specific network.
  49                   It is referred to by a unique identifier called the UUID. A connection
  50                   is tied to a one specific device type, but not necessarily a specific
  51                   hardware device. It is composed of one or more <emphasis>Settings</emphasis>
  52                   objects.
  53                 </para>
  54               </listitem>
  55             </varlistentry>
  56           </variablelist>
  57           <variablelist>
  58             <varlistentry>
  59               <term>Setting</term>
  60               <listitem>
  61                 <para>
  62                   A group of related key/value pairs describing a specific piece of a
  63                   <emphasis>Connection (profile)</emphasis>. Settings keys and allowed values are
  64                   described in the tables below. Keys are also referred to as properties.
  65                   Developers can find the setting objects and their properties in the libnm-util
  66                   sources. Look for the <function>class_init</function> functions near the bottom of
  67                   each setting source file.
  68                 </para>
  69               </listitem>
  70             </varlistentry>
  71           </variablelist>
  72           <variablelist>
  73             <para>
  74               The settings and properties shown in tables below list all available connection
  75               configuration options. However, note that not all settings are applicable to all
  76               connection types. NetworkManager provides a command-line tool <emphasis>nmcli</emphasis>
  77               that allows direct configuration of the settings and properties according to a connection
  78               profile type. <emphasis>nmcli</emphasis> connection editor has also a built-in
  79               <emphasis>describe</emphasis> command that can display description of particular settings
  80               and properties of this page.
  81             </para>
  82           </variablelist>
  83         </para>
  84         <xsl:apply-templates/>
  85         <refsect2 id="secrets-flags">
  86           <title>Secret flag types:</title>
  87           <para>
  88             Each secret property in a setting has an associated <emphasis>flags</emphasis> property
  89             that describes how to handle that secret. The <emphasis>flags</emphasis> property is a bitfield
  90             that contains zero or more of the following values logically OR-ed together.
  91           </para>
  92           <itemizedlist>
  93             <listitem>
  94               <para>0x0 (none) - the system is responsible for providing and storing this secret.</para>
  95             </listitem>
  96             <listitem>
  97               <para>0x1 (agent-owned) - a user-session secret agent is responsible for providing and storing
  98               this secret; when it is required, agents will be asked to provide it.</para>
  99             </listitem>
 100             <listitem>
 101               <para>0x2 (not-saved) - this secret should not be saved but should be requested from the user
 102               each time it is required. This flag should be used for One-Time-Pad secrets, PIN codes from hardware tokens,
 103               or if the user simply does not want to save the secret.</para>
 104             </listitem>
 105             <listitem>
 106               <para>0x4 (not-required) - in some situations it cannot be automatically determined that a secret
 107               is required or not. This flag hints that the secret is not required and should not be requested from the user.</para>
 108             </listitem>
 109           </itemizedlist>
 110         </refsect2>
 111       </refsect1>
 112       <refsect1>
 113         <title>AUTHOR</title>
 114         <para>
 115           <author>
 116             <firstname>NetworkManager developers</firstname>
 117           </author>
 118         </para>
 119       </refsect1>
 120       <refsect1>
 121         <title>FILES</title>
 122         <para>/etc/NetworkManager/system-connections</para>
 123         <para>or distro plugin-specific location</para>
 124       </refsect1>
 125       <refsect1>
 126         <title>SEE ALSO</title>
 127         <para>https://wiki.gnome.org/Projects/NetworkManager/ConfigurationSpecification</para>
 128         <para>NetworkManager(8), nmcli(1), nmcli-examples(5), NetworkManager.conf(5)</para>
 129       </refsect1>
 130     </refentry>
 131   </xsl:template>
 132
 133   <xsl:template match="setting">
 134     <table>
 135       <title><xsl:value-of select="@name"/> setting</title>
 136       <tgroup cols="4">
 137         <thead>
 138           <row>
 139             <entry>Key Name</entry>
 140             <entry>Value Type</entry>
 141             <entry>Default Value</entry>
 142             <entry>Value Description</entry>
 143           </row>
 144         </thead>
 145         <tbody>
 146           <xsl:apply-templates/>
 147         </tbody>
 148       </tgroup>
 149     </table>
 150   </xsl:template>
 151
 152   <xsl:template match="property">
 153     <xsl:variable name="setting_name" select="../@name"/>
 154     <row>
 155       <entry align="left"><xsl:value-of select="@name"/></entry>
 156       <entry align="left"><xsl:value-of select="@type"/></entry>
 157       <entry align="left"><xsl:value-of select="@default"/></entry>
 158       <entry><xsl:value-of select="@description"/><xsl:if test="@type = 'NMSettingSecretFlags (uint32)'"> (see <xref linkend="secrets-flags"/> for flag values)</xsl:if></entry>
 159     </row>
 160   </xsl:template>
 161
 162 </xsl:stylesheet>