cookbook 'windows_ad', '= 0.7.1', :supermarket
windows_ad (11) Versions 0.7.1 Follow41
Installs/Configures windows active directory
cookbook 'windows_ad', '= 0.7.1'
knife supermarket install windows_ad
knife supermarket download windows_ad
windows_ad Cookbook
This cookbook installs Active Directory Domain Services on Windows Server including all necessary roles and features.
Requirements
Platform
- Windows workstations (join and unjoin)
- Windows Server 2008 R2 Family
- Windows Server 2012 Family
- Windows Server 2016 Family
- Windows Server 2019 Family
Cookbooks
- Windows * Official windows cookbook from opscode https://github.com/opscode-cookbooks/windows.git
Usage
This is a library style cookbook that provides a set of resources to install and configure Windows ADDS in a composable way. It is intended to be used in your own wrapper cookbook suited to your specific needs. You can see example usage in the recipes of the windows_ad_test cookbook that is included in this repo. These recipes are used as part of integration testing.
- add
depends 'windows_ad'
to the metadata.rb for your cookbook. - use the provided resources in your cookbook
Testing
For more details look at the [TESTING.md](./TESTING.md).
Recipes
windows_ad::default
The windows_ad::default recipe installs the required roles and features to support a domain controller.
Resource/Provider
computer
Actions
- :create: Adds a computer object to Active Directory
- :delete: Remove a computer object from Active Directory.
- :join: Joins computer to domain.
- :modify: Modifies an existing computer object.
- :move: Rename a computer object without moving it in the directory tree, or move an object from its current location in the directory to a new location within a single domain controller.
- :unjoin: Removes computer from domain.
Property Parameters
- name: name property. Name of the computer object.
- domain_name: FQDN
- domain_pass: domain password
- domain_user: domain user
- ou: Organization Unit path where object is to be located.
- options: ability to pass additional options http://technet.microsoft.com/en-us/library/cc754539.aspx
- cmd_user: user under which the interaction with AD should happen
- cmd_pass: password for user specified in cmd_user (only needed if user requires password)
- cmd_domain: domain of the user specified in cmd_user (only needed if user is a domain account)
- restart: allows preventing reboot after join or unjoin action. Default true to reboot. Required
Examples
```rb
# Create computer "workstation1" in the Computers OU
windows_ad_computer "workstation1" do
action :create
domain_name "contoso.local"
ou "computers"
end
# Create computer "workstation1" in the Computers OU with description of "Computer"
windows_ad_computer "workstation1" do
action :create
domain_name "contoso.local"
ou "computers"
options ({ "desc" => "computer" })
end
# Create computer "workstation1" in the Computers OU using domain admin account
windows_ad_computer "workstation1" do
action :create
domain_name "contoso.local"
ou "computers"
cmd_user "Administrator"
cmd_pass "password"
cmd_domain "contoso.local"
end
# Join Contoso.com domain
windows_ad_computer 'Workstation' do
action :join
domain_pass 'Passw0rd'
domain_user 'Administrator'
domain_name 'contoso.local'
end
# Join Contoso.com domain without restart
windows_ad_computer "contoso.local" do
action :join
domain_pass 'Passw0rd'
domain_user 'Administrator'
domain_name 'contoso.local'
restart false
end
# Join Contoso.com domain with OU
windows_ad_computer "contoso.local" do
action :join
domain_pass 'Passw0rd'
domain_user 'Administrator'
domain_name 'contoso.local'
ou "Servers/Web"
end
# Unjoin Contoso.com domain
windows_ad_computer "contoso.local" do
action :unjoin
domain_pass 'Passw0rd'
domain_user 'Administrator'
domain_name 'contoso.local'
end
# Unjoin Contoso.com domain without restart
windows_ad_computer "contoso.local" do
action :unjoin
domain_pass 'Passw0rd'
domain_user 'Administrator'
domain_name 'contoso.local'
restart false
end
```
contact
Actions
- :create: Adds a contact object to Active Directory
- :delete: Remove a contact object from Active Directory.
- :modify: Modifies an existing contact object.
- :move: Rename a contact object without moving it in the directory tree, or move an object from its current location in the directory to a new location within a single domain controller.
Property Parameters
- name: name property. Name of the contact object.
- domain_name: FQDN
- ou: Organization Unit path where object is to be located.
- options: ability to pass additional options http://technet.microsoft.com/en-us/library/cc771883.aspx
- cmd_user: user under which the interaction with AD should happen
- cmd_pass: password for user specified in cmd_user (only needed if user requires password)
- cmd_domain: domain of the user specified in cmd_user (only needed if user is a domain account)
Examples
```rb
# Create contact "Bob Smith" in the Users OU with firstname "Bob" and lastname "Smith"
windows_ad_contact "Bob Smith" do
action :create
domain_name "contoso.local"
ou "users"
options ({ "fn" => "Bob",
"ln" => "Smith"
})
end
# Create contact "Bob Smith" in the Users OU with firstname "Bob" and lastname "Smith"
# using domain admin account
windows_ad_contact "Bob Smith" do
action :create
domain_name "contoso.local"
ou "users"
options ({ "fn" => "Bob",
"ln" => "Smith"
})
cmd_user "Administrator"
cmd_pass "password"
cmd_domain "contoso.local"
end
```
domain
Actions
- :create: Installs a forest, domain, or domain controller
- :delete: Removes a domain controller from domain
Property Parameters
- name: name property. Name of the forest/domain to operate against.
- type: type of install. Valid values: forest, domain, read-only.
- safe_mode_pass: safe mode administrative password.
- domain_user: User account to join the domain or to create a domain controller. Required: for
:create
except ontype
forest
on windows 2012 and above. - domain_pass: User password to join the domain or to create a domain controller. Required: for
:create
except ontype
forest
on windows 2012 and above. - local_pass: Local Administrator Password for removing domain controller.
- replica_type: For Windows Server 2008, specifies installing new or additional domain controller. Valid values: domain, replica.
- restart: when creating domain, will prevent Windows from automatically restarting. If not specified, defaults to true (which queues the restart). Valid values: true, false.
- options: additional options as needed by AD DS Deployment http://technet.microsoft.com/en-us/library/cc732887.aspx for Windows Server 2008 and http://technet.microsoft.com/en-us/library/hh974719.aspx for Windows Server 2012. Single parameters use nil for key value, see example below.
Examples
```rb
# Create Contoso.com forest
windows_ad_domain "contoso.local" do
action :create
type "forest"
safe_mode_pass "Passw0rd"
end
# Create Contoso.com forest and don't restart Windows
windows_ad_domain "contoso.local" do
action :create
type "forest"
safe_mode_pass "Passw0rd"
restart false
end
# Create Contoso.com replica
windows_ad_domain "contoso.local" do
action :create
type "replica"
safe_mode_pass "Passw0rd"
domain_pass "Passw0rd"
domain_user "Administrator"
end
# Create Contoso.com forest with DNS, Win2008 R2 Operational Mode Windows Server 2008 R2
windows_ad_domain "contoso.local" do
action :create
type "forest"
safe_mode_pass "Passw0rd"
options ({ "domainlevel" => "4",
"forestlevel" => "4",
"InstallDNS" => "yes"
})
end
# Create Contoso.com forest with DNS, Win2008 Operational Mode Windows Server 2012
windows_ad_domain "contoso.local" do
action :create
type "forest"
safe_mode_pass "Passw0rd"
options ({ "ForestMode" => "Win2008",
"InstallDNS" => nil
})
end
# Remove Domain Controller
windows_ad_domain "contoso.local" do
action :delete
local_pass "Passw0rd"
end
```
group
Actions
- :create: Adds a group object to Active Directory
- :modify: Modifies a group object.
- :move: Rename a group object without moving it in the directory tree, or move an object from its current location in the directory to a new location within a single domain controller.
- :delete: Remove a group object from Active Directory.
Property Parameters
- name: name property. Name of the group object.
- domain_name: FQDN
- ou: Organization Unit path where object is to be located.
- options: ability to pass additional options http://technet.microsoft.com/en-us/library/cc754037.aspx
- cmd_user: user under which the interaction with AD should happen
- cmd_pass: password for user specified in cmd_user (only needed if user requires password)
- cmd_domain: domain of the user specified in cmd_user (only needed if user is a domain account)
Examples
```rb
# Create group "IT" in the Users OU
windows_ad_group "IT" do
action :create
domain_name "contoso.local"
ou "users"
end
# Create group "IT" in the Users OU with Description "Information Technology Security Group"
windows_ad_group "IT" do
action :create
domain_name "contoso.local"
ou "users"
options ({ "desc" => "Information Technology Security Group"
})
end
# Create group "IT" in the Users OU using domain admin account
windows_ad_group "IT" do
action :create
domain_name "contoso.local"
ou "users"
cmd_user "Administrator"
cmd_pass "password"
cmd_domain "contoso.local"
end
```
group_member
Actions
- :add: Adds a user to a group.
- :remove: Removes a user from a group.
Property Parameters
- user_name: user name property. Name of the user object.
- group_name: group name property. Name of the group object.
- domain_name: FQDN.
- user_ou: Organization Unit path where user object is located.
- group_ou: Organization Unit path where group object is located.
- cmd_user: user under which the interaction with AD should happen
- cmd_pass: password for user specified in cmd_user (only needed if user requires password)
- cmd_domain: domain of the user specified in cmd_user (only needed if user is a domain account)
Examples
```rb
# Add user "Joe Smith" in the Users OU to group "Admins" in OU "AD/Groups"
windows_ad_group_member 'Joe Smith' do
action :add
group_name 'Admins'
domain_name 'contoso.local'
user_ou 'users'
group_ou 'AD/Groups'
end
# Add user "Joe Smith" in the Users OU to group "Admins" in OU "AD/Groups" using domain admin account
windows_ad_group_member 'Joe Smith' do
action :add
group_name 'Admins'
domain_name 'contoso.local'
user_ou 'users'
group_ou 'AD/Groups'
cmd_user "Administrator"
cmd_pass "password"
cmd_domain "contoso.local"
end
```
ou
Note: Chef 12 Custom Resource WIP.
ou provider will call ou_2008
or ou_2012
based on OS version.
Warning: Data bags can be used, however OU names must be unique (restriction of data bags)
Actions
- :create: Adds organizational units to Active Directory.
- :modify: Modifies an organizational unit.
- :move: Rename an organizational unit object without moving it in the directory tree, or move an object from its current location in the directory to a new location within a single domain controller.
- :delete: Remove an organizational unit object from Active Directory.
Property Parameters
- name: name property. Name of the Organization Unit object.
- domain_name: FQDN
- ou: Organization Unit path where object is to be located.
- options: ability to pass additional options http://technet.microsoft.com/en-us/library/cc770883.aspx
- cmd_user: user under which the interaction with AD should happen
- cmd_pass: password for user specified in cmd_user (only needed if user requires password)
- cmd_domain: domain of the user specified in cmd_user (only needed if user is a domain account)
Examples
```rb
# Create Organizational Unit "Departments" in the root
windows_ad_ou "Departments" do
action :create
domain_name "contoso.local"
end
# Create Organizational Unit "IT" in the "Department" OUroot
windows_ad_ou "IT" do
action :create
domain_name "contoso.local"
ou "Departments"
end
# Create Organizational Unit "Departments" in the root using domain admin account
windows_ad_ou "Departments" do
action :create
domain_name "contoso.local"
cmd_user "Administrator"
cmd_pass "password"
cmd_domain "contoso.local"
end
```
'ou_2008'
Actions
- :create: Adds organizational units to Active Directory. WIP:
- :modify: Modifies an organizational unit.
- :move: Rename an organizational unit object without moving it in the directory tree, or move an object from its current location in the directory to a new location within a single domain controller.
- :delete: Remove an organizational unit object from Active Directory.
Property Parameters
- name: name property. Name of the Organization Unit object.
- domain_name: FQDN
- ou: Organization Unit path where object is to be located.
- options: ability to pass additional options http://technet.microsoft.com/en-us/library/cc770883.aspx
- cmd_user: user under which the interaction with AD should happen
- cmd_pass: password for user specified in cmd_user (only needed if user requires password)
- cmd_domain: domain of the user specified in cmd_user (only needed if user is a domain account)
'ou_2012'
Actions
- :create: Adds organizational units to Active Directory. WIP:
- :modify: Modifies an organizational unit.
- :move: Rename an organizational unit object without moving it in the directory tree, or move an object from its current location in the directory to a new location within a single domain controller.
- :delete: Remove an organizational unit object from Active Directory.
Property Parameters
- name: name property. Name of the Organization Unit object.
- domain_name: FQDN
- path: Organization Unit path where object is to be located.
- options: ability to pass additional options http://technet.microsoft.com/en-us/library/cc770883.aspx
- cmd_user: user under which the interaction with AD should happen
- cmd_pass: password for user specified in cmd_user (only needed if user requires password)
- cmd_domain: domain of the user specified in cmd_user (only needed if user is a domain account)
users
Actions
- :create: Adds a user object to Active Directory.
- :modify: Modifies an user object.
- :move: Rename an user object without moving it in the directory tree, or move an object from its current location in the directory to a new location within a single domain controller.
- :delete: Remove an user object from Active Directory.
Property Parameters
- name: name property. Name of the user object.
- domain_name: FQDN
- ou: Organization Unit path where object is located.
- options: ability to pass additional options http://technet.microsoft.com/en-us/library/cc731279.aspx
- reverse: allows the reversing of "First Name Last Name" to "Last Name, First Name"
- cmd_user: user under which the interaction with AD should happen
- cmd_pass: password for user specified in cmd_user (only needed if user requires password)
- cmd_domain: domain of the user specified in cmd_user (only needed if user is a domain account)
Examples
```rb
# Create user "Joe Smith" in the Users OU
windows_ad_user "Joe Smith" do
action :create
domain_name "contoso.local"
ou "users"
options ({ "samid" => "JSmith",
"upn" => "JSmith@contoso.local",
"fn" => "Joe",
"ln" => "Smith",
"display" => "Smith, Joe",
"disabled" => "no",
"pwd" => "Passw0rd"
})
end
# Create user "Joe Smith" in the Users OU using domain admin account
windows_ad_user "Joe Smith" do
action :create
domain_name "contoso.local"
ou "users"
options ({ "samid" => "JSmith",
"upn" => "JSmith@contoso.local",
"fn" => "Joe",
"ln" => "Smith",
"display" => "Smith, Joe",
"disabled" => "no",
"pwd" => "Passw0rd"
})
cmd_user "Administrator"
cmd_pass "password"
cmd_domain "contoso.local"
end
```
Contributing
- Fork the repository on Github
- Create a named feature branch (like
add_component_x
) - Write you change
- Write tests for your change (if applicable)
- Run the tests, ensuring they all pass
- Submit a Pull Request using Github
License and Authors
Authors:: Derek Groh (dgroh@github.com) Richard Guin Miroslav Kyurchev (mkyurchev@gmail.com) Matt Wrock (matt@mattwrock.com) Miguel Ferreira (miguelferreira@me.com)
Dependent cookbooks
This cookbook has no specified dependencies.
Contingent cookbooks
Collaborator Number Metric
0.7.1 failed this metric
Failure: Cookbook has 0 collaborators. A cookbook must have at least 2 collaborators to pass this metric.
Contributing File Metric
0.7.1 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a CONTRIBUTING.md file
Foodcritic Metric
0.7.1 passed this metric
No Binaries Metric
0.7.1 passed this metric
Publish Metric
0.7.1 passed this metric
Supported Platforms Metric
0.7.1 passed this metric
Testing File Metric
0.7.1 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
0.7.1 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number
0.7.1 failed this metric
0.7.1 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a CONTRIBUTING.md file
Foodcritic Metric
0.7.1 passed this metric
No Binaries Metric
0.7.1 passed this metric
Publish Metric
0.7.1 passed this metric
Supported Platforms Metric
0.7.1 passed this metric
Testing File Metric
0.7.1 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
0.7.1 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number
0.7.1 passed this metric
0.7.1 passed this metric
Publish Metric
0.7.1 passed this metric
Supported Platforms Metric
0.7.1 passed this metric
Testing File Metric
0.7.1 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
0.7.1 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number
0.7.1 passed this metric
0.7.1 passed this metric
Testing File Metric
0.7.1 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
0.7.1 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number
0.7.1 failed this metric
0.7.1 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number