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 Access Control
  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 .. _user_tokens:
  89
  90 API Tokens
  91 ----------
  92
  93 Any authenticated user can generate API tokens which can in turn be used to
  94 configure various clients, instead of directly providing the username and
  95 password.
  96
  97 API tokens serve two purposes:
  98
  99 #. Easy revocation in case client gets compromised
 100 #. Limit permissions for each client/token within the users' permission
 101
 102 An API token consists of two parts: an identifier consisting of the user name,
 103 the realm and a tokenname (``user@realm!tokenname``), and a secret value. Both
 104 need to be provided to the client in place of the user ID (``user@realm``) and
 105 the user password, respectively.
 106
 107 The API token is passed from the client to the server by setting the
 108 ``Authorization`` HTTP header with method ``PBSAPIToken`` to the value
 109 ``TOKENID:TOKENSECRET``.
 110
 111 Generating new tokens can done using ``proxmox-backup-manager`` or the GUI:
 112
 113 .. code-block:: console
 114
 115   # proxmox-backup-manager user generate-token john@pbs client1
 116   Result: {
 117     "tokenid": "john@pbs!client1",
 118     "value": "d63e505a-e3ec-449a-9bc7-1da610d4ccde"
 119   }
 120
 121 .. note:: The displayed secret value needs to be saved, since it cannot be
 122   displayed again after generating the API token.
 123
 124 The ``user list-tokens`` sub-command can be used to display tokens and their
 125 metadata:
 126
 127 .. code-block:: console
 128
 129   # proxmox-backup-manager user list-tokens john@pbs
 130   ┌──────────────────┬────────┬────────┬─────────┐
 131   │ tokenid          │ enable │ expire │ comment │
 132   ╞══════════════════╪════════╪════════╪═════════╡
 133   │ john@pbs!client1 │      1 │        │         │
 134   └──────────────────┴────────┴────────┴─────────┘
 135
 136 Similarly, the ``user delete-token`` subcommand can be used to delete a token
 137 again.
 138
 139 Newly generated API tokens don't have any permissions. Please read the next
 140 section to learn how to set access permissions.
 141
 142
 143 .. _user_acl:
 144
 145 Access Control
 146 --------------
 147
 148 By default new users and API tokens do not have any permission. Instead you
 149 need to specify what is allowed and what is not. You can do this by assigning
 150 roles to users/tokens on specific objects like datastores or remotes. The
 151 following roles exist:
 152
 153 **NoAccess**
 154   Disable Access - nothing is allowed.
 155
 156 **Admin**
 157   Can do anything.
 158
 159 **Audit**
 160   Can view things, but is not allowed to change settings.
 161
 162 **DatastoreAdmin**
 163   Can do anything on datastores.
 164
 165 **DatastoreAudit**
 166   Can view datastore settings and list content. But
 167   is not allowed to read the actual data.
 168
 169 **DatastoreReader**
 170   Can Inspect datastore content and can do restores.
 171
 172 **DatastoreBackup**
 173   Can backup and restore owned backups.
 174
 175 **DatastorePowerUser**
 176   Can backup, restore, and prune owned backups.
 177
 178 **RemoteAdmin**
 179   Can do anything on remotes.
 180
 181 **RemoteAudit**
 182   Can view remote settings.
 183
 184 **RemoteSyncOperator**
 185   Is allowed to read data from a remote.
 186
 187 .. image:: images/screenshots/pbs-gui-permissions-add.png
 188   :align: right
 189   :alt: Add permissions for user
 190
 191 Access permission information is stored in ``/etc/proxmox-backup/acl.cfg``. The
 192 file contains 5 fields, separated using a colon (':') as a delimiter. A typical
 193 entry takes the form:
 194
 195 ``acl:1:/datastore:john@pbs:DatastoreBackup``
 196
 197 The data represented in each field is as follows:
 198
 199 #. ``acl`` identifier
 200 #. A ``1`` or ``0``, representing whether propagation is enabled or disabled,
 201    respectively
 202 #. The object on which the permission is set. This can be a specific object
 203    (single datastore, remote, etc.) or a top level object, which with
 204    propagation enabled, represents all children of the object also.
 205 #. The user(s)/token(s) for which the permission is set
 206 #. The role being set
 207
 208 You can manage permissions via **Configuration -> Access Control ->
 209 Permissions** in the web interface. Likewise, you can use the ``acl``
 210 subcommand to manage and monitor user permissions from the command line. For
 211 example, the command below will add the user ``john@pbs`` as a
 212 **DatastoreAdmin** for the datastore ``store1``, located at
 213 ``/backup/disk1/store1``:
 214
 215 .. code-block:: console
 216
 217   # proxmox-backup-manager acl update /datastore/store1 DatastoreAdmin --auth-id john@pbs
 218
 219 You can list the ACLs of each user/token using the following command:
 220
 221 .. code-block:: console
 222
 223    # proxmox-backup-manager acl list
 224    ┌──────────┬──────────────────┬───────────┬────────────────┐
 225    │ ugid     │ path             │ propagate │ roleid         │
 226    ╞══════════╪══════════════════╪═══════════╪════════════════╡
 227    │ john@pbs │ /datastore/disk1 │         1 │ DatastoreAdmin │
 228    └──────────┴──────────────────┴───────────┴────────────────┘
 229
 230 A single user/token can be assigned multiple permission sets for different datastores.
 231
 232 .. Note::
 233   Naming convention is important here. For datastores on the host,
 234   you must use the convention ``/datastore/{storename}``. For example, to set
 235   permissions for a datastore mounted at ``/mnt/backup/disk4/store2``, you would use
 236   ``/datastore/store2`` for the path. For remote stores, use the convention
 237   ``/remote/{remote}/{storename}``, where ``{remote}`` signifies the name of the
 238   remote (see `Remote` below) and ``{storename}`` is the name of the datastore on
 239   the remote.
 240
 241 API Token permissions
 242 ~~~~~~~~~~~~~~~~~~~~~
 243
 244 API token permissions are calculated based on ACLs containing their ID
 245 independent of those of their corresponding user. The resulting permission set
 246 on a given path is then intersected with that of the corresponding user.
 247
 248 In practice this means:
 249
 250 #. API tokens require their own ACL entries
 251 #. API tokens can never do more than their corresponding user
 252
 253 Effective permissions
 254 ~~~~~~~~~~~~~~~~~~~~~
 255
 256 To calculate and display the effective permission set of a user or API token
 257 you can use the ``proxmox-backup-manager user permission`` command:
 258
 259 .. code-block:: console
 260
 261   # proxmox-backup-manager user permissions john@pbs -- path /datastore/store1
 262   Privileges with (*) have the propagate flag set
 263
 264   Path: /datastore/store1
 265   - Datastore.Audit (*)
 266   - Datastore.Backup (*)
 267   - Datastore.Modify (*)
 268   - Datastore.Prune (*)
 269   - Datastore.Read (*)
 270
 271   # proxmox-backup-manager acl update /datastore/store1 DatastoreBackup --auth-id 'john@pbs!client1'
 272   # proxmox-backup-manager user permissions 'john@pbs!test' -- path /datastore/store1
 273   Privileges with (*) have the propagate flag set
 274
 275   Path: /datastore/store1
 276   - Datastore.Backup (*)