From a55f0640b037a6d0771367622bd44996b8c74330 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sat, 3 Jul 2021 19:36:14 +0800 Subject: [PATCH] nixos: nixos/doc/manual/configuration/user-mgmt.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../manual/configuration/user-mgmt.chapter.md | 92 +++++++++++++++ nixos/doc/manual/configuration/user-mgmt.xml | 88 -------------- .../configuration/user-mgmt.chapter.xml | 107 ++++++++++++++++++ 4 files changed, 200 insertions(+), 89 deletions(-) create mode 100644 nixos/doc/manual/configuration/user-mgmt.chapter.md delete mode 100644 nixos/doc/manual/configuration/user-mgmt.xml create mode 100644 nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 6949189b8883..006205215f6e 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -15,7 +15,7 @@ - + diff --git a/nixos/doc/manual/configuration/user-mgmt.chapter.md b/nixos/doc/manual/configuration/user-mgmt.chapter.md new file mode 100644 index 000000000000..64eacc5f7dd6 --- /dev/null +++ b/nixos/doc/manual/configuration/user-mgmt.chapter.md @@ -0,0 +1,92 @@ +# User Management {#sec-user-management} + +NixOS supports both declarative and imperative styles of user +management. In the declarative style, users are specified in +`configuration.nix`. For instance, the following states that a user +account named `alice` shall exist: + +```nix +users.users.alice = { + isNormalUser = true; + home = "/home/alice"; + description = "Alice Foobar"; + extraGroups = [ "wheel" "networkmanager" ]; + openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; +}; +``` + +Note that `alice` is a member of the `wheel` and `networkmanager` +groups, which allows her to use `sudo` to execute commands as `root` and +to configure the network, respectively. Also note the SSH public key +that allows remote logins with the corresponding private key. Users +created in this way do not have a password by default, so they cannot +log in via mechanisms that require a password. However, you can use the +`passwd` program to set a password, which is retained across invocations +of `nixos-rebuild`. + +If you set [`users.mutableUsers`](options.html#opt-users.mutableUsers) to +false, then the contents of `/etc/passwd` and `/etc/group` will be congruent +to your NixOS configuration. For instance, if you remove a user from +[`users.users`](options.html#opt-users.users) and run nixos-rebuild, the user +account will cease to exist. Also, imperative commands for managing users and +groups, such as useradd, are no longer available. Passwords may still be +assigned by setting the user\'s +[hashedPassword](#opt-users.users._name_.hashedPassword) option. A +hashed password can be generated using `mkpasswd -m + sha-512`. + +A user ID (uid) is assigned automatically. You can also specify a uid +manually by adding + +```nix +uid = 1000; +``` + +to the user specification. + +Groups can be specified similarly. The following states that a group +named `students` shall exist: + +```nix +users.groups.students.gid = 1000; +``` + +As with users, the group ID (gid) is optional and will be assigned +automatically if it's missing. + +In the imperative style, users and groups are managed by commands such +as `useradd`, `groupmod` and so on. For instance, to create a user +account named `alice`: + +```ShellSession +# useradd -m alice +``` + +To make all nix tools available to this new user use \`su - USER\` which +opens a login shell (==shell that loads the profile) for given user. +This will create the \~/.nix-defexpr symlink. So run: + +```ShellSession +# su - alice -c "true" +``` + +The flag `-m` causes the creation of a home directory for the new user, +which is generally what you want. The user does not have an initial +password and therefore cannot log in. A password can be set using the +`passwd` utility: + +```ShellSession +# passwd alice +Enter new UNIX password: *** +Retype new UNIX password: *** +``` + +A user can be deleted using `userdel`: + +```ShellSession +# userdel -r alice +``` + +The flag `-r` deletes the user's home directory. Accounts can be +modified using `usermod`. Unix groups can be managed using `groupadd`, +`groupmod` and `groupdel`. diff --git a/nixos/doc/manual/configuration/user-mgmt.xml b/nixos/doc/manual/configuration/user-mgmt.xml deleted file mode 100644 index e83e7b75ef54..000000000000 --- a/nixos/doc/manual/configuration/user-mgmt.xml +++ /dev/null @@ -1,88 +0,0 @@ - - User Management - - NixOS supports both declarative and imperative styles of user management. In - the declarative style, users are specified in - configuration.nix. For instance, the following states - that a user account named alice shall exist: - -.alice = { - isNormalUser = true; - home = "/home/alice"; - description = "Alice Foobar"; - extraGroups = [ "wheel" "networkmanager" ]; - openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; -}; - - Note that alice is a member of the - wheel and networkmanager groups, which - allows her to use sudo to execute commands as - root and to configure the network, respectively. Also note - the SSH public key that allows remote logins with the corresponding private - key. Users created in this way do not have a password by default, so they - cannot log in via mechanisms that require a password. However, you can use - the passwd program to set a password, which is retained - across invocations of nixos-rebuild. - - - If you set to false, then the - contents of /etc/passwd and /etc/group - will be congruent to your NixOS configuration. For instance, if you remove a - user from and run nixos-rebuild, the user - account will cease to exist. Also, imperative commands for managing users and - groups, such as useradd, are no longer available. Passwords may still be - assigned by setting the user's - hashedPassword - option. A hashed password can be generated using mkpasswd -m - sha-512. - - - A user ID (uid) is assigned automatically. You can also specify a uid - manually by adding - -uid = 1000; - - to the user specification. - - - Groups can be specified similarly. The following states that a group named - students shall exist: - -.students.gid = 1000; - - As with users, the group ID (gid) is optional and will be assigned - automatically if it’s missing. - - - In the imperative style, users and groups are managed by commands such as - useradd, groupmod and so on. For - instance, to create a user account named alice: - -# useradd -m alice - To make all nix tools available to this new user use `su - USER` which opens - a login shell (==shell that loads the profile) for given user. This will - create the ~/.nix-defexpr symlink. So run: - -# su - alice -c "true" - The flag causes the creation of a home directory for the - new user, which is generally what you want. The user does not have an initial - password and therefore cannot log in. A password can be set using the - passwd utility: - -# passwd alice -Enter new UNIX password: *** -Retype new UNIX password: *** - - A user can be deleted using userdel: - -# userdel -r alice - The flag deletes the user’s home directory. Accounts - can be modified using usermod. Unix groups can be managed - using groupadd, groupmod and - groupdel. - - diff --git a/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml b/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml new file mode 100644 index 000000000000..b865fabfe3cc --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml @@ -0,0 +1,107 @@ + + User Management + + NixOS supports both declarative and imperative styles of user + management. In the declarative style, users are specified in + configuration.nix. For instance, the following + states that a user account named alice shall + exist: + + +users.users.alice = { + isNormalUser = true; + home = "/home/alice"; + description = "Alice Foobar"; + extraGroups = [ "wheel" "networkmanager" ]; + openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; +}; + + + Note that alice is a member of the + wheel and networkmanager + groups, which allows her to use sudo to execute + commands as root and to configure the network, + respectively. Also note the SSH public key that allows remote logins + with the corresponding private key. Users created in this way do not + have a password by default, so they cannot log in via mechanisms + that require a password. However, you can use the + passwd program to set a password, which is + retained across invocations of nixos-rebuild. + + + If you set + users.mutableUsers + to false, then the contents of /etc/passwd and + /etc/group will be congruent to your NixOS + configuration. For instance, if you remove a user from + users.users + and run nixos-rebuild, the user account will cease to exist. Also, + imperative commands for managing users and groups, such as useradd, + are no longer available. Passwords may still be assigned by setting + the user's + hashedPassword + option. A hashed password can be generated using + mkpasswd -m sha-512. + + + A user ID (uid) is assigned automatically. You can also specify a + uid manually by adding + + +uid = 1000; + + + to the user specification. + + + Groups can be specified similarly. The following states that a group + named students shall exist: + + +users.groups.students.gid = 1000; + + + As with users, the group ID (gid) is optional and will be assigned + automatically if it’s missing. + + + In the imperative style, users and groups are managed by commands + such as useradd, groupmod and + so on. For instance, to create a user account named + alice: + + +# useradd -m alice + + + To make all nix tools available to this new user use `su - USER` + which opens a login shell (==shell that loads the profile) for given + user. This will create the ~/.nix-defexpr symlink. So run: + + +# su - alice -c "true" + + + The flag -m causes the creation of a home + directory for the new user, which is generally what you want. The + user does not have an initial password and therefore cannot log in. + A password can be set using the passwd utility: + + +# passwd alice +Enter new UNIX password: *** +Retype new UNIX password: *** + + + A user can be deleted using userdel: + + +# userdel -r alice + + + The flag -r deletes the user’s home directory. + Accounts can be modified using usermod. Unix + groups can be managed using groupadd, + groupmod and groupdel. + +