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.
Note
Review the list of common options available to this (and all) knife subcommands and plugins.
This subcommand has the following options:
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.
Use to specify an Ohai hint to be set on the target node.
Ohai hints are used to tell Ohai something about the system that it is running on that it would not be able to discover itself. An Ohai hint exists if a JSON file exists in the hint directory with the same name as the hint. For example, calling hint?('antartica') in an Ohai plugin would return an empty hash if the file antartica.json existed in the hints directory, and return nil if the file does not exist.
If the hint file contains JSON content, it will be returned as a hash from the call to hint?.
{
"snow": true,
"penguins": "many"
}
arctic_hint = hint?('antartica')
if arctic_hint['snow']
"There are #{arctic_hint['penguins']} penguins here."
else
"There is no snow here, and penguins like snow."
end
The default directory in which hint files are located is /etc/chef/ohai/hints/. Use the Ohai::Config[:hints_path] setting in the client.rb file to customize this location.
HINT_FILE is the name of the JSON file. HINT_NAME is the name of a hint in a JSON file. Use multiple --hint options to specify multiple hints.
The verify mode for HTTPS requests.
Use :verify_none to do no validation of SSL certificates.
Use :verify_peer to do validation of all SSL certificates, including the Chef server connections, S3 connections, and any HTTPS remote_file resource URLs used in the chef-client run. This is the recommended setting.
If this option is not specified, the setting for ssl_verify_mode in the configuration file is applied.
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.
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/chef/chef/tree/master/lib/chef/knife/bootstrap. Copy the template to ~/.chef-repo/.chef/bootstrap/ubuntu12.04-apt.erb and modify the template appropriately.
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:
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
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 %>
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