Ansible Role bertvv.samba

This is an Ansible role for setting up Samba as a file server.

Because of time and resource constraints, I have passed the maintenance of this role to @vladgh. I won't be able to manage issues and pull requests or ensure that new releases meet quality standards.

• The new GitHub repository is here: https://github.com/vladgh/ansible-collection-vladgh-samba
• Ansible Galaxy page: https://galaxy.ansible.com/vladgh/samba
• To install, run: ansible-galaxy collection install vladgh.samba --upgrade

Thank you to everyone who has supported this project over the years, especially @vladgh for volunteering to take over maintenance.

Responsibilities of this role include:

• Installing necessary packages
• Configuring SELinux settings (if SELinux is active)
• Creating shared directories
• Managing Samba users and passwords
• Managing access to shares

This role does not handle:

• Firewall settings
• Creating system users (Samba users must already be system users)

If you like this role, please consider giving it a star! Thanks!

CVE-2017-7494

There is a remote code execution vulnerability that may affect your Samba server if it's running versions 3.5.0 and earlier than 4.6.4. If SELinux is enabled, your system is not vulnerable.

This role will check if your Samba version is affected and will add a fix: nt pipe support = no to the [global] section of the configuration, which prevents Windows clients from browsing shares.

You can disable this fix by setting the role variable samba_mitigate_cve_2017_7494 to false.

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

Requirements

No specific requirements.

Role Variables

Defining Users

To allow users to access shares, they need a separate Samba password:

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

Passwords must be plain text for now. The role will not change an existing user's password.

These users must already be system accounts! You should create system users separately, possibly using my role bertvv.rh-base. Example:

rhbase_users:
  - name: alice
    comment: 'Alice'
    password: !!
    shell: /sbin/nologin
    groups:
      [...]

This user cannot log in to the system (e.g., via SSH) and only has access to Samba shares.

Defining Shares

Configuring Samba shares can be tricky because it involves getting Samba settings, user permissions, and SELinux settings right. This role aims to simplify that.

To define a share, you must specify at least a name:

samba_shares:
  - name: readonlyshare

This setup allows registered users to read the share, while guests cannot see it.

To configure write access, create a system user group, add users to it, and ensure they have write permissions for the share directory. Assuming users jack and teach belong to the pirates group, you can define the share:

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

Guests cannot access this share, but registered users can read it. You can adjust access settings further by allowing guest read access (public: yes) or restricting it to specific users or groups (valid_users: +pirates).

Here’s how to configure multiple VFS object modules to share a glusterfs volume (you’ll need the necessary VFS object modules installed):

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

Here’s a summary of share options (only name is required):

For valid_users and write_list, use a comma-separated list. Names with + or @ are interpreted as groups. Check the Samba configuration documentation for more details.

Adding Custom Configuration Files

You can add custom settings through configuration files that will be included in the main config file. Three types of include files exist: global, homes, and individual shares. Place your custom config files in a templates subdirectory next to your master playbook, and reference them in samba_global_include, samba_homes_include, or include_file within samba_shares.

Custom config files are treated as Jinja templates, allowing you to use Ansible variables. These files will be verified for correctness.

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

samba_global_include: global-include.conf

You don't need to specify the templates/ directory.

Similarly, for piratecove, include the file like this:

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

Check the test playbook for examples. You'll find custom configuration files in the docker-tests branch.

Dependencies

No dependencies.

Example Playbook

For an example playbook, please refer to the test playbook.

Testing

This role is tested using Ansible Molecule. Tests run automatically on Travis CI after each commit and pull request.

The Molecule setup will:

• Run Yamllint and Ansible Lint
• Create a Docker container
• Perform a syntax check
• Apply the role with a test playbook
• Run acceptance tests with BATS

This process will repeat for supported Linux distributions.

Local Test Environment

For a local test setup, use this reproducible setup with Vagrant+VirtualBox: https://github.com/bertvv/ansible-testenv. Follow these steps to install the necessary tools manually:

1. Install Docker, BATS, and smbclient on your Linux machine. Ensure no Docker containers are running when you start testing.
2. Create a Python virtual environment as recommended by Molecule.
3. Install required software: python3 -m pip install molecule docker yamllint ansible-lint.
4. From the root of the role directory, run molecule test.

Molecule will clean up the containers after testing. If you want to inspect them, run molecule converge then molecule login --host HOSTNAME.

Docker containers are based on images from Jeff Geerling, specifically made for Ansible testing (look for images named geerlingguy/docker-DISTRO-ansible). You can use any of his images, but only those listed in meta/main.yml are supported.

By default, a CentOS 7 container starts. To choose another distribution, set the MOLECULE_DISTRO variable like this:

MOLECULE_DISTRO=debian9 molecule test

or

MOLECULE_DISTRO=debian9 molecule converge

You can run the acceptance tests on both servers with molecule verify or manually with:

SUT_IP=172.17.0.2 bats molecule/default/files/samba.bats

Make sure to set the variable SUT_IP, which is the IP address of the server under test. The server smb1 should have the IP address 172.17.0.2.

Contributing

Your input is welcome! You can report issues, request features, or post ideas in the Issues section.

Pull requests are also encouraged. The best way to submit a PR is to fork the GitHub project, create a topic branch for your changes, and push that branch to your fork. GitHub can easily create a PR based on that branch. Don’t forget to add yourself to the contributor list!

License

This role is licensed under the 2-clause BSD license. See LICENSE.md for details.

Contributors

This role is the result of contributions from the following individuals. If you have an idea for improvement, please join in!

You can submit issues, feature requests, or ideas in the Issues section.

Pull requests are welcomed—just create a topic branch for your changes. Avoid creating conflicts in your fork after merging. Please add yourself to the contributor list 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,
Slavek Jurkowski,
Sven Eeckeman,
Tiemo Kieft,
Tobias Wolter,
Tomohiko Ozawa,
Robin Ophalvens.