An Ansible collection for setting up Samba as a file server. It is tested on Ubuntu, Debian, CentOS and Arch Linux. Specifically, the responsibilities of this collection are to:

• Install the necessary packages
• Configure SELinux settings (when SELinux is active)
• Create share directories
• Manage Samba users and passwords
• Manage access to shares

The following are not considered concerns of this collection, and you should configure these using another collection:

• Managing firewall settings.
• Creating system users. Samba users should already exist as system users.

If you like/use this collection, please consider giving it a star! Thanks!

A remote code execution vulnerability may affect your Samba server installation. Samba versions 3.5.0 and before 4.6.4 are affected. If SELinux is enabled on your system, it is NOT vulnerable.

This collection will check if the installed version of Samba is affected by the vulnerability and apply the proposed workaround: adding nt pipe support = no to the [global] section of the configuration. Remark that this disables share browsing by Windows clients.

You can explicitly disable the fix if necessary, by setting the server role variable samba_mitigate_cve_2017_7494 to false.

More info: https://access.redhat.com/security/cve/cve-2017-7494

Install it with the Ansible Galaxy CLI:

ansible-galaxy collection install vladgh.samba  --upgrade

You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml, using the format:

---
collections:
  - name: vladgh.samba

Using the GitHub repository and specific branch or release:

collections:
  - name: https://github.com/vladgh/ansible-collection-vladgh-samba
    version: main
    type: git

---
- name: Common
  hosts: all
  become: yes
  roles:
    - role: vladgh.samba.server

---
- import_playbook: vladgh.samba.server

See Ansible Using collections for more details.

In order to allow users to access the shares, they need to get a password specifically for Samba:

samba_users:
  - name: alice
    password: ecila
  - name: bob
    password: bob
  - name: charlie
    password: eilrahc

It is recommended to encrypt the password content with Ansible Vault. Also, remark that this collection will not change the password of an existing user.

These users should already have an account on the host! Creating system users is not a concern of this collection, so you should do this separately:

- name: Add the user 'james' with a bash shell, appending the group 'admins' and 'developers' to the user's groups
  ansible.builtin.user:
    name: james
    shell: /bin/bash
    groups: admins,developers
    append: yes

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 collection attempts to simplify the process.

To specify a share, you should at least give it a name:

samba_shares:
  - name: readonlyshare

This will create a share with only read access for registered users. Guests will not be able to see the contents of the share.

A good way to configure write access for a share is to create a system user group, add users to that group, and make sure they have write access to the directory of the share. This collection assumes groups are already set up and users are members of the groups that control write access. Let's assume you have two users jack and teach, members of the group pirates. This share definition will give both read and write access to the pirates:

samba_shares:
  - name: piratecove
    comment: 'A place for pirates to hang out'
    group: pirates
    write_list: +pirates

Guests have no access to this share, registered users can read. You can further tweak access control. Read access can be extended to guests (add public: yes) or restricted to specified users or groups (add valid_users: +pirates). Write access can be restricted to individual pirates (e.g. write_list: jack). Files added to the share will be added to the specified group and group write access will be granted by default.

This is an example of configuring multiple vfs object modules to share a glusterfs volume. VFS object options are optional. The necessary VFS object modules must be present/installed outside this collection. In this case samba-glusterfs was installed on centos. See samba documentation for how to install or what the default VFS object modules are.

samba_shares:
  - name: gluster-app_deploys
    comment: 'For samba share of volume app_deploys'
    vfs_objects:
      - name: audit
        options:
          - name: facility
            value: LOCAL1
          - name: priority
            value: NOTICE
      - name: glusterfs
        options:
          - name: volume
            value: app_deploys
          - name: logfile
            value: /var/log/samba/glusterfs-app_deploys.%M.log
          - name: loglevel
            value: 7
    path: /
    read_only: no
    guest_ok: yes
    write_list: tomcat
    group: tomcat

A complete overview of share options follows below. Only name is required, the rest is optional.

The values for valid_users and write_list should be a comma separated list of users. Names prepended with + or @ are interpreted as groups. The documentation for the Samba configuration has more details on these options.

You can add settings that are not supported by this collection out-of-the-box through custom configuration files that will be included from the main configuration file. There are three types of include files: for the global section, for the homes section, and for individual shares. Put your custom configuration files in a subdirectory templates, relative to your master playbook location. Then, specify them in the variables samba_global_include, samba_homes_include, or include_file in the samba_shares definition.

Your custom configuration files are considered to be Jinja templates, so you can use Ansible variables inside them. The configuration files will be validated to ensure they are syntactically correct.

For example, to include templates/global-include.conf, set:

samba_global_include: global-include.conf

Remark that is it not necessary to specify the templates/ directory.

Likewise, to include templates/piratecove-include.conf, specific for the piratecove share (see the example above); set:

samba_shares:
  - name: piratecove
    comment: 'A place for pirates to hang out'
    group: pirates
    write_list: +pirates
    include_file: piratecove-include.conf

The test playbook has some examples.

• Ansible Posix

This collection is tested using Ansible Molecule. Tests are launched automatically via GitHub Actions after each commit and PR.

This Molecule configuration will:

• Create a Docker container
• Run a syntax check
• Apply the role with a test playbook
• Run idempotence check

This process is repeated for the supported Linux distributions.

Steps to install the necessary tools manually:

1. Docker and Python >= 3.8 should be installed on your machine (assumed to run Linux).
2. As recommended by Molecule, create a python virtual environment
3. Install the software tools python3 -m pip install --user --upgrade pip ansible ansible-lint molecule docker
4. Navigate to the root of the collection directory and run molecule test

Molecule automatically deletes the containers after a test. If you would like to check out the containers yourself, run molecule converge followed by molecule login --host HOSTNAME.

The Docker containers are based on images created by Jeff Geerling, specifically for Ansible testing (look for images named geerlingguy/docker-DISTRO-ansible). You can use any of his images, but only the distributions mentioned in meta/main.yml are supported.

The default config will start an Ubuntu 22.04 container. Choose another distro by setting the MOLECULE_DISTRO variable with the command, e.g.:

MOLECULE_DISTRO=debian11 molecule test

This repository keeps a change log using GitHub's releases functionality.

Releases are based on Semantic Versioning, and use the format of MAJOR.MINOR.PATCH. The version will be incremented based on the following:

• MAJOR: Incompatible or major changes
• MINOR: Backwards-compatible new features and enhancements
• PATCH: Backwards-compatible bugfixes and package updates

Contributions are always welcome! Please read the contribution guidelines and the code of conduct.

This collection could only have been realized thanks to the contributions of the people listed below. If you have an idea to improve it even further, don't hesitate to pitch in! Please create a topic branch for your proposed changes. If you don't, this will create conflicts in your fork after the merge. Don't hesitate to add yourself to the contributor list below in your PR!

Ben Tomasik, Bengt Giger, Bert Van Vreckem (maintainer), Birgit Croux, DarkStar1973, George Hartzell, Ian Young, Jonas Heinrich, Jonathan Underwood, Karl Goetz, morbidick, Paul Montero, Robin Ophalvens, Slavek Jurkowski, Sven Eeckeman, Tiemo Kieft, Tobias Wolter, Tomohiko Ozawa, Vlad Ghinea (maintainer),

2-clause BSD license, see LICENSE.md