251 lines
7.4 KiB
Markdown
251 lines
7.4 KiB
Markdown
# volker-raschek.unix-users
|
|
|
|
|
|
|
|
The ansible role `volker-raschek.unix-users` create and manage users on Linux based distributions. For example for Arch
|
|
Linux, Fedora and Ubuntu. Furthermore, the role can also be used to create groups, `~/.forward`, `~/.netrc` and to
|
|
manage the `~/.ssh` directory.
|
|
|
|
## Requirements
|
|
|
|
The role requires `ansible-core` 2.11 or newer. A home directory can optionally be created as btrfs subvolume, which
|
|
relies on the `btrfs_subvolume` module of the collection `community.general`.
|
|
|
|
```bash
|
|
ansible-galaxy collection install -r requirements.yml
|
|
```
|
|
|
|
The role manages users, groups and their home directories, so it has to be executed with `become: true`.
|
|
|
|
## Tests
|
|
|
|
The role is tested with [Molecule](https://ansible.readthedocs.io/projects/molecule/). The scenario starts one docker
|
|
container per supported distribution family, applies the role, asserts that a second run reports no change and finally
|
|
verifies the created users and groups, the permissions and the content of the managed files and that a user declared
|
|
as `absent` is gone again. A btrfs home is not covered, because a container has no btrfs filesystem to create a
|
|
subvolume on.
|
|
|
|
The ssh key pair the scenario feeds into the role is generated during `molecule create` and removed again during
|
|
`molecule destroy`, so no private key is kept in the repository.
|
|
|
|
Molecule ships only its `default` driver, therefore `docker` is required besides molecule itself. The collections are
|
|
declared in `molecule/default/collections.yml` and installed by molecule.
|
|
|
|
```bash
|
|
pip install molecule docker
|
|
```
|
|
|
|
The complete sequence creates the containers, tests them and removes them afterwards.
|
|
|
|
```bash
|
|
molecule test
|
|
```
|
|
|
|
While working on the role the containers are better kept alive.
|
|
|
|
```bash
|
|
# create the containers and apply the role
|
|
molecule converge
|
|
|
|
# run the assertions of molecule/default/verify.yml against the running containers
|
|
molecule verify
|
|
|
|
# open a shell in one of the containers
|
|
molecule login --host unix-users-debian
|
|
|
|
# remove the containers
|
|
molecule destroy
|
|
```
|
|
|
|
## Examples
|
|
|
|
### User and group
|
|
|
|
The following example create the user `toor` and group `toor`. Booth with a specific id.
|
|
|
|
```yaml
|
|
unix_groups:
|
|
toor:
|
|
gid: "1001"
|
|
state: present
|
|
|
|
unix_users:
|
|
toor:
|
|
state: present
|
|
name: Toor
|
|
uid: "1000"
|
|
home: /home/toor
|
|
shell: /bin/bash
|
|
password: toor
|
|
group: toor
|
|
```
|
|
|
|
### Btrfs home dir
|
|
|
|
Optionally, the home directory of a user can also be created as dedicated btrfs subvolume. This make it possible to
|
|
create snapshots of the home directory, for example via `btrbk`.
|
|
|
|
> [!WARNING]
|
|
> Removing a user with `state: absent` also deletes the btrfs subvolume of the home directory. Snapshots taken from that
|
|
> subvolume are not removed and keep the data available.
|
|
|
|
```yaml
|
|
unix_users:
|
|
toor:
|
|
state: present
|
|
name: Toor
|
|
uid: "1000"
|
|
home: /home/toor
|
|
btrfs: true
|
|
shell: /bin/bash
|
|
password: toor
|
|
group: toor
|
|
```
|
|
|
|
### .netrc
|
|
|
|
The ansible role supports the creation and management of the `.netrc` file in a user's home directory. The `.netrc` file
|
|
for the user `toor` is created below. This contains entries for GitHub.
|
|
|
|
```yaml
|
|
unix_users:
|
|
toor:
|
|
state: present
|
|
name: Toor
|
|
uid: "1000"
|
|
home: /home/toor
|
|
netrc:
|
|
- machine: github.com
|
|
login: octocat
|
|
password: pat_12345
|
|
- machine: api.github.com
|
|
login: octocat
|
|
password: pat_12345
|
|
shell: /bin/bash
|
|
password: toor
|
|
group: toor
|
|
```
|
|
|
|
### .ssh
|
|
|
|
The SSH client directory `~/.ssh` can also be managed via the Ansible role. This supports the creation and management of
|
|
`~/.ssh/config`, `~/.ssh/authorized_keys` as well as the maintenance of private and public SSH keys.
|
|
|
|
The following example create two entries in `~/.ssh/authorized_keys`. One normal SSH access for `claire`. If `bob`
|
|
establish a SSH connection the command `/usr/local/bin/upload-file.sh` will be executed and exited. Furthermore,
|
|
environment variables can be espcilitly defined, to consume it during execution of the command.
|
|
|
|
> [!IMPORTANT]
|
|
> To allow consuming environment variables must be set `PermitUserEnvironment yes` in `/etc/ssh/sshd_config`.
|
|
|
|
Private keys are configured using `filename` and `content`; the role writes them to `~/.ssh/<filename>` and extracts
|
|
their public keys to `~/.ssh/<filename>.pub`. Store private key content encrypted with Ansible Vault.
|
|
|
|
Entries in `authorized_keys` are also added to `~/.ssh/authorized_keys`, including their optional command and environment
|
|
settings.
|
|
|
|
```yaml
|
|
unix_users:
|
|
toor:
|
|
state: present
|
|
name: Toor
|
|
uid: "1000"
|
|
home: /home/toor
|
|
ssh:
|
|
config:
|
|
- Host: "*"
|
|
StrictHostKeyChecking: "no"
|
|
UserKnownHostFile: /dev/null
|
|
authorized_keys:
|
|
- content: ssh-ed25519 AAAAC3NzaC... claire
|
|
- command: /usr/local/bin/upload-file.sh
|
|
envs:
|
|
- key: SSH_KEY_NAME
|
|
value: bob@bob-pc
|
|
content: ssh-ed25519 AAAAC3NzaC... bob
|
|
private_keys:
|
|
- filename: toor@toor-pc.ed25519.key
|
|
content: |
|
|
-----BEGIN OPENSSH PRIVATE KEY-----
|
|
...
|
|
-----END OPENSSH PRIVATE KEY-----
|
|
shell: /bin/bash
|
|
password: toor
|
|
group: toor
|
|
```
|
|
|
|
### .forward
|
|
|
|
If on the system is postfix installed, postfix will respect the `~/.forward`
|
|
[file](https://www.postfix.org/local.8.html). This allows to forward local emails to external email addresses. The
|
|
following example create the `~/.forward` file for `toor` to forward emails to `toor@company.example.local`.
|
|
|
|
```yaml
|
|
unix_users:
|
|
toor:
|
|
state: present
|
|
name: Toor
|
|
uid: "1000"
|
|
home: /home/toor
|
|
email: toor@company.example.local
|
|
shell: /bin/bash
|
|
password: toor
|
|
group: toor
|
|
```
|
|
|
|
### shell_rc files
|
|
|
|
The role also supports the creation of bashrc drop-in files. These are created in `~/.bashrc.d` and included by
|
|
`~/.bashrc` via `source`.
|
|
|
|
Program-related configurations can be made via a drop-in file. For example, the configuration of the bash history via
|
|
the environment variables `HISTCONTROL` or `HISTFILE`. In addition to environment variables, aliases and complete
|
|
functions can also be defined.
|
|
|
|
```yaml
|
|
unix_users:
|
|
toor:
|
|
state: present
|
|
name: Toor
|
|
uid: "1000"
|
|
home: /home/toor
|
|
email: toor@company.example.local
|
|
shell: /bin/bash
|
|
shell_rc_files:
|
|
- file: "/home/toor/.bashrc.d/10-docker.bashrc" # absolute or relative path to home dir
|
|
aliases:
|
|
- key: "dcd"
|
|
value: "docker-compose down"
|
|
envs:
|
|
- export: true
|
|
key: "PATH"
|
|
value: "/home/toor/workspace/docker-compose/bin:${PATH}" # Add local compiled docker-compose into $PATH
|
|
functions:
|
|
- name: "foo"
|
|
value: |
|
|
if ! which docker 1> /dev/null; then
|
|
echo "ERROR: docker not found" 1>&2
|
|
exit 1
|
|
fi
|
|
password: toor
|
|
group: toor
|
|
```
|
|
|
|
## Further ansible roles
|
|
|
|
This ansible role is used in combination with other ansible roles of `volker-raschek`. You can search for the other
|
|
ansible roles via the following command.
|
|
|
|
```bash
|
|
$ ansible-galaxy role search --author "volker-raschek"
|
|
|
|
Found roles matching your search:
|
|
|
|
Name Description
|
|
---- -----------
|
|
volker-raschek.bind9 Role to install and configure bind9 on different distributions
|
|
volker-raschek.dhcpd Role to install and configure dhcpd on different distributions
|
|
volker-raschek.renovate Role to configure renovate as container image
|
|
...
|
|
```
|