knife bootstrap

A bootstrap is a process that installs Chef on a target system so that it can run as a chef-client and communicate with a Chef Server.

The bootstrap subcommand is used run a bootstrap operation that installs Chef on the target system. The bootstrap operation must specify the IP address or FQDN of the target system.

Syntax

This argument has the following syntax:

$ knife bootstrap FQDN_or_IP_ADDRESS (options)

Options

Note

Review the list of common options available to this (and all) Knife subcommands and plugins.

This subcommand has the following options:

--bootstrap-proxy PROXY_URL

The proxy server for the node that is the target of a bootstrap operation.

--bootstrap-version VERSION

The version of Chef to install.

-d DISTRO, --distro DISTRO

The template file to be used during a bootstrap operation. Use this option if the specific location of the template file is unknown. The following distributions are supported: chef-full (the default bootstrap), centos5-gems, fedora13-gems, ubuntu10.04-gems, ubuntu10.04-apt, and ubuntu12.04-gems. If this option is used, Knife will search for the template file in the following order: a bootstrap/ folder in the current working directory, a bootstrap/ folder in the Chef repository, a bootstrap/ folder in ~/.chef/, or a bootstrap file shipped with Chef. Do not use the --template-file option when --distro is specified.

-G GATEWAY, --ssh-gateway GATEWAY

The SSH tunnel or gateway that is used to run a bootstrap action on a machine that is not accessible from the workstation.

--hint HINT_NAME[=HINT_FILE]

Indicates that an Ohai hint will be set on the target of the bootstrap. Use multiple --hint options to specify multiple hints.

-i IDENTITY_FILE, --identity-file IDENTITY_FILE

The SSH identity file used for authentication. Key-based authentication is recommended.

-j JSON_ATTRIBS, --json-attributes JSON_ATTRIBS

A JSON string that is added to the first run of a chef-client.

-N NAME, --node-name NAME

The name of the node.

--[no-]host-key-verify

Use --no-host-key-verify to disable host key verification. Default setting: --host-key-verify.

-p PORT, --ssh-port PORT

The SSH port.

-P PASSWORD, --ssh-password PASSWORD

The SSH password. This can be used to pass the password directly on the command line. If this option is not specified (and a password is required) Knife will prompt for the password.

--prerelease

Indicates that pre-release Chef gems should be installed.

-r RUN_LIST, --run-list RUN_LIST

A comma-separated list of roles and/or recipes to be applied.

--sudo

Indicates that a bootstrap operation should be executed using sudo.

--template-file TEMPLATE

The path to a template file that will be used during a bootstrap operation. Do not use the --distro option when --template-file is specified.

-x USERNAME, --ssh-user USERNAME

The SSH user name.

knife.rb Settings

Note

See knife.rb for more information about how to add optional settings to the knife.rb file.

The following knife bootstrap settings can be added to the knife.rb file:

knife[:bootstrap_proxy]

Use to add the --bootstrap-proxy option.

knife[:bootstrap_version]

Use to add the --bootstrap-version option.

knife[:distro]

Use to add the --distro option.

knife[:run_list]

Use to add the --run-list option.

knife[:template_file]

Use to add the --template-file option.

knife[:use_sudo]

Use to add the --sudo option.

Note

The knife bootstrap subcommand relies on a number of SSH-related settings that are handled by the knife ssh subcommand.

Examples

To pass an SSH password as part of the command:

$ knife bootstrap 192.168.1.1 -x username -P PASSWORD --sudo

To use a file that contains a private key:

$ knife bootstrap 192.168.1.1 -x username -i ~/.ssh/id_rsa --sudo

The following examples show how to customize the default bootstraps that are included with Chef.

Ubuntu 12.04

The following example shows how to modify the default script for Ubuntu 12.04. First, copy the bootstrap template from the default location. If Chef is installed from a RubyGems, the full path can be found in the gem contents:

% gem contents chef | grep ubuntu12.04-gems
/Users/jtimberman/.rvm/gems/ruby-1.9.2-p180/gems/chef-0.10.2/lib/chef/knife/bootstrap/ubuntu12.04-gems.erb

Copy the template to the Chef repository in the .chef/bootstrap directory:

% cp /Users/jtimberman/.rvm/gems/ruby-1.9.2-p180/gems/chef-0.10.2/
   lib/chef/knife/bootstrap/ubuntu12.04-gems.erb ~/chef-repo/.chef/
   bootstrap/ubuntu12.04-gems-mine.erb

Modify the template with any editor, then use it with the -d or --distro option in the knife bootstrap operation, or use any of the Knife plug-ins that support cloud computing.

$ knife bootstrap 192.168.1.100 -r 'role[webserver]' -d ubuntu12.04-gems-mine

Alternatively, an example bootstrap template can be found in the Chef source repository: https://github.com/opscode/chef/blob/master/lib/chef/knife/bootstrap/ubuntu12.04-gems.erb. Copy the template to ~/.chef-repo/.chef/bootstrap/ubuntu12.04-apt.erb and modify the template appropriately.

Debian and Apt

The following example shows how to use the knife bootstrap sub-command to create a client configuration file (/etc/chef/client.rb) that uses Hosted Chef as the Chef Server. The configuration file will look something like:

log_level        :info
log_location     STDOUT
chef_server_url  'https://api.opscode.com/organizations/ORGNAME'
validation_client_name 'ORGNAME-validator'

The knife bootstrap sub-command will look in three locations for the template that is used during the bootstrap operation. The locations are:

1. A bootstrap directory in the installed Knife library; the actual location may vary, depending how Chef is installed
2. A bootstrap directory in the $PWD/.chef, e.g. in ~/chef-repo/.chef
3. A bootstrap directory in the users $HOME/.chef

If, in the example above, the second location was used, then create the .chef/bootstrap/ directory in the Chef repository, and then create the erb template file by running commands similar to the following:

mkdir ~/.chef/bootstrap
vi ~/.chef/bootstrap/debian5.0-apt.erb

When finished creating the directory and the erb template file, edit the template to run the SSH commands. Then set up the validation certificate and the client configuration file.

Finally, run the chef-client on using a knife bootstrap command that specifies a run-list (the -r option). The bootstrap template can be called using a command similar to the following:

$ knife bootstrap mynode.example.com -r 'role[webserver]','role[production]' --distro debian5.0-apt