|
This page describes how to use Chef to configure itself to either act as a Chef Server in your environment, or to configure clients to connect to a running Chef Server. If you are only using chef-solo, proceed to the Chef Solo page to learn more.
RubyGems InstallationsThe goal of these instructions is to configure a RubyGems installation of Chef consistently with Platform-Specific Package installations. We do this because RubyGems does not have any way to automatically handle several items that platform specific packages do easily.
Platform RequirementsThis procedure has been tested for setting up clients and servers on several platforms. ClientThese instructions have been tested on the following Client platforms. That is, the client was correctly configured to connect to a specified Chef Server.
ServerFor a fully automated setup, the server is a bit more limited in the platforms supported, mainly due to dependencies. Other platforms may work if you customize the cookbooks, but at that point you may be better off manually setting up the server.
Cookbook DifferencesOpscode provides two cookbooks to configure Chef. The chef cookbook is used for existing installations, while the topic of this page, bootstrap cookbook is used to get Chef installed using itself. ServerThe bootstrap::server recipe tries to manage external dependencies - CouchDB, RabbitMQ, Java, zlib, lib-xml; it also sets up runit_service. The authentication certificates are created when the chef-server starts. The chef::server recipe manages the template for /etc/chef/server.rb and restarts the server-related chef services. It also compacts the Chef CouchDB if the database is larger than 100Mb. ClientThe bootstrap::client recipe handles a runit_service for the chef-client if so designated with init_style attribute setting. The chef::client recipe does not set up a service but assumes this is already handled. It also uses a ruby_block resource to reload the configuration if the /etc/chef/client.rb template changes. To delete the validation certificate if it exists and the client.pem certificate exists, use the chef::delete_validation recipe. |
Bootstrap Introduction
"Configuring my chef server with chef - it doesn't get any more meta than this" - bbrowning
When we talk about "bootstrap" we're referring to the initial configuration of a Chef client or server, not the provisioning process of launching a new server or virtual machine. The configuration in this case is handled by Chef Solo, using a remote URL for the target cookbooks. These cookbooks are a special archive a few of Opscode's Cookbooks. The workhorse is bootstrap which is a derivative of the Opscode Chef Cookbook.
Typically, the Chef Server only needs to be set up once. We will cover that first. Then, you'll probably want to configure one or more clients to point to the server you just set up.
Here's some information about assumptions made with this process.
Default Init Scheme
We use runit as the init style because it is cross platform, reliable, and has other benefits. For the cookbook to work, runit needs to be available as a package named "runit" on your platform, and installable through the platform's default package provider (apt, yum, etc).
The default init scheme for the services can be changed with an attribute setting.
 | Runit Service Logs By default, Runit handles log output for services it manages by sending STDOUT and STDERR to /etc/sv/<service_name>/log/main/current. These logs are autorotated and truncated. See the runit home page for documentation. |
Fully Qualified Domain Names
Chef and the Opscode Cookbooks make heavy use of fully qualified domain names. In particular, for the Chef Server's hostname in URLs, and for clients' default node names when authenticating. You should verify that you have a fully qualified domain name set, even if it is "hostname".localdomain. You can check if an FQDN is set with the hostname command.
Default Paths
The default paths used by the cookbook match the settings in the Chef Repository, and the Opscode Chef Cookbook. The location can be changed, see below.
Chef Solo Configuration
We'll need to configure Chef Solo on where to store and look for the cookbooks, as the archive of cookbooks at the remote URL will be downloaded and extracted locally. On both Chef Servers and Chef Clients, you'll need the following configuration file, save it as ~/solo.rb. The option recipe_url can also be specified on the chef-solo commandline with -r.
JSON Configuration
We're going to pass some information about the node to chef-solo with a JSON attribute file. Attributes in the bootstrap cookbook recipes are namespaced under bootstrap[:chef], so e.g., "node[:bootstrap][:chef][:umask]" in a recipe. Example JSON, which will be edited per the Server and Client sections below.
umask
Sets the umask for files created by the server process.
url_type
Set up the URLs the client should connect to with this. Default is 'http', which tells the client to connect to 'http://server:4000'. If you want to set up your chef-server to use an SSL front-end, set this to 'https' and the URLs will be 'https://server/'. The bootstrap::server recipe does not support an SSL front-end configuration, see chef::server_proxy for an example.
init_style
Specifies the init style to use. Default 'runit'. Other possible values 'init', 'bsd', any other string will be treated as unknown.
If your platform doesn't have a 'runit' package or if the cookbook doesn't detect it, but you stil want to use runit, set init_style to 'none' and install runit separately.
path
This is the base location where chef will store its associated data. Default '/srv/chef' for RubyGems installed systems. The location preference varies by platform. The default is a filesystem hiearchy standard suggestion. Some other locations you may consider, by platform:
Debian and Red Hat based Linux distros (Ubuntu, CentOS, Fedora, etc):
- /var/lib/chef
Any BSD and Gentoo:
- /var/chef
run_path
Location for pidfiles on systems using init scripts. Runit tracks the pidfile and does not use this setting. Default '/var/run/chef'.
If init_style is 'init', this is used, and should match what the init script itself uses for the PID files.
cache_path
Location where the client will cache cookbooks and other data. Default is 'cache' underneath the bootstrap[:chef][:path] location. Some Linux distributions might prefer /var/cache/chef instead.
serve_path
Used by the Chef server as the base location to "serve" cookbooks, roles and other assets. Default is /srv/chef.
server_port
Port for the chef-server API process. Default is 4000.
webui_port
Port for the chef-server-webui process. Default is 4040.
webui_enabled
Whether the web user interface should be installed and enabled. Default is 'false'. In Chef versions prior to 0.8 the webui provided the API, but 0.8 split them apart so now the webui is optional.
webui_admin_password
Set a random, secure default password for the webui user. See /etc/chef/server.rb when the chef-solo run completes for the value of web_ui_admin_default_password to log into the webui. This password is generated with the openssl cookbook, though can be set with JSON.
server_version, client_version
Set the version of the Gems to install. This can be used to upgrade Chef automatically. The chef gems are not managed by the Opscode Chef cookbook, however.
client_interval
Number of seconds to run chef-client periodically. Default '1800' (30 minutes).
client_splay
Splay interval to randomly add to interval. Default '20'.
log_dir
Directory where logs are stored if logs are not sent to STDOUT. Systems using runit should send logs to STDOUT as runit manages log output. Default '/var/log/chef'. Runit's logs are in /etc/sv/SERVICE_NAME/log/main/current, where SERVICE_NAME is the name of the service, e.g., 'chef-client', 'chef-server', 'chef-solr' etc. See the recipes for the runit_services that get set up.
client_log, indexer_log, server_log
Location of the client, indexer and server logs, respectively. Default 'STDOUT' on systems with runit, '/var/log/chef/{client,indexer,server}.log' on other systems.
server_fqdn
Fully qualified domain name of the server. Default is the current node's fqdn as detected by Ohai. For clients, set this to the hostname of your environment's Chef Server.
server_token
The validation_token used to automatically authorize chef-clients. Default is a random string generated every time chef-solo runs. Use chef-client -t 'validation_token' to automatically validate the client.
Bootstrap Chef Server
This procedure will set up the chef-server to run the chef-server-api Merb slice on port 4000 using the thin adapter, and optionally the chef-server-webui on port 4040. SSL encryption can be provided by proxying with Apache.
In earlier versions of Chef, the webui provided the API. One of the major features of 0.8.x is that it is separate. Read more about [New Features in Chef 0.8.x].
Create JSON Data
As mentioned above, we'll configure how the bootstrap should behave with a JSON attribute file.
The webui is now separate from the API, so it is now optional. Setting the attribute webui_enabled to true will install and configure it.
Change server_fqdn to the desired fully-qualified domain name of the server.
Other configurable attributes of interest are listed in the bootstrap README.
Run chef-solo
Now that we told it how to behave, run chef-solo, and tell it to fetch a remote tarball of cookbooks from a URL in Amazon's S3, this retrieves the cookbooks via the recipe_url setting in the solo.rb config file from above. You can override this with a different URL with -r http://something.example.com/bootstrap.tar.gz.
To bootstrap with the current release, make sure the [gem is installed], and use:
This command will bring up the Chef Server environment, by doing the following:
- Bootstrap the system as a Client (see section below for what this entails).
- Install RabbitMQ if possible (see below).
- Install CouchDB if possible (see below).
- Install development libraries zlib and xml, for chef-solr.
- Install the chef-server, chef-server-api, chef-solr gems.
- Optionally (if webui_enabled) install chef-server-webui gem.
- Create the server configuration file, /etc/chef/server.rb.
- Create some directories the server needs.
- If init_style is "runit", set up chef-solr-indexer, chef-solr, chef-server (API) as runit services. If webui_enabled, it chef-server-webui will be added as a runit service as well. If "init", display a message where init scripts can be found. If "bsd", display a hint about startup commands. Otherwise, display a message about manual setup.
The services configured here will be running:
| Service | Port |
|---|---|
| chef-server-api | 4000 |
| chef-server-webui | 4040 |
| couchdb | 5984 |
| rabbitmq | 5672,4369,47762 |
| chef-solr | 8983 |
CouchDB
The chef-server itself requires CouchDB to store node data. Ubuntu (8.10 - 9.04) and Debian 5.0.x have CouchDB available as a native package. Red Hat / CentOS 5 and Fedora have CouchDB available in the EPEL repository. Other platforms may not have a CouchDB package available and the bootstrap recipes should print out a message that CouchDB needs to be installed manually.
 | CouchDB 0.9.1+ Required As of Chef version 0.8.x+, CouchDB 0.8.0 is no longer supported. See the breaking changes page for more information. |
Java
Java is required for SOLR, the search engine in Chef 0.8.0. Similar to CouchDB, it's best if the platform you're using has a Java package available natively. The java cookbook will attempt to install sun-java6-jdk on Ubuntu and Debian, and java-1.6.0-openjdk on Red Hat, CentOS and Fedora. It will print a message if the platform isn't known to have a package. You'll need to make sure Java is installed and working for SOLR if you're using another platform.
RabbitMQ
RabbitMQ is installed via the rabbitmq-server package where available, and a message is printed if the platform isn't known to have the package available.
Next Steps
Verify you can log into the Chef Server webui. Then you'll probably want to set about bootstrapping clients; see the next section. Or, start setting up a Chef Repository to store your configuration. Since this section set up the server as a client to itself, you can test that it works with chef-client.
Configure Knife for API Access
In order to get working with your new Chef Server, you'll need to configure the command-line API tool, Knife.
You can now use knife to work with the server. See the Knife documentation for more information on usage.
Log into the WebUI
If you enabled the webui, it will be running on port 4040. The password is randomly generated by the bootstrap recipe. To retrieve it for login, see /etc/chef/server.rb for the web_ui_admin_default_password value, and login as the admin user. From there you can associate an OpenID for login as admin, change the default password, and add more users.
Read more about managing WebUI Users.
For RHEL/CentOS Systems
Some manual steps are required. See the end of the Preparing Red Hat and CentOS 5 for RubyGems#Post Bootstrap Steps page for instructions.
Bootstrap Chef Clients
This procedure will set up a client-client to connect to the Chef Server configured in the previous section.
Create JSON Data
As before, we'll set up the client based on the JSON attributes.
Make sure the server_fqdn matches what was used above. If your server's hostname is "chef", you can omit that attribute. Note the recipe is client here, not server.
You can add or change other attributes as listed in the bootstrap README, if required for your environment.
Run chef-solo
The chef-solo command is the same as for the server.
To bootstrap with the current release, make sure the [gem is installed], and use:
The Chef Client will be configured for the following:
- If init_style is "runit", set up chef-client as a runit service. If "init", create the pidfile directory (run_path) and display a message where init scripts can be found. If "bsd", display a hint about startup commands. Otherwise, display a message about manual setup.
- Creates some directories that Chef needs.
- Creates the client configuration file, /etc/chef/client.rb, with server URLs based on url_type.
Validate Chef Clients
The new client needs to register with the server. The validation certificate generated by the chef-server startup is used. Copy it to /etc/chef/validation.pem, and the next time chef-client runs, it will be registered and generate /etc/chef/client.pem which is used for authentication and signing all transactions. You will want to delete the validation.pem from client nodes once they are registered. You can use the Opscode Chef cookbook's delete_validation recipe to do this.
See Nodes for more information.
Next Steps
After running the chef-solo commands above, your Chef Server and Chef Clients will be ready to go.
We recommend building yourself a new Chef Repository.
