From f27fac5109ca28173b4a3a9ff225df7757f4cd57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ji=C5=99=C3=AD=20Klime=C5=A1?= Date: Tue, 8 Jul 2014 12:28:04 +0200 Subject: [PATCH] man: generate nm-settings-ifcfg-rh(5) manual page --- man/Makefile.am | 15 +- man/nm-settings-ifcfg-rh.xsl | 362 +++++++++++++++++++++++++++++++++++ 2 files changed, 375 insertions(+), 2 deletions(-) create mode 100644 man/nm-settings-ifcfg-rh.xsl diff --git a/man/Makefile.am b/man/Makefile.am index 0f4b139afb..376a8b42ac 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -41,6 +41,13 @@ nm-settings-keyfile.xml: nm-settings-keyfile.xsl $(top_builddir)/libnm-util/nm-k --stringparam date "`date +'%d %B %Y'`" \ $^ +nm-settings-ifcfg-rh.xml: nm-settings-ifcfg-rh.xsl $(top_builddir)/libnm-util/nm-ifcfg-rh-docs.xml + $(AM_V_GEN) xsltproc \ + --output $@ \ + --stringparam version $(NM_VERSION) \ + --stringparam date "`date +'%d %B %Y'`" \ + $^ + endif configure_generated_man_pages = \ @@ -55,19 +62,23 @@ docbook_generated_man_pages = \ docbook_autogenerated_man_pages = \ nm-settings.5 \ - nm-settings-keyfile.5 + nm-settings-keyfile.5 \ + nm-settings-ifcfg-rh.5 EXTRA_DIST += \ nm-settings.xml \ nm-settings.xsl \ nm-settings-keyfile.xml \ nm-settings-keyfile.xsl \ + nm-settings-ifcfg-rh.xml \ + nm-settings-ifcfg-rh.xsl \ $(docbook_generated_man_pages:.%=.xml) \ $(docbook_autogenerated_man_pages) DISTCLEANFILES = \ nm-settings.xml \ - nm-settings-keyfile.xml + nm-settings-keyfile.xml \ + nm-settings-ifcfg-rh.xml man_MANS += $(configure_generated_man_pages) diff --git a/man/nm-settings-ifcfg-rh.xsl b/man/nm-settings-ifcfg-rh.xsl new file mode 100644 index 0000000000..5c7fbfae15 --- /dev/null +++ b/man/nm-settings-ifcfg-rh.xsl @@ -0,0 +1,362 @@ + + + + + + + + + + + + + + + + + + + nm-settings-ifcfg-rh + 5 + NetworkManager + Configuration + + + + nm-settings-ifcfg-rh + Description of ifcfg-rh settings plugin + + + DESCRIPTION + + NetworkManager is based on the concept of connection profiles that contain + network configuration (see nm-settings + 5 for details). The profiles can be + stored in various formats. NetworkManager uses plugins for reading and writing + the data. The plugins can be configured in + NetworkManager.conf5. + + + The ifcfg-rh plugin is used on the Fedora and Red Hat + Enterprise Linux distributions to read/write configuration from/to + the standard /etc/sysconfig/network-scripts/ifcfg-* files. + Each NetworkManager connection maps to one ifcfg-* file, with + possible usage of keys-* for passwords, route-* + for static IPv4 routes and route6-* for static IPv6 routes. + The plugin currently supports reading and writing Ethernet, Wi-Fi, InfiniBand, + VLAN, Bond, Bridge, and Team connections. Unsupported connection types (such as + (WWAN, PPPoE, VPN, or ADSL) are handled by keyfile plugin + (nm-settings-keyfile5). + The main reason for using ifcfg-rh plugin is the compatibility + with legacy configurations for ifup and ifdown + (initscripts). + + + + File Format + + The ifcfg-rh config format is a simple text file containing + VARIABLE="value" lines. The format is described in sysconfig.txt + of initscripts package. Note that the configuration files + may be sourced by initscripts, so they must be valid shell + scripts. That means, for instance, that # character can be used + for comments, strings with spaces must be quoted, special characters must be escaped, + etc. + + + Users can create or modify the ifcfg-rh connection files + manually, even if that is not the recommended way of managing the profiles. + However, if they choose to do that, they must inform NetworkManager about + their changes (see monitor-connection-file in + nm-settings5 + , and nmcli con (re)load). + + + Some <emphasis>ifcfg-rh</emphasis> configuration examples: + + + Simple DHCP ethernet configuration: +NAME=ethernet +UUID=1c4ddf70-01bf-46d6-b04f-47e842bd98da +TYPE=Ethernet +BOOTPROTO=dhcp +DEFROUTE=yes +PEERDNS=yes +PEERROUTES=yes +IPV4_FAILURE_FATAL=no +ONBOOT=yes + + + + + Simple ethernet configuration with static IP: +TYPE=Ethernet +BOOTPROTO=none +IPADDR=10.1.0.25 +PREFIX=24 +GATEWAY=10.1.0.1 +DEFROUTE=yes +IPV4_FAILURE_FATAL=no +IPV6INIT=yes +IPV6_AUTOCONF=yes +IPV6_DEFROUTE=yes +IPV6_PEERDNS=yes +IPV6_PEERROUTES=yes +IPV6_FAILURE_FATAL=no +NAME=ethernet-em2 +UUID=51bb3904-c0fc-4dfe-83b2-0a71e7928c13 +DEVICE=em2 +ONBOOT=yes + + + + + WPA2 Enterprise WLAN (TTLS with inner MSCHAPV2 authentication): +ESSID="CompanyWLAN" +MODE=Managed +KEY_MGMT=WPA-EAP +TYPE=Wireless +IEEE_8021X_EAP_METHODS=TTLS +IEEE_8021X_IDENTITY=joe +IEEE_8021X_PASSWORD_FLAGS=ask +IEEE_8021X_INNER_AUTH_METHODS=MSCHAPV2 +IEEE_8021X_CA_CERT=/home/joe/.cert/company.crt +BOOTPROTO=dhcp +DEFROUTE=yes +PEERDNS=yes +PEERROUTES=yes +IPV4_FAILURE_FATAL=no +IPV6INIT=no +NAME=MyCompany +UUID=f79848ff-11a6-4810-9e1a-99039dea84c4 +ONBOOT=yes + + + + + Team and team port configuration: +ifcfg-my_team0: +DEVICE=team0 +TEAM_CONFIG="{ \"device\": \"team0\", \"runner\": {\"name\": \"roundrobin\"}, \"ports\": {\"eth1\": {}, \"eth2\": {}} }" +DEVICETYPE=Team +BOOTPROTO=dhcp +NAME=team0-profile +UUID=1d3460a0-7b37-457f-a300-fe8d92da4807 +ONBOOT=yes + +ifcfg-my_team0_slave1: +NAME=team0-slave1 +UUID=d5aed298-c567-4cc1-b808-6d38ecef9e64 +DEVICE=eth0 +ONBOOT=yes +TEAM_MASTER=team0 +DEVICETYPE=TeamPort + + + + + + + Differences against initscripts + + The main differences of NetworkManager ifcfg-rh plugin and traditional + initscripts are: + + + NM_CONTROLLED=yes|no + + NM_CONTROLLED is NetworkManager-specific variable used by NetworkManager + for determining whether the device of the ifcfg file + should be managed. NM_CONTROLLED=yes is supposed if the variable is not + present in the file. + Note that if you have more ifcfg files for a single + device, NM_CONTROLLED=no in one of the files will cause the device not + to be managed. The profile may not even be the active one. + + + + New variables + + NetworkManager has introduced some new variable, not present in initscripts, + to be able to store data for its new features. The variables are marked + as extensions in the tables bellows. + + + + Semantic change of variables + + NetworkManager had to slightly change the semantic for a few variables. + + + PEERDNS - + initscripts interpret PEERDNS=no to mean "never touch resolv.conf". + NetworkManager interprets it to say "never add automatic (DHCP, PPP, VPN, etc.) + nameservers to resolv.conf". + + + ONBOOT - + initscripts use ONBOOT=yes to mark the devices that are to be activated + during boot. NetworkManager extents this to also mean that this profile + can be used for auto-connecting at any time. + + + + + + + + See the next section for detailed mapping of NetworkManager properties and + ifcfg-rh variables. Variable names, format and usage + differences in NetworkManager and initscripts are documented in the tables bellow. + + + + + DETAILS + + ifcfg-rh plugin variables marked with (+) + are NetworkManager specific extensions not understood by traditional initscripts. + + + + Secret flags + + Each secret property in a NetworkManager setting has an associated + flags property that describes how to handle that secret. + In the fcfg-rh plugin variables for secret flags have a + -FLAGS suffix. The variables contain one or more of the + folowing values (space separated). Missing (or empty) -FLAGS variable means + that the password is owned by NetworkManager. + + + + user - a user-session secret agent is responsible for providing + and storing this secret; when it is required, agents will be asked to provide it. + + + ask - the associated password is not saved but it will be + requested from the user each time it is required. + + + unused - 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. + + + + + + + AUTHOR + + + NetworkManager developers + + + + + FILES + /etc/sysconfig/network-scripts/ifcfg-* + /etc/sysconfig/network-scripts/keys-* + /etc/sysconfig/network-scripts/route-* + /etc/sysconfig/network-scripts/route6-* + /usr/share/doc/initscripts/sysconfig.txt + + + SEE ALSO + https://developer.gnome.org/NetworkManager/unstable/ref-settings.html + nm-settings(5), nm-settings-keyfile(5), NetworkManager(8), NetworkManager.conf(5), nmcli(1), nmcli-examples(5) + + + + + + + + + + <xsl:value-of select="@name"/> setting + + + + Property + Ifcfg-rh Variable + Default + Description + + + + + + +
+ + + + + All DCB related configuration is a NetworkManager extention. DCB=yes must be + used explicitly to enable DCB so that the rest of the DCB_* variables can apply. + + + + + The following settings are not supported by ifcfg-rh plugin: + + + + + + + + + + + + + + + + + + + (see for _FLAGS values) + + + + +Example: + + + + +Allowed values: + + + + + + + + + + + + + + + + + + + + + + + +