libnm-core: clarify the meaning of the connection.permissions property

https://bugzilla.redhat.com/show_bug.cgi?id=1457939

2 files changed, 8 insertions, 6 deletions

diff --git a/clients/common/settings-docs.c.in b/clients/common/settings-docs.c.in
index e92152b3e8..71a634afe9 100644
--- a/clients/common/settings-docs.c.in
+++ b/clients/common/settings-docs.c.in
@@ -144,7 +144,7 @@
 #define DESCRIBE_DOC_NM_SETTING_CONNECTION_MASTER N_("Interface name of the master device or UUID of the master connection.")
 #define DESCRIBE_DOC_NM_SETTING_CONNECTION_METERED N_("Whether the connection is metered. When updating this property on a currently activated connection, the change takes effect immediately.")
 #define DESCRIBE_DOC_NM_SETTING_CONNECTION_NAME N_("The setting's name, which uniquely identifies the setting within the connection.  Each setting type has a name unique to that type, for example \"ppp\" or \"wireless\" or \"wired\".")
-#define DESCRIBE_DOC_NM_SETTING_CONNECTION_PERMISSIONS N_("An array of strings defining what access a given user has to this connection.  If this is NULL or empty, all users are allowed to access this connection.  Otherwise a user is allowed to access this connection if and only if they are in this list. Each entry is of the form \"[type]:[id]:[reserved]\"; for example, \"user:dcbw:blah\". At this time only the \"user\" [type] is allowed.  Any other values are ignored and reserved for future use.  [id] is the username that this permission refers to, which may not contain the \":\" character. Any [reserved] information present must be ignored and is reserved for future use.  All of [type], [id], and [reserved] must be valid UTF-8.")
+#define DESCRIBE_DOC_NM_SETTING_CONNECTION_PERMISSIONS N_("An array of strings defining what access a given user has to this connection.  If this is NULL or empty, all users are allowed to access this connection; otherwise users are allowed if and only if they are in this list.  When this is not empty, the connection can be active only when one of the specified users is logged into an active session.  Each entry is of the form \"[type]:[id]:[reserved]\"; for example, \"user:dcbw:blah\". At this time only the \"user\" [type] is allowed.  Any other values are ignored and reserved for future use.  [id] is the username that this permission refers to, which may not contain the \":\" character. Any [reserved] information present must be ignored and is reserved for future use.  All of [type], [id], and [reserved] must be valid UTF-8.")
 #define DESCRIBE_DOC_NM_SETTING_CONNECTION_READ_ONLY N_("FALSE if the connection can be modified using the provided settings service's D-Bus interface with the right privileges, or TRUE if the connection is read-only and cannot be modified.")
 #define DESCRIBE_DOC_NM_SETTING_CONNECTION_SECONDARIES N_("List of connection UUIDs that should be activated when the base connection itself is activated. Currently only VPN connections are supported.")
 #define DESCRIBE_DOC_NM_SETTING_CONNECTION_SLAVE_TYPE N_("Setting name of the device type of this slave's master connection (eg, \"bond\"), or NULL if this connection is not a slave.")
diff --git a/libnm-core/nm-setting-connection.c b/libnm-core/nm-setting-connection.c
index a0a7efe02e..f94bc6b547 100644
--- a/libnm-core/nm-setting-connection.c
+++ b/libnm-core/nm-setting-connection.c
@@ -1562,9 +1562,10 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
 	 *
 	 * An array of strings defining what access a given user has to this
 	 * connection.  If this is %NULL or empty, all users are allowed to access
-	 * this connection.  Otherwise a user is allowed to access this connection
-	 * if and only if they are in this list. Each entry is of the form
-	 * "[type]:[id]:[reserved]"; for example, "user:dcbw:blah".
+	 * this connection; otherwise users are allowed if and only if they are in
+	 * this list.  When this is not empty, the connection can be active only when
+	 * one of the specified users is logged into an active session.  Each entry
+	 * is of the form "[type]:[id]:[reserved]"; for example, "user:dcbw:blah".
 	 *
 	 * At this time only the "user" [type] is allowed.  Any other values are
 	 * ignored and reserved for future use.  [id] is the username that this
@@ -1575,8 +1576,9 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
 	/* ---ifcfg-rh---
 	 * property: permissions
 	 * variable: USERS(+)
-	 * description: USERS restrict the access for this conenction to certain
-	 *   users only.
+	 * description: Restrict to certain users the access to this connection, and
+	 *     allow the connection to be active only when at least one of the
+	 *     specified users is logged into an active session.
 	 * example: USERS="joe bob"
 	 * ---end---
 	 */