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