2014-06-13 15:08:56 +00:00
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
2016-04-04 17:22:45 +00:00
|
|
|
<!DOCTYPE stylesheet [
|
|
|
|
<!ENTITY % entities SYSTEM "common.ent" >
|
|
|
|
%entities;
|
|
|
|
]>
|
2014-06-13 15:08:56 +00:00
|
|
|
<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:template match="nm-setting-docs">
|
docs: add more nm-settings manpages (dbus,nmcli,keyfile,ifcfg-rh)
A significant part of NetworkManager's API are the connection profiles, documented
in `man nm-settings*`. But there are different aspects about profiles, depending
on what you are interested. There is the D-Bus API, nmcli options, keyfile format,
and ifcfg-rh format. Additionally, there is also libnm API.
Add distinct manual pages for the four aspects. Currently the two new manual
pages "nm-settings-dbus" and "nm-settings-nmcli" are still identical to the
former "nm-settings.5" manual. In the future, they will diverge to
account for the differences.
There are the following aspects:
- "dbus"
- "keyfile"
- "ifcfg-rh"
- "nmcli"
For "libnm" we don't generate a separate "nm-settings-libnm" manual
page. That is instead documented via gtk-doc.
Currently the keyfile and ifcfg-rh manual pages only detail settings
which differ. But later I think also these manual pages should contain
all settings that apply.
2020-06-02 17:24:12 +00:00
|
|
|
<refentry id="nm-settings-dbus">
|
2016-04-04 17:51:58 +00:00
|
|
|
<refentryinfo>
|
docs: add more nm-settings manpages (dbus,nmcli,keyfile,ifcfg-rh)
A significant part of NetworkManager's API are the connection profiles, documented
in `man nm-settings*`. But there are different aspects about profiles, depending
on what you are interested. There is the D-Bus API, nmcli options, keyfile format,
and ifcfg-rh format. Additionally, there is also libnm API.
Add distinct manual pages for the four aspects. Currently the two new manual
pages "nm-settings-dbus" and "nm-settings-nmcli" are still identical to the
former "nm-settings.5" manual. In the future, they will diverge to
account for the differences.
There are the following aspects:
- "dbus"
- "keyfile"
- "ifcfg-rh"
- "nmcli"
For "libnm" we don't generate a separate "nm-settings-libnm" manual
page. That is instead documented via gtk-doc.
Currently the keyfile and ifcfg-rh manual pages only detail settings
which differ. But later I think also these manual pages should contain
all settings that apply.
2020-06-02 17:24:12 +00:00
|
|
|
<title>nm-settings-dbus</title>
|
2016-04-04 17:51:58 +00:00
|
|
|
<author>NetworkManager developers</author>
|
|
|
|
</refentryinfo>
|
2014-06-13 15:08:56 +00:00
|
|
|
<refmeta>
|
docs: add more nm-settings manpages (dbus,nmcli,keyfile,ifcfg-rh)
A significant part of NetworkManager's API are the connection profiles, documented
in `man nm-settings*`. But there are different aspects about profiles, depending
on what you are interested. There is the D-Bus API, nmcli options, keyfile format,
and ifcfg-rh format. Additionally, there is also libnm API.
Add distinct manual pages for the four aspects. Currently the two new manual
pages "nm-settings-dbus" and "nm-settings-nmcli" are still identical to the
former "nm-settings.5" manual. In the future, they will diverge to
account for the differences.
There are the following aspects:
- "dbus"
- "keyfile"
- "ifcfg-rh"
- "nmcli"
For "libnm" we don't generate a separate "nm-settings-libnm" manual
page. That is instead documented via gtk-doc.
Currently the keyfile and ifcfg-rh manual pages only detail settings
which differ. But later I think also these manual pages should contain
all settings that apply.
2020-06-02 17:24:12 +00:00
|
|
|
<refentrytitle>nm-settings-dbus</refentrytitle>
|
2014-07-11 13:08:09 +00:00
|
|
|
<manvolnum>5</manvolnum>
|
|
|
|
<refmiscinfo class="source">NetworkManager</refmiscinfo>
|
|
|
|
<refmiscinfo class="manual">Configuration</refmiscinfo>
|
2016-04-04 17:22:45 +00:00
|
|
|
<refmiscinfo class="version">&NM_VERSION;</refmiscinfo>
|
2014-06-13 15:08:56 +00:00
|
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
docs: add more nm-settings manpages (dbus,nmcli,keyfile,ifcfg-rh)
A significant part of NetworkManager's API are the connection profiles, documented
in `man nm-settings*`. But there are different aspects about profiles, depending
on what you are interested. There is the D-Bus API, nmcli options, keyfile format,
and ifcfg-rh format. Additionally, there is also libnm API.
Add distinct manual pages for the four aspects. Currently the two new manual
pages "nm-settings-dbus" and "nm-settings-nmcli" are still identical to the
former "nm-settings.5" manual. In the future, they will diverge to
account for the differences.
There are the following aspects:
- "dbus"
- "keyfile"
- "ifcfg-rh"
- "nmcli"
For "libnm" we don't generate a separate "nm-settings-libnm" manual
page. That is instead documented via gtk-doc.
Currently the keyfile and ifcfg-rh manual pages only detail settings
which differ. But later I think also these manual pages should contain
all settings that apply.
2020-06-02 17:24:12 +00:00
|
|
|
<refname>nm-settings-dbus</refname>
|
2020-06-04 14:41:43 +00:00
|
|
|
<refpurpose>Description of settings and properties of NetworkManager connection profiles on the D-Bus API</refpurpose>
|
2014-06-13 15:08:56 +00:00
|
|
|
</refnamediv>
|
2016-04-04 17:51:58 +00:00
|
|
|
|
|
|
|
<refsect1 id='description'><title>Description</title>
|
2014-07-11 13:08:09 +00:00
|
|
|
<para>
|
|
|
|
NetworkManager is based on a concept of connection profiles, sometimes referred to as
|
|
|
|
connections only. These connection profiles contain a network configuration. When
|
|
|
|
NetworkManager activates a connection profile on a network device the configuration will
|
|
|
|
be applied and an active network connection will be established. Users are free to create
|
|
|
|
as many connection profiles as they see fit. Thus they are flexible in having various network
|
|
|
|
configurations for different networking needs. The connection profiles are handled by
|
|
|
|
NetworkManager via <emphasis>settings service</emphasis> and are exported on D-Bus
|
|
|
|
(<emphasis>/org/freedesktop/NetworkManager/Settings/<num></emphasis> objects).
|
|
|
|
The conceptual objects can be described as follows:
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>Connection (profile)</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
A specific, encapsulated, independent group of settings describing
|
|
|
|
all the configuration required to connect to a specific network.
|
|
|
|
It is referred to by a unique identifier called the UUID. A connection
|
|
|
|
is tied to a one specific device type, but not necessarily a specific
|
|
|
|
hardware device. It is composed of one or more <emphasis>Settings</emphasis>
|
|
|
|
objects.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>Setting</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
A group of related key/value pairs describing a specific piece of a
|
|
|
|
<emphasis>Connection (profile)</emphasis>. Settings keys and allowed values are
|
2015-12-24 08:48:20 +00:00
|
|
|
described in the tables below. Keys are also referred to as properties.
|
2016-12-15 14:36:57 +00:00
|
|
|
Developers can find the setting objects and their properties in the libnm-core
|
|
|
|
sources. Look for the <function>*_class_init</function> functions near the bottom
|
|
|
|
of each setting source file.
|
2014-07-11 13:08:09 +00:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<variablelist>
|
|
|
|
<para>
|
|
|
|
The settings and properties shown in tables below list all available connection
|
|
|
|
configuration options. However, note that not all settings are applicable to all
|
|
|
|
connection types. NetworkManager provides a command-line tool <emphasis>nmcli</emphasis>
|
|
|
|
that allows direct configuration of the settings and properties according to a connection
|
|
|
|
profile type. <emphasis>nmcli</emphasis> connection editor has also a built-in
|
|
|
|
<emphasis>describe</emphasis> command that can display description of particular settings
|
|
|
|
and properties of this page.
|
|
|
|
</para>
|
|
|
|
</variablelist>
|
|
|
|
</para>
|
2014-06-13 15:08:56 +00:00
|
|
|
<xsl:apply-templates/>
|
2014-07-11 13:08:09 +00:00
|
|
|
<refsect2 id="secrets-flags">
|
|
|
|
<title>Secret flag types:</title>
|
|
|
|
<para>
|
2017-09-28 15:29:45 +00:00
|
|
|
Each password or secret property in a setting has an associated <emphasis>flags</emphasis> property
|
2014-07-11 13:08:09 +00:00
|
|
|
that describes how to handle that secret. The <emphasis>flags</emphasis> property is a bitfield
|
|
|
|
that contains zero or more of the following values logically OR-ed together.
|
|
|
|
</para>
|
|
|
|
<itemizedlist>
|
2014-06-13 15:08:56 +00:00
|
|
|
<listitem>
|
2017-09-28 15:29:45 +00:00
|
|
|
<para>0x0 (none) - the system is responsible for providing and storing this secret. This
|
|
|
|
may be required so that secrets are already available before the user logs in.
|
|
|
|
It also commonly means that the secret will be stored in plain text on disk, accessible
|
|
|
|
to root only. For example via the keyfile settings plugin as described in the "PLUGINS" section
|
|
|
|
in <link linkend='NetworkManager.conf'><citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></link>.
|
|
|
|
</para>
|
2014-06-13 15:08:56 +00:00
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>0x1 (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>0x2 (not-saved) - this secret should not be saved but should be requested from the user
|
|
|
|
each time it is required. This flag should be used for One-Time-Pad secrets, PIN codes from hardware tokens,
|
|
|
|
or if the user simply does not want to save the secret.</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>0x4 (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>
|
2014-07-11 13:08:09 +00:00
|
|
|
</itemizedlist>
|
|
|
|
</refsect2>
|
2014-06-13 15:08:56 +00:00
|
|
|
</refsect1>
|
2016-04-04 17:51:58 +00:00
|
|
|
|
|
|
|
<refsect1 id='files'><title>Files</title>
|
|
|
|
<para><filename>/etc/NetworkManager/system-connections</filename> or distro plugin-specific location</para>
|
2014-06-13 15:08:56 +00:00
|
|
|
</refsect1>
|
2016-04-04 17:51:58 +00:00
|
|
|
|
|
|
|
<refsect1 id='see_also'><title>See Also</title>
|
2020-06-04 14:41:43 +00:00
|
|
|
<para>
|
|
|
|
<link linkend='nm-settings-nmcli'><citerefentry><refentrytitle>nm-settings-nmcli</refentrytitle><manvolnum>5</manvolnum></citerefentry></link>,
|
|
|
|
<link linkend='nm-settings-keyfile'><citerefentry><refentrytitle>nm-settings-keyfile</refentrytitle><manvolnum>5</manvolnum></citerefentry></link>,
|
|
|
|
<link linkend='NetworkManager'><citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
|
2016-05-30 18:24:32 +00:00
|
|
|
<link linkend='nmcli'><citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
|
|
|
|
<link linkend='nmcli-examples'><citerefentry><refentrytitle>nmcli-examples</refentrytitle><manvolnum>7</manvolnum></citerefentry></link>,
|
2020-06-04 14:41:43 +00:00
|
|
|
<link linkend='NetworkManager.conf'><citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></link>
|
|
|
|
</para>
|
2014-06-13 15:08:56 +00:00
|
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
</xsl:template>
|
|
|
|
|
|
|
|
<xsl:template match="setting">
|
2017-03-10 20:02:09 +00:00
|
|
|
<refsect2>
|
2014-06-13 15:08:56 +00:00
|
|
|
<title><xsl:value-of select="@name"/> setting</title>
|
2017-03-10 20:02:09 +00:00
|
|
|
<para><xsl:value-of select="@description"/>.</para>
|
|
|
|
<informaltable>
|
|
|
|
<tgroup cols="4">
|
|
|
|
<thead>
|
|
|
|
<row>
|
|
|
|
<entry>Key Name</entry>
|
|
|
|
<entry>Value Type</entry>
|
|
|
|
<entry>Default Value</entry>
|
|
|
|
<entry>Value Description</entry>
|
|
|
|
</row>
|
|
|
|
</thead>
|
|
|
|
<tbody>
|
|
|
|
<xsl:apply-templates/>
|
|
|
|
</tbody>
|
|
|
|
</tgroup>
|
|
|
|
</informaltable>
|
|
|
|
</refsect2>
|
2014-06-13 15:08:56 +00:00
|
|
|
</xsl:template>
|
|
|
|
|
|
|
|
<xsl:template match="property">
|
|
|
|
<xsl:variable name="setting_name" select="../@name"/>
|
|
|
|
<row>
|
docs: add more nm-settings manpages (dbus,nmcli,keyfile,ifcfg-rh)
A significant part of NetworkManager's API are the connection profiles, documented
in `man nm-settings*`. But there are different aspects about profiles, depending
on what you are interested. There is the D-Bus API, nmcli options, keyfile format,
and ifcfg-rh format. Additionally, there is also libnm API.
Add distinct manual pages for the four aspects. Currently the two new manual
pages "nm-settings-dbus" and "nm-settings-nmcli" are still identical to the
former "nm-settings.5" manual. In the future, they will diverge to
account for the differences.
There are the following aspects:
- "dbus"
- "keyfile"
- "ifcfg-rh"
- "nmcli"
For "libnm" we don't generate a separate "nm-settings-libnm" manual
page. That is instead documented via gtk-doc.
Currently the keyfile and ifcfg-rh manual pages only detail settings
which differ. But later I think also these manual pages should contain
all settings that apply.
2020-06-02 17:24:12 +00:00
|
|
|
<entry align="left"><xsl:attribute name="id">nm-settings-dbus.property.<xsl:value-of select="../@name"/>.<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></entry>
|
2014-06-13 15:08:56 +00:00
|
|
|
<entry align="left"><xsl:value-of select="@type"/></entry>
|
|
|
|
<entry align="left"><xsl:value-of select="@default"/></entry>
|
2022-09-07 08:28:16 +00:00
|
|
|
<entry><xsl:apply-templates select="description"/><xsl:if test="deprecated">
|
|
|
|
|
|
|
|
This property is deprecated since version <xsl:value-of select="deprecated/@since"/>.<xsl:value-of select="deprecated"/></xsl:if></entry>
|
2014-06-13 15:08:56 +00:00
|
|
|
</row>
|
|
|
|
</xsl:template>
|
|
|
|
|
2022-06-16 19:09:33 +00:00
|
|
|
<xsl:template match="description">
|
|
|
|
<xsl:value-of select="."/><xsl:if test="@type = 'NMSettingSecretFlags (uint32)'"> (see <xref linkend="secrets-flags"/> for flag values)</xsl:if>
|
|
|
|
</xsl:template>
|
|
|
|
|
2014-06-13 15:08:56 +00:00
|
|
|
</xsl:stylesheet>
|