mirror of
git://git.proxmox.com/git/pve-docs.git
synced 2025-03-19 18:50:06 +03:00
import pveum docs
This commit is contained in:
Dietmar Maurer
parent
c7eda5e6f5
commit
3c8533f240
371
pveum.adoc
Normal file
371
pveum.adoc
Normal file
@ -0,0 +1,371 @@
|
||||
include::attributes.txt[]
|
||||
ifdef::manvolnum[]
|
||||
PVE({manvolnum})
|
||||
================
|
||||
|
||||
NAME
|
||||
----
|
||||
|
||||
pveum - Proxmox VE User Manager
|
||||
|
||||
|
||||
SYNOPSYS
|
||||
--------
|
||||
|
||||
include::pveum.1-synopsis.adoc[]
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
endif::manvolnum[]
|
||||
|
||||
ifndef::manvolnum[]
|
||||
User Management
|
||||
===============
|
||||
endif::manvolnum[]
|
||||
|
||||
// Copied from pve wiki: Revision as of 16:10, 27 October 2015
|
||||
|
||||
Proxmox VE supports multiple authentication sources, e.g. Microsoft
|
||||
Active Directory, LDAP, Linux PAM or the integrated Proxmox VE
|
||||
authentication server.
|
||||
|
||||
By using the role based user- and permission management for all
|
||||
objects (VM´s, storages, nodes, etc.) granular access can be defined.
|
||||
|
||||
Authentication Realms
|
||||
---------------------
|
||||
|
||||
Proxmox VE stores all user attributes in '/etc/pve/user.cfg'. So there
|
||||
must be an entry for each user in that file. The password is not
|
||||
stored, instead you can use configure several realms to verify
|
||||
passwords.
|
||||
|
||||
Microsoft Active Directory::
|
||||
|
||||
LDAP::
|
||||
|
||||
Linux PAM standard authentication::
|
||||
|
||||
You need to create the system users first with 'adduser'
|
||||
(e.g. adduser heinz) and possibly the group as well. After that you
|
||||
can create the user on the GUI!
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
useradd heinz
|
||||
passwd heinz
|
||||
groupadd watchman
|
||||
usermod -a -G watchman heinz
|
||||
----
|
||||
|
||||
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. Users are allowed to change passwords.
|
||||
|
||||
Terms and Definitions
|
||||
---------------------
|
||||
|
||||
Users
|
||||
~~~~~
|
||||
|
||||
A Proxmox VE user name consists of two parts: `<userid>@<realm>`. The
|
||||
login screen on the GUI shows them a separate items, but it is
|
||||
internally used as single string.
|
||||
|
||||
We store the following attribute for users ('/etc/pve/user.cfg'):
|
||||
|
||||
* first name
|
||||
* last name
|
||||
* email address
|
||||
* expiration date
|
||||
* flag to enable/disable account
|
||||
* comment
|
||||
|
||||
Superuser
|
||||
^^^^^^^^^
|
||||
|
||||
The traditional unix superuser account is called 'root@pam'. All
|
||||
system mails are forwarded to the email assigned to that account.
|
||||
|
||||
Groups
|
||||
~~~~~~
|
||||
|
||||
Each user can be member of several groups. Groups are the preferred
|
||||
way to organize access permissions. You should always grant permission
|
||||
to groups instead of using individual users. That way you will get a
|
||||
much shorter access control list which is easier to handle.
|
||||
|
||||
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 filesystem like paths to
|
||||
address those objects. Those paths form a natural tree, and
|
||||
permissions can be inherited down that hierarchy.
|
||||
|
||||
Privileges
|
||||
~~~~~~~~~~
|
||||
|
||||
A privilege is the right to perform a specific action. To simplify
|
||||
management, lists of privileges are grouped into roles, which can then
|
||||
be uses to set permissions.
|
||||
|
||||
We currently use the following privileges:
|
||||
|
||||
Node / System related privileges::
|
||||
|
||||
* `Permissions.Modify`: modify access permissions
|
||||
* `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.Modify`: create/remove/modify node network parameters
|
||||
* `Group.Allocate`: create/remove/modify groups
|
||||
* `Pool.Allocate`: create/remove/modify a pool
|
||||
* `Realm.Allocate`: create/remove/modify authentication realms
|
||||
* `Realm.AllocateUser`: assign user to a realm
|
||||
* `User.Modify`: create/remove/modify user access and details.
|
||||
|
||||
Virtual machine related privileges::
|
||||
|
||||
* `VM.Allocate`: create/remove new VM to server inventory
|
||||
* `VM.Migrate`: migrate VM to alternate server on cluster
|
||||
* `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
|
||||
* `VM.Console`: console access to VM
|
||||
* `VM.Monitor`: access to VM monitor (kvm)
|
||||
* `VM.Backup`: backup/restore VMs
|
||||
* `VM.Audit`: view VM config
|
||||
* `VM.Clone`: clone/copy a VM
|
||||
* `VM.Config.Disk`: add/modify/delete Disks
|
||||
* `VM.Config.CDROM`: eject/change CDROM
|
||||
* `VM.Config.CPU`: modify CPU settings
|
||||
* `VM.Config.Memory`: modify Memory settings
|
||||
* `VM.Config.Network`: add/modify/delete Network devices
|
||||
* `VM.Config.HWType`: modify emulated HW type
|
||||
* `VM.Config.Options`: modify any other VM configuration
|
||||
* `VM.Snapshot`: create/remove VM snapshots
|
||||
|
||||
Storage related privileges::
|
||||
|
||||
* `Datastore.Allocate`: create/remove/modify a data store, delete volumes
|
||||
* `Datastore.AllocateSpace`: allocate space on a datastore
|
||||
* `Datastore.AllocateTemplate`: allocate/upload templates and iso images
|
||||
* `Datastore.Audit`: view/browse a datastore
|
||||
|
||||
Roles
|
||||
~~~~~
|
||||
|
||||
A role is simply a list of privileges. Proxmox VE comes with a number
|
||||
of predefined roles which satisfies most needs.
|
||||
|
||||
* `Administrator`: has all privileges
|
||||
* `NoAccess`: has no privileges (used to forbid access)
|
||||
* `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
|
||||
* `PVEAuditor`: read only access
|
||||
* `PVEDatastoreAdmin`: create and allocate backup space and templates
|
||||
* `PVEDatastoreUser`: allocate backup space and view storage
|
||||
* `PVEPoolAdmin`: allocate pools
|
||||
* `PVESysAdmin`: User ACLs, audit, system console and system logs
|
||||
* `PVETemplateUser`: view and clone templates
|
||||
* `PVEUserAdmin`: user administration
|
||||
* `PVEVMAdmin`: fully administer VMs
|
||||
* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
|
||||
|
||||
You can see the whole set of predefined roles on the GUI.
|
||||
|
||||
Adding new roles using the CLI:
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
|
||||
pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
|
||||
----
|
||||
|
||||
|
||||
Permissions
|
||||
~~~~~~~~~~~
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Inheritance
|
||||
^^^^^^^^^^^
|
||||
|
||||
As mentioned earlier, object paths forms a filesystem like tree, and
|
||||
permissions can be inherited down that tree (the propagate flag is set
|
||||
by default). We use the following inheritance rules:
|
||||
|
||||
* permission for individual users always overwrite group permission.
|
||||
* permission for groups apply when the user is member of that group.
|
||||
* permission set at higher level always overwrites inherited permissions.
|
||||
|
||||
What permission do I need?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
The required API permissions are documented for each individual method, and can be found at http://pve.proxmox.com/pve2-api-doc/
|
||||
|
||||
Pools
|
||||
~~~~~
|
||||
|
||||
Pools can be used to group a set of virtual machines and data
|
||||
stores. You can then simply set permissions on pools ('/pool/{poolid}'),
|
||||
which are inherited to all pool members. This is a great way simplify
|
||||
access control.
|
||||
|
||||
Command Line Tool
|
||||
-----------------
|
||||
|
||||
Most users will simply use the GUI to manage users. But there is also
|
||||
a full featured command line tool called 'pveum' (short for 'Proxmox
|
||||
VE User Manager'). I will use that tool in the following
|
||||
examples. Please note that all Proxmox VE command line tools are
|
||||
wrappers around the API, so you can also access those function through
|
||||
the REST API.
|
||||
|
||||
Here are some simple usage examples. To show help type:
|
||||
|
||||
[source,bash]
|
||||
pveum
|
||||
|
||||
or (to show detailed help about a specific command)
|
||||
|
||||
[source,bash]
|
||||
pveum help useradd
|
||||
|
||||
Create a new user:
|
||||
|
||||
[source,bash]
|
||||
pveum useradd testuser@pve -comment "Just a test"
|
||||
|
||||
Set or Change the password (not all realms support that):
|
||||
|
||||
[source,bash]
|
||||
pveum passwd testuser@pve
|
||||
|
||||
Disable a user:
|
||||
|
||||
[source,bash]
|
||||
pveum usermod testuser@pve -enable 0
|
||||
|
||||
Create a new group:
|
||||
|
||||
[source,bash]
|
||||
pveum groupadd testgroup
|
||||
|
||||
Create a new role:
|
||||
|
||||
[source,bash]
|
||||
pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
|
||||
|
||||
|
||||
Real World Examples
|
||||
-------------------
|
||||
|
||||
Administrator Group
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
One of the most wanted features was the ability to define a group of
|
||||
users with full administartor rights (without using the root account).
|
||||
|
||||
Define the group:
|
||||
|
||||
[source,bash]
|
||||
pveum groupadd admin -comment "System Administrators"
|
||||
|
||||
Then add the permission:
|
||||
|
||||
[source,bash]
|
||||
pveum aclmod / -group admin -role Administrator
|
||||
|
||||
You can finally add users to the new 'admin' group:
|
||||
|
||||
[source,bash]
|
||||
pveum usermod testuser@pve -group admin
|
||||
|
||||
|
||||
Auditors
|
||||
~~~~~~~~
|
||||
|
||||
You can give read only access to users by assigning the `PVEAuditor`
|
||||
role to users or groups.
|
||||
|
||||
Example1: Allow user 'joe@pve' to see everything
|
||||
|
||||
[source,bash]
|
||||
pveum aclmod / -user joe@pve -role PVEAuditor
|
||||
|
||||
Example1: Allow user 'joe@pve' to see all virtual machines
|
||||
|
||||
[source,bash]
|
||||
pveum aclmod /vms -user joe@pve -role PVEAuditor
|
||||
|
||||
Delegate User Management
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you want to delegate user managenent to user 'joe@pve' you can do
|
||||
that with:
|
||||
|
||||
[source,bash]
|
||||
pveum aclmod /access -user joe@pve -role PVEUserAdmin
|
||||
|
||||
User 'joe@pve' can now add and remove users, change passwords and
|
||||
other user attributes. This is a very powerful role, and you most
|
||||
likely want to limit that to selected realms and groups. The following
|
||||
example allows 'joe@pve' to modify users within realm 'pve' if they
|
||||
are members of group 'customers':
|
||||
|
||||
[source,bash]
|
||||
pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
|
||||
pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
|
||||
|
||||
Note: The user is able to add other users, but only if they are
|
||||
members of group 'customers' and within realm 'pve'.
|
||||
|
||||
Pools
|
||||
~~~~~
|
||||
|
||||
An enterprise is usually structured into several smaller departments,
|
||||
and it is common that you want to assign resources to them and
|
||||
delegate management tasks. A pool is simply a set of virtual machines
|
||||
and data stores. You can create pools on the GUI. After that you can
|
||||
add resources to the pool (VMs, Storage).
|
||||
|
||||
You can also assign permissions to the pool. Those permissions are
|
||||
inherited to all pool members.
|
||||
|
||||
Lets assume you have a software development department, so we first
|
||||
create a group
|
||||
|
||||
[source,bash]
|
||||
pveum groupadd developers -comment "Our software developers"
|
||||
|
||||
Now we create a new user which is a member of that group
|
||||
|
||||
[source,bash]
|
||||
pveum useradd developer1@pve -group developers -password
|
||||
|
||||
Note: The -password parameter will prompt you for a password
|
||||
|
||||
I assume we already created a pool called 'dev-pool' on the GUI. So we can now assign permission to that pool:
|
||||
|
||||
[source,bash]
|
||||
pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
|
||||
|
||||
Our software developers can now administrate the resources assigned to
|
||||
that pool.
|
||||
|
||||
|
||||
ifdef::manvolnum[]
|
||||
include::pve-copyright.adoc[]
|
||||
endif::manvolnum[]
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user