knife bootstrap — chef-client Man Pages

# knife bootstrap

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

The knife bootstrap subcommand is used to run a bootstrap operation that installs the chef-client on the target system. The bootstrap operation must specify the IP address or FQDN of the target system.

Note

To bootstrap the chef-client on Microsoft Windows machines, the knife-windows plugins is required, which includes the necessary bootstrap scripts that are used to do the actual installation.

## Syntax

This subcommand 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:

`-A`, `--forward-agent`
  Use to enable SSH agent forwarding.
`--bootstrap-curl-options OPTIONS`
  Use to specify arbitrary options to be added to the bootstrap command when using cURL. This option may not be used in the same command with `--bootstrap-install-command`.
`--bootstrap-install-command COMMAND`
  Use to execute a custom installation command sequence for the chef-client. This option may not be used in the same command with `--bootstrap-curl-options`, `--bootstrap-install-sh`, or `--bootstrap-wget-options`.
`--bootstrap-install-sh URL`
  Use to fetch and execute an installation script at the specified URL. This option may not be used in the same command with `--bootstrap-install-command`.
`--bootstrap-no-proxy NO_PROXY_URL_or_IP`

  A URL or IP address that specifies a location that should not be proxied.

  Note

  This option is used internally by Chef to help verify bootstrap operations during testing and should never be used during an actual bootstrap operation.

`--bootstrap-proxy PROXY_URL`
  The proxy server for the node that is the target of a bootstrap operation.
`--bootstrap-version VERSION`
  The version of the chef-client to install.
`--bootstrap-wget-options OPTIONS`
  Use to specify arbitrary options to be added to the bootstrap command when using GNU Wget. This option may not be used in the same command with `--bootstrap-install-command`.
`-d DISTRO`, `--distro DISTRO`

  The template file to be used during a bootstrap operation. The following distributions are supported: `chef-full` (the default bootstrap), `centos5-gems`, `fedora13-gems`, `ubuntu10.04-gems`, `ubuntu10.04-apt`, `ubuntu12.04-gems`, and the name of a custom bootstrap template file. When this option is used, knife will search for the template file in the following order: the `bootstrap/` folder in the current working directory, the `bootstrap/` folder in the chef-repo, the `bootstrap/` folder in the `~/.chef/` directory, or a default bootstrap file. Do not use the `--template-file` option when `--distro` is specified.

  Warning

  The default bootstrap operation uses the omnibus installer, which means the default template file (`chef-full`) should work on all supported platforms. It is recommended to use custom bootstrap templates only when the omnibus installer cannot be used. The `.erb` file extension is added automatically and should not be passed as part of the bootstrap command.

`-E ENVIRONMENT`, `--environment ENVIRONMENT`
  The name of the environment. When this option is added to a command, the command will run only against the named environment.
`-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]`
  An Ohai hint to be set on the target of the bootstrap. The hint is contained in a file and is formatted as JSON: `{"attribute":"value","attribute":"value"...}`. `HINT_NAME` is the name of the hint and `HINT_FILE` is the name of the hint file located at `/etc/chef/ohai/hints/HINT_FILE.json`. Use multiple `--hint` options in the command 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`
  Use to install pre-release gems.
`-r RUN_LIST`, `--run-list RUN_LIST`
  A comma-separated list of roles and/or recipes to be applied.
`--secret SECRET`
  The encryption key that is used for values contained within a data bag item.
`--secret-file FILE`
  The path to the file that contains the encryption key.
`--sudo`
  Use to execute a bootstrap operation with 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.
`--use-sudo-password`
  Use to perform a bootstrap operation with sudo; specify the password with the `-P` (or `--ssh-password`) option.
`-V -V`
  Use to run the initial chef-client run at the `debug` log-level (e.g. `chef-client -l debug`).
`-x USERNAME`, `--ssh-user USERNAME`
  The SSH user name.

## Custom Templates

The `chef-full` distribution uses the omnibus installer. For most bootstrap operations, regardless of the platform on which the target node is running, using the `chef-full` distribution is the best approach for installing the chef-client on a target node. In some situations, using another supported distribution is necessary. And in some situations, a custom template may be required. For example, the default bootstrap operation relies on an Internet connection to get the distribution to the target node. If a target node cannot access the Internet, then a custom template can be used to define a specific location for the distribution so that the target node may access it during the bootstrap operation.

A custom bootstrap template file (`template_filename.erb`) must be located in a `bootstrap/` directory. Use the `--distro` option with the `knife bootstrap` subcommand to specify the bootstrap template file. For example, a bootstrap template file named “british_sea_power.erb”:

    $ knife bootstrap 123.456.7.8 -x username -P password --sudo --distro "british_sea_power.erb"

The following examples show how a bootstrap template file can be customized for various platforms.

### 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 the chef-client 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-repo 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 git source for the chef-repo: https://github.com/opscode/chef/tree/master/lib/chef/knife/bootstrap. 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 the chef-client 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-repo, and then create the Embedded Ruby (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 Embedded Ruby (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 the node 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

### Microsoft Windows

The following example shows how to modify the default script for Microsoft Windows and Windows PowerShell:

    @setlocal

    <%= "SETX HTTP_PROXY \"#{knife_config[:bootstrap_proxy]}\"" if knife_config[:bootstrap_proxy] %>
    @mkdir <%= bootstrap_directory %>

    > <%= bootstrap_directory %>\wget.ps1 (
     <%= win_wget_ps %>
    )

    :install
    @rem Install Chef using chef-client MSI installer

    <% url="http://reposerver.example.com/chef-client-11.6.0.rc.1-1.windows.msi" -%>
    @set "REMOTE_SOURCE_MSI_URL=<%= url %>"
    @set "LOCAL_DESTINATION_MSI_PATH=<%= local_download_path %>"

    @powershell -ExecutionPolicy Unrestricted -NoProfile -NonInteractive "& '<%= bootstrap_directory %>\wget.ps1' '%REMOTE_SOURCE_MSI_URL%' '%LOCAL_DESTINATION_MSI_PATH%'"

    @REM Replace install_chef from knife-windows Gem with one that has extra flags to turn on Chef service feature -- only available in Chef >= 11.6.x
    @REM <%= install_chef %>
    @echo Installing Chef Client 11.6.0.rc1 with msiexec
    @msiexec /q /i "%LOCAL_DESTINATION_MSI_PATH%" ADDLOCAL="ChefClientFeature,ChefServiceFeature"
    @endlocal

    @echo Writing validation key...

    > <%= bootstrap_directory %>\validation.pem (
     <%= validation_key %>
    )

    @echo Validation key written.

    <% if @config[:encrypted_data_bag_secret] -%>
    > <%= bootstrap_directory %>\encrypted_data_bag_secret (
     <%= encrypted_data_bag_secret %>
    )
    <% end -%>

    > <%= bootstrap_directory %>\client.rb (
     <%= config_content %>
    )

    > <%= bootstrap_directory %>\first-boot.json (
     <%= run_list %>
    )

    <%= start_chef %>

## Examples

The following examples show how to use this knife subcommand:

Use an SSH password

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

Use a file that contains a private key

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