confctl 1.0.0 → 2.1.0

data/man/man8/confctl-options.nix.8.md

@@ -1,4 +1,4 @@
-# confctl-options.nix 8           2024-02-17                             master
+# confctl-options.nix 8           2024-05-07                             master
 
 ## NAME
 `confctl-options.nix` - confctl configuration documentation
@@ -601,6 +601,22 @@ the deployment configuration directory, i.e. `cluster/<machine-name>/module.nix`
 
     *Declared by:* `<confctl/nix/modules/cluster>`
 
+`cluster.<name>.buildAttribute`
+  Path to the attribute in machine system config that should be built
+  
+  For example, `[ "system" "build" "toplevel" ]` will select attribute
+  `config.system.build.toplevel`.
+
+    *Type:* list of string
+
+    *Default:* `[
+  "system"
+  "build"
+  "toplevel"
+]`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
 `cluster.<name>.buildGenerations.max`
   The maximum number of build generations to be kept on the build
   machine.
@@ -634,6 +650,151 @@ the deployment configuration directory, i.e. `cluster/<machine-name>/module.nix`
 
     *Declared by:* `<confctl/nix/modules/cluster>`
 
+`cluster.<name>.carrier.enable`
+  Whether to enable This machine is a carrier for other machines.
+
+    *Type:* boolean
+
+    *Default:* `false`
+
+    *Example:* `true`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines`
+  List of carried machines
+
+    *Type:* list of (submodule)
+
+    *Default:* `[ ]`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines.*.alias`
+  Alias for carried machine name
+
+    *Type:* null or string
+
+    *Default:* `null`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines.*.buildAttribute`
+  Path to the attribute in machine system config that should be built
+  
+  For example, `[ "system" "build" "toplevel" ]` will select attribute
+  `config.system.build.toplevel`.
+
+    *Type:* list of string
+
+    *Default:* `[
+  "system"
+  "build"
+  "toplevel"
+]`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines.*.buildGenerations.max`
+  The maximum number of build generations to be kept on the build
+  machine.
+
+    *Type:* null or signed integer
+
+    *Default:* `null`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines.*.buildGenerations.maxAge`
+  Delete build generations older than
+  `cluster.<name>.carrier.machines.*.buildGenerations.maxAge`
+  seconds from the build machine. Old generations are deleted even
+  if `cluster.<name>.carrier.machines.*.buildGenerations.max` is
+  not reached.
+
+    *Type:* null or signed integer
+
+    *Default:* `null`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines.*.buildGenerations.min`
+  The minimum number of build generations to be kept on the build
+  machine.
+
+    *Type:* null or signed integer
+
+    *Default:* `null`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines.*.extraModules`
+  A list of additional NixOS modules to be imported for this machine
+
+    *Type:* list of path
+
+    *Default:* `[ ]`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines.*.hostGenerations.max`
+  The maximum number of generations to be kept on the machine.
+
+    *Type:* null or signed integer
+
+    *Default:* `null`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines.*.hostGenerations.maxAge`
+  Delete generations older than
+  `cluster.<name>.carrier.machines.*.hostGenerations.maxAge`
+  seconds from the machine. Old generations are deleted even
+  if `cluster.<name>.carrier.machines.*.hostGenerations.max` is
+  not reached.
+
+    *Type:* null or signed integer
+
+    *Default:* `null`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines.*.hostGenerations.min`
+  The minimum number of generations to be kept on the machine.
+
+    *Type:* null or signed integer
+
+    *Default:* `null`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines.*.labels`
+  Optional user-defined labels to classify the machine
+
+    *Type:* attribute set
+
+    *Default:* `{ }`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines.*.machine`
+  Machine name
+
+    *Type:* string
+
+    *Default:* `null`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
+`cluster.<name>.carrier.machines.*.tags`
+  Optional user-defined tags to classify the machine
+
+    *Type:* list of string
+
+    *Default:* `[ ]`
+
+    *Declared by:* `<confctl/nix/modules/cluster>`
+
 `cluster.<name>.healthChecks.builderCommands`
   Check commands run on the build machine
 
@@ -1034,6 +1195,9 @@ the deployment configuration directory, i.e. `cluster/<machine-name>/module.nix`
 
 `cluster.<name>.host.target`
   Address/host to which the configuration is deployed to
+  
+  Set to null if the machine is not deployable, e.g. when it is only used
+  as a carried machine.
 
     *Type:* null or string
 

data/man/man8/confctl.8

@@ -37,6 +37,11 @@ for more information.
 similarly to shell patterns, see
 \[la]http://ruby-doc.org/core/File.html#method-c-fnmatch-3F\[ra] for more
 information.
+.SH GENERATION OFFSETS
+.PP
+Generations can be selected by \fIoffset\fP\&. \fB\fC0\fR is the current (last) generation.
+\fB\fC1\fR is the first (oldest) generation, \fB\fC2\fR the second generation, etc. \fB\fC\-1\fR is
+the generation before last and so on.
 .SH GLOBAL OPTIONS
 .TP
 \fB\fC\-c\fR, \fB\fC\-\-color\fR \fB\fCalways\fR|\fB\fCnever\fR|\fB\fCauto\fR
@@ -113,6 +118,10 @@ generations can be managed using \fB\fCconfctl generation\fR command family.
     \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\-\-cores\fR \fInumber\fP
+      Number of CPU cores to use, 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.
@@ -135,7 +144,7 @@ the target machine. The default action is \fB\fCswitch\fR\&.
     \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\fC\-g\fR, \fB\fC\-\-generation\fR \fIgeneration\fP|\fIoffset\fP|\fB\fCcurrent\fR
       Do not build a new generation, but deploy an existing generation.
 .PP
     \fB\fC\-\-outdated\fR
@@ -165,6 +174,12 @@ the target machine. The default action is \fB\fCswitch\fR\&.
 .PP
     \fB\fC\-\-copy\-only\fR
       Do not activate the copied closures.
+.PP
+    \fB\fC\-\-enable\-auto\-rollback\fR
+      Enable auto\-rollback on deploy even if it is not enabled in machine configuration.
+.PP
+    \fB\fC\-\-disable\-auto\-rollback\fR
+      Disable auto\-rollback on deploy if it is enabled in machine configuration.
 .PP
     \fB\fC\-\-reboot\fR
       Applicable only when \fIswitch\-action\fP is \fB\fCboot\fR\&. Reboot the machine after the
@@ -177,6 +192,10 @@ the target machine. The default action is \fB\fCswitch\fR\&.
     \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\-\-cores\fR \fInumber\fP
+      Number of CPU cores to use, 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
@@ -218,7 +237,7 @@ Probe managed machines and determine their status.
     \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
+    \fB\fC\-g\fR, \fB\fC\-\-generation\fR \fIgeneration\fP|\fIoffset\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.
@@ -226,6 +245,10 @@ Probe managed machines and determine their status.
     \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\-\-cores\fR \fInumber\fP
+      Number of CPU cores to use, 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
@@ -252,7 +275,7 @@ itself, it works only on software pins.
     \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\fC\-g\fR, \fB\fC\-\-generation\fR \fIgeneration\fP|\fIoffset\fP|\fB\fCcurrent\fR
       Show changelog against software pins from a selected generation instead
       of the current configuration.
 .PP
@@ -270,6 +293,10 @@ itself, it works only on software pins.
     \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\-\-cores\fR \fInumber\fP
+      Number of CPU cores to use, 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
@@ -296,7 +323,7 @@ itself, it works only on software pins.
     \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\fC\-g\fR, \fB\fC\-\-generation\fR \fIgeneration\fP|\fIoffset\fP|\fB\fCcurrent\fR
       Show diff against software pins from a selected generation instead
       of the current configuration.
 .PP
@@ -308,6 +335,10 @@ itself, it works only on software pins.
     \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\-\-cores\fR \fInumber\fP
+      Number of CPU cores to use, 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
@@ -386,7 +417,7 @@ Open ClusterSSH to selected or all machines.
     \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]
+\fB\fCconfctl generation ls\fR [\fImachine\-pattern\fP [\fIgeneration\-pattern\fP]|\fIn\fP\fB\fCd\fR|\fIoffset\fP|\fB\fCold\fR]
 List all or selected generations. By default only local build generations
 are listed.
 .PP
@@ -405,11 +436,13 @@ are listed.
     \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]]
+\fB\fCconfctl generation rm\fR [\fImachine\-pattern\fP [\fIgeneration\-pattern\fP|\fIn\fP\fB\fCd\fR|\fIoffset\fP|\fB\fCold\fR]]
 Remove selected generations.
 .IP
 \fIn\fP\fB\fCd\fR will remove generations older than \fIn\fP days.
 .IP
+\fIoffset\fP will remove generations at a specific offset, see \fB\fCGENERATION OFFSETS\fR\&.
+.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
@@ -465,6 +498,9 @@ configuration also runs \fB\fCnix\-collect\-garbage\fR\&.
 .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
+      Do not run the garbage collector even if it is enabled in configuration.
 .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.
@@ -520,17 +556,17 @@ on the type of the software pin, for git it is a git reference, e.g. a revision.
 \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.
+.PP
+    \fB\fC\-\-[no\-]commit\fR
+      Commit changed swpins files to git. Disabled by default.
+.PP
+    \fB\fC\-\-[no\-]changelog\fR
+      Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+      default.
+.PP
+    \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.
@@ -539,33 +575,33 @@ List existing channels with pinned software packages.
 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.
+.PP
+    \fB\fC\-\-[no\-]commit\fR
+      Commit changed swpins files to git. Disabled by default.
+.PP
+    \fB\fC\-\-[no\-]changelog\fR
+      Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+      default.
+.PP
+    \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.
+.PP
+    \fB\fC\-\-[no\-]commit\fR
+      Commit changed swpins files to git. Disabled by default.
+.PP
+    \fB\fC\-\-[no\-]changelog\fR
+      Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+      default.
+.PP
+    \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.
@@ -574,48 +610,48 @@ List core software packages used internally by confctl.
 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.
+.PP
+    \fB\fC\-\-[no\-]commit\fR
+      Commit changed swpins files to git. Disabled by default.
+.PP
+    \fB\fC\-\-[no\-]changelog\fR
+      Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+      default.
+.PP
+    \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.
+.PP
+    \fB\fC\-\-[no\-]commit\fR
+      Commit changed swpins files to git. Disabled by default.
+.PP
+    \fB\fC\-\-[no\-]changelog\fR
+      Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+      default.
+.PP
+    \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.
+.PP
+    \fB\fC\-\-[no\-]commit\fR
+      Commit changed swpins files to git. Disabled by default.
+.PP
+    \fB\fC\-\-[no\-]changelog\fR
+      Include changelog in the commit message when \fB\fC\-\-commit\fR is used. Enabled by
+      default.
+.PP
+    \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
@@ -656,5 +692,5 @@ 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 
+vpsFree.cz \[la]https://vpsfree.org\[ra] and its cluster
 configuration \[la]https://github.com/vpsfreecz/vpsfree-cz-configuration\[ra]\&.