Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

Select Status


dhcp (53) Versions 6.1.0

Installs and configures DHCP

cookbook 'dhcp', '= 6.1.0', :supermarket
cookbook 'dhcp', '= 6.1.0'
knife supermarket install dhcp
knife supermarket download dhcp
Quality 100%

DHCP Cookbook

Cookbook Version
Build Status


Data bag and Attribute driven DHCP server.

  • Supports setting up Master/Master isc DHCP failover.
  • Includes Support for ddns
  • Includes LWRPs for managing hosts, groups and subnets.
  • Use databags or attributes + wrapper cooks to manage dhcp server [Example](examples/attribute_based.rb)

Large parts were borrowed from work initially done by Dell, extended by Atalanta Systems and reworked by Matt Ray and Chef. Big thanks to all of them.


This cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit or come chat with us on the Chef Community Slack in #sous-chefs.


  • Debian / Ubuntu
  • CentOS and derivatives
  • Fedora and derivatives


  • 13+


  • only setup to handle ipv4



The node will install and configure the dhcp-server application. Configuration is through various dhcp_X bags, and the current role/environment

Node Attributes

Almost everyone of the parameters and options are able to be overrode in the host/group/network scope these are general defaults for the server.

Check out the [man page][1] for details on dhcpd.conf options/params.

attribute Type Default description
node[:dhcp][:use_bags] Boolean true When false we won't attempt to load data from bags.
node[:dhcp][:hosts] Array [] The list of hosts items that this server should load
node[:dhcp][:groups] Array [] The list of group items this server should load
node[:dhcp][:networks] Array [] The list of network items this node should load
node[:dhcp][:interfaces] Array [] The Network Interface(s) to listen on. If an empty list then we will listen on all interfaces.
node[:dhcp][:rndc_keys] Array Attribute based representation of rndc keys you want to use.
node[:dhcp][:hosts_bag] String dhcp_hosts The name of the data bag that holds host items.
node[:dhcp][:groups_bag] String dhcp_groups The name of the data bag that holds group items
node[:dhcp][:networks_bag] String dhcp_networks The name of the data bag that holds network items
node[:dhcp][:host_data] Hash {} Hash of hosts data. The node[dhcp][:hosts] entries should have a corresponding entry here when not using bags
node[:dhcp][:group_data] Hash {} Same as host_data, but for groups
node[:dhcp][:network_data] Hash {} Same as host_data, but for networks
node[:dhcp][:failover] Boolean false Enable Failover support buy setting to true
node[:dhcp][:failover_lease_hack] Boolean false Force partner-down state on start by rewriting lease file
node[:dhcp][:allows] Array ["booting", "bootp", "unknown-clients"] Global Dhcpd allow entries
node[:dhcp][:my_ip] String Nil Set host IP address in failover setup. node[:ipaddress] is used if empty.
node[:dhcp][:masters] Array Array of hashes to override node search for masters. Must have :ipaddress key.
node[:dhcp][:slaves] Array Array of hashes to override node search for slaves.
node['dhcp']['extra_files'] Array Array of file paths to also include as configs in node['dhcp']['config_file']
node['dhcp']['hooks'] Hash Ability to run scripts when events occur. More info @ and [example](spec/_config_spec.rb)

DHCP Global Options

attribute Type Default description
node[:dhcp][:options]['domain-name-servers'] String "," List of dns servers to send to clients in the global scope
node[:dhcp][:options]['host-name'] String " = binary-to-ascii (16, 8, \"-\", substring (hardware, 1, 6))" Options for global scope host-name settings. The default here will generate a host as mac address if the node doesn't provide a hostname or is not defined in dns/hosts/groups.
node[:dhcp][:options]['domain-name'] String "\"#{domain}\"" Set domainname in the global scope to this nodes domain

DHCP Global Parameters

These are all just k/v entries in the global params hash. All values are type: String

attribute Type Default description
node[:dhcp][:parameters]["default-lease-time"] String "6400" Set the default lease time in the global scope
node[:dhcp][:parameters]["ddns-domainname"] String "#{domain}" Set the ddns domain to this nodes domain
node[:dhcp][:parameters]["ddns-update-style"] String "interim" ddns Update style
node[:dhcp][:parameters]["max-lease-time"] String "86400" Max Lease time
node[:dhcp][:parameters]["update-static-leases"] String "true" Make sure we push static ip adresses defined in groups/hosts to the dns server
node[:dhcp][:parameters]["one-lease-per-client"] String "true" When a client requests an ip it will release any held leases.
node[:dhcp][:parameters]["authoritative"] String "" This setting has no value on purpose thats how isc-dhcpd wants it.
node[:dhcp][:parameters]["ping-check"] String "true" Enable Address collision checking
node[:dhcp][:parameters]["next-server"] String "#{ipaddress}" Set this server as the global next-server
node[:dhcp][:parameters]["filename"] String '"pxelinux.0"' For tftp file name Note: the quotes are necessary for this option in the fall throught to dhcpd config.

Failover parameters

attribute Type Default description
node[:dhcp][:failover_params]["mclt"] String "3600" Set Maximum Client Lead Time
node[:dhcp][:failover_params]["port"] String "647" TCP port to listen for connections from peer
node[:dhcp][:failover_params]["peer_port"] String "647" TCP port to connect to failover peer
node[:dhcp][:failover_params][auto_partner_down""] String "0" Timeout in seconds to enter partner-down state if peer is unavailable

Platform Default Attributes

RHEL Platforms

attribute Type Default
node[:dhcp][:dir] String "/etc/dhcpd"
node[:dhcp][:package_name] String "dhcp"
node[:dhcp][:service_name] String "dhcpd"
node[:dhcp][:config_file] String "/etc/dhcp/dhcpd.conf"
node[:dhcp][:init_config] String "/etc/sysconfig/dhcpd"

Debian Platforms

attribute Type Default
node[:dhcp][:dir] String "/etc/dhcpd"
node[:dhcp][:package_name] String "isc-dhcp-server"
node[:dhcp][:service_name] String "isc-dhcp-server"
node[:dhcp][:config_file] String "/etc/dhcp/dhcpd.conf"
node[:dhcp][:init_config] String "/etc/default/isc-dhcp-server"

Data Bags

Data bags drive the lionshare of the dhcp configuration. Beyond the global settings. It is not required to configure any bags other than dhcp_networks to get up and running, But if you want to statically map a network or have handy Host names provisioned by dhcp you will have to add either dhcp_groups/dhcp_hosts bags and items.

You can generate example bags by using these handy commands

knife data bag create dhcp_networks
knife data bag create dhcp_groups
knife data bag create dhcp_hosts
knife data bag from file dhcp_networks examples/data_bags/dhcp_networks
knife data bag from file dhcp_groups examples/data_bags/dhcp_groups
knife data bag from file dhcp_hosts examples/data_bags/dhcp_hosts


Looked up via node[:dhcp][:networks_bag]. Describes networks this dhcp server should be configured to provide services for. Per-network options can be provided as an array of strings where each string is a dhcp option. Make sure you escape "'s properly as dhcpd is touchy about the format of values.

  "id": "192-168-1-0_24",
  "routers": [ "" ],
  "address": "",
  "netmask": "",
  "broadcast": "",
  "range": "",
  "options": [ "time-offset 10" ],
  "next_server": ""


Looked up via node[:dhcp][:grougroups] Items for this bag are group entries as per the [man page][1]. Groups are sets of machines that can be configured with common parameters. A group can be bare. I.e. Contains no host or parameters entries whatsover, and just defines options.

The only required key in a host def is the "mac": key. Everything else is optional

Example Group Bag

  "id": "test",
  "pxe":  "ubuntu-precise",
  "parameters": [
    "use-host-decl-names on",
    "max-lease-time 300",
    "default-lease-time 120",
    "next-server \"someplace\""
  "hosts": {
    "some-vm": {
      "parameters": [  ],
      "mac": "11:22:33:44:55:66",
      "ip": ""
    "another-host": {
      "mac": "22:33:44:55:66:77"

There are a few keys that merit more discussion:

"hosts": key dhcp_group Items

Groups in isc-dhcp can define lists of hosts. In this example we are using the use-host-decl-names on tell dhcp to use the "some-vm" and "another-host" entries as the host-name for these clients. As well as setting other per-group parameters.

Each Host in the hosts Hash can have a number of settings, but the only required setting is "mac": the mac address for the host.

Key Description
"mac": mac address of this host
"ip": ip address of this host
"parameters": an array of isc-dhcpd parameters as-per the global parameter setting.
"pxe": This key is used by my pxe cookbook to figure out what pxe item you want this group to boot too. That Pxe cookbook should be released soon (hopefully).


Dhcp hosts bag is looked up via node[:dhcp][:hosts_bag], and contains Host Items.

Example Most Basic host:

  "id": "vagrant-vm",
  "hostname": "vagrant.vm",
  "mac": "08:00:27:f1:1f:b6",

Example Complex host:

  "id": "pxe_test-vm",
  "hostname": "pxe_test.vm",
  "mac": "08:00:27:8f:7b:db",
  "ip": "",
  "parameters": [ ],
  "options": [ ],
  "pxe": "ubuntu-precise"



Manipulate host entries in dhcpd


Action Description
add _default_ Add this host record
remove Delete this host record


Param Type Default
hostname String
macaddress String
ipaddress String
options Array []
parameters Array []
conf_dir String "/etc/dhcp"


Add a Node

dhcp_host "myhost" do
  hostname   ""
  macaddress "08:00:27:f1:1f:b6"
  ipaddress  ""
  options   [ "domain-name-servers" ]

Remove a node

dhcp_host "myhost" do
  action :remove
  hostname ""

If you undefine an entry it will also get removed.



Action Description
add _default_ Add this host record
remove Delete this host record


Param Type Default Desciption
name String :name_attribute
hosts Hash {} This is a hash of host entries that follow the host-databag format. See the example entry in examples directory
parameters Array []
evals Array [] This is an array of multiline strings of eval
conf_dir String "/etc/dhcp" The directory where the config files are stored


hosts_data = {
  "some-vm"=> {"parameters"=>[], "mac"=>"11:22:33:44:55:66", "ip"=>""},

dhcp_group "some_group" do
  parameters [ "default-lease-time 120", "next-server \"someplace\""]
  hosts hosts_data


Action Description
add _default_ Add this host record
remove Delete this host record


Param Type Default Desciption
subnet String :name_attribute The network subnet
broadcast String nil The broadcast address for the subnet
netmask String nil The netmask address for the subnet
routers Array [] Gateways for the subnet
options Array [] DHCP options to set for the subnet
pool block nil Define a pool block for a dhcp_subnet. See 'Parameters for pool' below.
next_server String nil Next server for TFTP/PXE
evals Array [] This is an array of multiline strings of eval
ddns String nil Domain name that will be appended to the client's hostname to form a fully-qualified domain-name (FQDN)
key Hash {} Shared secret key for DDNS
zones Array [] NOTE: Please help update with a good description
conf_dir String "/etc/dhcp" Main dhcpd config directory
Parameters for pool
Param Type Default Desciption
peer String nil Peer server for this segment
range String or Array [] Range of IPs to make available for DHCP in the subnet
allow String or Array [] Only those clients that match any entries on the allow list will be eligible.
deny String or Array [] Only those clients that do not match any entries on the deny list will be eligible.


dhcp_subnet "" do
  pool do
    range ["", ""]
  netmask ""
  broadcast ""
  options [ "time-offset 10" ]
  next_server ""
  routers ""
  evals [ %q|
    if exists user-class and option user-class = "iPXE" {
      filename "bootstrap.ipxe";
    } else {
      filename "undionly.kpxe";
  | ]


Action Description
add _default_ Add this shared network
remove Delete this shared network record


Param Type Default Desciption
subnet dhcp_subnet nil The network subnet to define inside the shared network. Can define multiple.


dhcp_shared_network 'mysharednet' do
  subnet '' do
    pool do
      range ['', '']
    netmask ''
    broadcast ''
    next_server ''
    routers ''
    evals [ %q|
      if exists user-class and option user-class = "iPXE" {
        filename "bootstrap.ipxe";
      } else {
        filename "undionly.kpxe";
    | ]
  subnet '' do
    broadcast ''
    netmask ''
    pool do
      range ['']


Manage dhcp classes


Action Description
add _default_ Add this host record


Param Type Default
match String
subclass String
subclasses Array []


Add a Node

dhcp_class 'ignorehosts' do
  match 'hardware'
  subclass '1:10:bf:48:42:55:01'
  subclass '1:10:bf:48:42:55:02'

If you undefine an entry it will also get removed.


Testing uses Chef Workstation


This project exists thanks to all the people who contribute.


Thank you to all our backers!


Support this project by becoming a sponsor. Your logo will show up here with a link to your website.


6.1.0 (2019-10-19)

6.0.0 (2018-03-04)

  • Remove matchers. Breaking change. This requires ChefDK 2.0+
  • Allow specifying array of allow and deny declarations in dhcp_subnet pool
  • Convert to custom resources
  • Drop support for Chef 12
  • Add support for Fedora

5.5.0 (2018-03-04)

  • Use Berkshelf instead of Policyfiles
  • Remove support for RHEL5

5.4.4 (2018-03-04)

  • Use dokken images for travis testing

5.4.3 (2018-03-04)

  • Require Chef 12.7+ for apt_update fix

5.4.2 (2017-12-02)

  • Remove Chef 10/11 compatibility code that resulted in Foodcritic deprecation warnings
  • Fix misplaced closing brace for dhcpd hooks in template file


  • Fix: attribute breaking Chef 13 runs.


  • Added hooks


  • bug #67: Removed blank? from helper libraries but was still calling in code. Addressed by removing blank? calls from code and using empty? instead.


  • bug: Update _hosts recipe for Helpers::DataBags.escape_bagname change to Dhcp::Helpers.escape


  • Remove dependencies on helper cookbooks


  • Add allow attribute for pool in dhcp_subnet provider


  • Allow specifying with node['dhcp']['extra_files'] externally managed configs to load


  • bug: Load classes before subnets


  • bug: Include classes.d/list.conf in dhcp.conf
  • bug: Make dhcp_subnet names declared in dhcp_shared_network more unique


  • bug: Pin partial templates to dhcp cookbook


  • BREAKING feature: Allow defining multiple pools in a subnet

    • This moves range and peer attribtue from dhcp_subnet block to embedded pool block inside dhcp_subnet. See updated examples.
    • Currently this DOES NOT break defining subnets via data_bags or node attributes


  • bug: Allow defining dhcp_class with no subclasses


  • improve: Add dhcp_class ChefSpec matcher


  • feature: dhcp_class provider


  • fix: be able to declare a blank subnet inside a shared-network


  • feature: dhcp_shared_network provider to define subnets inside a shared-network block
  • improve: allowing as blank as possible of a subnet block
  • improve: setting next-server in a subnet block
  • improve: allow dhcp_subnet range to be set with a String
  • improve: documentation
  • fix: including dhcp_host config files
  • fix: Chef 12 support
  • fix/improve: testing


  • feature: allow setting multiple ranges in subnets. The range param now HAS to be an array, existing cooks will not work.
  • improve: hostname in group configs is no long forced instead you can specify this in paramaters you pass.


  • fix: Debian system have Chef with version Chef: 11.10.0.rc.1 that Chef::Version doesn't detect correctly
  • fix: handle case where peer is unavailable on cluster start
  • improve: better chef-solo support
  • feature: Allow setting slaves and masters in attributes.
  • feature: Added ability to pass eval into subnets


  • support attribute driven mode, where no databags are needed to operate
  • feature: add evals to groups
  • fix error in subnet provider caused by mis-merged comma :(


  • change write_config to write_include, write_config doesn't work on ubuntu 12.04
  • allow you to set ddns-domainname for each subnet
  • convert "not if"'s to "unles"
  • Cleanup Readme for readability and attribution
  • update contributors


  • add tailor cane, kitchen testing
  • chef specs for chefspec 3.0
  • allow ddns update in subnet (pull request #13 from simonjohansson)
  • fixes for chef11 compatibility
  • fix version check in DSL condition
  • update service notifications to new format


  • Initial public release
  • Restructure entire cookbook for better reusability
  • Remove Internal/non-public dependencies
  • Fix: master/slave replication issues
  • Fix: LWRP notification method
  • Add minimal spec's for libraries
  • New: examples directory with databags and environments
  • New: configurable bag lookups for dhcp/dns bags
  • New: Group host list support
  • New: Defaults to mac address as hostname for non registered clients
  • New: Defines global defaults in default attributes

Collaborator Number Metric

6.1.0 passed this metric

Contributing File Metric

6.1.0 passed this metric

Foodcritic Metric

6.1.0 passed this metric

No Binaries Metric

6.1.0 passed this metric

Testing File Metric

6.1.0 passed this metric

Version Tag Metric

6.1.0 passed this metric