-
Notifications
You must be signed in to change notification settings - Fork 69
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
* Update users.rst reorganiza and improve right documentation * Update users.rst * group management documentation improved and completed the missing explanations * fix misctakes in group subsection, add missing information about groups * fix redundant information on homes and group technical details of user management * Make some adaptions Signed-off-by: Volker Theile <[email protected]> --------- Signed-off-by: Volker Theile <[email protected]> Co-authored-by: Volker Theile <[email protected]>
- Loading branch information
1 parent
1f61b6c
commit 54930b7
Showing
1 changed file
with
180 additions
and
66 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,106 +1,220 @@ | ||
| Users | ||
| ##### | ||
|
|
||
| In this section you can create, edit and access information of |omv| users and groups. | ||
| The user management in |omv| is provided by the user management of the | ||
| operating system on which it is running. | ||
|
|
||
| However, |omv| also maintains control over these users, **so management is a team effort** | ||
| between the Debian operating system and the internal database of |omv|. | ||
|
|
||
| Users that are managed via the |webui| are so-called *non-system users*. | ||
| Their *UID* is in a specific range, usually from 1000 to 60000. The same applies | ||
| to groups that are managed via the |webui|. Their *GID* is in a specific | ||
| range, usually from 1000 to 60000. Check ``/etc/login.defs`` for more information. | ||
|
|
||
| The **Users** management section in the |webui| is divided into three | ||
| subsections: ``Settings``, ``Users`` and ``Groups``. | ||
|
|
||
| Users can log into the |webui| to see their own profile information. The | ||
| administrator can prohibit this behaviour for each user individually. | ||
|
|
||
|
|
||
| Settings | ||
| ======== | ||
|
|
||
| User home directory | ||
| ------------------- | ||
|
|
||
| Due to the nature explained, users are supposed to have their own private place for | ||
| files that is called "*home*", depending on the type of service, automatically becomes | ||
| a personal private shared location. | ||
|
|
||
| You can select a |sf| as root for the *home* directories of all non-system users. | ||
|
|
||
| If *User home directory* is disabled and a new user is created, the following happens: | ||
|
|
||
| * No home directory will be created and assigned to the user | ||
|
|
||
| If *User home directory* is enabled and a new user is created, the following happens: | ||
|
|
||
| * A home directory will be created in the selected |sf| and assigned to the user | ||
| * The "skel" templates from Debian will applied to the new home directory | ||
|
|
||
| If *User home directory* is enabled, the following actions will be performed: | ||
|
|
||
| * The home directory path will be updated for all existing non-system users. | ||
| * The previous home directory content will NOT be moved to the new location. This has to be done manually. | ||
|
|
||
| If *User home directory* is disabled, the following actions will be performed: | ||
|
|
||
| * The home directory will be unset for all existing non-system users. | ||
| * The home directory content will NOT be deleted. | ||
|
|
||
|
|
||
| User | ||
| ==== | ||
|
|
||
| Here you can create or modify user information and configure the user home folders. | ||
| This page lists all non-system users and allows you to *Create* or *Edit* | ||
| those users as well as their |sf| *Permissions*. There is also a special | ||
| option that allows you to *Import* multiple users at once. | ||
|
|
||
| Add | ||
| ^^^^ | ||
| Create | ||
| ------ | ||
|
|
||
| Information | ||
| The configuration panel gives you options to add, edit or remove users. The table displays all | ||
| |omv| current users. | ||
| The following form fields are available: | ||
|
|
||
| When a user is created |omv| backend executes :command:`useradd` in non-interactive | ||
| mode with all the information passed from the form fields, this command also creates an | ||
| entry in :file:`/etc/passwd`, a hashed password in :file:`/etc/shadow`. Samba service is watching any changes | ||
| in users database section so it also sets the password in the Samba tdbsam storage backend. | ||
| Name | ||
| This must be only numbers and letters. Its the "username" of the login credentials | ||
| and must be all lowercase to avoid confusion. | ||
|
|
||
| The mail field is used for cron jobs when the task is selected to run as | ||
| specific user. By default users are created with :command:`/bin/nologin` | ||
| shell, this will prevent local and remote console access. | ||
| Password | ||
| This field will provide the password of the user. | ||
|
|
||
| Group | ||
| Add or remove users from specific groups. In Linux groups can be used to control | ||
| access to certain features and also for permissions. | ||
| Shell | ||
| The shell is only used for remote access to interact with the server. | ||
| By default the form will offers :command:`/usr/bin/sh` shell, but is recommended usage of | ||
| the :command:`/usr/bin/nologin` shell to prevent local and remote console access. | ||
|
|
||
| Adding a user to the ``sudo`` group will give them root privileges, adding | ||
| a user to ``saned`` will give access to scanners, etc. By default all users created using | ||
| the |webui| are added to the ``users`` group (``gid=100``). | ||
| Groups | ||
| This field allows to add or remove users from specific groups. Groups are the means of access | ||
| for multiple users to multiple shared resources. | ||
|
|
||
| Public Key | ||
| Add or remove :doc:`public keys </administration/services/ssh>` for granting remote access for users. | ||
| Some groups only affect the system (as of Linux), others are specific to the |omv| system. | ||
| By default all users created using the |webui| are added to the ``users`` group (``gid=100``). | ||
|
|
||
| .. note:: | ||
| SSH public keys | ||
| Add or remove :doc:`public SSH keys </administration/services/ssh>` for granting remote access for users. | ||
|
|
||
| Disallow account modification | ||
| Disallow the user to modify their own account information. | ||
|
|
||
| Tags | ||
| Specify tags to categorize the user. | ||
|
|
||
| - The user profile information (except password) is also stored in the internal |omv| database, along with the public keys. | ||
| - The table shows information from internal database and also parses information from :file:`/etc/passwd` lines with a `UID` number higher than 1000. A user created in terminal is not in the internal database. This causes trouble with samba, as there is no user/password entry in the tdbsam file. Just click edit for the user, enter the same or new password, now the user has the linux and samba password synced. | ||
| - A user can log into the |webui| to see their own profile information. Depending if the administrator has setup the username account to allow changes, they can change their password and mail account. | ||
| - A non-privileged user can become a |webui| administrator by adding them to the ``openmediavault-admin`` group. | ||
|
|
||
| Import | ||
| ^^^^^^ | ||
| ------ | ||
|
|
||
| Designed for bulk user creation. Create a spreadsheet with the corresponding data as | ||
| described in the import dialog window, save it as CSV (make sure the field separator is semicolon :code:`;`), then just | ||
| simply:: | ||
| Designed for bulk user creation. The user data must be entered as CSV data. | ||
| An example is prepared as a comment. | ||
|
|
||
| $ cat usersfile.csv | ||
| Those fields are the same as the form of the *Create* user page. | ||
|
|
||
| Example outputs:: | ||
| The field of *UID* must be numeric and must be in the range from 1000 to 60000 (check ``/etc/login.defs`` for more information). | ||
|
|
||
| # <name>;<uid>;<tags>;<email>;<password>;<shell>;<group,group,...>;<disallowusermod> | ||
| user1;1001;user1;[email protected];password1;/bin/bash;sudo;1 | ||
| user2;1002;user2;[email protected];password2;/bin/sh;;0 | ||
| user3;1003;user3;[email protected];password3;/bin/false;;1 | ||
| user4;1004;user4;[email protected];password4;;;1 | ||
| Example data:: | ||
|
|
||
| .. note:: | ||
| - :file:`/etc/shells` will give you a list of valid shells. | ||
| - The last field is a boolean for allowing the user to change their account. | ||
| # <name>;<uid>;<tags>;<email>;<password>;<shell>;<group,group,...>;<disallowusermod> | ||
| user1;1001;user1;[email protected];password1;/bin/bash;sudo;1 | ||
| user2;1002;user2;[email protected];password2;/bin/sh;;0 | ||
| user3;1003;user3;[email protected];password3;/bin/false;;1 | ||
| user4;1004;user4;[email protected];password4;;;1 | ||
|
|
||
| Edit | ||
| ---- | ||
|
|
||
| Paste the contents into the import dialog. | ||
| Here you can modify the user information, the fields are the same as the form of the *Create* user page. | ||
|
|
||
| Permissions | ||
| ^^^^^^^^^^^ | ||
| ----------- | ||
|
|
||
| The button opens a window that displays all current existing |sf| and their | ||
| permissions for selected user from the table. How the permissions are stored is | ||
| described further down in the :doc:`shared folder </administration/storage/sharedfolders>` section. | ||
| All existing |sf| and the access rights of the user to be edited are displayed | ||
| on this page. The following access rights are available: | ||
|
|
||
| Settings | ||
| ^^^^^^^^ | ||
| - Read/Write | ||
| - Read-only | ||
| - No access | ||
|
|
||
| These settings are used by the services to configure the access rights for the users. | ||
|
|
||
| .. note:: | ||
|
|
||
| Please note that these settings have no effect on file system permissions. | ||
|
|
||
| How the permissions are stored is described further down in the :doc:`shared folder </administration/storage/sharedfolders>` section. | ||
|
|
||
| Option to select a |sf| as root for home folders for new users created in the | ||
| |webui|. Previously existing users created before enabling this setting will not have | ||
| their home folders moved to this new location. You can manually edit :file:`/etc/passwd` | ||
| to point them to the new location. Also existing users data in default linux location :file:`/home` | ||
| has to be moved manually. | ||
|
|
||
| Group | ||
| ===== | ||
|
|
||
| This page lists all non-system groups and allows you to *Create* or *Edit* those groups as well as their |sf| *Permissions*. There is also a special option that allows you to *Import* multiple groups at once. | ||
|
|
||
|
|
||
| Add | ||
| ^^^ | ||
| --- | ||
|
|
||
| Create groups and select the members. You can select current |omv| users | ||
| and system accounts. Information is stored in ``config.xml`` and | ||
| :file:`/etc/group`. | ||
| The following form fields are available: | ||
|
|
||
| Name | ||
| This must be only numbers and letters. | ||
|
|
||
| Members | ||
| This field allows to add or remove users for this group. | ||
|
|
||
| Import | ||
| ^^^^^^ | ||
| ------ | ||
|
|
||
| Designed for bulk group creation. The group data must be entered as CSV data. | ||
| An example is prepared as a comment. | ||
|
|
||
| Those fields are the same as the form of the *Create* group page. | ||
|
|
||
| Bulk import works in similar as user account import. Just a csv text, | ||
| delimited with a semicolon :code:`;`. The dialog displays the necessary | ||
| fields. | ||
| The field of *GID* must be numeric and must be in the range from 1000 to 60000 (check ``/etc/login.defs`` for more information). | ||
|
|
||
| Edit | ||
| ^^^^ | ||
| Just to add or remove members from groups. Default groups created in the | ||
| |webui| have a ``GID`` greater than ``1000``. Same as usernames, groups created | ||
| in terminal are not stored in the internal database. Just edit, insert a | ||
| comment and their information should now be stored in ``config.xml``. | ||
| ---- | ||
|
|
||
| Here you can modify the group information, the fields are the same as the form of the *Create* group page. | ||
|
|
||
| Permissions | ||
| ----------- | ||
|
|
||
| All existing |sf| and the access rights of the group to be edited are displayed | ||
| on this page. The following access rights are available: | ||
|
|
||
| - Read/Write | ||
| - Read-only | ||
| - No access | ||
|
|
||
| These settings are used by the services to configure the access rights for the groups. | ||
|
|
||
| .. note:: | ||
|
|
||
| Please note that these settings have no effect on file system permissions. | ||
|
|
||
| How the permissions are stored is described further down in the :doc:`shared folder </administration/storage/sharedfolders>` section. | ||
|
|
||
|
|
||
| Technical details | ||
| ================= | ||
|
|
||
| When a user is created |omv| backend executes :command:`useradd` in non-interactive | ||
| mode with all the information passed from the form fields. This command is responsible for creating an | ||
| entry in :file:`/etc/passwd` and a hashed password in :file:`/etc/shadow`. | ||
|
|
||
| The |omv| backend monitors all database changes to users to allow other services to react to these changes. | ||
| This ensures, for example, that the *Samba* user database is updated when a user password is changed. | ||
|
|
||
| .. attention:: | ||
|
|
||
| - The user profile information (except password) is also stored in the | ||
| internal |omv| database, along with the public keys. | ||
| - A non-privileged user can become a |webui| administrator by adding them | ||
| to the ``openmediavault-admin`` group. | ||
|
|
||
| Manual management | ||
| ----------------- | ||
|
|
||
| If a user is created via the |webui|, no corresponding group with the name of the user is created. | ||
|
|
||
| A user created in terminal by the :command:`useradd` command will not be in the |omv| internal | ||
| database. This causes trouble with some services, by example *Samba*, as there is no | ||
| user/password entry in the ``tdbsam`` database of *Samba*. | ||
|
|
||
| To synchronize users or groups that have not been created in the |webui|, simply | ||
| perform an *Edit* action and change the password or membership. | ||
|
|
||
| Shared home directories | ||
| ----------------------- | ||
|
|
||
| If *User Home directory* is enabled and configured properly, then the home directories can be shared by some services as well, e.g. *Samba* and *FTP*. |