qm: Add section explaining fs-freeze/-thaw QGA option

[pve-docs.git] / pveum.adoc

diff --git a/pveum.adoc b/pveum.adoc
index 38fd9413182149fd1f091f07c7b533a80b85355f..147f3174f5e57d9efecde312fcb404c61de8a936 100644 (file)
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -1,4 +1,7 @@
 [[chapter_user_management]]
+
+[[user_mgmt]]
+
 ifdef::manvolnum[]
 pveum(1)
 ========
@@ -161,6 +164,7 @@ OpenID Connect is implemented as an identity layer on top of the OATH 2.0
 protocol. It allows clients to verify the identity of the user, based on
 authentication performed by an external authorization server.
 
+[[user-realms-pam]]
 Linux PAM Standard Authentication
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -172,6 +176,7 @@ authentication with logins from the realm and to set the realm as the default
 authentication realm.
 
 
+[[user-realms-pve]]
 {pve} Authentication Server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -185,6 +190,7 @@ through {pve}, rather than authenticating against another system. Hence, you are
 required to set a password for this type of user upon creation.
 
 
+[[user-realms-ldap]]
 LDAP
 ~~~~
 
@@ -249,6 +255,7 @@ you must also add them as a user of that realm from the {pve} server. This can
 be carried out automatically with <<pveum_ldap_sync, syncing>>.
 
 
+[[user-realms-ad]]
 Microsoft Active Directory (AD)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -295,12 +302,21 @@ pveum realm sync <realm>
 Users and groups are synced to the cluster-wide configuration file,
 `/etc/pve/user.cfg`.
 
+
+Attributes to Properties
+^^^^^^^^^^^^^^^^^^^^^^^^
+
 If the sync response includes user attributes, they will be synced into the
-matching user property in the `user.cfg` (for example: 'firstname', 'lastname',
-etc.). If the names of the attributes are not matching the PVE properties, you
-can set a custom field-to-field map in the config with the 'sync_attributes'
+matching user property in the `user.cfg`. For example: `firstname` or
+`lastname`.
+
+If the names of the attributes are not matching the {pve} properties, you can
+set a custom field-to-field map in the config by using the `sync_attributes`
 option.
 
+How such properties are handled if anything vanishes can be controlled via the
+sync options, see below.
+
 Sync Configuration
 ^^^^^^^^^^^^^^^^^^
 
@@ -378,6 +394,32 @@ The main options for syncing are:
 * `Preview` (`dry-run`): No data is written to the config. This is useful if you
   want to see which users and groups would get synced to the `user.cfg`.
 
+[[pveum_ldap_reserved_characters]]
+Reserved characters
+^^^^^^^^^^^^^^^^^^^
+
+Certain characters are reserved (see https://www.ietf.org/rfc/rfc2253.txt[RFC2253]) and cannot be
+easily used in attribute values in DNs without being escaped properly.
+
+Following characters need escaping:
+
+* Space ( )
+* Comma (`,`)
+* Plus sign (`+`)
+* Double quote (`"`)
+* Forward slashes (`/`)
+* Angle brackets (`<>`)
+* Semicolon (`;`)
+* Equals sign (`=`)
+
+To use such characters in DNs, surround the attribute value in double quotes.
+For example, to bind with a user with the CN (Common Name) `Example, User`, use
+`CN="Example, User",OU=people,DC=example,DC=com` as value for `bind_dn`.
+
+This applies to the `base_dn`, `bind_dn`, and `group_dn` attributes.
+
+NOTE: Users with colons and forward slashes cannot be synced since these are
+reserved characters in usernames.
 
 [[pveum_openid]]
 OpenID Connect
@@ -449,7 +491,7 @@ example, you need to replace the `--issuer-url` and `--client-id` with
 your information:
 
 ----
-pveum realm add myrealm2 --type openid --issuer-url  https://your.server:8080/auth/realms/your-realm --client-id XXX --username-claim username
+pveum realm add myrealm2 --type openid --issuer-url  https://your.server:8080/realms/your-realm --client-id XXX --username-claim username
 ----
 
 Using `--username-claim username` enables simple usernames on the
@@ -615,8 +657,7 @@ registrations unusable!
 This is done via `/etc/pve/datacenter.cfg`. For instance:
 
 ----
-webauthn:
-rp=mypve.example.com,origin=https://mypve.example.com:8006,id=mypve.example.com
+webauthn: rp=mypve.example.com,origin=https://mypve.example.com:8006,id=mypve.example.com
 ----
 
 [[pveum_configure_u2f]]
@@ -745,6 +786,7 @@ Node / System related privileges::
 * `Sys.Syslog`: view syslog
 * `Sys.Audit`: view node status/config, Corosync cluster config, and HA config
 * `Sys.Modify`: create/modify/remove node network parameters
+* `Sys.Incoming`: allow incoming data streams from other clusters (experimental)
 * `Group.Allocate`: create/modify/remove groups
 * `Pool.Allocate`: create/modify/remove a pool
 * `Pool.Audit`: view a pool
@@ -769,6 +811,7 @@ Virtual machine related privileges::
 * `VM.Config.Network`: add/modify/remove network devices
 * `VM.Config.HWType`: modify emulated hardware types
 * `VM.Config.Options`: modify any other VM configuration
+* `VM.Config.Cloudinit`: modify Cloud-init parameters
 * `VM.Snapshot`: create/delete VM snapshots
 
 Storage related privileges::
@@ -882,9 +925,9 @@ The `path` is a templated parameter (see
 `Permissions.Modify` privilege or,
 depending on the path, the following privileges as a possible substitute:
 +
-* `/storage/...`: additionally requires 'Datastore.Allocate`
-* `/vms/...`: additionally requires 'VM.Allocate`
-* `/pool/...`: additionally requires 'Pool.Allocate`
+* `/storage/...`: requires 'Datastore.Allocate`
+* `/vms/...`: requires 'VM.Allocate`
+* `/pool/...`: requires 'Pool.Allocate`
 +
 If the path is empty, `Permission.Modify` on `/access` is required.