import pveum docs

diff --git a/pveum.adoc b/pveum.adoc
new file mode 100644 (file)
index 0000000..a3b1cff
--- /dev/null
+++ b/pveum.adoc
@@ -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[]
+