libnm, libnm-util: move settings doc generation to libnm-core

Move the settings/plugins doc generation from libnm-util to
libnm-core, since libnm-util isn't being updated for all new
properties.

With this commit, the keyfile and ifcfg-rh documentation is basically
unchanged, except that deprecated properties are now gone, and new
properties have been added, and the sections are in a different order.
(generate-plugin-docs.pl just outputs the settings in Makefile order,
and they were unsorted in libnm-util, but are sorted in libnm-core).

The settings documentation used for nm-settings.5, the D-Bus API docs,
and the nmcli help is changed a bit more at this point, and mostly for
the worse, since the libnm-core setting properties don't match up with
the D-Bus API as well as the libnm-util ones do. To be fixed...

(I also removed the "plugins docs" line in each plugin docs comment
block while moving them, since those blocks will be used for more than
just plugins soon, and it's sort of obvious anyway.)

1 files changed, 204 insertions, 0 deletions

diff --git a/libnm-core/nm-setting-8021x.c b/libnm-core/nm-setting-8021x.c
index 144b9b5986..90f52f6025 100644
--- a/libnm-core/nm-setting-8021x.c
+++ b/libnm-core/nm-setting-8021x.c
@@ -3101,6 +3101,14 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * properties of this setting; refer to wpa_supplicant documentation for the
 	 * allowed combinations.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: eap
+	 * variable: IEEE_8021X_EAP_METHODS(+)
+	 * values: "LEAP", "PWD", "TLS", "PEAP", "TTLS", "FAST"
+	 * description: EAP method for 802.1X authentication.
+	 * example: IEEE_8021X_EAP_METHODS=PEAP
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_EAP,
 		 g_param_spec_boxed (NM_SETTING_802_1X_EAP, "", "",
@@ -3114,6 +3122,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * Identity string for EAP authentication methods.  Often the user's user or
 	 * login name.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: identity
+	 * variable: IEEE_8021X_IDENTITY(+)
+	 * description: Identity for EAP authentication methods.
+	 * example: IEEE_8021X_IDENTITY=itsme
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_IDENTITY,
 		 g_param_spec_string (NM_SETTING_802_1X_IDENTITY, "", "",
@@ -3128,6 +3143,12 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * unencrypted identity with EAP types that support different tunneled
 	 * identity like EAP-TTLS.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: anonymous-identity
+	 * variable: IEEE_8021X_ANON_IDENTITY(+)
+	 * description: Anonymous identity for EAP authentication methods.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_ANONYMOUS_IDENTITY,
 		 g_param_spec_string (NM_SETTING_802_1X_ANONYMOUS_IDENTITY, "", "",
@@ -3140,6 +3161,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 *
 	 * UTF-8 encoded file path containing PAC for EAP-FAST.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: pac-file
+	 * variable: IEEE_8021X_PAC_FILE(+)
+	 * description: File with PAC (Protected Access Credential) for EAP-FAST.
+	 * example: IEEE_8021X_PAC_FILE=/home/joe/my-fast.pac
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PAC_FILE,
 		 g_param_spec_string (NM_SETTING_802_1X_PAC_FILE, "", "",
@@ -3165,6 +3193,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * Setting this property directly is discouraged; use the
 	 * nm_setting_802_1x_set_ca_cert() function instead.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: ca-cert
+	 * variable: IEEE_8021X_CA_CERT(+)
+	 * description: CA certificate for EAP.
+	 * example: IEEE_8021X_CA_CERT=/home/joe/cacert.crt
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_CA_CERT,
 		 g_param_spec_boxed (NM_SETTING_802_1X_CA_CERT, "", "",
@@ -3183,6 +3218,12 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * certificates to be added to the verification chain in addition to the
 	 * certificate specified in the #NMSetting8021x:ca-cert property.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: ca-path
+	 * variable: (none)
+	 * description: The property is not handled by ifcfg-rh plugin.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_CA_PATH,
 		 g_param_spec_string (NM_SETTING_802_1X_CA_PATH, "", "",
@@ -3197,6 +3238,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * by the authentication server. When unset, no verification of the
 	 * authentication server certificate's subject is performed.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: subject-match
+	 * variable: IEEE_8021X_SUBJECT_MATCH(+)
+	 * description: Substring to match subject of server certificate against.
+	 * example: IEEE_8021X_SUBJECT_MATCH="Red Hat"
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_SUBJECT_MATCH,
 		 g_param_spec_string (NM_SETTING_802_1X_SUBJECT_MATCH, "", "",
@@ -3211,6 +3259,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * certificate presented by the authentication server. If the list is empty,
 	 * no verification of the server certificate's altSubjectName is performed.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: altubject-matches
+	 * variable: IEEE_8021X_AlTSUBJECT_MATCHES(+)
+	 * description: List of strings to be matched against the altSubjectName.
+	 * example: IEEE_8021X_ALTSUBJECT_MATCHES="s1.domain.cc"
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_ALTSUBJECT_MATCHES,
 		 g_param_spec_boxed (NM_SETTING_802_1X_ALTSUBJECT_MATCHES, "", "",
@@ -3234,6 +3289,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * Setting this property directly is discouraged; use the
 	 * nm_setting_802_1x_set_client_cert() function instead.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: client-cert
+	 * variable: IEEE_8021X_CLIENT_CERT(+)
+	 * description: Client certificate for EAP.
+	 * example: IEEE_8021X_CLIENT_CERT=/home/joe/mycert.crt
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_CLIENT_CERT,
 		 g_param_spec_boxed (NM_SETTING_802_1X_CLIENT_CERT, "", "",
@@ -3255,6 +3317,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * so, this property may be set to "0" or "1" to force that specific PEAP
 	 * version.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: phase1-peapver
+	 * variable: IEEE_8021X_PEAP_VERSION(+)
+	 * values: 0, 1
+	 * description: Use to force a specific PEAP version.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PHASE1_PEAPVER,
 		 g_param_spec_string (NM_SETTING_802_1X_PHASE1_PEAPVER, "", "",
@@ -3270,6 +3339,14 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * PEAPv1.  Set to "1" to force use of the new PEAP label.  See the
 	 * wpa_supplicant documentation for more details.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: phase1-peaplabel
+	 * variable: IEEE_8021X_PEAP_FORCE_NEW_LABEL(+)
+	 * values: yes, no
+	 * default: no
+	 * description: Use to force the new PEAP label during key derivation.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PHASE1_PEAPLABEL,
 		 g_param_spec_string (NM_SETTING_802_1X_PHASE1_PEAPLABEL, "", "",
@@ -3287,6 +3364,14 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * both authenticated and unauthenticated provisioning).  See the
 	 * wpa_supplicant documentation for more details.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: phase1-fast-provisioning
+	 * variable: IEEE_8021X_FAST_PROVISIONING(+)
+	 * values: space-separated list of these values [allow-auth, allow-unauth]
+	 * description: Enable in-line provisioning of EAP-FAST credentials.
+	 * example: IEEE_8021X_FAST_PROVISIONING="allow-auth allow-unauth"
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PHASE1_FAST_PROVISIONING,
 		 g_param_spec_string (NM_SETTING_802_1X_PHASE1_FAST_PROVISIONING, "", "",
@@ -3304,6 +3389,15 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * Each "phase 2" inner method requires specific parameters for successful
 	 * authentication; see the wpa_supplicant documentation for more details.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: phase2-auth
+	 * variable: IEEE_8021X_INNER_AUTH_METHODS(+)
+	 * values: "PAP", "CHAP", "MSCHAP", "MSCHAPV2", "GTC", "OTP", "MD5" and "TLS"
+	 * description: Inner non-EAP authentication methods. IEEE_8021X_INNER_AUTH_METHODS
+	 *   can contain values both for 'phase2-auth' and 'phase2-autheap' properties.
+	 * example: IEEE_8021X_INNER_AUTH_METHODS=PAP
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PHASE2_AUTH,
 		 g_param_spec_string (NM_SETTING_802_1X_PHASE2_AUTH, "", "",
@@ -3321,6 +3415,15 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * requires specific parameters for successful authentication; see the
 	 * wpa_supplicant documentation for more details.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: phase2-autheap
+	 * variable: IEEE_8021X_INNER_AUTH_METHODS(+)
+	 * values: "EAP-MD5", "EAP-MSCHAPV2", "EAP-GTC", "EAP-OTP" and "EAP-TLS"
+	 * description: Inner EAP-based authentication methods. Note that
+	 *   IEEE_8021X_INNER_AUTH_METHODS is also used for 'phase2-auth' values.
+	 * example: IEEE_8021X_INNER_AUTH_METHODS="MSCHAPV2 EAP-TLS"
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PHASE2_AUTHEAP,
 		 g_param_spec_string (NM_SETTING_802_1X_PHASE2_AUTHEAP, "", "",
@@ -3380,6 +3483,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * authentication. When unset, no verification of the authentication server
 	 * certificate's subject is performed.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: phase2-subject-match
+	 * variable: IEEE_8021X_PHASE2_SUBJECT_MATCH(+)
+	 * description: Substring to match subject of server certificate against.
+	 * example: IEEE_8021X_PHASE2_SUBJECT_MATCH="Red Hat"
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PHASE2_SUBJECT_MATCH,
 		 g_param_spec_string (NM_SETTING_802_1X_PHASE2_SUBJECT_MATCH, "", "",
@@ -3395,6 +3505,11 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * "phase 2" authentication. If the list is empty, no verification of the
 	 * server certificate's altSubjectName is performed.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: phase2-altsubject-matches
+	 * variable: IEEE_8021X_PHASE2_ALTSUBJECT_MATCHES(+)
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PHASE2_ALTSUBJECT_MATCHES,
 		 g_param_spec_boxed (NM_SETTING_802_1X_PHASE2_ALTSUBJECT_MATCHES, "", "",
@@ -3421,6 +3536,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * Setting this property directly is discouraged; use the
 	 * nm_setting_802_1x_set_phase2_client_cert() function instead.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: phase2-client-cert
+	 * variable: IEEE_8021X_INNER_CLIENT_CERT(+)
+	 * description: Client certificate for inner EAP method.
+	 * example: IEEE_8021X_INNER_CLIENT_CERT=/home/joe/mycert.crt
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PHASE2_CLIENT_CERT,
 		 g_param_spec_boxed (NM_SETTING_802_1X_PHASE2_CLIENT_CERT, "", "",
@@ -3439,6 +3561,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * #NMSetting8021x:password property and the #NMSetting8021x:password-raw
 	 * property are specified, #NMSetting8021x:password is preferred.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: password
+	 * variable: IEEE_8021X_PASSWORD(+)
+	 * description: UTF-8 encoded password used for EAP. It can also go to "key-"
+	 *   lookaside file, or it can be owned by a secret agent.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PASSWORD,
 		 g_param_spec_string (NM_SETTING_802_1X_PASSWORD, "", "",
@@ -3452,6 +3581,12 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 *
 	 * Flags indicating how to handle the #NMSetting8021x:password property.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: password-flags
+	 * variable: IEEE_8021X_PASSWORD_FLAGS(+)
+	 * description: Password flags for IEEE_8021X_PASSWORD password.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PASSWORD_FLAGS,
 		 g_param_spec_flags (NM_SETTING_802_1X_PASSWORD_FLAGS, "", "",
@@ -3468,6 +3603,12 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * #NMSetting8021x:password property and the #NMSetting8021x:password-raw
 	 * property are specified, #NMSetting8021x:password is preferred.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: password-raw
+	 * variable: (none)
+	 * description: The property is not handled by ifcfg-rh plugin.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PASSWORD_RAW,
 		 g_param_spec_boxed (NM_SETTING_802_1X_PASSWORD_RAW, "", "",
@@ -3485,6 +3626,12 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 *
 	 * Flags indicating how to handle the #NMSetting8021x:password-raw property.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: password-raw-flags
+	 * variable: (none)
+	 * description: The property is not handled by ifcfg-rh plugin.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PASSWORD_RAW_FLAGS,
 		 g_param_spec_flags (NM_SETTING_802_1X_PASSWORD_RAW_FLAGS, "", "",
@@ -3524,6 +3671,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * private key password to prevent unauthorized access to unencrypted
 	 * private key data.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: private-key
+	 * variable: IEEE_8021X_PRIVATE_KEY(+)
+	 * description: Private key for EAP-TLS.
+	 * example: IEEE_8021X_PRIVATE_KEY=/home/joe/mykey.p12
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PRIVATE_KEY,
 		 g_param_spec_boxed (NM_SETTING_802_1X_PRIVATE_KEY, "", "",
@@ -3545,6 +3699,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * secrets to NetworkManager; it is generally set automatically when setting
 	 * the private key by the nm_setting_802_1x_set_private_key() function.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: private-key-password
+	 * variable: IEEE_8021X_PRIVATE_KEY_PASSWORD(+)
+	 * description: Password for IEEE_8021X_PRIVATE_KEY. It can also go to "key-"
+	 *   lookaside file, or it can be owned by a secret agent.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PRIVATE_KEY_PASSWORD,
 		 g_param_spec_string (NM_SETTING_802_1X_PRIVATE_KEY_PASSWORD, "", "",
@@ -3559,6 +3720,12 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * Flags indicating how to handle the #NMSetting8021x:private-key-password
 	 * property.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: private-key-password-flags
+	 * variable: IEEE_8021X_PRIVATE_KEY_PASSWORD_FLAGS(+)
+	 * description: Password flags for IEEE_8021X_PRIVATE_KEY_PASSWORD password.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PRIVATE_KEY_PASSWORD_FLAGS,
 		 g_param_spec_flags (NM_SETTING_802_1X_PRIVATE_KEY_PASSWORD_FLAGS, "", "",
@@ -3593,6 +3760,12 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * Setting this property directly is discouraged; use the
 	 * nm_setting_802_1x_set_phase2_private_key() function instead.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: phase2-private-key
+	 * variable: IEEE_8021X_INNER_PRIVATE_KEY(+)
+	 * description: Private key for inner authentication method for EAP-TLS.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PHASE2_PRIVATE_KEY,
 		 g_param_spec_boxed (NM_SETTING_802_1X_PHASE2_PRIVATE_KEY, "", "",
@@ -3615,6 +3788,13 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * the private key by the nm_setting_802_1x_set_phase2_private_key()
 	 * function.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: phase2-private-key-password
+	 * variable: IEEE_8021X_INNER_PRIVATE_KEY_PASSWORD(+)
+	 * description: Password for IEEE_8021X_INNER_PRIVATE_KEY. It can also go to "key-"
+	 *   lookaside file, or it can be owned by a secret agent.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PHASE2_PRIVATE_KEY_PASSWORD,
 		 g_param_spec_string (NM_SETTING_802_1X_PHASE2_PRIVATE_KEY_PASSWORD, "", "",
@@ -3629,6 +3809,12 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * Flags indicating how to handle the
 	 * #NMSetting8021x:phase2-private-key-password property.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: phase2-private-key-password-flags
+	 * variable: IEEE_8021X_INNER_PRIVATE_KEY_PASSWORD_FLAGS(+)
+	 * description: Password flags for IEEE_8021X_INNER_PRIVATE_KEY_PASSWORD password.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PHASE2_PRIVATE_KEY_PASSWORD_FLAGS,
 		 g_param_spec_flags (NM_SETTING_802_1X_PHASE2_PRIVATE_KEY_PASSWORD_FLAGS, "", "",
@@ -3642,6 +3828,12 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 *
 	 * PIN used for EAP authentication methods.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: pin
+	 * variable: (none)
+	 * description: The property is not handled by ifcfg-rh plugin.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PIN,
 		 g_param_spec_string (NM_SETTING_802_1X_PIN, "", "",
@@ -3655,6 +3847,12 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 *
 	 * Flags indicating how to handle the #NMSetting8021x:pin property.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: pin-flags
+	 * variable: (none)
+	 * description: The property is not handled by ifcfg-rh plugin.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_PIN_FLAGS,
 		 g_param_spec_flags (NM_SETTING_802_1X_PIN_FLAGS, "", "",
@@ -3673,6 +3871,12 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * addition to any certificates specified by the #NMSetting8021x:ca-cert and
 	 * #NMSetting8021x:phase2-ca-cert properties.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: system-ca-certs
+	 * variable: (none)
+	 * description: The property is not handled by ifcfg-rh plugin.
+	 * ---end---
+	 */
 	g_object_class_install_property
 		(object_class, PROP_SYSTEM_CA_CERTS,
 		 g_param_spec_boolean (NM_SETTING_802_1X_SYSTEM_CA_CERTS, "", "",