docs/user-management.rst

   1 .. _user_mgmt:
   2
   3 User Management
   4 ===============
   5
   6
   7 User Configuration
   8 ------------------
   9
  10 .. image:: images/screenshots/pbs-gui-user-management.png
  11   :align: right
  12   :alt: User management
  13
  14 Proxmox Backup Server supports several authentication realms, and you need to
  15 choose the realm when you add a new user. Possible realms are:
  16
  17 :pam: Linux PAM standard authentication. Use this if you want to
  18       authenticate as Linux system user (Users need to exist on the
  19       system).
  20
  21 :pbs: Proxmox Backup Server realm. This type stores hashed passwords in
  22       ``/etc/proxmox-backup/shadow.json``.
  23
  24 After installation, there is a single user ``root@pam``, which
  25 corresponds to the Unix superuser. User configuration information is stored in the file
  26 ``/etc/proxmox-backup/user.cfg``. You can use the
  27 ``proxmox-backup-manager`` command line tool to list or manipulate
  28 users:
  29
  30 .. code-block:: console
  31
  32   # proxmox-backup-manager user list
  33   ┌─────────────┬────────┬────────┬───────────┬──────────┬────────────────┬────────────────────┐
  34   │ userid      │ enable │ expire │ firstname │ lastname │ email          │ comment            │
  35   ╞═════════════╪════════╪════════╪═══════════╪══════════╪════════════════╪════════════════════╡
  36   │ root@pam    │      1 │        │           │          │                │ Superuser          │
  37   └─────────────┴────────┴────────┴───────────┴──────────┴────────────────┴────────────────────┘
  38
  39 .. image:: images/screenshots/pbs-gui-user-management-add-user.png
  40   :align: right
  41   :alt: Add a new user
  42
  43 The superuser has full administration rights on everything, so you
  44 normally want to add other users with less privileges. You can create a new
  45 user with the ``user create`` subcommand or through the web interface, under
  46 **Configuration -> User Management**. The ``create`` subcommand lets you specify
  47 many options like ``--email`` or ``--password``. You can update or change any
  48 user properties using the ``update`` subcommand later (**Edit** in the GUI):
  49
  50
  51 .. code-block:: console
  52
  53   # proxmox-backup-manager user create john@pbs --email john@example.com
  54   # proxmox-backup-manager user update john@pbs --firstname John --lastname Smith
  55   # proxmox-backup-manager user update john@pbs --comment "An example user."
  56
  57 .. todo:: Mention how to set password without passing plaintext password as cli argument.
  58
  59
  60 The resulting user list looks like this:
  61
  62 .. code-block:: console
  63
  64   # proxmox-backup-manager user list
  65   ┌──────────┬────────┬────────┬───────────┬──────────┬──────────────────┬──────────────────┐
  66   │ userid   │ enable │ expire │ firstname │ lastname │ email            │ comment          │
  67   ╞══════════╪════════╪════════╪═══════════╪══════════╪══════════════════╪══════════════════╡
  68   │ john@pbs │      1 │        │ John      │ Smith    │ john@example.com │ An example user. │
  69   ├──────────┼────────┼────────┼───────────┼──────────┼──────────────────┼──────────────────┤
  70   │ root@pam │      1 │        │           │          │                  │ Superuser        │
  71   └──────────┴────────┴────────┴───────────┴──────────┴──────────────────┴──────────────────┘
  72
  73 Newly created users do not have any permissions. Please read the next
  74 section to learn how to set access permissions.
  75
  76 If you want to disable a user account, you can do that by setting ``--enable`` to ``0``
  77
  78 .. code-block:: console
  79
  80   # proxmox-backup-manager user update john@pbs --enable 0
  81
  82 Or completely remove the user with:
  83
  84 .. code-block:: console
  85
  86   # proxmox-backup-manager user remove john@pbs
  87
  88
  89 .. _user_acl:
  90
  91 Access Control
  92 --------------
  93
  94 By default new users do not have any permission. Instead you need to
  95 specify what is allowed and what is not. You can do this by assigning
  96 roles to users on specific objects like datastores or remotes. The
  97 following roles exist:
  98
  99 **NoAccess**
 100   Disable Access - nothing is allowed.
 101
 102 **Admin**
 103   Can do anything.
 104
 105 **Audit**
 106   Can view things, but is not allowed to change settings.
 107
 108 **DatastoreAdmin**
 109   Can do anything on datastores.
 110
 111 **DatastoreAudit**
 112   Can view datastore settings and list content. But
 113   is not allowed to read the actual data.
 114
 115 **DatastoreReader**
 116   Can Inspect datastore content and can do restores.
 117
 118 **DatastoreBackup**
 119   Can backup and restore owned backups.
 120
 121 **DatastorePowerUser**
 122   Can backup, restore, and prune owned backups.
 123
 124 **RemoteAdmin**
 125   Can do anything on remotes.
 126
 127 **RemoteAudit**
 128   Can view remote settings.
 129
 130 **RemoteSyncOperator**
 131   Is allowed to read data from a remote.
 132
 133 .. image:: images/screenshots/pbs-gui-permissions-add.png
 134   :align: right
 135   :alt: Add permissions for user
 136
 137 Access permission information is stored in ``/etc/proxmox-backup/acl.cfg``. The
 138 file contains 5 fields, separated using a colon (':') as a delimiter. A typical
 139 entry takes the form:
 140
 141 ``acl:1:/datastore:john@pbs:DatastoreBackup``
 142
 143 The data represented in each field is as follows:
 144
 145 #. ``acl`` identifier
 146 #. A ``1`` or ``0``, representing whether propagation is enabled or disabled,
 147    respectively
 148 #. The object on which the permission is set. This can be a specific object
 149    (single datastore, remote, etc.) or a top level object, which with
 150    propagation enabled, represents all children of the object also.
 151 #. The user for which the permission is set
 152 #. The role being set
 153
 154 You can manage datastore permissions from **Configuration -> Permissions** in the
 155 web interface. Likewise, you can use the ``acl`` subcommand to manage and
 156 monitor user permissions from the command line. For example, the command below
 157 will add the user ``john@pbs`` as a **DatastoreAdmin** for the datastore
 158 ``store1``, located at ``/backup/disk1/store1``:
 159
 160 .. code-block:: console
 161
 162   # proxmox-backup-manager acl update /datastore/store1 DatastoreAdmin --userid john@pbs
 163
 164 You can monitor the roles of each user using the following command:
 165
 166 .. code-block:: console
 167
 168    # proxmox-backup-manager acl list
 169    ┌──────────┬──────────────────┬───────────┬────────────────┐
 170    │ ugid     │ path             │ propagate │ roleid         │
 171    ╞══════════╪══════════════════╪═══════════╪════════════════╡
 172    │ john@pbs │ /datastore/disk1 │         1 │ DatastoreAdmin │
 173    └──────────┴──────────────────┴───────────┴────────────────┘
 174
 175 A single user can be assigned multiple permission sets for different datastores.
 176
 177 .. Note::
 178   Naming convention is important here. For datastores on the host,
 179   you must use the convention ``/datastore/{storename}``. For example, to set
 180   permissions for a datastore mounted at ``/mnt/backup/disk4/store2``, you would use
 181   ``/datastore/store2`` for the path. For remote stores, use the convention
 182   ``/remote/{remote}/{storename}``, where ``{remote}`` signifies the name of the
 183   remote (see `Remote` below) and ``{storename}`` is the name of the datastore on
 184   the remote.
 185
 186