mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager
synced 2024-07-22 10:46:59 +00:00
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.
This commit is contained in:
parent
d8992ce931
commit
47d39a7fb7
6
.gitignore
vendored
6
.gitignore
vendored
|
@ -150,8 +150,10 @@ test-*.trs
|
||||||
/libnm/nm-property-infos-dbus.xml
|
/libnm/nm-property-infos-dbus.xml
|
||||||
/libnm/nm-property-infos-ifcfg-rh.xml
|
/libnm/nm-property-infos-ifcfg-rh.xml
|
||||||
/libnm/nm-property-infos-keyfile.xml
|
/libnm/nm-property-infos-keyfile.xml
|
||||||
|
/libnm/nm-property-infos-nmcli.xml
|
||||||
/libnm/nm-settings-docs-dbus.xml
|
/libnm/nm-settings-docs-dbus.xml
|
||||||
/libnm/nm-settings-docs-gir.xml
|
/libnm/nm-settings-docs-gir.xml
|
||||||
|
/libnm/nm-settings-docs-nmcli.xml
|
||||||
/libnm/tests/test-libnm
|
/libnm/tests/test-libnm
|
||||||
/libnm/tests/test-nm-client
|
/libnm/tests/test-nm-client
|
||||||
/libnm/tests/test-remote-settings-client
|
/libnm/tests/test-remote-settings-client
|
||||||
|
@ -192,9 +194,10 @@ test-*.trs
|
||||||
/m4/xsize.m4
|
/m4/xsize.m4
|
||||||
|
|
||||||
/man/*.[1785]
|
/man/*.[1785]
|
||||||
/man/nm-settings.xml
|
/man/nm-settings-dbus.xml
|
||||||
/man/nm-settings-ifcfg-rh.xml
|
/man/nm-settings-ifcfg-rh.xml
|
||||||
/man/nm-settings-keyfile.xml
|
/man/nm-settings-keyfile.xml
|
||||||
|
/man/nm-settings-nmcli.xml
|
||||||
/man/common.ent
|
/man/common.ent
|
||||||
|
|
||||||
/po/*.gmo
|
/po/*.gmo
|
||||||
|
@ -298,6 +301,7 @@ test-*.trs
|
||||||
/docs/libnm-util/tmpl/
|
/docs/libnm-util/tmpl/
|
||||||
/docs/libnm-util/version.xml
|
/docs/libnm-util/version.xml
|
||||||
/docs/libnm-util/xml/
|
/docs/libnm-util/xml/
|
||||||
|
/man/nm-settings.xml
|
||||||
/include/
|
/include/
|
||||||
/initscript/*/[Nn]etwork[Mm]anager
|
/initscript/*/[Nn]etwork[Mm]anager
|
||||||
/initscript/Slackware/rc.networkmanager
|
/initscript/Slackware/rc.networkmanager
|
||||||
|
|
40
Makefile.am
40
Makefile.am
|
@ -1556,8 +1556,10 @@ libnm_noinst_data = \
|
||||||
libnm/nm-property-infos-dbus.xml \
|
libnm/nm-property-infos-dbus.xml \
|
||||||
libnm/nm-property-infos-ifcfg-rh.xml \
|
libnm/nm-property-infos-ifcfg-rh.xml \
|
||||||
libnm/nm-property-infos-keyfile.xml \
|
libnm/nm-property-infos-keyfile.xml \
|
||||||
|
libnm/nm-property-infos-nmcli.xml \
|
||||||
libnm/nm-settings-docs-dbus.xml \
|
libnm/nm-settings-docs-dbus.xml \
|
||||||
libnm/nm-settings-docs-gir.xml \
|
libnm/nm-settings-docs-gir.xml \
|
||||||
|
libnm/nm-settings-docs-nmcli.xml \
|
||||||
$(NULL)
|
$(NULL)
|
||||||
|
|
||||||
noinst_DATA += $(libnm_noinst_data)
|
noinst_DATA += $(libnm_noinst_data)
|
||||||
|
@ -4959,17 +4961,20 @@ man/%.1 man/%.5 man/%.7 man/%.8: man/%.xml man/common.ent
|
||||||
endif
|
endif
|
||||||
|
|
||||||
man_nm_settings_xml = \
|
man_nm_settings_xml = \
|
||||||
man/nm-settings.xml \
|
man/nm-settings-dbus.xml \
|
||||||
man/nm-settings-keyfile.xml \
|
|
||||||
man/nm-settings-ifcfg-rh.xml \
|
man/nm-settings-ifcfg-rh.xml \
|
||||||
|
man/nm-settings-keyfile.xml \
|
||||||
|
man/nm-settings-nmcli.xml \
|
||||||
$(NULL)
|
$(NULL)
|
||||||
|
|
||||||
if HAVE_INTROSPECTION
|
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,$^)
|
$(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,$^)
|
$(AM_V_GEN) $(XSLTPROC) --output $@ $(xsltproc_flags) $< $(word 2,$^)
|
||||||
|
|
||||||
CLEANFILES += $(man_nm_settings_xml)
|
CLEANFILES += $(man_nm_settings_xml)
|
||||||
|
@ -4986,15 +4991,10 @@ man_pages += \
|
||||||
man/nmtui.1
|
man/nmtui.1
|
||||||
|
|
||||||
man_pages_autogen += \
|
man_pages_autogen += \
|
||||||
|
man/nm-settings-dbus.5 \
|
||||||
man/nm-settings-keyfile.5 \
|
man/nm-settings-keyfile.5 \
|
||||||
man/nm-settings.5
|
man/nm-settings-nmcli.5 \
|
||||||
|
$(NULL)
|
||||||
if WITH_OPENVSWITCH
|
|
||||||
man_pages += man/nm-openvswitch.7
|
|
||||||
else
|
|
||||||
EXTRA_DIST += man/nm-openvswitch.7
|
|
||||||
dist_dependencies += man/nm-openvswitch.7
|
|
||||||
endif
|
|
||||||
|
|
||||||
if CONFIG_PLUGIN_IFCFG_RH
|
if CONFIG_PLUGIN_IFCFG_RH
|
||||||
man_pages_autogen += man/nm-settings-ifcfg-rh.5
|
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
|
dist_dependencies += man/nm-settings-ifcfg-rh.5
|
||||||
endif
|
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 += \
|
CLEANFILES += \
|
||||||
man/common.ent
|
man/common.ent
|
||||||
|
|
||||||
|
@ -5012,7 +5019,8 @@ EXTRA_DIST += \
|
||||||
$(addsuffix .xsl,$(basename $(man_nm_settings_xml))) \
|
$(addsuffix .xsl,$(basename $(man_nm_settings_xml))) \
|
||||||
$(man_pages) \
|
$(man_pages) \
|
||||||
$(addsuffix .xml,$(basename $(man_pages))) \
|
$(addsuffix .xml,$(basename $(man_pages))) \
|
||||||
$(man_pages_autogen)
|
$(man_pages_autogen) \
|
||||||
|
$(NULL)
|
||||||
|
|
||||||
|
|
||||||
if HAVE_DOCS
|
if HAVE_DOCS
|
||||||
|
@ -5021,7 +5029,8 @@ install-data-hook-man:
|
||||||
for link in $(nmtui_links); do \
|
for link in $(nmtui_links); do \
|
||||||
ln -f $(DESTDIR)$(mandir)/man1/nmtui.1 $(DESTDIR)$(mandir)/man1/$$link.1; \
|
ln -f $(DESTDIR)$(mandir)/man1/nmtui.1 $(DESTDIR)$(mandir)/man1/$$link.1; \
|
||||||
done; \
|
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
|
install_data_hook += install-data-hook-man
|
||||||
|
|
||||||
|
@ -5029,7 +5038,8 @@ uninstall-hook-man:
|
||||||
for link in $(nmtui_links); do \
|
for link in $(nmtui_links); do \
|
||||||
rm -f $(DESTDIR)$(mandir)/man1/$$link.1; \
|
rm -f $(DESTDIR)$(mandir)/man1/$$link.1; \
|
||||||
done; \
|
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
|
uninstall_hook += uninstall-hook-man
|
||||||
|
|
||||||
|
|
|
@ -1284,9 +1284,10 @@ if test "$build_docs" != "yes" -a \
|
||||||
\
|
\
|
||||||
-f "$srcdir"/man/nm-openvswitch.7 -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-ifcfg-rh.5 -a \
|
||||||
-f "$srcdir"/man/nm-settings-keyfile.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.xml -a \
|
||||||
-f "$srcdir"/man/nm-settings-keyfile.xml -a \
|
-f "$srcdir"/man/nm-settings-keyfile.xml -a \
|
||||||
|
|
|
@ -88,8 +88,9 @@ content_files = \
|
||||||
$(top_builddir)/man/NetworkManager.xml \
|
$(top_builddir)/man/NetworkManager.xml \
|
||||||
$(top_builddir)/man/NetworkManager.conf.xml \
|
$(top_builddir)/man/NetworkManager.conf.xml \
|
||||||
$(top_builddir)/man/nmcli-examples.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-keyfile.xml \
|
||||||
|
$(top_builddir)/man/nm-settings-nmcli.xml \
|
||||||
version.xml \
|
version.xml \
|
||||||
$(NULL)
|
$(NULL)
|
||||||
|
|
||||||
|
|
|
@ -73,7 +73,8 @@
|
||||||
<xi:include href="../../man/nmcli.xml"/>
|
<xi:include href="../../man/nmcli.xml"/>
|
||||||
<xi:include href="../../man/nmcli-examples.xml"/>
|
<xi:include href="../../man/nmcli-examples.xml"/>
|
||||||
<xi:include href="../../man/nmtui.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-keyfile.xml"><xi:fallback /></xi:include>
|
||||||
<xi:include href="../../man/nm-settings-ifcfg-rh.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"/>
|
<xi:include href="../../man/nm-online.xml"/>
|
||||||
|
|
|
@ -212,7 +212,7 @@ if enable_introspection
|
||||||
install: true,
|
install: true,
|
||||||
)
|
)
|
||||||
|
|
||||||
infos = [ 'dbus', 'keyfile' ]
|
infos = [ 'dbus', 'nmcli', 'keyfile' ]
|
||||||
if enable_ifcfg_rh
|
if enable_ifcfg_rh
|
||||||
infos += [ 'ifcfg-rh' ]
|
infos += [ 'ifcfg-rh' ]
|
||||||
endif
|
endif
|
||||||
|
@ -238,20 +238,24 @@ if enable_introspection
|
||||||
nm_property_infos_xml_keyfile = t
|
nm_property_infos_xml_keyfile = t
|
||||||
elif info == 'ifcfg-rh'
|
elif info == 'ifcfg-rh'
|
||||||
nm_property_infos_xml_ifcfg_rh = t
|
nm_property_infos_xml_ifcfg_rh = t
|
||||||
|
elif info == 'nmcli'
|
||||||
|
nm_property_infos_xml_nmcli = t
|
||||||
else
|
else
|
||||||
assert(false)
|
assert(false)
|
||||||
endif
|
endif
|
||||||
endforeach
|
endforeach
|
||||||
if enable_ifcfg_rh
|
if enable_ifcfg_rh
|
||||||
nm_property_infos_xml = {
|
nm_property_infos_xml = {
|
||||||
'dbus': nm_property_infos_xml_dbus,
|
'dbus': nm_property_infos_xml_dbus,
|
||||||
'keyfile': nm_property_infos_xml_keyfile,
|
'keyfile': nm_property_infos_xml_keyfile,
|
||||||
|
'nmcli': nm_property_infos_xml_nmcli,
|
||||||
'ifcfg-rh': nm_property_infos_xml_ifcfg_rh,
|
'ifcfg-rh': nm_property_infos_xml_ifcfg_rh,
|
||||||
}
|
}
|
||||||
else
|
else
|
||||||
nm_property_infos_xml = {
|
nm_property_infos_xml = {
|
||||||
'dbus': nm_property_infos_xml_dbus,
|
'dbus': nm_property_infos_xml_dbus,
|
||||||
'keyfile': nm_property_infos_xml_keyfile,
|
'keyfile': nm_property_infos_xml_keyfile,
|
||||||
|
'nmcli': nm_property_infos_xml_nmcli,
|
||||||
}
|
}
|
||||||
endif
|
endif
|
||||||
|
|
||||||
|
@ -288,24 +292,33 @@ if enable_introspection
|
||||||
depends: libnm_gir,
|
depends: libnm_gir,
|
||||||
)
|
)
|
||||||
|
|
||||||
name = 'dbus'
|
foreach name: ['dbus', 'nmcli']
|
||||||
nm_settings_docs_xml_dbus = custom_target(
|
t = custom_target(
|
||||||
'nm-settings-docs-' + name + '.xml',
|
'nm-settings-docs-' + name + '.xml',
|
||||||
input: [nm_settings_docs_xml_gir, nm_property_infos_xml[name]],
|
input: [nm_settings_docs_xml_gir, nm_property_infos_xml[name]],
|
||||||
output: 'nm-settings-docs-' + name + '.xml',
|
output: 'nm-settings-docs-' + name + '.xml',
|
||||||
command: [
|
command: [
|
||||||
python.path(),
|
python.path(),
|
||||||
join_paths(meson.current_source_dir(), 'generate-docs-nm-settings-docs-merge.py'),
|
join_paths(meson.current_source_dir(), 'generate-docs-nm-settings-docs-merge.py'),
|
||||||
'@OUTPUT@',
|
'@OUTPUT@',
|
||||||
nm_property_infos_xml[name],
|
nm_property_infos_xml[name],
|
||||||
nm_settings_docs_xml_gir,
|
nm_settings_docs_xml_gir,
|
||||||
],
|
],
|
||||||
depends: libnm_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 = {
|
nm_settings_docs_xml = {
|
||||||
'gir': nm_settings_docs_xml_gir,
|
'gir': nm_settings_docs_xml_gir,
|
||||||
'dbus': nm_settings_docs_xml_dbus,
|
'dbus': nm_settings_docs_xml_dbus,
|
||||||
|
'nmcli': nm_settings_docs_xml_nmcli,
|
||||||
}
|
}
|
||||||
|
|
||||||
endif
|
endif
|
||||||
|
|
|
@ -58,7 +58,8 @@ endforeach
|
||||||
if enable_introspection
|
if enable_introspection
|
||||||
mans = [
|
mans = [
|
||||||
['nm-settings-keyfile', '5', nm_property_infos_xml['keyfile']],
|
['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
|
if enable_ifcfg_rh
|
||||||
|
|
|
@ -13,20 +13,20 @@
|
||||||
/>
|
/>
|
||||||
|
|
||||||
<xsl:template match="nm-setting-docs">
|
<xsl:template match="nm-setting-docs">
|
||||||
<refentry id="nm-settings">
|
<refentry id="nm-settings-dbus">
|
||||||
<refentryinfo>
|
<refentryinfo>
|
||||||
<title>nm-settings</title>
|
<title>nm-settings-dbus</title>
|
||||||
<author>NetworkManager developers</author>
|
<author>NetworkManager developers</author>
|
||||||
</refentryinfo>
|
</refentryinfo>
|
||||||
<refmeta>
|
<refmeta>
|
||||||
<refentrytitle>nm-settings</refentrytitle>
|
<refentrytitle>nm-settings-dbus</refentrytitle>
|
||||||
<manvolnum>5</manvolnum>
|
<manvolnum>5</manvolnum>
|
||||||
<refmiscinfo class="source">NetworkManager</refmiscinfo>
|
<refmiscinfo class="source">NetworkManager</refmiscinfo>
|
||||||
<refmiscinfo class="manual">Configuration</refmiscinfo>
|
<refmiscinfo class="manual">Configuration</refmiscinfo>
|
||||||
<refmiscinfo class="version">&NM_VERSION;</refmiscinfo>
|
<refmiscinfo class="version">&NM_VERSION;</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>nm-settings</refname>
|
<refname>nm-settings-dbus</refname>
|
||||||
<refpurpose>Description of settings and properties of NetworkManager connection profiles</refpurpose>
|
<refpurpose>Description of settings and properties of NetworkManager connection profiles</refpurpose>
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
|
@ -155,7 +155,7 @@
|
||||||
<xsl:template match="property">
|
<xsl:template match="property">
|
||||||
<xsl:variable name="setting_name" select="../@name"/>
|
<xsl:variable name="setting_name" select="../@name"/>
|
||||||
<row>
|
<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="@type"/></entry>
|
||||||
<entry align="left"><xsl:value-of select="@default"/></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>
|
<entry><xsl:value-of select="@description"/><xsl:if test="@type = 'NMSettingSecretFlags (uint32)'"> (see <xref linkend="secrets-flags"/> for flag values)</xsl:if></entry>
|
165
man/nm-settings-nmcli.xsl
Normal file
165
man/nm-settings-nmcli.xsl
Normal file
|
@ -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>
|
|
@ -52,6 +52,7 @@ if [ "$enable_docs" = 1 ]; then
|
||||||
done
|
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/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
|
fi
|
||||||
|
|
||||||
if [ "$enable_ifcfg_rh" = 1 ]; then
|
if [ "$enable_ifcfg_rh" = 1 ]; then
|
||||||
|
|
Loading…
Reference in a new issue