confctl 1.0.0

data/man/man8/confctl.8

@@ -0,0 +1,660 @@
+.TH confctl 8                       2020\-11\-01                             master
+.SH NAME
+.PP
+\fB\fCconfctl\fR \- Nix deployment management tool
+.SH SYNOPSIS
+.PP
+\fB\fCconfctl\fR [\fIglobal options\fP] \fIcommand\fP [\fIcommand options\fP] [\fIarguments...\fP]
+.SH DESCRIPTION
+.PP
+\fB\fCconfctl\fR is a Nix deployment configuration management tool. It can be used to
+build and deploy \fINixOS\fP and \fIvpsAdminOS\fP machines.
+.SH SOFTWARE PINS
+.PP
+Each machine managed by \fB\fCconfctl\fR uses predefined software packages
+like \fB\fCnixpkgs\fR, \fB\fCvpsadminos\fR and possibly other components. These packages
+are pinned to particular versions, e.g. specific git commits.
+.PP
+Software pins are defined in the Nix configuration and then prefetched using
+\fB\fCconfctl\fR\&. Selected software pins are added to environment variable \fB\fCNIX_PATH\fR
+for \fB\fCnix\-build\fR and can also be read by \fB\fCNix\fR while building machines.
+.PP
+Software pins can be defined using channels or on specific machines.
+The advantage of using channels is that changing a pin in a channel changes
+also all machines that use the channel. Channels are defined in file
+\fB\fCconfigs/swpins.nix\fR using option \fB\fCconfctl.swpins.channels\fR\&. Deployments
+declare software pins and channels in their respective \fB\fCmodule.nix\fR files,
+option \fB\fCcluster.<name>.swpins.channels\fR is a list of channels to use and option
+\fB\fCcluster.<name>.swpins.pins\fR is an attrset of pins to extend or override pins
+from channels.
+.PP
+Software pins declared in the Nix configuration have to be prefetched before
+they can be used to build machines. See the \fB\fCconfctl swpins\fR command family
+for more information.
+.SH PATTERNS
+.PP
+\fB\fCconfctl\fR commands accept patterns instead of names. These patterns work
+similarly to shell patterns, see
+\[la]http://ruby-doc.org/core/File.html#method-c-fnmatch-3F\[ra] for more
+information.
+.SH GLOBAL OPTIONS
+.TP
+\fB\fC\-c\fR, \fB\fC\-\-color\fR \fB\fCalways\fR|\fB\fCnever\fR|\fB\fCauto\fR
+Set output color mode. Defaults to \fB\fCauto\fR, which enables colors when
+the standard output is connected to a terminal.
+.SH COMMANDS
+.TP
+\fB\fCconfctl init\fR
+Create a new configuration in the current directory. The current directory
+is set up to be used with \fB\fCconfctl\fR\&.
+.TP
+\fB\fCconfctl add\fR \fIname\fP
+Add new machine to the configuration.
+.TP
+\fB\fCconfctl rename\fR \fIold\-name\fP \fInew\-name\fP
+Rename machine from the configuration.
+.TP
+\fB\fCconfctl rediscover\fR
+Auto\-discover machines within the \fB\fCcluster/\fR directory and generate a list
+of their modules in \fB\fCcluster/cluster.nix\fR\&.
+.TP
+\fB\fCconfctl ls\fR [\fIoptions\fP] [\fImachine\-pattern\fP]
+List matching machines available for deployment.
+.PP
+    \fB\fC\-\-show\-trace\fR
+      Enable traces in Nix.
+.PP
+    \fB\fC\-\-managed\fR \fB\fCy\fR|\fB\fCyes\fR|\fB\fCn\fR|\fB\fCno\fR|\fB\fCa\fR|\fB\fCall\fR
+      The configuration can contain machines which are not managed by confctl
+      and are there just for reference. This option determines what kind of
+      machines should be listed.
+.PP
+    \fB\fC\-L\fR, \fB\fC\-\-list\fR
+      List possible attributes that can be used with options \fB\fC\-\-output\fR
+      or \fB\fC\-\-attr\fR and exit.
+.PP
+    \fB\fC\-o\fR, \fB\fC\-\-output\fR \fIattributes\fP
+      Comma\-separated list of attributes to output. Defaults to the value
+      of option \fB\fCconfctl.list.columns\fR\&.
+.PP
+    \fB\fC\-H\fR, \fB\fC\-\-hide\-header\fR
+      Do not print the line with column labels.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.TP
+\fB\fCconfctl build\fR [\fIoptions\fP] [\fImachine\-pattern\fP]
+Build matching machines. The result of a build is one generation for each
+built machine. Subsequent builds either return an existing generation if there
+had been no changes for a machine or a new generation is created. Built
+generations can be managed using \fB\fCconfctl generation\fR command family.
+.PP
+    \fB\fC\-\-show\-trace\fR
+      Enable traces in Nix.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-y\fR, \fB\fC\-\-yes\fR
+      Do not ask for confirmation on standard input, assume the answer is yes.
+.PP
+    \fB\fC\-j\fR, \fB\fC\-\-max\-jobs\fR \fInumber\fP
+      Maximum number of build jobs, passed to \fB\fCnix\-build\fR\&. See man 
+.BR nix-build (1).
+.TP
+\fB\fCconfctl deploy\fR [\fIoptions\fP] [\fImachine\-pattern\fP [\fB\fCboot\fR|\fB\fCswitch\fR|\fB\fCtest\fR|\fB\fCdry\-activate\fR]]
+Deploy either a new or an existing build generation to matching machines.
+.IP
+\fIswitch\-action\fP is the argument to \fB\fCswitch\-to\-configuration\fR called on
+the target machine. The default action is \fB\fCswitch\fR\&.
+.PP
+    \fB\fC\-\-show\-trace\fR
+      Enable traces in Nix.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-y\fR, \fB\fC\-\-yes\fR
+      Do not ask for confirmation on standard input, assume the answer is yes.
+.PP
+    \fB\fC\-g\fR, \fB\fC\-\-generation\fR \fIgeneration\fP|\fB\fCcurrent\fR
+      Do not build a new generation, but deploy an existing generation.
+.PP
+    \fB\fC\-\-outdated\fR
+      Run \fB\fCconfctl status\fR and deploy only outdated machines. \fB\fCconfctl\fR will
+      first build machines described by \fImachine\-pattern\fP and then check
+      their status.
+.PP
+    \fB\fC\-\-outdated\-swpins\fR
+      Run \fB\fCconfctl status \-g none\fR and deploy only machines that have outdated
+      software pins.
+.PP
+    \fB\fC\-i\fR, \fB\fC\-\-interactive\fR
+      Deploy machines one by one while asking for confirmation for activation.
+.PP
+    \fB\fC\-\-dry\-activate\-first\fR
+      After the new system is copied to the target machine, try to switch the
+      configuration using \fIdry\-activate\fP action to see what would happen before
+      the real switch.
+.PP
+    \fB\fC\-\-one\-by\-one\fR
+      Instead of copying the systems to all machines in bulk before activations,
+      copy and deploy machines one by one.
+.PP
+    \fB\fC\-\-max\-concurrent\-copy\fR \fIn\fP
+      Use at most \fIn\fP concurrent nix\-copy\-closure processes to deploy closures
+      to the target machines. Defaults to \fB\fC5\fR\&.
+.PP
+    \fB\fC\-\-copy\-only\fR
+      Do not activate the copied closures.
+.PP
+    \fB\fC\-\-reboot\fR
+      Applicable only when \fIswitch\-action\fP is \fB\fCboot\fR\&. Reboot the machine after the
+      configuration is activated.
+.PP
+    \fB\fC\-\-wait\-online\fR [\fIseconds\fP | \fB\fCwait\fR | \fB\fCnowait\fR]
+      Determines whether to wait for the machines to come back online
+      if \fB\fC\-\-reboot\fR is used. \fB\fCconfctl\fR will wait for \fB\fC600 seconds\fR by default.
+.PP
+    \fB\fC\-j\fR, \fB\fC\-\-max\-jobs\fR \fInumber\fP
+      Maximum number of build jobs, passed to \fB\fCnix\-build\fR\&. See man 
+.BR nix-build (1).
+.PP
+    \fB\fC\-\-no\-health\-checks\fR
+      Do not run configured health checks. Health checks are run by default
+      when \fIswitch\-action\fP is \fB\fCswitch\fR, \fB\fCtest\fR or \fB\fCboot\fR with \fB\fC\-\-reboot\fR\&.
+.PP
+    \fB\fC\-\-keep\-going\fR
+      Do not abort when health checks fail.
+.TP
+\fB\fCconfctl health\-check\fR [\fIoptions\fP] [\fImachine\-pattern\fP]
+Run health checks on all or selected machines.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-y\fR, \fB\fC\-\-yes\fR
+      Do not ask for confirmation on standard input, assume the answer is yes.
+.PP
+    \fB\fC\-j\fR, \fB\fC\-\-max\-jobs\fR \fInumber\fP
+      Maximum number of check jobs, defaults to \fB\fC5\fR\&.
+.TP
+\fB\fCconfctl status\fR [\fIoptions\fP] [\fImachine\-pattern\fP]
+Probe managed machines and determine their status.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-y\fR, \fB\fC\-\-yes\fR
+      Do not ask for confirmation on standard input, assume the answer is yes.
+.PP
+    \fB\fC\-g\fR, \fB\fC\-\-generation\fR \fIgeneration\fP|\fB\fCcurrent\fR|\fB\fCnone\fR
+      Check status against a selected generation instead of a new build. If set
+      to \fB\fCnone\fR, only the currently configured software pins are checked and not
+      the system version itself.
+.PP
+    \fB\fC\-j\fR, \fB\fC\-\-max\-jobs\fR \fInumber\fP
+      Maximum number of build jobs, passed to \fB\fCnix\-build\fR\&. See man 
+.BR nix-build (1).
+.TP
+\fB\fCconfctl changelog\fR [\fIoptions\fP] [\fImachine\-pattern\fP [\fIsw\-pattern\fP]]
+Show differences in deployed and configured software pins. For git software
+pins, it's a git log.
+.IP
+By default, \fB\fCconfctl\fR assumes that the configuration contains upgraded
+software pins, i.e. that the configuration is equal to or ahead of the deployed
+machines. \fB\fCconfctl changelog\fR then prints a lists of changes that are missing
+from the deployed machines. Too see a changelog for downgrade, use option
+\fB\fC\-d\fR, \fB\fC\-\-downgrade\fR\&.
+.IP
+\fB\fCconfctl changelog\fR will not show changes to the deployment configuration
+itself, it works only on software pins.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-y\fR, \fB\fC\-\-yes\fR
+      Do not ask for confirmation on standard input, assume the answer is yes.
+.PP
+    \fB\fC\-g\fR, \fB\fC\-\-generation\fR \fIgeneration\fP|\fB\fCcurrent\fR
+      Show changelog against software pins from a selected generation instead
+      of the current configuration.
+.PP
+    \fB\fC\-d\fR, \fB\fC\-\-downgrade\fR
+      Use when the configuration has older software pins than deployed machines,
+      e.g. when doing a downgrade. Show a list of changes that are deployed
+      on the machines and are missing in the configured software pins.
+.PP
+    \fB\fC\-v\fR, \fB\fC\-\-verbose\fR
+      Show full\-length changelog descriptions.
+.PP
+    \fB\fC\-p\fR, \fB\fC\-\-patch\fR
+      Show patches.
+.PP
+    \fB\fC\-j\fR, \fB\fC\-\-max\-jobs\fR \fInumber\fP
+      Maximum number of build jobs, passed to \fB\fCnix\-build\fR\&. See man 
+.BR nix-build (1).
+.TP
+\fB\fCconfctl diff\fR [\fIoptions\fP] [\fImachine\-pattern\fP [\fIsw\-pattern\fP]]
+Show differences in deployed and configured software pins. For git software
+pins, it's a git diff.
+.IP
+By default, \fB\fCconfctl\fR assumes that the configuration contains upgraded
+software pins, i.e. that the configuration is equal to or ahead of the deployed
+machines. \fB\fCconfctl diff\fR then considers changes that are missing from the
+deployed machines. Too see a diff for downgrade, use option
+\fB\fC\-d\fR, \fB\fC\-\-downgrade\fR\&.
+.IP
+\fB\fCconfctl diff\fR will not show changes to the deployment configuration
+itself, it works only on software pins.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-y\fR, \fB\fC\-\-yes\fR
+      Do not ask for confirmation on standard input, assume the answer is yes.
+.PP
+    \fB\fC\-g\fR, \fB\fC\-\-generation\fR \fIgeneration\fP|\fB\fCcurrent\fR
+      Show diff against software pins from a selected generation instead
+      of the current configuration.
+.PP
+    \fB\fC\-d\fR, \fB\fC\-\-downgrade\fR
+      Use when the configuration has older software pins than deployed machines,
+      e.g. when doing a downgrade. Show a list of changes that are deployed
+      on the machines and are missing in the configured software pins.
+.PP
+    \fB\fC\-j\fR, \fB\fC\-\-max\-jobs\fR \fInumber\fP
+      Maximum number of build jobs, passed to \fB\fCnix\-build\fR\&. See man 
+.BR nix-build (1).
+.TP
+\fB\fCconfctl test\-connection\fR [\fIoptions\fP] [\fImachine\-pattern\fP]
+Try to open a SSH connection to the selected machines. This command can be
+used to confirm SSH host keys of the selected machines.
+.PP
+    \fB\fC\-\-managed\fR \fB\fCy\fR|\fB\fCyes\fR|\fB\fCn\fR|\fB\fCno\fR|\fB\fCa\fR|\fB\fCall\fR
+      The configuration can contain machines which are not managed by confctl
+      and are there just for reference. This option determines what kind of
+      machines should be selected.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-y\fR, \fB\fC\-\-yes\fR
+      Do not ask for confirmation on standard input, assume the answer is yes.
+.TP
+\fB\fCconfctl ssh\fR [\fIoptions\fP] [\fImachine\-pattern\fP [\fIcommand\fP [\fIarguments...\fP]]]
+Run command over SSH on the selected machines. If \fImachine\-pattern\fP matches
+only one machine and no \fIcommand\fP is provided, an interactive shell is started.
+.PP
+    \fB\fC\-\-managed\fR \fB\fCy\fR|\fB\fCyes\fR|\fB\fCn\fR|\fB\fCno\fR|\fB\fCa\fR|\fB\fCall\fR
+      The configuration can contain machines which are not managed by confctl
+      and are there just for reference. This option determines what kind of
+      machines should be selected.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-y\fR, \fB\fC\-\-yes\fR
+      Do not ask for confirmation on standard input, assume the answer is yes.
+.PP
+    \fB\fC\-p\fR, \fB\fC\-\-parallel\fR
+      Run the command on all machines in parallel. By default, the command is run
+      on machines sequentially.
+.PP
+    \fB\fC\-g\fR, \fB\fC\-\-aggregate\fR
+      If the command has the same output and exit status on a group of one or more
+      machines, print it just once for the group. This option suppresses output
+      until the command has been run on all machines.
+.PP
+    \fB\fC\-i\fR, \fB\fC\-\-input\-string\fR \fIdata\fP
+      Data passed to the executed command on standard input.
+.PP
+    \fB\fC\-f\fR, \fB\fC\-\-input\-file\fR \fIfile\fP
+      Pass \fIfile\fP as standard input to the executed command.
+.TP
+\fB\fCconfctl cssh\fR [\fIoptions\fP] [\fImachine\-pattern\fP]
+Open ClusterSSH to selected or all machines.
+.PP
+    \fB\fC\-\-managed\fR \fB\fCy\fR|\fB\fCyes\fR|\fB\fCn\fR|\fB\fCno\fR|\fB\fCa\fR|\fB\fCall\fR
+      The configuration can contain machines which are not managed by confctl
+      and are there just for reference. This option determines what kind of
+      machines should be selected.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-y\fR, \fB\fC\-\-yes\fR
+      Do not ask for confirmation on standard input, assume the answer is yes.
+.TP
+\fB\fCconfctl generation ls\fR [\fImachine\-pattern\fP [\fIgeneration\-pattern\fP]|\fIn\fP\fB\fCd\fR|\fB\fCold\fR]
+List all or selected generations. By default only local build generations
+are listed.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-l\fR, \fB\fC\-\-local\fR
+      List build generations.
+.PP
+    \fB\fC\-r\fR, \fB\fC\-\-remote\fR
+      List remote generations found on deployed machines.
+.TP
+\fB\fCconfctl generation rm\fR [\fImachine\-pattern\fP [\fIgeneration\-pattern\fP|\fIn\fP\fB\fCd\fR|\fB\fCold\fR]]
+Remove selected generations.
+.IP
+\fIn\fP\fB\fCd\fR will remove generations older than \fIn\fP days.
+.IP
+\fB\fCold\fR will remove all generations except the current one, i.e. the one that
+was built by \fB\fCconfctl build\fR the last.
+.IP
+By default, only local build generations are considered.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-y\fR, \fB\fC\-\-yes\fR
+      Do not ask for confirmation on standard input, assume the answer is yes.
+.PP
+    \fB\fC\-l\fR, \fB\fC\-\-local\fR
+      Consider local build generations.
+.PP
+    \fB\fC\-r\fR, \fB\fC\-\-remote\fR
+      Consider generations found on deployed machines.
+.PP
+    \fB\fC\-\-[no\-]gc\fR, \fB\fC\-\-[no\-]collect\-garbage\fR
+      Run \fB\fCnix\-collect\-garbage\fR to delete unreachable store paths from deployed
+      machines where generations were removed. Enabled by default.
+.PP
+    \fB\fC\-\-max\-concurrent\-gc\fR \fIn\fP
+      Run \fB\fCnix\-collect\-garbage\fR at most on \fIn\fP machines at the same time.
+      Defaults to \fB\fC5\fR\&.
+.TP
+\fB\fCconfctl generation rotate\fR [\fIoptions\fP] [\fImachine\-pattern\fP]
+Delete old build generations of all or selected machines. Old generations are
+deleted based on rules configured in \fB\fCconfigs/confctl.nix\fR\&.
+.IP
+This command deletes old build generations from \fB\fCconfctl\fR, and given machine
+configuration also runs \fB\fCnix\-collect\-garbage\fR\&.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-y\fR, \fB\fC\-\-yes\fR
+      Do not ask for confirmation on standard input, assume the answer is yes.
+.PP
+    \fB\fC\-l\fR, \fB\fC\-\-local\fR
+      Consider local build generations.
+.PP
+    \fB\fC\-r\fR, \fB\fC\-\-remote\fR
+      Consider generations found on deployed machines.
+.PP
+    \fB\fC\-\-max\-concurrent\-gc\fR \fIn\fP
+      Run \fB\fCnix\-collect\-garbage\fR at most on \fIn\fP machines at the same time.
+      Defaults to \fB\fC5\fR\&.
+.TP
+\fB\fCconfctl collect\-garbage\fR [\fIoptions\fP] [\fImachine\-pattern\fP]
+Run \fB\fCnix\-collect\-garbage\fR on all or selected machines to delete unreachable
+store paths.
+.PP
+    \fB\fC\-a\fR, \fB\fC\-\-attr\fR \fIattribute\fP\fB\fC=\fR\fIvalue\fP | \fIattribute\fP\fB\fC!=\fR\fIvalue\fP
+      Filter machines by selected attribute, which is either tested for
+      equality or inequality. Any attribute from configuration module
+      \fB\fCcluster.<name>\fR can be tested.
+.PP
+    \fB\fC\-t\fR, \fB\fC\-\-tag\fR \fItag\fP|\fB\fC^\fR\fItag\fP
+      Filter machines that have \fItag\fP set. If the tag begins with \fB\fC^\fR, then
+      filter machines that do not have \fItag\fP set.
+.PP
+    \fB\fC\-y\fR, \fB\fC\-\-yes\fR
+      Do not ask for confirmation on standard input, assume the answer is yes.
+.PP
+    \fB\fC\-\-max\-concurrent\-gc\fR \fIn\fP
+      Run \fB\fCnix\-collect\-garbage\fR at most on \fIn\fP machines at the same time.
+      Defaults to \fB\fC5\fR\&.
+.TP
+\fB\fCconfctl gen\-data vpsadmin all\fR
+Generate all required data files from vpsAdmin API.
+.TP
+\fB\fCconfctl gen\-data vpsadmin containers\fR
+Generate container data files from vpsAdmin API.
+.TP
+\fB\fCconfctl gen\-data vpsadmin network\fR
+Generate network data files from vpsAdmin API.
+.TP
+\fB\fCconfctl swpins cluster ls\fR [\fIname\-pattern\fP [\fIsw\-pattern\fP]]
+List cluster machines with pinned software packages.
+.TP
+\fB\fCconfctl swpins cluster set\fR \fIname\-pattern\fP \fIsw\-pattern\fP \fIversion...\fP
+Set selected software packages to new \fIversion\fP\&. The value of \fIversion\fP depends
+on the type of the software pin, for git it is a git reference, e.g. a revision.
+.TP
+\fB\fC\-\-[no\-]commit\fR
+    Commit changed swpins files to git. Disabled by default.
+.TP
+\fB\fC\-\-[no\-]changelog\fR
+    Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+    default.
+.TP
+\fB\fC\-d\fR, \fB\fC\-\-downgrade\fR
+    Use when the new version is older than the previously set version. Used for
+    generating changelog for the commit message.
+.TP
+\fB\fCconfctl swpins cluster update\fR [\fIname\-pattern\fP [\fIsw\-pattern\fP]]
+Update selected or all software packages that have been configured to support
+this command. The usual case for git is to pin to the current branch head.
+.TP
+\fB\fC\-\-[no\-]commit\fR
+    Commit changed swpins files to git. Disabled by default.
+.TP
+\fB\fC\-\-[no\-]changelog\fR
+    Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+    default.
+.TP
+\fB\fC\-d\fR, \fB\fC\-\-downgrade\fR
+    Use when the new version is older than the previously set version. Used for
+    generating changelog for the commit message.
+.TP
+\fB\fCconfctl swpins channel ls\fR [\fIchannel\-pattern\fP [\fIsw\-pattern\fP]]
+List existing channels with pinned software packages.
+.TP
+\fB\fCconfctl swpins channel set\fR \fIchannel\-pattern\fP \fIsw\-pattern\fP \fIversion...\fP
+Set selected software packages in channels to new \fIversion\fP\&. The value
+of \fIversion\fP depends on the type of the software pin, for git it is a git
+reference, e.g. a revision.
+.TP
+\fB\fC\-\-[no\-]commit\fR
+    Commit changed swpins files to git. Disabled by default.
+.TP
+\fB\fC\-\-[no\-]changelog\fR
+    Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+    default.
+.TP
+\fB\fC\-d\fR, \fB\fC\-\-downgrade\fR
+    Use when the new version is older than the previously set version. Used for
+    generating changelog for the commit message.
+.TP
+\fB\fCconfctl swpins channel update\fR [\fIchannel\-pattern\fP [\fIsw\-pattern\fP]]
+Update selected or all software packages in channels that have been configured
+to support this command. The usual case for git is to pin to the current
+branch head.
+.TP
+\fB\fC\-\-[no\-]commit\fR
+    Commit changed swpins files to git. Disabled by default.
+.TP
+\fB\fC\-\-[no\-]changelog\fR
+    Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+    default.
+.TP
+\fB\fC\-d\fR, \fB\fC\-\-downgrade\fR
+    Use when the new version is older than the previously set version. Used for
+    generating changelog for the commit message.
+.TP
+\fB\fCconfctl swpins core ls\fR [\fIsw\-pattern\fP]
+List core software packages used internally by confctl.
+.TP
+\fB\fCconfctl swpins core set\fR \fIsw\-pattern\fP \fIversion...\fP
+Set selected core software package to new \fIversion\fP\&. The value
+of \fIversion\fP depends on the type of the software pin, for git it is a git
+reference, e.g. a revision.
+.TP
+\fB\fC\-\-[no\-]commit\fR
+    Commit changed swpins files to git. Disabled by default.
+.TP
+\fB\fC\-\-[no\-]changelog\fR
+    Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+    default.
+.TP
+\fB\fC\-d\fR, \fB\fC\-\-downgrade\fR
+    Use when the new version is older than the previously set version. Used for
+    generating changelog for the commit message.
+.TP
+\fB\fCconfctl swpins core update\fR [\fIsw\-pattern\fP]
+Update selected or all core software packages that have been configured
+to support this command. The usual case for git is to pin to the current
+branch head.
+.TP
+\fB\fC\-\-[no\-]commit\fR
+    Commit changed swpins files to git. Disabled by default.
+.TP
+\fB\fC\-\-[no\-]changelog\fR
+    Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+    default.
+.TP
+\fB\fC\-d\fR, \fB\fC\-\-downgrade\fR
+    Use when the new version is older than the previously set version. Used for
+    generating changelog for the commit message.
+.TP
+\fB\fCconfctl swpins update\fR
+Update software pins that have been configured for updates, including pins
+in all channels, all machine\-specific pins and the core pins.
+.TP
+\fB\fC\-\-[no\-]commit\fR
+    Commit changed swpins files to git. Disabled by default.
+.TP
+\fB\fC\-\-[no\-]changelog\fR
+    Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+    default.
+.TP
+\fB\fC\-d\fR, \fB\fC\-\-downgrade\fR
+    Use when the new version is older than the previously set version. Used for
+    generating changelog for the commit message.
+.TP
+\fB\fCconfctl swpins reconfigure\fR
+Regenerate all confctl\-managed software pin files according to the Nix
+configuration.
+.SH USER\-DEFINED COMMANDS
+.PP
+User\-defined Ruby scripts can be placed in directory \fB\fCscripts\fR\&. Each script
+should create a subclass of \fB\fCConfCtl::UserScript\fR and call class\-method \fB\fCregister\fR\&.
+Scripts can define their own \fB\fCconfctl\fR subcommands.
+.SS Example user script
+.PP
+.RS
+.nf
+class MyScript < ConfCtl::UserScript
+  register
+
+  def setup_cli(app)
+    app.desc 'My CLI command'
+    app.command 'my\-command' do |c|
+      c.action &ConfCtl::Cli::Command.run(c, MyCommand, :run)
+    end
+  end
+end
+
+class MyCommand < ConfCtl::Cli::Command
+  def run
+    puts 'Hello world'
+  end
+end
+.fi
+.RE
+.SH SEE ALSO
+.PP
+.BR confctl-options.nix (8)
+.SH BUGS
+.PP
+Report bugs to \[la]https://github.com/vpsfreecz/confctl/issues\[ra]\&.
+.SH ABOUT
+.PP
+\fB\fCconfctl\fR was originally developed for the purposes of
+vpsFree.cz \[la]https://vpsfree.org\[ra] and its cluster 
+configuration \[la]https://github.com/vpsfreecz/vpsfree-cz-configuration\[ra]\&.