Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

domain_join

Provides just enough configuration to join a Linux node to an Active Directory domain.
Project URLRSS FeedReport issues

13,211 downloads

1,460 latest version

4.9 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.1 (latest)
  • 1.1.0
  • 1.0.0
  • 0.5.1
  • 0.5.0
  • 0.4.1 (deleted)
  • 0.4.0
  • 0.3.2
  • 0.3.1
  • 0.3.0
  • 0.2.0
  • 0.1.0
released Dec 27th 2019
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 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

Start using this module

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

Add this module to your Puppetfile:

mod 'rnelson0-domain_join', '1.1.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add rnelson0-domain_join
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install rnelson0-domain_join --version 1.1.1

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

rnelson0/domain_join — version 1.1.1 Dec 27th 2019

Build Status Puppet Forge Puppet Forge Downloads Stories in Ready Stories In Progress

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with domain_join
  4. Usage - Configuration options and additional functionality
  5. Limitations - OS compatibility, etc.
  6. Creating a Least Privilege account

Overview

Provide the most minimal configuration required to allow a Linux node to join a Windows domain.

Module Description

This module is intended for the lazy Linux admin who wants their Linux nodes to join a Windows domain without needing to manage the components. Rather than managing SSSD, Samba, and Kerberos, just manage "the ability to join a domain"!

Unfortunately, if you want to manage those services separately, this module may not be perfect fit for you. You may skip the service and resolver configuration by setting one or both of manage_services and manage_resolver to false.

Setup

What domain_join affects

  • DNS resolution through /etc/resolv.conf unless manage_resolver is false.
  • SSSD, Samba, and Kerberos configs (/etc/sssd/sssd.conf, /etc/samba/smb.conf, /etc/krb5.conf) unless manage_services is false.
  • A domain join shell script at /usr/local/bin/domain_join, that includes credentials used to join the domain.

Beginning with domain_join

# Without hiera
class { 'domain_join':
  domain_fqdn               => 'example.com',
  domain_shortname          => 'example',
  ad_dns                    => ['10.0.0.1', '10.0.0.2'],
  register_account          => 'domainjoin',
  register_password         => 'Sup4rS3krEt',
  additional_search_domains => ['web.example.com', 'b2b.example.com'],
}

# With Hiera
# Manifest:
include domain_join

# Hiera yaml:
---
domain_join::domain_fqdn: example.com
domain_join::domain_shortname: example
domain_join::ad_dns:
  - 10.0.0.1
  - 10.0.0.2
domain_join::register_account: domainjoin
domain_join::register_password: 'Sup4rS3krEt'
domain_join::additional_search_domains:
  - web.example.com
  - b2b.example.com

Usage

Follow the above reference for simple domain joins. You can control the service and resolver configuration with two booleans: class { 'domain_join': ... # other options manage_services => false, manage_resolver => false, }

---
domain_join::manage_services: false
domain_join::manage_resolver: false

Additional configuration options include:

createcomputer: Name of the AD container to join the new node to, typically an OU or a built-in container object.

Limitations

This module may cause duplicate resource errors if used in the same catalog as any module that directly manages sssd, samba, or kerberos packages or configs unless manage_services is false. See the compatibility tab or metadata.json for tested OS support.

Creating a Least Privilege account

It is highly recommended that the register_account be an account that has the ability to join computers to domains and nothing else. The following is an overly simplistic method to create such a user. This is suitable for a lab but may need further review for use in production. Use at your own risk.

  • Create an account, ex: domainjoin, in the appropriate hierarchy of your Active Directory. It is recommend that User cannot change password and Password never expires are selected.
  • Delegate the ability to manage computer objects to the user with the Active Directory Users and Computers snap in (from JSI Tip 8144 with tweaks).
  • Open the Active Directory Users and Computers snap-in.
  • Right click the container under which you want the computers added (ex: Computers) and choose Delegate Control.
  • Click Next.
  • Click Add and supply your user account(s), e.g domainjoin. Click Next when complete.
  • Select Create custom task to delegate and click Next.
  • Select Only the following objects in the folder and then Computer objects. Click Next.
  • Under Permissions, check Create All Child Objects and Write All Properties. Click Next.
  • Click Finish

You may also need to run the following command to increase the Machine Account Quota to a very large number. This represents the number of machines a user can join to the domain and defaults to 10 for the domain. This can only be set at the domain level.

Set-ADDomain example.com -Replace @{"ms-ds-MachineAccountQuota"="10000"}