Forge Home


A Puppet module for configuring Winbind on a Linux host


3,415 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

  • 2.0.0 (latest)
  • 1.6.3
  • 1.6.1
  • 1.6.0
  • 1.5.2
  • 1.5.0
  • 1.4.1
  • 1.1.0 (deleted)
  • 1.0.0
  • 0.4.2
  • 0.4.0 (deleted)
  • 0.3.2
  • 0.3.0
  • 0.2.1
released Apr 21st 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
  • Puppet >= 5.0.0 < 7.0.0
  • , ,
  • run_join_domain
  • join_domain

Start using this module

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

Add this module to your Puppetfile:

mod 'genebean-winbind', '2.0.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add genebean-winbind
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install genebean-winbind --version 2.0.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.

Tags: smb, winbind


genebean/winbind — version 2.0.0 Apr 21st 2020

Build Status Puppet Forge GitHub tag


Table of Contents

  1. Overview
  2. Setup requirements
  3. Beginning with winbind
  4. Limitations
  5. Troubleshooting
  6. License
  7. Contributing


This module will configure winbind for joining Active Directory and is designed with hiera in mind. It will also, optionally, allow you to configure SMB shares since smb.conf is used for both purposes.

Setup Requirements

The configuration used in this module requires Samba >= 3.6. Bolt is required if you want to use the included task to join machines to your domain.

Beginning with winbind


This module does not join your machine to AD but does provide you a Puppet task to do so. The reason it is not done during a Puppet run is that we have not found a secure way to do the joins since they require a privileged account and its password. Having said that, below is a recommended method of putting this module to use that limits your manual work to running a single Puppet task with Bolt. The task can join one or many nodes to the domain in a single run.

Recommended setup

  1. Include this module in a suitable default location such as a profile that includes your base settings. An example of this can be seen in examples/winbind.pp.
  2. Add the defaults for your domain to hiera. An example of this can be seen in examples/common.yaml.
  3. Apply the profile to desired nodes.
  4. Run bolt plan run winbind::join_domain domainuser=some-ad-user domainpassword=$ad_password nodes=node1,node2,node3 --user root
  5. Enjoy

Alternate templates

This module contains scripts for joing mahcines in the Red Hat and SUSE families to a domain. If you would rather use your own scripts then be sure to add winbind::manage_joindomain_script: false to your common.yaml file. If, on the other hand, you simply find that the scripts in here could be improved or expanded then please send us a pull request on GitHub.

Configuring SMB shares

The settings above will get you on a domain. If you want to supplement those with one or more SMB shares you will need the following additional configuration settings:

  1. Add winbind::enable_sharing : true to your node's file in hiera

  2. Create a share by either placing files with the needed settings in /etc/samba/smb.conf.d/ OR by using a hash. Using a hash is the recommended method.

    If you choose to use files, their names will need to be listed in an array as part of winbind::smb_includes_files

    If you choose to use a hash, you can either put it in a manifest like so:

    $my_smb_settings_hash = {
      'share1' => {
        'path'      => '/tmp',
        'browsable' => 'yes',
        'read only' => 'yes'
      'share2' => {
        'path'      => '/mnt',
        'browsable' => 'no',
        'read only' => 'yes'
    class { winbind:
      enable_sharing    => true,
      smb_settings_hash => $my_smb_settings_hash,

    Or if you choose to use hiera the same hash would look like this:

        path      : '/tmp'
        browsable : 'yes'
        read only : 'yes'
        path      : '/mnt'
        browsable : 'no'
        read only : 'yes'


There is a parameter that corresponds directly to each setting in the four configuration files that get edited by this module. Each is prefixed so that you know which file it effects:

  • pam = /etc/security/pam_winbind.con
  • smb = /etc/samba/smb.conf
  • krb5 = /etc/krb5.conf
  • oddjobd = /etc/oddjobd.conf.d/oddjobd-mkhomedir.conf

The full list of parameters is listed at the top of the init.pp file. A fully functional setup should be attainable by providing values for the following three parameters:


If set, this will limit who can log in via winbind


This is the short name of your domain.


This is the long name of your domain. It is also used in krb5.conf for the realms and domain_realms settings.

Additional Parameters


Allows disabling the management of /root/ Defaults to true.


Allows disabling the management of the messagebus service. Defaults to true.


Allows disabling the management of the oddjobd service. Defaults to true.


Defines the ensure setting passed to all managed packages. Defaults to present.


This module has only been tested on Red Hat 5, CentOS 6 & 7, and SLES 11 & 12.


On RHEL 5 we found that joining was difficult if just the right things were not in /etc/hosts. In particular, I got errors that my DNS name had to match the domain I was joining. I resolved this issue by making a host entry like this:

# this should all be on a single line server localhost
localhost.localdomain  localhost4 localhost4.localdomain4

This entry is maintained via a host resource defined elsewhere in my Puppet setup.


This is released under the New BSD / BSD-3-Clause license. A copy of the license can be found in the root of the module.


Pull requests are welcome!


  • Adam Stephens (@adamcstephens) - Added support for toggling service management and overriding the package ensure setting
  • Jake Spain (@thespain) - Added support for SLES 11 & 12