The Bootstrap subcommand for Knife performs a Chef Bootstrap on the target node.

The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server (or Hosted Chef).

The main assumption is a baseline OS installation exists. This sub-command is used internally by some cloud computing server create commands and the others will be migrated in a future version of Chef. It is primarily intended for Chef Client systems that talk to a Chef server.

Man Page in Chef 0.10+ Additional knife-bootstrap detail is available on your local system as a man page. Type knife help bootstrap to view it.

As of Chef 0.9.8, the bootstrap sub-command supports supplying a template to perform the bootstrap steps. If the distro is not specified (via -d or --distro option), an Ubuntu 10.04 with RubyGems is assumed. The DISTRO value corresponds to the base filename of the template, in other words DISTRO.erb. A template file can be specified with the --template-file option in which case the DISTRO is not used. The sub-command looks in the following locations for the template to use:

• bootstrap directory in the installed Chef Knife library (Location varies depending how you installed Chef).
• bootstrap directory in the $PWD/.chef, e.g. in ~/chef-repo/.chef.
• bootstrap directory in the users $HOME/.chef.

Additional Options

• -i, --identity-file IDENTITY_FILE:
  The SSH identity file used for authentication
• -N, --node-name NAME:
  The Chef node name for your new node
• -P, --ssh-password PASSWORD:
  The ssh password
• -x, --ssh-user USERNAME:
  The ssh username
• -p, --ssh-port PORT:
  The ssh port
• --bootstrap-version VERSION:
  The version of Chef to install
• --bootstrap-proxy PROXY_URL:
  The proxy server for the node being bootstrapped
• --prerelease:
  Install pre-release Chef gems
• -r, --run-list RUN_LIST:
  Comma separated list of roles/recipes to apply
• --template-file TEMPLATE:
  Full path to location of template to use
• --sudo:
  Execute the bootstrap via sudo
• -d, --distro DISTRO:
  Bootstrap a distro using a template
• --no-host-key-verify:
  Disable host key verification

Supported Distros

The default bootstrap templates are scripts that get copied to the target node (FQDN). As of Chef 0.9.8, the following distros are supported:

• centos5-gems
• fedora13-gems
• ubuntu10.04-gems
• ubuntu10.04-apt

Authentication

Knife bootstrap communicates with the target node over SSH. We recommend using key-based authentication. You can pass the path to the private key used to authenticate to the node using the -i command line option or use a program such as ssh-agent to manage your keys automatically. knife bootstrap also supports password-based authentication. You can use the -P option to pass the password directly on the command line or, with Chef 0.10.6+, allow knife bootstrap to prompt you for a password.

Examples

Here are two example bootstrap commands, using different types of authentication. In this example we pass it the SSH password as part of the command:

And in this example, we use a private key file:

Afterwards you'll be prompted for your sudo password on the node you are SSHing into. You will want to change IP_ADDRESS to the ip or hostname you are trying to bootstrap, and this assumes you want to login with the username 'ubuntu'.

Known Authentication Bug

If you have not customized your ssh configuration, you will most likely not be affected by this bug.

Knife uses the net-ssh gem to create ssh connections to your nodes. Currently, net-ssh processes your ssh configuration files (e.g. ~/.ssh/config) differently than your system's ssh client. One difference is that if you explicitly set various authentication methods to "yes", then all authentications not explicitly set to "yes" will be excluded. For example, if you set the following in your configuration file:

Other methods of authentication, such as key based authentication, will not be attempted. You can fix this either by removing the explicit authentication directive in your configuration file, or by ensuring that all methods you want to use are set to "yes", even if "yes" is typically their default value on your system. To explicitly allow key-based authentication, use the following setting

For more information about this bug see CHEF-2783.

Creating Custom Bootstrap Templates

Custom bootstrap templates can be created and stored in .chef/bootstrap/DISTRO.erb, replacing DISTRO with the value passed with the -d or --distro option. Custom Knife Bootstrap Script has a couple of examples on the creation of a custom bootstrap template..

Installs RubyGems and Chef as a gem

The gems installations will use RubyGems 1.3.6 and Chef installed as a gem. A future release will install RubyGems 1.3.7, though you can customize this yourself by copying the template to one of the locations specified above. The apt installation will use the Opscode APT repository.

Writes Config Files

In addition to handling the software installation, these bootstrap templates do the following:

• Write the validation.pem per the local knife configuration.
• Write a default config file for Chef (/etc/chef/client.rb) using values from the knife.rb.
• Create a JSON attributes file containing the specified run list and run Chef.

In the case of the RubyGems, the client.rb will be written from scratch with a minimal set of values, and you may want to customize it. In the case of APT Package installation, client.rb will have the validation_client_name appended if it is not set to chef-validator (default config value), and the node_name will be added if chef_node_name option is specified.

Using encrypted data bags

As of 0.10.6, knife bootstrap supports the 'encrypted_data_bag_secret' setting in knife.rb. You will want to add this line to your knife.rb:

And change '/path/to/your/data_bag_key' to the location of where the data bag key is located. When you run knife bootstrap afterwards it automatically adds this line to the client.rb for the node you are bootstrapping and copies the key over.

Completed State

When this is complete, the bootstrapped node will have:

• Latest Chef version installed from RubyGems or APT Packages from Opscode. This may be a later version than the local system.
• Be validated with the configured Chef Server.
• Have run Chef with its default run list if one is specified.

If The Run Does Not Complete

The run list for the first run of a newly provisioned node is passed in by knife as a file with the special command line:

At the end of the first run, the node object is saved with this list, shows up on the console and knife commands, and is used on subsequent chef-client runs. If the run does not complete, (the instance is created but the installs are not completed), then the node with the run list applied to it is never saved.

Run the above command if this occurs. The normal state is for the first chef-client run to complete - an incomplete run is the sort of thing that will happen while debugging changes and new recipes. A typical cause is an unmet dependency in cookbooks. Review the metadata.rb files of the cookbooks in your base role, or any other roles being established in the initial run for any dependencies.

Knife Built In Subcommands

Custom Knife Bootstrap Script