diff --git a/README.md b/README.md index c3abb0a..c32e31b 100644 --- a/README.md +++ b/README.md @@ -8,33 +8,33 @@ An Ansible role for setting up Samba as a file server. Specifically, the respons - Manage users and passwords - Manage access to shares +Setting the firewall is not a concern of this role, so you should configure this using another role (e.g. [bertvv.el7](https://galaxy.ansible.com/list#/roles/2305)). + ## Requirements - SELinux is expected to be running -- The firewall should be active -- Samba users should already exist as system users - -You can take a look at role [bertvv.el7](https://galaxy.ansible.com/list#/roles/2305) that does all this and more. +- Samba users should already exist as system users. You can take a look at role [bertvv.el7](https://galaxy.ansible.com/list#/roles/2305) that does all this and more. ## Role Variables +Variables are not required, unless specified. -| Variable | Required | Default | Comments | -| :--- | :--- | :--- | :--- | -| `samba_create_varwww_symlinks` | no | - | When this is set to `yes`, symlinks are created in `/var/www/html` to the shares. | -| `samba_load_homes` | no | no | Make user home directories accessible. | -| `samba_load_printers` | no | no | Make printers accessible. | -| `samba_log` | no | - | Set the log file. If left undefined, logging is done through syslog. | -| `samba_log_size` | no | 5000 | Set the maximum size of the log file. | -| `samba_map_to_guest` | no | `bad user` | Behaviour when unregistered users access the shares. | -| `samba_netbios_name` | yes | - | The NetBIOS name of this server. | -| `samba_passdb_backend` | no | `tdbsam` | Password database backend. | -| `samba_security` | no | `user` | Samba security setting | -| `samba_server_string` | no | `fileserver %m` | Comment string for the server. | -| `samba_shares` | no | - | List of dicts containing share definitions. See below for details. | -| `samba_shares_root` | no | `/srv/shares` | Directories for the shares are created under this directory. | -| `samba_users` | no | - | List of dicts defining users that can access shares. | -| `samba_workgroup` | no | `WORKGROUP` | Name of the server workgroup. | +| Variable | Default | Comments | +| :--- | :--- | :--- | +| `samba_create_varwww_symlinks` | - | When this is set to `yes`, symlinks are created in `/var/www/html` to the shares. | +| `samba_load_homes` | false | When true, user home directories are accessible. | +| `samba_load_printers` | false | When true, printers attached to the host are shared | +| `samba_log` | - | Set the log file. If left undefined, logging is done through syslog. | +| `samba_log_size` | 5000 | Set the maximum size of the log file. | +| `samba_map_to_guest` | `bad user` | Behaviour when unregistered users access the shares. | +| `samba_netbios_name` | - | **Required.** The NetBIOS name of this server. | +| `samba_passdb_backend` | `tdbsam` | Password database backend. | +| `samba_security` | `user` | Samba security setting | +| `samba_server_string` | `fileserver %m` | Comment string for the server. | +| `samba_shares` | - | List of dicts containing share definitions. See below for details. | +| `samba_shares_root` | `/srv/shares` | Directories for the shares are created under this directory. | +| `samba_users` | - | List of dicts defining users that can access shares. | +| `samba_workgroup` | `WORKGROUP` | Name of the server workgroup. | ### Defining users @@ -52,6 +52,18 @@ samba_users: Unfortunately, passwords have to be in plain text for now. +These users should already have an account on the host! Creating system users is not a concern of this role, so you should do this separately. A possibility is my role [bertvv.el7](https://galaxy.ansible.com/list#/roles/2305). An example: + +```Yaml +el7_users: + - name: alice + comment: 'Alice' + password: !! + shell: /sbin/nologin + groups: + [...] +``` + ### Defining shares Defining Samba shares and configuring access control can be challenging, since it involves not only getting the Samba configuration right, but also user and file permissions, and SELinux settings. This role attempts to simplify the process. @@ -107,7 +119,12 @@ See the [test playbook](tests/test.yml) ## Testing -The `tests` directory contains acceptance tests for this role in the form of a Vagrant environment. The directory `tests/roles/samba` is a symbolic link that should point to the root of this project in order to work. To create it, do +The `tests` directory contains tests for this role in the form of a Vagrant environment. + +- [`test.yml`](tests/test.yml) is a minimal playbook that only sets the NetBios name (the only required variable) +- [`test-full.yml`](tests/test-full.yml) is a more complete playbook that applies most features of this role. + +The directory `tests/roles/samba` is a symbolic link that should point to the root of this project in order to work. To create it, do ```ShellSession $ cd tests/ @@ -115,9 +132,7 @@ $ mkdir roles $ ln -frs ../../PROJECT_DIR roles/samba ``` -You may want to change the base box into one that you like. The current one is based on Box-Cutter's [CentOS Packer template](https://github.com/boxcutter/centos). - -The playbook [`test.yml`](tests/test.yml) applies the role to a VM, setting role variables. +You may want to change the base box into one that you like. The current one is a base box I generated based on Box-Cutter's [CentOS Packer template](https://github.com/boxcutter/centos). It is shared on Atlas as [bertvv/centos71](https://atlas.hashicorp.com/bertvv/boxes/centos71/). ## See also @@ -125,7 +140,7 @@ If you are looking for a Samba role for Debian or Ubuntu, take a look at this [c ## Contributing -Issues, feature requests, ideas are appreciated and can be posted in the Issues section. Pull requests are also very welcome. Preferably, create a topic branch and when submitting, squash your commits into one (with a descriptive message). +Issues, feature requests, ideas are appreciated and can be posted in the Issues section. Pull requests are also very welcome. ## License