.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "CHAKE" "1" "June 2021" ""
.SH "NAME"
\fBchake\fR \- serverless configuration management tool
.SH "SYNOPSIS"
\fBchake\fR init
.P
\fBchake\fR [rake arguments]
.SH "DESCRIPTION"
chake is a tool that helps you manage multiple hosts without the need for a central server\. Configuration is managed in a local directory, which should (but doesn't need to) be under version control with \fBgit(1)\fR or any other version control system\.
.P
Configuration is deployed to managed hosts remotely, either by invoking a configuration management tool that will connect to them, or by first uploading the necessary configuration and them remotely running a tool on the hosts\.
.SH "SUPPORTED CONFIGURATION MANAGERS\."
chake supports the following configuration management tools:
.IP "\[ci]" 4
\fBitamae\fR: configuration is applied by running the itamae command line tool on the management host; no configuration needs to be uploaded to the managed hosts\. See chake\-itamae(7) for details\.
.IP "\[ci]" 4
\fBshell\fR: the local repository is copied to the host, and the shell commands specified in the node configuration is executed from the directory where that copy is\. See chake\-shell(7) for details\.
.IP "\[ci]" 4
\fBchef\fR: the local repository is copied to the host, and \fBchef\-solo\fR is executed remotely on the managed host\. See chake\-chef(7) for details\.
.IP "" 0
.P
Beyond applying configuration management recipes on the hosts, chake also provides useful tools to manage multiple hosts, such as listing nodes, running commands against all of them simultaneously, logging in to interactive shells, and others\.
.SH "CREATING THE REPOSITORY"
.nf
$ chake init[:configmanager]
.fi
.P
This will create an initial directory structure\. Some of the files are specific to your your chosen \fBconfigmanager\fR, which can be one of [SUPPORTED CONFIGURATION MANAGERS]\. The following files, though, will be common to any usage of chake:
.IP "\[ci]" 4
\fBnodes\.yaml\fR: where you will list the hosts you will be managing, and what recipes to apply to each of them\.
.IP "\[ci]" 4
\fBnodes\.d\fR: a directory with multiple files in the same format as nodes\.yaml\. All files matching \fB*\.yaml\fR in it will be added to the list of nodes\.
.IP "\[ci]" 4
\fBRakefile\fR: Contains just the \fBrequire 'chake'\fR line\. You can augment it with other tasks specific to your intrastructure\.
.IP "" 0
.P
If you omit \fIconfigmanager\fR, \fBitamae\fR will be used by default\.
.P
After the repository is created, you can call either \fBchake\fR or \fBrake\fR, as they are completely equivalent\.
.SH "MANAGING NODES"
Just after you created your repository, the contents of \fBnodes\.yaml\fR is the following:
.IP "" 4
.nf
host1\.mycompany\.com:
  itamae:
    \- roles/basic\.rb
.fi
.IP "" 0
.P
The exact contents depends on the chosen configuration management tool\.
.P
You can list your hosts with \fBrake nodes\fR:
.IP "" 4
.nf
$ rake nodes
host1\.mycompany\.com                      ssh
.fi
.IP "" 0
.P
To add more nodes, just append to \fBnodes\.yaml\fR:
.IP "" 4
.nf
host1\.mycompany\.com:
  itamae:
    \- roles/basic\.rb
host2\.mycompany\.com:
  itamae:
    \- roles/basic\.rb
.fi
.IP "" 0
.P
And chake now knows about your new node:
.IP "" 4
.nf
$ rake nodes
host1\.mycompany\.com                      ssh
host2\.mycompany\.com                      ssh
.fi
.IP "" 0
.SH "PREPARINGS NODES TO BE MANAGED"
Nodes have very few initial requirements to be managed with \fBchake\fR:
.IP "\[ci]" 4
The node must be accessible via SSH\.
.IP "\[ci]" 4
The user you connect to the node must either be \fBroot\fR, or be allowed to run \fBsudo\fR (in which case \fBsudo\fR must be installed)\.
.IP "" 0
.P
\fBA note on password prompts:\fR every time chake calls ssh on a node, you may be required to type in your password; every time chake calls sudo on the node, you may be require to type in your password\. For managing one or two nodes this is probably fine, but for larger numbers of nodes it is not practical\. To avoid password prompts, you can:
.IP "\[ci]" 4
Configure SSH key\-based authentication\. This is more secure than using passwords\. While you are at it, you also probably want disable password authentication completely, and only allow key\-based authentication
.IP "\[ci]" 4
Configure passwordless \fBsudo\fR access for the user you use to connect to your nodes\.
.IP "" 0
.SH "CHECKING CONNECTIVITY AND INITIAL HOST SETUP"
To check whether hosts are correctly configured, you can use the \fBcheck\fR task:
.IP "" 4
.nf
$ rake check
.fi
.IP "" 0
.P
That will run the the \fBsudo true\fR command on each host\. If that pass without you having to type any passwords, it means that:
.IP "\[ci]" 4
you have SSH access to each host; and
.IP "\[ci]" 4
the user you are connecting as has password\-less sudo correctly setup\.
.IP "" 0
.SH "APPLYING CONFIGURATION"
Note that by default all tasks that apply to all hosts will run in parallel, using rake's support for multitasks\. If for some reason you need to prevent that, you can pass \fB\-j1\fR (or \-\-jobs=1\fB) in the rake invocation\. Note that by default rake will only run N+4 tasks in parallel, where N is the number of cores on the machine you are running it\. If you have more than N+4 hosts and want all of them to be handled in parallel, you might want to pass\fR\-j\fB(or\fR\-\-jobs`), without any number, as the last argument; with that rake will have no limit on the number of tasks to perform in parallel\.
.P
To apply the configuration to all nodes, run
.IP "" 4
.nf
$ rake converge
.fi
.IP "" 0
.P
To apply the configuration to a single node, run
.IP "" 4
.nf
$ rake converge:$NODE
.fi
.IP "" 0
.P
To apply a single recipe on all nodes, run
.IP "" 4
.nf
$ rake apply[myrecipe]
.fi
.IP "" 0
.P
What \fBrecipe\fR is depends on the configuration manager\.
.P
To apply a single recipe on a specific node, run
.IP "" 4
.nf
$ rake apply:$NODE[myrecipe]
.fi
.IP "" 0
.P
If you don't inform a recipe in the command line, you will be prompted for one\.
.P
To run a shell command on all nodes, run
.IP "" 4
.nf
$ rake run The above will prompt you for a command, then execute it on all nodes\.
.fi
.IP "" 0
.P
To pass the command to run in the command line, use the following syntax:
.IP "" 4
.nf
$ rake run[command]
.fi
.IP "" 0
.P
If the \fBcommand\fR you want to run contains spaces, or other characters that are special do the shell, you have to quote them, for example:
.IP "" 4
.nf
$ rake run["cat /etc/hostname"]
.fi
.IP "" 0
.P
To run a shell command on a specific node, run
.IP "" 4
.nf
$ rake run:$NODE[command]
.fi
.IP "" 0
.P
As before, if you run just \fBrake run:$NODE\fR, you will be prompted for the command\.
.P
To list all existing tasks, run:
.IP "" 4
.nf
$ rake \-T
.fi
.IP "" 0
.SH "WRITING CONFIGURATION MANAGEMENT CODE"
As chake supports different configuration management tools, the specifics of configuration management code depends on the the tool you choose\. See the corresponding documentation\.
.SH "THE NODE BOOTSTRAPPING PROCESS"
Some of the configuration management tools require some software to be installed on the managed hosts\. When that's the case, chake acts on a node for the first time, it has to bootstrap it\. The bootstrapping process includes doing the following:
.IP "\[ci]" 4
installing and configuring the needed software
.IP "\[ci]" 4
setting up the hostname
.IP "" 0
.SH "NODE URLS"
The keys in the hash that is represented in \fBnodes\.yaml\fR is a node URL\. All components of the URL but the hostname are optional, so just listing hostnames is the simplest form of specifying your nodes\. Here are all the components of the node URLs:
.IP "" 4
.nf
[connection://][username@]hostname[:port][/path]
.fi
.IP "" 0
.IP "\[ci]" 4
\fBconnection\fR: what to use to connect to the host\. \fBssh\fR or \fBlocal\fR (default: \fBssh\fR)
.IP "\[ci]" 4
\fBusername\fR: user name to connect with (default: the username on your local workstation)
.IP "\[ci]" 4
\fBhostname\fR: the hostname to connect to (default: \fInone\fR)
.IP "\[ci]" 4
\fBport\fR: port number to connect to (default: 22)
.IP "\[ci]" 4
\fB/path\fR: where to store the cookbooks at the node (default: \fB/var/tmp/chef\.$USERNAME\fR)
.IP "" 0
.SH "EXTRA FEATURES"
.SS "HOOKS"
You can define rake tasks that will be executed before bootstrapping nodes, before uploading configuration management content to nodes, and before converging\. To do this, you just need to enhance the corresponding tasks:
.IP "\[ci]" 4
\fBbootstrap_common\fR: executed before bootstrapping nodes (even if nodes have already been bootstrapped)
.IP "\[ci]" 4
\fBupload_common\fR: executed before uploading content to the node
.IP "\[ci]" 4
\fBconverge_common\fR: executed before converging (i\.e\. running chef)
.IP "\[ci]" 4
\fBconnect_common\fR: executed before doing any action that connects to any of the hosts\. This can be used for example to generate a ssh configuration file based on the contents of the nodes definition files\.
.IP "" 0
.P
Example:
.IP "" 4
.nf
task :bootstrap_common do
  sh '\./scripts/pre\-bootstrap\-checks'
end
.fi
.IP "" 0
.SS "ENCRYPTED FILES"
Any files ending matching \fB*\.gpg\fR and \fB*\.asc\fR will be decrypted with GnuPG before being sent to the node (for the configuration management tools that required files to be sent)\. You can use them to store passwords and other sensitive information (SSL keys, etc) in the repository together with the rest of the configuration\.
.P
For configuration managers that don't require uploading files to the managed node, this decryption will happen right before converging or applying single recipes, and the decrypted files will be wiped right after that\.
.P
If you use this feature, make sure that you have the \fBwipe\fR program installed\. This way chake will be able to delete the decrypted files in a slightly more secure way, after being done with them\.
.SS "REPOSITORY\-LOCAL SSH CONFIGURATION"
If you need special SSH configuration parameters, you can create a file called \fB\.ssh_config\fR (or whatever file name you have in the \fB$CHAKE_SSH_CONFIG\fR environment variable, see below for details) in at the root of your repository, and chake will use it when calling \fBssh\fR\.
.SS "LOGGING IN TO A HOST"
To easily login to one of your host, just run \fBrake login:$HOSTNAME\fR\. This will automatically use the repository\-local SSH configuration as above so you don't have to type \fB\-F \.ssh_config\fR all the time\.
.SS "RUNNING ALL SSH INVOCATIONS WITH SOME PREFIX COMMAND"
Some times, you will also want or need to prefix your SSH invocations with some prefix command in order to e\.g\. tunnel it through some central exit node\. You can do this by setting \fB$CHAKE_SSH_PREFIX\fR on your environment\. Example:
.IP "" 4
.nf
CHAKE_SSH_PREFIX=tsocks rake converge
.fi
.IP "" 0
.P
The above will make all SSH invocations to all hosts be called as \fBtsocks ssh [\|\.\|\.\|\.]\fR
.SS "CONVERGING LOCAL HOST"
If you want to manage your local workstation with chake, you can declare a local node using the "local" connection type, like this (in \fBnodes\.yaml\fR):
.IP "" 4
.nf
local://thunderbolt:
  itamae:
    \- role/workstation\.rb
.fi
.IP "" 0
.P
To apply the configuration to the local host, you can use the conventional \fBrake converge:thunderbolt\fR, or the special target \fBrake local\fR\.
.P
When converging all nodes, \fBchake\fR will skip nodes that are declared with the \fBlocal://\fR connection and whose hostname does not match the hostname in the declaration\. For example:
.IP "" 4
.nf
local://desktop:
  itamae:
    \- role/workstation\.rb
local://laptop:
  itamae:
    \- role/workstation\.rb
.fi
.IP "" 0
.P
When you run \fBrake converge\fR on \fBdesktop\fR, \fBlaptop\fR will be skipped, and vice\-versa\.
.SS "ACCESSING NODE DATA FROM YOUR OWN TASKS"
It's often useful to be able to run arbitrary commands against the data you have about nodes\. You can use the \fBChake\.nodes\fR for that\. For example, if you want to geolocate each of yours hosts:
.IP "" 4
.nf
task :geolocate do
  Chake\.nodes\.each do |node|
    puts "#{node\.hostname}: %s" % `geoiplookup #{node\.hostname}`\.strip
  end
end
.fi
.IP "" 0
.SH "ENVIRONMENT VARIABLES"
.TP
\fB$CHAKE_SSH_CONFIG\fR
Local SSH configuration file\. Defaults to \fB\.ssh_config\fR\.
.TP
\fB$CHAKE_SSH_PREFIX\fR
Command to prefix SSH (and rsync over SSH) calls with\.
.TP
\fB$CHAKE_RSYNC_OPTIONS\fR
extra options to pass to \fBrsync\fR\. Useful to e\.g\. exclude large files from being upload to each server\.
.TP
\fB$CHAKE_NODES\fR
File containing the list of servers to be managed\. Default: \fBnodes\.yaml\fR\.
.TP
\fB$CHAKE_NODES_D\fR
Directory containing node definition files servers to be managed\. Default: \fBnodes\.d\fR\.
.TP
\fB$CHAKE_TMPDIR\fR
Directory used to store temporary cache files\. Default: \fBtmp/chake\fR\.
.TP
\fB$CHAKE_CHEF_CONFIG\fR
Chef configuration file, relative to the root of the repository\. Default: \fBconfig\.rb\fR\.
.SH "SEE ALSO"
.IP "\[ci]" 4
\fBrake(1)\fR
.IP "\[ci]" 4
\fBchake\-itamae(7)\fR, https://itamae\.kitchen/
.IP "\[ci]" 4
\fBchake\-shell(7)\fR
.IP "\[ci]" 4
\fBchake\-chef(7)\fR, \fBchef\-solo(1)\fR, https://docs\.chef\.io/
.IP "" 0