Forge Home

Modules

Resources

PuppetEcosystemPuppet CommunityUpdates

samba

Puppet module for configuring samba.
Project URLRSS FeedReport issues

6,967 downloads

1,818 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.1.0 (latest)
  • 1.0.2
  • 1.0.1
  • 1.0.0
released Jun 18th 2020
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.7.0 < 7.0.0
  • ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'millerjl1701-samba', '1.1.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add millerjl1701-samba
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install millerjl1701-samba --version 1.1.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

millerjl1701/samba — version 1.1.0 Jun 18th 2020

samba

master branch: Build Status

Table of Contents

  1. Module Description - What the module does and why it is useful
  2. Setup - The basics of getting started with samba
  3. Usage - Configuration options and additional functionality
  4. Reference - An under-the-hood peek at what the module is doing and how
  5. Limitations - OS compatibility, etc.
  6. Development - Guide for contributing to the module
  7. Credits

Module Description

This module installs, configures, and manages samba without the use of opinionated templates or sets of parameters.

For more details on Samba and the capabilities it provides, please see: https://www.samba.org/

This module provides puppet data in module as well as uses the Puppet 4 type classes. It will not work on older versions of Puppet. It seems to work on Puppet 5 so far.

This module is currently written to support samba on CentOS/RedHat 6/7 operating systems. Other operating system support could be added if time permits (Pull requests are welcome. :)

Setup

What samba affects

  • A list of files, packages, services, or operations that the module will alter, impact, or execute on the system it's installed on.
  • Package(s): samba
  • File: /etc/samba/smb.conf
  • Service(s): smb, nmb

Setup Requirements

This module just configures samba. If you need to configure krb5.conf as a prerequite for samba (allowing for sssd for instance), may I suggest one of the following modules:

Speaking of, if you are trying to configure sssd for use with samba, may I suggest one of the following modules:

Beginning with samba

include samba should be all that is needed to install, configure, and start the smb service using the parameters specified by the default smb.conf of the package install.

This module depends on the puppetlabs/stdlib and puppetlabs/concat modules.

Usage

All parameters to the main classc an be passed via puppet code or hiera.

Note: the Puppet lookup function will by default create a merged hash from hiera data for the samba::shares_definitions parameter. It would be possible to override the merge behavior in your own hiera data; however, this has not been tested and could create unexpected results.

Some examples are presented below with the file that is output from the code.

Creating the default CentOS 7 smb.conf file via hiera (less all the commented out parameters and comments)

samba::global_config:
  'global':
    'workgroup': 'SAMBA'
    'security': 'user'
    'passdb backend': 'tdbsam'
    'printing': 'cups'
    'printcap name': 'cups'
    'load printers': 'yes'
    'cups options': 'raw'
  'homes':
    'comment': 'Home Directories'
    'valid users': '%S, %D%w%S'
    'browseable': 'No'
    'read only': 'No'
    'inherit acls': 'Yes'
  'printers':
    'comment': 'All Printers'
    'path': '/var/tmp'
    'printable': 'Yes'
    'create mask': '0600'
    'browseable': 'No'
  'print$':
    'comment': 'Printer Drivers'
    'path': '/var/lib/samba/drivers'
    'write list': 'root'
    'create mask': '0664'
    'directory mask': '0775'

and the resulting configuration file:

# Managed by Puppet.

[global]
        workgroup = SAMBA
        security = user
        passdb backend = tdbsam
        printing = cups
        printcap name = cups
        load printers = yes
        cups options = raw

[homes]
        comment = Home Directories
        valid users = %S, %D%w%S
        browseable = No
        read only = No
        inherit acls = Yes

[printers]
        comment = All Printers
        path = /var/tmp
        printable = Yes
        create mask = 0600
        browseable = No

[print$]
        comment = Printer Drivers
        path = /var/lib/samba/drivers
        write list = root
        create mask = 0664
        directory mask = 077

Adding comments to the global and special sections

samba::global_config:
  'global':
    'load printers': 'yes'
    'cups options': 'raw'
    '#comment1': 'Here is the end of the global section... moving on.'

results in smb.conf:

[global]
        load printers = yes
        cups options = raw
# Here is the end of the global section... moving on.

How it works: The template checks for a parameter that begins with the '#' character, and then uses the specified value as the actual comment. If you have multiple comment lines, each parameter needs to start with a '#' character and the rest of the characters need to be unique for that comment to prevent an error.

Adding white space between options

samba::global_config:
  'global':
    'workgroup': 'SAMBA'
    '__blank1': ''
    'security': 'user'
    'passdb backend': 'tdbsam'
    '__blank2': ''
    'printing': 'cups'

results in:

[global]
        workgroup = SAMBA

        security = user
        passdb backend = tdbsam

        printing = cups

How it works: The template checks for a parameter that begins with two _ characters, and then just inserts a blank line into the resulting file. If you place multiple blank lines into a file, each parameter must begin with two _ characters and be different from the others in the rest of the characters to prevent an error. The string value is ignored.

Creating commented configuration items in the global and special sections

samba::global_config:
  'global':
    'workgroup': 'SAMBA'
    'security': 'user'
    ';passdb backend': 'tdbsam'

results is:

[global]
        workgroup = SAMBA
        security = user
;       passdb backend = tdbsam

How it works: The template checks for a parameter that begins with a ';' character, and then starts the line with a ';' character, tabs and places the rest of characters (less the ';') followed by an equal sign, and then parses the string or array for the values of the parameter.

Specifying multiple settings for an global or special section option

samba::global_config:
  'global':
    'interfaces':
      - 'lo'
      - 'eth0'
    'bind interfaces only': 'yes'

results in:

[global]
        interfaces = lo eth0
        bind interfaces only = yes

Specifying multiple settings for a share option

samba::shares_definitions:
  'admin':
    'comment': 'Admin Stuff'
    'path': '/mnt/stuff'
    'valid users':
      - 'bar'
      - 'bob'
      - '@foo'

results in:

[admin]
       comment = Admin Stuff
       path = /mnt/stuff
       valid users = bar, bob, @foo

Creating multiple shares using hiera

samba::shares_definitions:
  'admin':
    'comment': 'Admin Stuff'
    'path': '/mnt/stuff'
    'valid users': 'bar, bob, @foo'
    'writable': 'yes'
  'public':
    'comment': 'Public Stuff'
    'path': '/mnt/public'
    'writable': 'no'

results in:

[admin]
       comment = Admin Stuff
       path = /mnt/stuff
       valid users = bar, bob, @foo
       writable = yes
[public]
       comment = Public Stuff
       path = /mnt/public
       writable = no

Creating the same multiple shares as the previous example using puppet code

class { 'samba':
  shares_definitions => {
    'admin' => {
      'comment'     => 'Admin Stuff',
      'path'        => '/mnt/stuff',
      'valid users' => [ 'bar', 'bob', '@foo', ],
      'writable'    => 'yes',
    },
    'public' => {
      'comment'  => 'Public Stuff',
      'path'     => '/mnt/stuff',
      'writable' => 'no',
    },
  }
}

Reference

Generated puppet strings documentation with examples is available from https://millerjl1701.github.io/millerjl1701-samba/

The puppet strings documentation is also included in the /docs folder.

Public Classes

  • samba: Main class which installs, configures, and manages the smb and nmb services.

Private Classes

  • samba::install: Class for installation of the samba package.
  • samba::config: Class for construction of the /etc/samba/smb.conf configuration file.
  • samba::service: Class for managing the state of the smb and nmb services.

Limitations

This module was setup using CentOS 6 and 7 installation and documentation for rules. In time, other operating systems will be added as they have been tested. Pull requests with tests are welcome!

No validation or testing of the resulting /etc/samba/smb.conf file is done. This is left as an exercise for the reader.

Development

This module has been converted over to using the Puppet Development Kit from a legacy Gemfile setup. Prior to submitting a pull request, run the pdk validate command to ensure that the metadata and puppet manifests are of correct syntax. To specify a specific version of puppet to validate sysntax, run the command pdk validate --puppet-version 5.5.12 which would validate against Puppet 5.5.12.

All new code should have unit tests using rspec-puppet in the spec/classes directory. Once written, the pdk test unit command compiles catalogs for all supported operating systems ensuring that all resources are present in the catalog according the the unit test requirements.

All new functionality should have acceptance tests written using ServerSpec. Beaker is used as the test harness to provision a virtual machine, install puppet, and then configure the virtual machine with the module. If you have vagrant installed, the commands that you would use to run acceptance tests would be:

BEAKER_PUPPET_COLLECTION=puppet5 pdk bundle exec rake beaker
BEAKER_destroy=no BEAKER_PUPPET_COLLECTION=puppet5 pdk bundle exec rake beaker
BEAKER_provision=no BEAKER_destroy=no BEAKER_PUPPET_COLLECTION=puppet5 pdk bundle exec rake beaker
BEAKER_PUPPET_COLLECTION=puppet5 BEAKER_set=centos-6-x64 pdk bundle exec rake beaker

The first command runs acceptance tests against the default node set using the puppet5 collection. The second command add BEAKER_destroy=no to prevent the virtual machine from being destroyed at the end of the run in order to inspect the actual virtual machine. The third command allows you rerun the acceptance tests against the virtual machine without reprovisioning. The last command adds BEAKER_set to change the nodeset away from default to allow for testing other operating systems.

Contributors

To see who is involved with this module, see the GitHub list of contributors or the CONTRIBUTORS document.

Credits

This module was inspired from the excellent design work of the sgnl05/sgnl05-sssd puppet module. I loved how I could use it to specify a configuration file at will without having to wrangle parameterized classes for management of sssd. As that modules does, I used the sssd.conf template from walkamongus/sssd to generate concat fragments which then are assembled into the final samba configuration file.