Manage the Open Source Chef Server

The open source Chef Server is a free version of the Chef Server that contains much of the same functionality as Hosted Chef, but requires that each instance be configured and managed locally, including performing data migrations, applying updates to the open source Chef Server, and ensuring that the open source Chef Server scales as the local infrastructure it is supporting grows. The open source Chef Server includes support from the Chef community, but does not include support directly from Opscode.

The Chef manager is a web-based interface that provides users of Chef a way to manage the following from the Chef Server:

• Nodes
• Cookbooks and recipes
• Roles
• Stores of JSON data (data bags), including encrypted data
• Environments
• Searching of indexed data on the Chef Server
• User accounts and user data for the individuals who have permission to log on to and access the Chef Server

Note

In order to set up and start the management console, use the bootstrap_server recipe with webui_enabled. The management console will be running on port 4040.

Manage API Clients

A chef-client is an agent that runs locally on every node that is registered with the Chef Server. When a chef-client is run, it will perform all of the steps that are required to bring the node into the expected state, including:

• Registering and authenticating the node with the Chef Server
• Building the node object
• Synchronizing cookbooks
• Compiling the resource collection by loading each of the required cookbooks, including recipes, attributes, and all other dependencies
• Taking the appropriate and required actions to configure the node
• Looking for exceptions and notifications, handling each as required

The Management Console allows users to create, read, edit, and delete API clients.

Add

To create a client:

1. Log on to the Management Console and click the Clients tab.
2. Click Create in the sub-navigation menu.

1. Enter a name, and select whether or not you want the new client to be an admin.

1. Click Create Client.

1. Save the private key somewhere safe.

Delete

To delete a client:

1. Log on to the Management Console and click the Clients tab.
2. Next to the name of the client you want to delete, click the Delete link.

Or, click on the name of the client and click Delete on the sub-navigation menu.

1. Click OK on the confirmation message box.

Edit

To edit a client:

1. Log on to the Management Console and click the Clients tab.
2. Next to the name of the client you want to edit, click the Edit link.

1. You are allowed to regenerate a private key or change its admin status. Click Save Client to save your change.

1. If you chose to regenerate the private key, copy and save it somewhere safe.

List

To view a list of clients:

1. Log on to the Management Console.
2. Click Clients.

View

To view a client:

1. Log on to the Management Console and click the Clients tab.
2. Click on the link of the name of the client you want to view.

View Public Key

To view the public key:

1. Log on to the Management Console and click the Clients tab.
2. Click on the link of the name of the client you want to view.

1. Click on the Show tab.

Manage Cookbooks

A cookbook is the fundamental unit of configuration and policy distribution in Chef. Each cookbook defines a scenario, such as everything needed to install and configure MySQL, and then it contains all of the components that are required to support that scenario, including:

• Attribute values that are set on nodes
• Definitions that allow the creation of reusable collections of resources
• File distributions
• Libraries that extend Chef and/or provide helpers to Ruby code
• Recipes that specify which resources to manage and the order in which those resources will be applied
• Custom resources and providers
• Templates
• Metadata about recipes (including dependencies), version constraints, supported platforms, and so on

The Management Console allows users to view and list cookbooks.

List

To list cookbooks:

1. Log on to the Management Console.
2. Click Cookbooks on the main navigation menu.

View

To view the contents of a specific cookbook:

1. Log on to the Management Console.
2. Click Cookbooks on the main navigation menu.
3. Click the link of the cookbook you want to view. This may take longer for very large cookbooks.

1. Click on Library Files, Attribute Files, Definition Files, Recipe Files, or Template Files to view the contents of the cookbook. If you do not see one of these links, the cookbook does not have files of that type.

Manage Data Bags

A data bag is a global variable that is stored as JSON data and is accessible from a Chef Server. A data bag is indexed for searching and can be loaded by a recipe or accessed during a search. The contents of a data bag can vary, but they often include sensitive information (such as database passwords).

The Management Console allows users to create, read, update, and delete data bags and data bag items.

Add

To create a data bag item in a specific data bag:

1. Repeat the 4 steps in the Viewing or Editing a Specific Data Bag section.
2. Click Create Item on the sub navigation bar. You will see a page with a JSON editor.
3. Click the Source tab in the JSON editor to edit the data bag item directly, or use the tree view on the left and the Editor tab to add and edit keys and values. You should not delete the “id” key.

Delete

To delete a data bag:

1. Log on to the Management Console.
2. Click Databags on the main navigation menu.
3. Click the Delete link next to the name of the data bag you want to delete, and click OK on the confirmation message box. Or, click the link of the data bag to view its details, and click Delete on the sub navigation menu.

Edit

To view or edit a specific data bag:

1. Log on to the Management Console.
2. Click Databags on the main navigation menu.
3. Click on the specific data bag you want to view or edit.
4. On the following page, you can create, edit, and delete items in the data bag. For details, refer to the sections below. .. image:: ../../images/step_manage_server_open_source_data_bag_view_1.jpg

Editor Tab

To edit a data bag using the JSON editor:

1. Expand the Data Attributes tree on the left, click id, and enter an value for the name of the data bag item, and then click Save Attribute.
2. Click json from the Data Attributes tree on the left, and click the Editor tab on the right, and then click the green add button under the Editor tab, enter a name as the key and a body as the value and click Add Attribute. The following figures show the Data Attribute tree and the JSON editor.

1. Click Create Databag Item to save the data bag item.

Source tab

To edit a data bag using JSON:

1. Enter the JSON body of your data bag item in the editor, and click the Load JSON from source button .
2. Click Create Databag Item button to save the data bag item. Here’s an example:

List

To list data bags:

1. Log on to the Management Console.
2. Click Databags on the main navigation menu.

View

To view or edit a specific data bag:

1. Log on to the Management Console.
2. Click Databags on the main navigation menu.
3. Click on the specific data bag you want to view or edit.
4. On the following page, you can create, edit, and delete items in the data bag. For details, refer to the sections below. .. image:: ../../images/step_manage_server_open_source_data_bag_view_1.jpg

Data Bag Items

A data bag is a container of related data bag items, where each individual data bag item is a JSON file. The only structural requirement of a data bag item is that it must have an id:

{
  "id": "ITEM_NAME"
  "key": "value"
}

where key and value are the key:value pair for each additional attribute within the data bag item. Knife can load a data bag item by specifying the name of the data bag to which the item belongs and then the filename of the data bag item.

Delete

To delete a data bag item in a specific data bag:

1. Repeat the 4 steps in the Viewing or Editing a Specific Data Bag section.
2. Click the Delete link next to the name of the data bag item you want to delete, and click OK on the confirmation message box. Or, click the link of the data bag item to view its details, and click Delete on the sub navigation menu.

Edit

To edit a data bag item in a specific data bag:

1. Repeat the 4 steps in the Viewing or Editing a Specific Data Bag section.
2. Click the Edit link next to the name of the data bag item you want to edit.
3. Follow step 3 in the Creating Data Bag Items section, except that in the last step click Edit Databag Item button instead of Create Databag Item button.

Manage Environments

An environment is a way to map an organization’s real-life workflow to what can be configured and managed when using Chef Server. Every Chef organization begins with a single environment called the _default environment, which cannot be modified (or deleted). Additional environments can be created, such as production, staging, testing, and development. Generally, an environment is also associated with one (or more) cookbook versions.

The Management Console allows users to create, read, update, delete environments, and to select a specific environment to view nodes and cookbooks in that environment.

Add

By clicking the Create tab under Environments, you are able to create a new environment. In the Create form you can specify a name (required), description, cookbook version constraints, and attributes.

Delete

An environment can be deleted by clicking the Delete link on the List page next to the name of the environment; or by clicking the Delete tab on the Show page when you view a specific environment.

List

The List page under Environments tab shows all existing environments. Clicking the link of the Environment name allows you to view the environment. You can also select the environment by clicking Select next to the name; doing so is equivalent to selecting an environment from the drop-down box on the top of the page.

Select

On the header of the Management Console, there is an Environment drop down box where you can select either “none” or a specific environment.

If “none” is selected, the Management Console shows everything when you view nodes and cookbooks; if a specific environment is selected, the Management Console only shows the available objects in that environment for nodes and cookbooks. For cookbooks, if you do not define any restriction in the environment, the Management Console shows all cookbooks.

When viewing a specific role, the per environment run list for the selected environment shows up; if none or _default is selected in the Environment drop down box, or there is no environment specific run list for the selected environment, the role page shows the _default run list.

Objects other than nodes, cookbooks, and roles are not affected by the environment selection.

View

Click the name of the environment on the List page under Environments allows you to view the environment. You are able to see the description, cookbook version constraints, and attributes defined in the environment you are viewing.

Manage Nodes

The Management Console allows users to create, read, update, and delete nodes.

Add

The node creation page lists all available recipes and roles, and allows you to include these in the run list of the node you are creating. There is also a JSON editor for editing, adding and removing the node’s attributes.

In order to create a node:

1. Login to the Management Console and navigate to the Nodes tab.
2. Click Create on the sub navigation bar.
3. Give the node a name.

1. Edit the node, as described in the next section. Continue with your normal edit steps and click Create Node to save the new node.

Delete

To delete a node:

1. Login to the Management Console and navigate to the Nodes tab.
2. Click the Delete link next to the name of the node you want to delete, and click OK on the confirmation message box. Or, click the link of the node to view its details, and click Delete on the sub navigation menu.

Note

You need delete permissions on the node to it. If you don’t have permission, you may not see a Delete link or tab.

Edit

In any of the following actions where a drag is involved, you must drag the item to the lighter grey area of the target list.

Editor Tab

Click the Editor tab on the right, click the green add button under the Editor tab, enter a name as the key and a body as the value and click Add Attribute. The following figure shows the Default and Override Attributes tree and the JSON editor.

Source Tab

Enter the JSON body in the editor, and click the Load JSON from source button. Click the Create Node or Save Node button to save the node. The following figure shows an example.

Edit Attributes

An attribute is a specific detail about a node. Attributes are used by Chef to understand:

• The current state of the node
• What the state of the node was at the end of the previous Chef run
• What the state of the node should be at the end of the current Chef run

Attributes are defined by:

• The state of the node itself
• Cookbooks (in attribute files and/or recipes)
• Roles
• Environments

During every Chef run, the chef-client builds the attribute list using:

• Data about the node collected by Ohai
• The node object that was saved to the Chef Server at the end of the previous Chef run
• The rebuilt node object from the current Chef run, after it is updated for changes to cookbooks (attribute files and/or recipes), roles, and/or environments, and updated for any changes to the state of the node itself

After the node object is rebuilt, all of attributes are compared, and then the node is updated based on attribute precedence. At the end of every Chef run, the node object that defines the current state of the node is uploaded to the Chef Server so that it can be indexed for search.

To modify the attributes of a node, such that they override the values of the included recipe or role, click json from the Default and Override Attributes tree on the bottom left.

Edit Run List

A run-list is an ordered list of roles and/or recipes that are run in an exact order. A run-list is always specific to the node on which it runs, though it is possible for many nodes to have run-lists that are similar or even identical. The items within a run-list are maintained using Knife and are uploaded to the Chef Server and stored as part of the node object for each node. Chef always configures a node in the exact order specified by its run-list and will never run the same recipe twice.

To edit a run-list:

1. To include a role in the run list of the node being edited, drag it from Available Roles to Run List.
2. To include a recipe in the run list of node being edited, drag it from Available Recipes to Run List.
3. To remove an included role or recipe from the node being edited, drag it from the “Run List” back to the respective Available section.
4. Click Save Node to save.

List

To list nodes:

1. Log on to the Management Console.
2. Click Nodes on the main navigation menu.

View

Viewing a node shows the recipes and roles in the node’s run list, as well as the node’s attributes. In order to view a specific node:

1. Login to the Management Console and navigate to the Nodes tab.
2. Click on the node you want to view.

On this page you can see the roles and recipes in the node’s run list, as well as an expandable tree view of the JSON attributes on the node.

Manage Roles

A role is a way to define certain patterns and processes that exist across nodes in a Chef organization as belonging to a single job function. Each role consists of zero (or more) attributes and a run list. Each node can have zero (or more) roles assigned to it. When a role is run against a node, the configuration details of that node are compared against the attributes of the role, and then the contents of that role’s run list are applied to the node’s configuration details. When a chef-client runs, it merges its own attributes and run lists with those contained within each assigned role.

The Management Console allows users to create, read, update, and delete roles.

Add

The role creation page allows you to add recipes and roles to the role you are editing. There is also a JSON editor for editing, adding and removing JSON attributes associated with the role. To create a role:

1. Login to the Management Console and navigate to the Roles tab.
2. Click Create on the sub navigation bar.
3. Give the role a name and an optional description.
4. Continue onto editing the role, as described in the next section. Continue with your normal edit steps and click Create Role to save the new role.

Delete

In order to delete a role:

1. Login to the Management Console and navigate to the Roles tab.
2. Click the Delete link next to the name of the role you want to delete, and click OK on the confirmation message box. Or, click the role to view its details, and click Delete on the sub navigation menu.

Edit

In any of the following actions where a drag is involved, you must drag the item to the lighter grey area of the target list.

1. To add a role to the role being edited, drag it from Available Roles to Run List.

1. To add a recipe to the role being edited, drag it from Available Recipes to Run List.

1. To remove a role or recipe from the role being edited, drag it from the Run List back to the respective Available section.
2. Click Save Role to save.

Editor Tab

You can edit the override attributes of a role, to override the values of an included recipe or role, and you can edit the default attributes of a role to specify attributes that do not exist in included recipes and roles. To do this, click json from the Default and Override Attributes tree on the bottom left. Then, click the Editor tab on the right, click the green add button under the Editor tab, enter a name as the key and a body as the value and click Add Attribute. The following figures show the Default and Override Attributes tree and the JSON editor.

Source Tab

To edit the JSON source for a role:

1. Enter the JSON body of your role in the editor, and click the Load JSON from source button.
2. Click the Create Role or Save Role button to save the role. The following figure shows an example.

List

To list roles:

1. Log on to the Management Console.
2. Click Roles on the main navigation menu.

View

Viewing a role shows the recipes and roles included in the role, as well as a tree view of the attributes associated with the role. In order to view a specific role, on the roles page, click the link of the specific role you want to view.

Manage Users

The Management Console runs on port 4040 by default. Navigate your browser to http://chef.example.com:4040/ (replacing chef.example.com with the actual hostname of your Chef server, of course). You’ll be redirected to the login screen.

Log In

When logging in for the first time, use the default credentials

Username	admin
Password	p@ssw0rd1

When you log in as the default admin user, you’re immediately redirected to the edit page for that user. After changing the default password, you can add add new users or use any other features of the Management Console.

Change the Default Password

Default passwords are no better than not having a password. They’re evil. They must die. Please change the default password and never use it again.

Use the Bootstrap Recipe

When using the bootstrap::server recipe, this is actually a randomly generated password, and set in /etc/chef/server.rb through the template, with the setting web_ui_admin_default_password. This can be set to a different value by setting webui_admin_password in the chef.json.

Manage User Accounts

Users are managed from the users tab:

Add

To create a new user, click Create on the Users page, then fill in the user’s name and password. Tick the box if the new user will be an administrator, then hit the Create button.

Delete

To delete a user, click the link for Delete next to the user’s name in the list. Chef will ask if you’re sure about deleting the user. Click OK to confirm.

Edit

To edit a user, click the Edit link next to the user’s name in the list. You’ll see the same edit form you saw when you first logged in as the “admin” user.

Search

Search indexes allow queries to be made for any type of data that is indexed by the Chef Server, including data bags (and data bag items), environments, nodes, and roles. Chef has a defined query syntax that supports search patterns like exact, wildcard, range, and fuzzy. A search is a full-text query that can be done from several locations, including from within a recipe, by using the search subcommand in Knife, by using the search functionality in the Management Console, or by using the /search or /search/INDEX endpoints in the Chef Server API. The search engine is based on Apache Solr and is run from the Chef Server.

You can view search indexes and search for nodes, API clients, roles, and data bags on the Management Console.

Search Queries

The query syntax described in the Search page also applies to the Management Console. The very basic syntax is attribute:value. If you do not enter anything in any search box, it searches for everything (*:*).

View Indexes

In order to view available search indexes, log on to the Management Console and click the Search tab. The search indexes should be listed. Nodes, roles, and clients are always available. Data bags are indexed by the data bag’s name.