Servers/Chef

Introduction

All chef configuration is managed via a git repository on horntail. The configuration can be obtained by cloning from here:

 ssh://horntail.openstreetmap.org/home/chef

Pushing configuration changes back will cause them be deployed automatically.

Each node will enforce the current configuration every half hour - if you want to force it to happen more quickly then you need to restart the chef-client service on the node.

Roles

Roles are defined by ruby files in the roles directory and can be applied to nodes via the web interface at https://chef.openstreetmap.org/ but our policy is to define a single role for each node which is applied when the node is first setup and to apply any further roles by editing the node's master role so that all changes are tracked in git.

Role files can setup attribute values and list other roles and recipes which should be applied.

Recipes

Recipes are the core of the system and define what tasks should be performed. They are defined by ruby files in the recipes directory of a cookbook and can decide exactly what to do based on the current configuration of the node and the value of any attributes applied to the node.

The code in a recipe can include more or less arbitrary ruby code and will run on the target node at the time that the configuration is being applied.

Attributes

Attributes are parameters - they can be simple ruby constants or complex data structures using ruby arrays and hashes.

Default attribute values can be defined using ruby files in the attributes directory of a cookbook and these can be supplemented in a role definition to allow different nodes to vary their configuration.

In addition a number of attribute values are provided automatically based on the configuration of the target node.

Templates

Templates are found in the templates directory of a cookbook and are erb files which a recipe will expand using the template resource to create node specific files on a target system.

Cookbooks

Cookbooks can be found in the cookbooks directory and are used to collect together recipes, default attribute values, templates and files.

Roles

Base

The base role is applied to all nodes (indirectly, via a location role) and ensures that a standard base configuration is applied to all machines.

Location Based

Each machine has a single location role applied based on its physical location. This in turn may include other locations roles covering larger areas. Current location roles are:

gb

Applied (indirectly) to all nodes located in the UK. Includes the base role.

ucl

Applied (indirectly) to all nodes located at UCL. Includes the gb role.

ucl-internal

Applied to all nodes at UCL which are on the internal network. Includes the ucl role.

ucl-external

Applied to all nodes at UCL which are only on the external network. Includes the ucl role.

ic

Applied to all nodes located at Imperial. Includes the gb role.

bytemark

Applied to all nodes located at Bytemark. Includes the gb role.

Service Based

There are a number of roles covering particular services which can be added to the node(s) which need to run those services.

Per Host

Each host is defined by a role with the same name as the machine. This role will include an appropriate location role and whatever other roles are needed to cover the services running on he machine

Cookbooks

This is a list of cookbooks currently in use. Unless otherwise specified each cookbook contains just a single, default, recipe.

accounts

Creates and configures user accounts. This recipe is applied to all nodes via the base role.

apache

Installs and configures an apache server and provides tools to help other cookbooks install and configure apache modules and virtual hosts. This cookbook has two recipes:

apache::default

The default recipe, applied to all apache servers.

apache::ssl

The ssl recipe, applied to any apache server needing SSL support.

apt

Installs and configures apt, making sure that the chosen package sources are available. This recipe is applied to all nodes via the base role.

cgiirc

Installs and configures the CGI::IRC web based IRC client.

clamav

Installs and configures the clamav virus scanner.

dev

Configures per-user web sites for the dev server.

exim

Installs and configures mail service using exim. This recipe is applied to all nodes via the base role.

git

Installs git and configures a git server with gitweb support.

mailman

Installs and configures the mailman mailing list manager.

mediawiki

Installs and configures mediawiki (doesn't actually do much yet).

munin

Installs and configures munin monitoring with common plugins and provides tools to allow other cookbooks to configure munin plugins. This cookbook has two recipes:

munin::default

The default recipe, applied to all nodes via the base role.

munin::server

The server recipe, applied to any munin servers.

networking

Configures networking. This recipe is applied to all nodes via the base role.

nfs

Installs and configures NFS clients and servers. This cookbook has two recipes:

nfs::default

The default recipe, applied to NFS clients.

nfs::server

Applied to NFS servers.

ntp

Installs and configures ntpd for time synchronisation. This recipe is applied to all nodes via the base role.

openssh

Installs and configures the ssh client and server, complete with a known_hosts file listing the ssh host keys for each machine. This recipe is applied to all nodes via the base role.

osqa

Installs and configures question and answer sites using the OSQA package.

spamassassin

Installs and configures the spamassassin spam scanner.

ssl

Installs the SSL certificate for use by other cookbooks.

sysctl

Configures kernel parameters using sysctl. This recipe is applied to all nodes via the base role.

tools

Install common tools. This recipe is applied to all nodes via the base role.

web

Installs and configures services for the web frontend and backend machines. This cookbook has three recipes:

web::rails

Installs and configures the rails code.

web::backend

Configures a backend server. Includes the web::rails recipe.

web::frontend

Configures a frontend server. Includes the web::rails recipe.

Common Tasks

Adding a User

If this is a completely new user then the first thing to do is to add their details to the end of cookbooks/accounts/attributes/default.rb taking care to allocate a new uid that is different to the existing ones. The relevant stanza would look something like:

 default[:accounts][:users][:example][:uid] = 1111
 default[:accounts][:users][:example][:comment] = "John Example"
 default[:accounts][:users][:example][:email] = "john@example.com"

Adding a user to a particular node or nodes can be done by settings the user's status using the attributes in an appropriate role definition along these lines

 default_attributes(
   :accounts => {
     :users => {
        :example => { :status => :user }
     }
   }
 )

The status should be either :user or :administrator depending on what role the user will be fulfilling.

Changing a Kernel Parameter

A kernel (sysctl) parameter can be set using the sysctl attributes in an appropriate role with an stanza along these lines:

 default_attributes(
   :sysctl => {
     :group => {
       :comment => "Increase shared memory for postgres",
       :parameters => { 
         "parameter.name.1" => "parameter.value.1",
         "parameter.name.2" => "parameter.value.2"
       }
     }
   }
 )

The group is an arbitrary name - all values in the same group will be collected together in the sysctl.conf file with the specified comment above.

Adding an APT Source

To add a completely new APT source first add the source details to the recipe in cookbooks/apt/recipes/default.rb along these lines

 apt_source "example" do
   url "http://apt.example.com/apt"
   key "1234abcd"
 end

The source can then be activated on specific nodes by adding the source to the appropriate attribute in the relevant role:

 default_attributes(
   :apt => {
     :sources => [ "example" ]
   }
 )

Attributes are deep merged, so source lists can be added in multiple roles and will all be merged together when they are applied to a node.