diff options
author | Thomas Haller <thaller@redhat.com> | 2020-06-02 19:24:12 +0200 |
---|---|---|
committer | Thomas Haller <thaller@redhat.com> | 2020-06-11 10:53:49 +0200 |
commit | 47d39a7fb7fe035e85b4e85748451ce85bc40608 (patch) | |
tree | 0fd87ac006e2b84122637ecf4c7785d69dbec8af | |
parent | d8992ce931d4648836b466270c757905b9fadab6 (diff) | |
download | NetworkManager-47d39a7fb7fe035e85b4e85748451ce85bc40608.tar.gz |
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.
-rw-r--r-- | .gitignore | 6 | ||||
-rw-r--r-- | Makefile.am | 40 | ||||
-rw-r--r-- | configure.ac | 3 | ||||
-rw-r--r-- | docs/api/Makefile.am | 3 | ||||
-rw-r--r-- | docs/api/network-manager-docs.xml | 3 | ||||
-rw-r--r-- | libnm/meson.build | 53 | ||||
-rw-r--r-- | man/meson.build | 3 | ||||
-rw-r--r-- | man/nm-settings-dbus.xsl (renamed from man/nm-settings.xsl) | 10 | ||||
-rw-r--r-- | man/nm-settings-nmcli.xsl | 165 | ||||
-rwxr-xr-x | tools/meson-post-install.sh | 1 |
10 files changed, 242 insertions, 45 deletions
diff --git a/.gitignore b/.gitignore index ed39ed7e02..dec2a8ed46 100644 --- a/.gitignore +++ b/.gitignore @@ -150,8 +150,10 @@ test-*.trs /libnm/nm-property-infos-dbus.xml /libnm/nm-property-infos-ifcfg-rh.xml /libnm/nm-property-infos-keyfile.xml +/libnm/nm-property-infos-nmcli.xml /libnm/nm-settings-docs-dbus.xml /libnm/nm-settings-docs-gir.xml +/libnm/nm-settings-docs-nmcli.xml /libnm/tests/test-libnm /libnm/tests/test-nm-client /libnm/tests/test-remote-settings-client @@ -192,9 +194,10 @@ test-*.trs /m4/xsize.m4 /man/*.[1785] -/man/nm-settings.xml +/man/nm-settings-dbus.xml /man/nm-settings-ifcfg-rh.xml /man/nm-settings-keyfile.xml +/man/nm-settings-nmcli.xml /man/common.ent /po/*.gmo @@ -298,6 +301,7 @@ test-*.trs /docs/libnm-util/tmpl/ /docs/libnm-util/version.xml /docs/libnm-util/xml/ +/man/nm-settings.xml /include/ /initscript/*/[Nn]etwork[Mm]anager /initscript/Slackware/rc.networkmanager diff --git a/Makefile.am b/Makefile.am index dbdcd12318..031bd9f12c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1556,8 +1556,10 @@ libnm_noinst_data = \ libnm/nm-property-infos-dbus.xml \ libnm/nm-property-infos-ifcfg-rh.xml \ libnm/nm-property-infos-keyfile.xml \ + libnm/nm-property-infos-nmcli.xml \ libnm/nm-settings-docs-dbus.xml \ libnm/nm-settings-docs-gir.xml \ + libnm/nm-settings-docs-nmcli.xml \ $(NULL) noinst_DATA += $(libnm_noinst_data) @@ -4959,17 +4961,20 @@ man/%.1 man/%.5 man/%.7 man/%.8: man/%.xml man/common.ent endif man_nm_settings_xml = \ - man/nm-settings.xml \ - man/nm-settings-keyfile.xml \ + man/nm-settings-dbus.xml \ man/nm-settings-ifcfg-rh.xml \ + man/nm-settings-keyfile.xml \ + man/nm-settings-nmcli.xml \ $(NULL) if HAVE_INTROSPECTION -man/nm-settings.xml: man/nm-settings.xsl libnm/nm-settings-docs-dbus.xml man/common.ent +man/nm-settings-%.xml: man/nm-settings-%.xsl libnm/nm-settings-docs-%.xml man/common.ent $(AM_V_GEN) $(XSLTPROC) --output $@ $(xsltproc_flags) $< $(word 2,$^) -man/nm-settings-%.xml: man/nm-settings-%.xsl libnm/nm-property-infos-%.xml man/common.ent +man/nm-settings-keyfile.xml: man/nm-settings-keyfile.xsl libnm/nm-property-infos-keyfile.xml man/common.ent + $(AM_V_GEN) $(XSLTPROC) --output $@ $(xsltproc_flags) $< $(word 2,$^) +man/nm-settings-ifcfg-rh.xml: man/nm-settings-ifcfg-rh.xsl libnm/nm-property-infos-ifcfg-rh.xml man/common.ent $(AM_V_GEN) $(XSLTPROC) --output $@ $(xsltproc_flags) $< $(word 2,$^) CLEANFILES += $(man_nm_settings_xml) @@ -4986,15 +4991,10 @@ man_pages += \ man/nmtui.1 man_pages_autogen += \ + man/nm-settings-dbus.5 \ man/nm-settings-keyfile.5 \ - man/nm-settings.5 - -if WITH_OPENVSWITCH -man_pages += man/nm-openvswitch.7 -else -EXTRA_DIST += man/nm-openvswitch.7 -dist_dependencies += man/nm-openvswitch.7 -endif + man/nm-settings-nmcli.5 \ + $(NULL) if CONFIG_PLUGIN_IFCFG_RH man_pages_autogen += man/nm-settings-ifcfg-rh.5 @@ -5003,6 +5003,13 @@ EXTRA_DIST += man/nm-settings-ifcfg-rh.5 dist_dependencies += man/nm-settings-ifcfg-rh.5 endif +if WITH_OPENVSWITCH +man_pages += man/nm-openvswitch.7 +else +EXTRA_DIST += man/nm-openvswitch.7 +dist_dependencies += man/nm-openvswitch.7 +endif + CLEANFILES += \ man/common.ent @@ -5012,7 +5019,8 @@ EXTRA_DIST += \ $(addsuffix .xsl,$(basename $(man_nm_settings_xml))) \ $(man_pages) \ $(addsuffix .xml,$(basename $(man_pages))) \ - $(man_pages_autogen) + $(man_pages_autogen) \ + $(NULL) if HAVE_DOCS @@ -5021,7 +5029,8 @@ install-data-hook-man: for link in $(nmtui_links); do \ ln -f $(DESTDIR)$(mandir)/man1/nmtui.1 $(DESTDIR)$(mandir)/man1/$$link.1; \ done; \ - ln -f $(DESTDIR)$(mandir)/man5/NetworkManager.conf.5 $(DESTDIR)$(mandir)/man5/nm-system-settings.conf.5; + ln -f $(DESTDIR)$(mandir)/man5/NetworkManager.conf.5 $(DESTDIR)$(mandir)/man5/nm-system-settings.conf.5; \ + ln -f $(DESTDIR)$(mandir)/man5/nm-settings-nmcli.5 $(DESTDIR)$(mandir)/man5/nm-settings.5; install_data_hook += install-data-hook-man @@ -5029,7 +5038,8 @@ uninstall-hook-man: for link in $(nmtui_links); do \ rm -f $(DESTDIR)$(mandir)/man1/$$link.1; \ done; \ - rm -f $(DESTDIR)$(mandir)/man5/nm-system-settings.conf.5; + rm -f $(DESTDIR)$(mandir)/man5/nm-system-settings.conf.5; \ + rm -f $(DESTDIR)$(mandir)/man5/nm-settings.5; uninstall_hook += uninstall-hook-man diff --git a/configure.ac b/configure.ac index 174b86ea55..f1f6afbf28 100644 --- a/configure.ac +++ b/configure.ac @@ -1284,9 +1284,10 @@ if test "$build_docs" != "yes" -a \ \ -f "$srcdir"/man/nm-openvswitch.7 -a \ \ + -f "$srcdir"/man/nm-settings-dbus.5 -a \ -f "$srcdir"/man/nm-settings-ifcfg-rh.5 -a \ -f "$srcdir"/man/nm-settings-keyfile.5 -a \ - -f "$srcdir"/man/nm-settings.5 -a \ + -f "$srcdir"/man/nm-settings-nmcli.5 -a \ \ -f "$srcdir"/man/nm-settings.xml -a \ -f "$srcdir"/man/nm-settings-keyfile.xml -a \ diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am index 5a79197c8f..520bb3f14d 100644 --- a/docs/api/Makefile.am +++ b/docs/api/Makefile.am @@ -88,8 +88,9 @@ content_files = \ $(top_builddir)/man/NetworkManager.xml \ $(top_builddir)/man/NetworkManager.conf.xml \ $(top_builddir)/man/nmcli-examples.xml \ - $(top_builddir)/man/nm-settings.xml \ + $(top_builddir)/man/nm-settings-dbus.xml \ $(top_builddir)/man/nm-settings-keyfile.xml \ + $(top_builddir)/man/nm-settings-nmcli.xml \ version.xml \ $(NULL) diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index 883df41d78..a97eaa895d 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -73,7 +73,8 @@ <xi:include href="../../man/nmcli.xml"/> <xi:include href="../../man/nmcli-examples.xml"/> <xi:include href="../../man/nmtui.xml"/> - <xi:include href="../../man/nm-settings.xml"><xi:fallback /></xi:include> + <xi:include href="../../man/nm-settings-dbus.xml"><xi:fallback /></xi:include> + <xi:include href="../../man/nm-settings-nmcli.xml"><xi:fallback /></xi:include> <xi:include href="../../man/nm-settings-keyfile.xml"><xi:fallback /></xi:include> <xi:include href="../../man/nm-settings-ifcfg-rh.xml"><xi:fallback /></xi:include> <xi:include href="../../man/nm-online.xml"/> diff --git a/libnm/meson.build b/libnm/meson.build index 1b8d128a43..b0d4e9f876 100644 --- a/libnm/meson.build +++ b/libnm/meson.build @@ -212,7 +212,7 @@ if enable_introspection install: true, ) - infos = [ 'dbus', 'keyfile' ] + infos = [ 'dbus', 'nmcli', 'keyfile' ] if enable_ifcfg_rh infos += [ 'ifcfg-rh' ] endif @@ -238,20 +238,24 @@ if enable_introspection nm_property_infos_xml_keyfile = t elif info == 'ifcfg-rh' nm_property_infos_xml_ifcfg_rh = t + elif info == 'nmcli' + nm_property_infos_xml_nmcli = t else assert(false) endif endforeach if enable_ifcfg_rh nm_property_infos_xml = { - 'dbus': nm_property_infos_xml_dbus, - 'keyfile': nm_property_infos_xml_keyfile, + 'dbus': nm_property_infos_xml_dbus, + 'keyfile': nm_property_infos_xml_keyfile, + 'nmcli': nm_property_infos_xml_nmcli, 'ifcfg-rh': nm_property_infos_xml_ifcfg_rh, } else nm_property_infos_xml = { - 'dbus': nm_property_infos_xml_dbus, + 'dbus': nm_property_infos_xml_dbus, 'keyfile': nm_property_infos_xml_keyfile, + 'nmcli': nm_property_infos_xml_nmcli, } endif @@ -288,24 +292,33 @@ if enable_introspection depends: libnm_gir, ) - name = 'dbus' - nm_settings_docs_xml_dbus = custom_target( - 'nm-settings-docs-' + name + '.xml', - input: [nm_settings_docs_xml_gir, nm_property_infos_xml[name]], - output: 'nm-settings-docs-' + name + '.xml', - command: [ - python.path(), - join_paths(meson.current_source_dir(), 'generate-docs-nm-settings-docs-merge.py'), - '@OUTPUT@', - nm_property_infos_xml[name], - nm_settings_docs_xml_gir, - ], - depends: libnm_gir, - ) + foreach name: ['dbus', 'nmcli'] + t = custom_target( + 'nm-settings-docs-' + name + '.xml', + input: [nm_settings_docs_xml_gir, nm_property_infos_xml[name]], + output: 'nm-settings-docs-' + name + '.xml', + command: [ + python.path(), + join_paths(meson.current_source_dir(), 'generate-docs-nm-settings-docs-merge.py'), + '@OUTPUT@', + nm_property_infos_xml[name], + nm_settings_docs_xml_gir, + ], + depends: libnm_gir, + ) + if name == 'dbus' + nm_settings_docs_xml_dbus = t + elif name == 'nmcli' + nm_settings_docs_xml_nmcli = t + else + assert(false) + endif + endforeach nm_settings_docs_xml = { - 'gir': nm_settings_docs_xml_gir, - 'dbus': nm_settings_docs_xml_dbus, + 'gir': nm_settings_docs_xml_gir, + 'dbus': nm_settings_docs_xml_dbus, + 'nmcli': nm_settings_docs_xml_nmcli, } endif diff --git a/man/meson.build b/man/meson.build index 7d9de1ffe9..8e1150833f 100644 --- a/man/meson.build +++ b/man/meson.build @@ -58,7 +58,8 @@ endforeach if enable_introspection mans = [ ['nm-settings-keyfile', '5', nm_property_infos_xml['keyfile']], - ['nm-settings', '5', nm_settings_docs_xml['dbus']], + ['nm-settings-dbus', '5', nm_settings_docs_xml['dbus']], + ['nm-settings-nmcli', '5', nm_settings_docs_xml['nmcli']], ] if enable_ifcfg_rh diff --git a/man/nm-settings.xsl b/man/nm-settings-dbus.xsl index 57d5ce41cf..0573d0d3b8 100644 --- a/man/nm-settings.xsl +++ b/man/nm-settings-dbus.xsl @@ -13,20 +13,20 @@ /> <xsl:template match="nm-setting-docs"> - <refentry id="nm-settings"> + <refentry id="nm-settings-dbus"> <refentryinfo> - <title>nm-settings</title> + <title>nm-settings-dbus</title> <author>NetworkManager developers</author> </refentryinfo> <refmeta> - <refentrytitle>nm-settings</refentrytitle> + <refentrytitle>nm-settings-dbus</refentrytitle> <manvolnum>5</manvolnum> <refmiscinfo class="source">NetworkManager</refmiscinfo> <refmiscinfo class="manual">Configuration</refmiscinfo> <refmiscinfo class="version">&NM_VERSION;</refmiscinfo> </refmeta> <refnamediv> - <refname>nm-settings</refname> + <refname>nm-settings-dbus</refname> <refpurpose>Description of settings and properties of NetworkManager connection profiles</refpurpose> </refnamediv> @@ -155,7 +155,7 @@ <xsl:template match="property"> <xsl:variable name="setting_name" select="../@name"/> <row> - <entry align="left"><xsl:attribute name="id">nm-settings.property.<xsl:value-of select="../@name"/>.<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></entry> + <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> <entry align="left"><xsl:value-of select="@type"/></entry> <entry align="left"><xsl:value-of select="@default"/></entry> <entry><xsl:value-of select="@description"/><xsl:if test="@type = 'NMSettingSecretFlags (uint32)'"> (see <xref linkend="secrets-flags"/> for flag values)</xsl:if></entry> diff --git a/man/nm-settings-nmcli.xsl b/man/nm-settings-nmcli.xsl new file mode 100644 index 0000000000..28e7504931 --- /dev/null +++ b/man/nm-settings-nmcli.xsl @@ -0,0 +1,165 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE stylesheet [ +<!ENTITY % entities SYSTEM "common.ent" > +%entities; +]> +<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"> + <refentry id="nm-settings-nmcli"> + <refentryinfo> + <title>nm-settings-nmcli</title> + <author>NetworkManager developers</author> + </refentryinfo> + <refmeta> + <refentrytitle>nm-settings-nmcli</refentrytitle> + <manvolnum>5</manvolnum> + <refmiscinfo class="source">NetworkManager</refmiscinfo> + <refmiscinfo class="manual">Configuration</refmiscinfo> + <refmiscinfo class="version">&NM_VERSION;</refmiscinfo> + </refmeta> + <refnamediv> + <refname>nm-settings-nmcli</refname> + <refpurpose>Description of settings and properties of NetworkManager connection profiles</refpurpose> + </refnamediv> + + <refsect1 id='description'><title>Description</title> + <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 + described in the tables below. Keys are also referred to as properties. + 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. + </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> + <xsl:apply-templates/> + <refsect2 id="secrets-flags"> + <title>Secret flag types:</title> + <para> + Each password or secret property in a setting has an associated <emphasis>flags</emphasis> property + 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> + <listitem> + <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> + </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> + </itemizedlist> + </refsect2> + </refsect1> + + <refsect1 id='files'><title>Files</title> + <para><filename>/etc/NetworkManager/system-connections</filename> or distro plugin-specific location</para> + </refsect1> + + <refsect1 id='see_also'><title>See Also</title> + <para><link linkend='NetworkManager'><citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>, + <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>, + <link linkend='NetworkManager.conf'><citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></link></para> + </refsect1> + </refentry> + </xsl:template> + + <xsl:template match="setting"> + <refsect2> + <title><xsl:value-of select="@name"/> setting</title> + <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> + </xsl:template> + + <xsl:template match="property"> + <xsl:variable name="setting_name" select="../@name"/> + <row> + <entry align="left"><xsl:attribute name="id">nm-settings-nmcli.property.<xsl:value-of select="../@name"/>.<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></entry> + <entry align="left"><xsl:value-of select="@type"/></entry> + <entry align="left"><xsl:value-of select="@default"/></entry> + <entry><xsl:value-of select="@description"/><xsl:if test="@type = 'NMSettingSecretFlags (uint32)'"> (see <xref linkend="secrets-flags"/> for flag values)</xsl:if></entry> + </row> + </xsl:template> + +</xsl:stylesheet> diff --git a/tools/meson-post-install.sh b/tools/meson-post-install.sh index a6fd0961ef..897a8c5c76 100755 --- a/tools/meson-post-install.sh +++ b/tools/meson-post-install.sh @@ -52,6 +52,7 @@ if [ "$enable_docs" = 1 ]; then done ln -f "${DESTDIR}${nm_mandir}/man5/NetworkManager.conf.5" "${DESTDIR}${nm_mandir}/man5/nm-system-settings.conf.5" + ln -f "${DESTDIR}${nm_mandir}/man5/nm-settings-nmcli.5" "${DESTDIR}${nm_mandir}/man5/nm-settings.5" fi if [ "$enable_ifcfg_rh" = 1 ]; then |