Chef 11 Server: Up and Running

In this post, we’re going to look at how easy it is to get up and running with a Chef Server on a brand new Ubuntu 12.04 or CentOS 6.3 system. We’ll also explore the new Chef Server management tool, chef-server-ctl, and the new configuration file.

Requirement: You should have a fully-qualified domain name set up for your Chef Server in DNS. This is outside the scope of this post, as we don’t know what your DNS setup looks like.

Installation and Startup

To get a link to the package to download, navigate to the Chef install page to get the package download URL. Use the form on the “Chef Server” tab to select the appropriate drop-down items for your system.

Install the package from the given URL. On Ubuntu, retrieve the DEB with wget and use dpkg to install it:

wget -O chef-server-11.deb
sudo dpkg -i chef-server-11.deb

On CentOS, use RPM directly.

sudo rpm -Uvh

The package just puts the bits on disk (in /opt/chef-server). The next step is to configure the Chef Server and start it.

sudo chef-server-ctl reconfigure

This runs the embedded chef-solo with the included cookbooks, and sets up everything required – Erchef, RabbitMQ, PostgreSQL, etc.

Optionally, run the Opscode Pedant test suite. This will verify that everything is working.

sudo chef-server-ctl test

Set Up an Admin User

Copy the default admin user’s key and the validator key to your local workstation system that you have Chef client installed on, and create a new user for yourself with knife. You’ll need version 11.2.0+. The key files on the Chef Server are readable only by root. For example:

mkdir ~/.chef
scp root@chef-server:/etc/chef-server/admin.pem ~/.chef
scp root@chef-server:/etc/chef-server/chef-validator.pem ~/.chef

Use knife configure -i to create an initial ~/.chef/knife.rb and new administrative API user for yourself. Use the FQDN of your newly installed Chef Server, with HTTPS. The validation key needs to be copied over from the Chef Server from /etc/chef-server/chef-validator.pem to ~/.chef to use it for automatically bootstrapping nodes with knife bootstrap.

% knife configure -i
WARNING: No knife configuration file found
Where should I put the config file? [/home/jtimberman/.chef/knife.rb]
Please enter the chef server URL: []
Please enter a name for the new user: [jtimberman]
Please enter the existing admin name: [admin]
Please enter the location of the existing admin's private key: [/etc/chef/admin.pem] .chef/admin.pem
Please enter the validation clientname: [chef-validator]
Please enter the location of the validation key: [/etc/chef/validation.pem] .chef/chef-validator.pem
Please enter the path to a chef repository (or leave blank):
Creating initial API user...
Please enter a password for the new user:
Created user[jtimberman]
Configuration file written to /home/jtimberman/.chef/knife.rb

The .chef/knife.rb file should look something like this:

log_level :info
log_location STDOUT
node_name 'jtimberman'
client_key '/home/jtimberman/.chef/jtimberman.pem'
validation_client_name 'chef-validator'
validation_key '/home/jtimberman/.chef/chef-validator.pem'
chef_server_url ''
syntax_check_cache_path '/home/jtimberman/.chef/syntax_check_cache'

Note that the cookbook_path is not set (we left the path to the chef repository blank), so you’ll need to set that up for wherever you’re storing your local cookbooks.

Your Chef Server is now ready to use. Test connectivity as your user with knife:

% knife client list

% knife user list

In previous versions of Open Source Chef Server, users were API clients. In Chef 11, users are separate entities on the Server to be consistent with Enterprise Chef.


The chef-server-ctl command is used on the Chef Server system for management. It has built-in help (-h) that will display the various sub-commands. We’ve already talked about the reconfigure and test commands. Let’s look at some others.

Obtain a list of all the running services of the Chef Server:

sudo chef-server-ctl service-list

These services are all managed by an embedded runit installation. Show their status:

sudo chef-server-ctl status

Other commands related to managing the services with runit are graceful-killhupintkilloncestartstop,term.

The service logs can be tailed with the tail sub-command. It can also be passed a service name to only tail that service’s logs.

sudo chef-server-ctl tail
sudo chef-server-ctl tail erchef

We use reconfigure to configure the Chef Server after installation, and after modifying the config file (see below). Once it has been reconfigured, we can view its configuration with show-config.

sudo chef-server-ctl show-config

Filesystem Locations

We’ve attempted to contain the Chef Server installation as much aspossible without littering files across the filesystem. Following FHS recommendations, we use the following filesystem locations for the Chef Server:

  • /opt/chef-server – The installation from the package is here.
  • /etc/chef-server – The API specific configuration files and keys are here.
  • /var/opt/chef-server – The dependent services such as RabbitMQ, Nginx and so on are here, including the PostgreSQL database, SOLR indexes.
  • /var/log/chef-server – All the runit services write their output here.

The design of the system is such that this is self contained and maintained using the chef-server-ctl program, rather than modifying the underlying components themselves.

Chef Server Configuration

The main configuration file for the Chef Server in Chef 11 is /etc/chef-server/chef-server.rb. It uses a Ruby DSL similar to other Chef configuration files, /etc/chef/client.rb~/.chef/knife.rb, etc. We’re working on getting all the various settings documented. For now, they’re all defined as attributes in the cookbook used by chef-server-ctl reconfigure. An example will illustrate this.

In the attributes file, we control whether the WebUI is enabled:

default['chef_server']['chef-server-webui']['enable'] = true

To modify this in /etc/chef-server/chef-server.rb, for example to disable it:

chef_server_webui['enable'] = false

Note Attributes that have a dash should have it replaced with an underscore in the chef-server.rb config file.

After making any changes to /etc/chef-server/chef-server.rb, reconfigure the Chef Server.

sudo chef-server-ctl reconfigure

Upon examination of the attributes, one might posit that the Chef Server’s various services can be run on separate systems with different configurations. Also, additional performance tuning can be done. As mentioned before, we’re working on getting all these settings documented, so stay tuned.

Posted in:

Joshua Timberman

Joshua Timberman is a Code Cleric at CHEF, where he Cures Technical Debt Wounds for 1d8+5 lines of code, casts Protection from Yaks, and otherwise helps continuously improve internal technical process.