- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with samba
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
- Credits
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. :)
- 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
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:
- https://forge.puppet.com/ccin2p3/mit_krb5
- https://forge.puppet.com/pfmooney/mit_krb5
- https://forge.puppet.com/simp/krb5
Speaking of, if you are trying to configure sssd for use with samba, may I suggest one of the following modules:
- [https://forge.puppet.com/sgnl05/sssd](https://forge.puppet.com/sgnl05/sssd
- https://forge.puppet.com/walkamongus/sssd
- https://forge.puppet.com/simp/sssd
- https://forge.puppet.com/bodgit/sssd
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.
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
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.
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.
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.
samba::global_config:
'global':
'interfaces':
- 'lo'
- 'eth0'
'bind interfaces only': 'yes'
results in:
[global]
interfaces = lo eth0
bind interfaces only = yes
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
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
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',
},
}
}
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.
- samba: Main class which installs, configures, and manages the smb and nmb services.
- 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.
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.
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.
To see who is involved with this module, see the GitHub list of contributors or the CONTRIBUTORS document.
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.