+[[chapter_user_management]]
ifdef::manvolnum[]
-PVE({manvolnum})
-================
-include::attributes.txt[]
+pveum(1)
+========
+:pve-toplevel:
NAME
----
pveum - Proxmox VE User Manager
-SYNOPSYS
+SYNOPSIS
--------
include::pveum.1-synopsis.adoc[]
DESCRIPTION
-----------
endif::manvolnum[]
-
ifndef::manvolnum[]
User Management
===============
-include::attributes.txt[]
+:pve-toplevel:
endif::manvolnum[]
// Copied from pve wiki: Revision as of 16:10, 27 October 2015
objects (VMs, storages, nodes, etc.) granular access can be defined.
+[[pveum_users]]
Users
-----
{pve} stores user attributes in `/etc/pve/user.cfg`.
Passwords are not stored here, users are instead associated with
-<<authentication-realms,authentication realms>> described below.
+<<pveum_authentication_realms,authentication realms>> described below.
Therefore a user is internally often identified by its name and
realm in the form `<userid>@<realm>`.
assigned to this user.
+[[pveum_groups]]
Groups
~~~~~~
much shorter access control list which is easier to handle.
-[[authentication-realms]]
+[[pveum_authentication_realms]]
Authentication Realms
---------------------
The following realms (authentication methods) are available:
Linux PAM standard authentication::
-In this case a system user has to exist (eg. created via the `adduser`
+In this case a system user has to exist (e.g. created via the `adduser`
command) on all nodes the user is allowed to login, and the user
authenticates with their usual system password.
+
Proxmox VE authentication server::
This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
Password are encrypted using the SHA-256 hash method.
-This is the most convenient method for for small (or even medium)
+This is the most convenient method for small (or even medium)
installations where users do not need access to anything outside of
{pve}. In this case users are fully managed by {pve} and are able to
change their own passwords via the GUI.
LDAP::
-It is possible to authenticate users via an LDAP server (eq.
+It is possible to authenticate users via an LDAP server (e.g.
openldap). The server and an optional fallback server can be
configured and the connection can be encrypted via SSL.
+
able to query and authenticate users, a bind domain name can be
configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
-(eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
+(e.g. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
single line containing the raw password.
Microsoft Active Directory::
host your own verification server].
+[[pveum_permission_management]]
Permission Management
---------------------
representing the target of these actions.
+[[pveum_roles]]
Roles
~~~~~
You can see the whole set of predefined roles on the GUI.
-Adding new roles can currently only be done from the command line, like
+Adding new roles can be done via both GUI and the command line, like
this:
[source,bash]
----
-Objects and Paths
-~~~~~~~~~~~~~~~~~
-
-Access permissions are assigned to objects, such as a virtual machines
-(`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of
-resources (`/pool/{poolname}`). We use file system like paths to
-address those objects. Those paths form a natural tree, and
-permissions can be inherited down that hierarchy.
-
-
Privileges
~~~~~~~~~~
* `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
* `Sys.Console`: console access to Node
* `Sys.Syslog`: view Syslog
-* `Sys.Audit`: view node status/config
+* `Sys.Audit`: view node status/config, Corosync cluster config and HA config
* `Sys.Modify`: create/remove/modify node network parameters
* `Group.Allocate`: create/remove/modify groups
* `Pool.Allocate`: create/remove/modify a pool
* `Datastore.Audit`: view/browse a datastore
-Permissions
-~~~~~~~~~~~
+Objects and Paths
+~~~~~~~~~~~~~~~~~
+
+Access permissions are assigned to objects, such as a virtual machines,
+storages or pools of resources.
+We use file system like paths to address these objects. These paths form a
+natural tree, and permissions of higher levels (shorter path) can
+optionally be propagated down within this hierarchy.
+
+[[pveum_templated_paths]]
+Paths can be templated. When an API call requires permissions on a
+templated path, the path may contain references to parameters of the API
+call. These references are specified in curly braces. Some parameters are
+implicitly taken from the API call's URI. For instance the permission path
+`/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
+`/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
+refers to the method's `path` parameter.
-Permissions are the way we control access to objects. In technical
-terms they are simply a triple containing `<path,user,role>`. This
-concept is also known as access control lists. Each permission
-specifies a subject (user or group) and a role (set of privileges) on
-a specific path.
+Some examples are:
-When a subject requests an action on an object, the framework looks up
-the roles assigned to that subject (using the object path). The set of
-roles defines the granted privileges.
+* `/nodes/{node}`: Access to {pve} server machines
+* `/vms`: Covers all VMs
+* `/vms/{vmid}`: Access to specific VMs
+* `/storage/{storeid}`: Access to a storages
+* `/pool/{poolname}`: Access to VMs part of a <<pveum_pools,pool>>
+* `/access/groups`: Group administration
+* `/access/realms/{realmid}`: Administrative access to realms
Inheritance
* Permissions replace the ones inherited from an upper level.
+[[pveum_pools]]
Pools
~~~~~
Each(`and`) or any(`or`) further element in the current list has to be true.
`["perm", <path>, [ <privileges>... ], <options>...]`::
-The `path` is a templated parameter (see <<templated-paths,Objects and
-Paths>>). All (or , if the `any` option is used, any) of the listed
+The `path` is a templated parameter (see
+<<pveum_templated_paths,Objects and Paths>>). All (or , if the `any`
+option is used, any) of the listed
privileges must be allowed on the specified path. If a `require-param`
option is specified, then its specified parameter is required even if the
API call's schema otherwise lists it as being optional.
`["userid-group", [ <privileges>... ], <options>...]`::
-The callermust have any of the listed privileges on `/access/groups`. In
+The caller must have any of the listed privileges on `/access/groups`. In
addition there are two possible checks depending on whether the
`groups_param` option is set:
+
`["userid-param", "Realm.AllocateUser"]`::
The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
-`<realm>` refering to the realm of the user passed via the `userid`
+`<realm>` referring to the realm of the user passed via the `userid`
parameter. Note that the user does not need to exist in order to be
associated with a realm, since user IDs are passed in the form of
`<username>@<realm>`.
`["perm-modify", <path>]`::
-The `path` is a templated parameter (see <<templated-paths,Objects and
-Paths>>). The user needs either the `Permissions.Modify` privilege, or,
+The `path` is a templated parameter (see
+<<pveum_templated_paths,Objects and Paths>>). The user needs either the
+`Permissions.Modify` privilege, or,
depending on the path, the following privileges as a possible substitute:
+
* `/storage/...`: additionally requires 'Datastore.Allocate`
Delegate User Management
~~~~~~~~~~~~~~~~~~~~~~~~
-If you want to delegate user managenent to user `joe@pve` you can do
+If you want to delegate user management to user `joe@pve` you can do
that with:
[source,bash]
projects / pve-docs.git / blobdiff