{"id":13929554,"url":"https://github.com/vpsfreecz/confctl","last_synced_at":"2026-03-03T21:30:54.575Z","repository":{"id":52172487,"uuid":"309099429","full_name":"vpsfreecz/confctl","owner":"vpsfreecz","description":"Nix deployment management tool","archived":false,"fork":false,"pushed_at":"2024-11-17T21:59:35.000Z","size":430,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-17T22:30:28.883Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vpsfreecz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-01T13:15:28.000Z","updated_at":"2024-11-17T21:59:37.000Z","dependencies_parsed_at":"2023-02-12T11:16:34.620Z","dependency_job_id":"981a840a-30dc-42e0-9c3f-463dd94214fd","html_url":"https://github.com/vpsfreecz/confctl","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpsfreecz%2Fconfctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpsfreecz%2Fconfctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpsfreecz%2Fconfctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpsfreecz%2Fconfctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vpsfreecz","download_url":"https://codeload.github.com/vpsfreecz/confctl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226597736,"owners_count":17657204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-07T18:02:24.902Z","updated_at":"2025-07-19T11:32:19.487Z","avatar_url":"https://github.com/vpsfreecz.png","language":"Ruby","funding_links":[],"categories":["others"],"sub_categories":[],"readme":"# confctl\nconfctl is a Nix deployment configuration management tool. It can be used to\nbuild and deploy [NixOS](https://nixos.org) and [vpsAdminOS](https://vpsadminos.org)\nmachines.\n\n## Features\n\n* Stateless\n* Per-machine nixpkgs (both modules and packages)\n* Build generations for easy rollback\n* Rotation of old generations\n* Support for configuration interconnections (declare and access other machines'\n  configurations)\n* Query machine state, view changelogs and diffs\n* Run health checks\n* Automatically roll back faulty configurations\n* Support for creating netboot servers with option to kexec, see [docs/carrier.md](docs/carrier.md)\n\n## Requirements\n\n* [Nix](https://nixos.org)\n\n## Quick start\n1. Either install confctl as a gem:\n```\ngem install confctl\n```\n\nOr clone this repository:\n\n```\ngit clone https://github.com/vpsfreecz/confctl\n```\n\nThis guide assumes you have cloned the repository, because otherwise man will\nnot find confctl's manual pages. If you install confctl using gem, you can\nignore steps with `shell.nix`.\n\nconfctl requires per-user garbage collection directory to be created:\n\n```\nsudo mkdir /nix/var/nix/gcroots/per-user/$USER\nsudo chown $USER /nix/var/nix/gcroots/per-user/$USER\n```\n\n2. Create a new directory, where your confctl-managed configuration will be\nstored:\n\n```\nmkdir cluster-configuration\n```\n3. Create `shell.nix` and import the same file from confctl:\n```\ncd cluster-configuration\ncat \u003e shell.nix \u003c\u003cEOF\nimport ../confctl/shell.nix\nEOF\n```\n\n4. Enter the `nix-shell`. This will make confctl available and install its\ndependencies into `.gems/`:\n```\nnix-shell\n```\n\nFrom within the shell, you can access the [manual](./man/man8/confctl.8.md)\nand a list of [configuration options](./man/man8/confctl-options.nix.8.md):\n\n```\nman confctl\nman confctl-options.nix\n```\n\n5. Initialize the configuration directory with confctl:\n```\nconfctl init\n```\n\n6. Add a new machine to be deployed:\n```\nconfctl add my-machine\n```\n\nYou can now edit the machine's configuration in directory `cluster/my-machine`.\n\n7. Update pre-configured software pins to fetch current nixpkgs:\n```\nconfctl swpins update\n```\n\n8. Build the machine\n```\nconfctl build my-machine\n```\n\n9. Deploy the machine\n```\nconfctl deploy my-machine\n```\n\n## Example configuration\nExample configuration, which can be used as a starting point, can be found in\ndirectory [example/](example/).\n\nSee also existing configurations:\n\n* [vpsfree-cz-configuration](https://github.com/vpsfreecz/vpsfree-cz-configuration)\n* [vpsadminos-org-configuration](https://github.com/vpsfreecz/vpsadminos-org-configuration)\n\n## Configuration directory structure\n`confctl` configurations should adhere to the following structure:\n\n    cluster-configuration/      # Configuration root\n    ├── cluster/                # Machine configurations\n    │   ├── \u003cname\u003e/             # Single machine, can be nested directories\n    │   │   ├── config.nix      # Standard NixOS system configuration\n    │   │   └── module.nix      # Config with machine metadata used by confctl\n    │   ├── cluster.nix         # confctl-generated list of machines\n    │   └── module-list.nix     # List of all machine modules (including those in cluster.nix)\n    ├── configs/                # confctl and other user-defined configs\n    │   ├── confctl.nix         # Configuration for the confctl tool itself\n    │   └── swpins.nix          # User-defined software pin channels\n    ├── data/                   # User-defined datasets available in machine configurations as confData\n    ├── environments/           # Environment presets for various types of machines, optional\n    ├── modules/                # User-defined modules\n    │   └── cluster/default.nix # User-defined extensions of `cluster.` options used in `\u003cmachine\u003e/module.nix` files\n    ├── scripts/                # User-defined scripts\n    ├── swpins/                 # confctl-generated software pins configuration\n    └── shell.nix               # Nix expression for nix-shell\n\n## Software pins\nSoftware pins in confctl allow you to use specific revisions of\n[nixpkgs](https://github.com/NixOS/nixpkgs) or any other software to build\nand deploy target machines. It doesn't matter what nixpkgs version the build\nmachine uses, because each machine gets its own nixpkgs as configured by the\nsoftware pin.\n\nSoftware pins can be grouped in channels, which can then be used by all\nor selected machines in the configuration. Or, if needed, custom software pins\ncan be configured on selected machines. See below for usage examples.\n\n## Software pin channels\nSoftware pin channels are defined in file `confctl/swpins.nix`:\n\n```nix\n{ config, ... }:\n{\n  confctl.swpins.channels = {\n    # Channel for NixOS unstable\n    nixos-unstable = {  # channel name\n      nixpkgs = {  # swpin name\n        # git-rev fetches the contents of a git commit and adds information\n        # about the current git revision\n        type = \"git-rev\";\n\n        git-rev = {  # swpin type-specific configuration\n          # Repository URL\n          url = \"https://github.com/NixOS/nixpkgs\";\n\n          # Fetch git submodules or not\n          fetchSubmodules = false;\n\n          # git reference to use for manual/automated update using\n\t  # `confctl swpins channel update`\n          update.ref = \"refs/heads/nixos-unstable\";\n\n          # Whether to enable automated updates triggered by `confctl build | deploy`\n          update.auto = true;\n\n          # If update.auto is true, this determines how frequently will confctl\n          # try to update the channel, in seconds\n          update.interval = 60*60;\n\t};\n      };\n    };\n\n    # Channel for vpsAdminOS staging\n    vpsadminos-staging = {\n      vpsadminos = {\n        type = \"git-rev\";\n\n        git-rev = {\n          url = \"https://github.com/vpsfreecz/vpsadminos\";\n          update.ref = \"refs/heads/staging\";\n\t  update.auto = true;\n        };\n      };\n    };\n  };\n}\n```\n\nThis configuration defines what channels exist, what packages they contain\nand how to fetch them. Such configured channels can then be manipulated using\n`confctl`. `confctl` prefetches selected software pins and saves their hashes\nin JSON files in the `swpins/` directory.\n\n```\n# List channels\n$ confctl swpins channel ls\nCHANNEL             SW           TYPE      PIN\nnixos-unstable      nixpkgs      git-rev   1f77a4c8\nvpsadminos-staging  vpsadminos   git-rev   9c9a7bcb\n\n# Update channels with update.auto = true to reference in update.ref\n$ confctl swpins channel update\n\n# You can update only selected channels or swpins\n$ confctl swpins channel update nixos-unstable\n$ confctl swpins channel update nixos-unstable nixpkgs\n\n# Set swpin to a custom git reference\n$ confctl swpins channel set nixos-unstable nixpkgs 1f77a4c8\n```\n\n`confctl build` and `confctl deploy` will now use the prefetched software pins.\n\n## Machine metadata and software pins\nMachine configuration directory usually contains at least two files:\n`cluster/\u003cmachine name\u003e/config.nix` and `cluster/\u003cmachine name\u003e/module.nix`.\n\n`config.nix` is evaluated only when that particular machine is being built. It is\na standard NixOS configuration module, similar to `/etc/nixos/configuration.nix`.\n\n`module.nix` is specific to confctl configurations. `module.nix` files from\nall machines are evaluated during every build, whether that particular machine\nis being built or not. `module.nix` contains metadata about machines from which\nconfctl knows how to treat them. It is also used to declare which software pins\nor channels the machine uses. Metadata about any machine can be read from\n`config.nix` of any other machine.\n\nFor example, machine named `my-machine` would be described in\n`cluster/my-machine/module.nix` as:\n\n```nix\n{ config, ... }:\n{\n  cluster.\"my-machine\" = {\n    # This tells confctl whether it is a NixOS or vpsAdminOS machine\n    spin = \"nixos\";\n\n    # Use NixOS unstable channel defined in configs/swpins.nix\n    swpins.channels = [ \"nixos-unstable\" ];\n\n    # If the machine name is not a hostname, configure the address to which\n    # should confctl deploy it\n    host.target = \"\u003cip address\u003e\";\n  };\n}\n```\n\nSee [man/man8/confctl-options.nix.8.md](./man/man8/confctl-options.nix.8.md)\nfor a list of all options.\n\n## Per-machine software pins\nIt is simpler to use software pins from channels, because they are usually\nused by multiple machines, but it is possible to define per-machine software\npins, either to override pins from channels or add custom ones.\n\nPer-machine software pins are configured in the machine's `module.nix` file:\n\n```nix\n{ config, ... }:\n{\n  cluster.\"my-machine\" = {\n    # List of channels\n    swpins.channels = [ \"...\" ];\n\n    # Per-machine swpins\n    swpins.pins = {\n      \"pin-name\" = {\n          type = \"git-rev\";\n\t  git-rev = {\n            # ...pin definition...\n\t  };\n       };\n    };\n  };\n}\n```\n\nThe configuration is exactly the same as that of software pins in channels.\nInstead of `confctl swpins channel` commands, use `confctl swpins cluster`\nto manage configured pins.\n\n## Nix flakes\nconfctl's software pins are an alternative to flakes and flakes are not supported\nby confctl at this time. Software pins are implemented by manipulating the `$NIX_PATH`\nenvironment variable, which is in conflict with using flakes. confctl is likely\nto be migrated to flakes when the interface will be stabilized. Since the transition\nis going to require a significant effort, there are no plans for it currently.\n\n## Extra module arguments\nMachine configs can use the following extra module arguments:\n\n- `confDir` - path to the cluster configuration directory\n- `confLib` - confctl functions, see [nix/lib/default.nix](nix/lib/default.nix)\n- `confData` - access to user-defined datasets found in `data/default.nix`,\n  see [example/data/default.nix](example/data/default.nix)\n- `confMachine` - attrset with information about the machine that is currently\n  being built, contains key `name` and all options from\n  [machine metadata module](##machine-metadata-and-software-pins)\n- `swpins` - attrset of software pins of the machine that is currently being built\n\nFor example in `cluster/my-machine/config.nix`:\n\n```nix\n{ config, lib, pkgs, confLib, confData, confMachine, ... }:\n{\n  # Set the hostname to the machine name from confctl\n  networking.hostName = confMachine.name;\n\n  # When used with the data defined at example/data/default.nix\n  users.users.root.openssh.authorizedKeys.keys = with confData.sshKeys; admins;\n}\n```\n\n## confctl configuration\nThe `confctl` utility itself can be configured using `configs/confctl.nix`:\n\n```nix\n{ config, ... }:\n{\n  confctl = {\n    # Columns that are shown by `confctl ls`. Any option from machine metadata\n    # can be used.\n    listColumns = {\n      \"name\"\n      \"spin\"\n      \"host.fqdn\"\n    };\n  };\n}\n```\n\n## Health checks\nHealth checks can be used to verify that the deployed systems behave correctly,\nall services are running, etc. Health checks are run automatically after deploy\nand can also be run on demand using `confctl health-check`. Health checks are\nconfigured in machine metadata module, i.e. in `cluster/\u003cmachine\u003e/module.nix`\nfiles.\n\n```nix\n{ config, ... }:\n{\n  cluster.\"my-machine\" = {\n    # [...]\n\n    healthChecks = {\n      # Check that there are no failed units (this is actually done automatically\n      # by confctl, you don't need to do this yourself)\n      systemd.systemProperties = [\n        { property = \"SystemState\"; value = \"running\"; }\n      ];\n\n      # Check that the firewall is active, we can check any property of any service\n      systemd.unitProperties.\"firewall.service\" = [\n        { property = \"ActiveState\"; value = \"active\"; }\n      ];\n\n      # Run arbitrary commands from the builder\n      builderCommands = [\n        # Ping the deployed machine\n        { command = [ \"ping\" \"-c1\" \"{host.fqdn}\" ]; }\n      ];\n\n      # Run commands on the deployed machine\n      machineCommands = [\n        # Try to access a fictional internal web server\n        { command = [ \"curl\" \"-s\" \"http://localhost:80\" ]; }\n\n        # We can also check command output\n        { command = [ \"hostname\" ]; standardOutput.match = \"my-machine\\n\"; }\n      ];\n    };\n  };\n}\n```\n\n## Rotate build generations\nconfctl can be used to rotate old generations both on the build machine\nand on the deployed machines.\n\nDefault rotation settings can be set in confctl settings at `configs/confctl.nix`:\n\n```nix\n{ config, lib, ... }:\nwith lib;\n{\n  confctl = {\n    # Generations on the build machine\n    buildGenerations = {\n      # Keep at least 4 generations\n      min = mkDefault 4;\n\n      # Do not keep more than 10 generations\n      max = mkDefault 10;\n\n      # Delete generations older than 90 days\n      maxAge = mkDefault (90*24*60*60);\n    };\n\n    # The same settings can be configured for generations on the deployed machines\n    hostGenerations = {\n      min = mkDefault 40;\n      max = mkDefault 100;\n      maxAge = mkDefault (180*24*60*60);\n\n      # On the deployed machines, confctl can also run nix-collect-garbage to\n      # delete unreachable store paths\n      collectGarbage = mkDefault true;\n    };\n  };\n}\n```\n\nIf these settings are not set, confctl uses its own defaults. Further, rotation\nsettings can be configured on per-machine basis in machine metadata module\nat `cluster/\u003cmachine\u003e/module.nix`:\n\n```nix\n{ config, ... }:\n{\n  cluster.\"my-machine\" = {\n    # [...]\n\n    buildGenerations = {\n      min = 8;\n      max = 16;\n    };\n\n    hostGenerations = {\n      min = 80;\n    };\n  };\n}\n```\n\nSettings from the machine metadata modules override default confctl settings\nfrom `configs/confctl.nix`.\n\nTo rotate the generations both on the build and deployed machines, run:\n\n```\nconfctl generation rotate --local --remote\n```\n\nGenerations can also be deleted manually, e.g. to delete generations older than\n90 days, run:\n\n```\nconfctl generation rm --local --remote '*' 30d\n```\n\n## Extending machine metadata\nTo define your own options to be used within the `cluster.\u003cname\u003e` modules in\n`cluster/\u003cmachine\u003e/module.nix` files, create file `modules/cluster/default.nix`,\ne.g.:\n\n```nix\n{ config, lib, ... }:\nwith lib;\nlet\n  myMachine =\n    { config, ... }:\n    {\n      options = {\n        myParameter = mkOption { ... };\n      };\n    };\nin {\n  options = {\n    cluster = mkOption {\n      type = types.attrsOf (types.submodule myMachine);\n    };\n  };\n}\n```\n\nThen you can use it in machine module as:\n\n```nix\n{ config, ... }:\n{\n  cluster.\"my-machine\" = {\n    myParameter = \"1234\";\n  };\n}\n```\n\nNote that these modules are self-contained. They are not evaluated with the full\nset of NixOS modules. You have to import modules that you need.\n\n## User-defined confctl commands\nUser-defined Ruby scripts can be placed in directory `scripts`. Each script\nshould create a subclass of `ConfCtl::UserScript` and call class-method `register`.\nScripts can define their own `confctl` subcommands.\n\n### Example user script\n\n```ruby\nclass MyScript \u003c ConfCtl::UserScript\n  register\n\n  def setup_cli(app)\n    app.desc 'My CLI command'\n    app.command 'my-command' do |c|\n      c.action \u0026ConfCtl::Cli::Command.run(c, MyCommand, :run)\n    end\n  end\nend\n\nclass MyCommand \u003c ConfCtl::Cli::Command\n  def run\n    puts 'Hello world'\n  end\nend\n```\n\n## More information\nSee the [man pages](./man/man8) for more information:\n\n* [confctl(8)](./man/man8/confctl.8.md)\n* [confctl-options.nix(8)](./man/man8/confctl-options.nix.8.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvpsfreecz%2Fconfctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvpsfreecz%2Fconfctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvpsfreecz%2Fconfctl/lists"}