Skip to content

BuildClan

This provides an overview of the available arguments of the clan interface.

Each attribute is documented below

  • buildClan: A function that takes an attribute set.`.

    buildClan Example 
    buildClan {
    directory = self;
    machines = {
        jon = { };
        sara = { };
    };
};

  • flake-parts: Each attribute can be defined via clan.<attribute name>. See our flake-parts guide.

    flake-parts Example 
    flake-parts.lib.mkFlake { inherit inputs; } ({
    systems = [];
    imports = [
        clan-core.flakeModules.default
    ];
    clan = {
        machines = {
            jon = { };
            sara = { };
        };
    };
});

directory

Attribute: directory

The directory containing the clan.

A typical directory structure could look like this:

.
├── flake.nix
├── assets
├── machines
├── modules
└── sops

Type: path

Default:

"Root directory of the flake"

interface.nix

inventory

Attribute: inventory

The Inventory submodule.

For details see the Inventory documentation.

Type: submodule

interface.nix

machines

Attribute: inventory.machines

Machines in the inventory.

Each machine declared here can be referencd via its attributeName by the inventory.services roles.

Type: attribute set of (submodule)

Default:

{ }

interface.nix

deploy

Attribute: inventory.machines.<name>.deploy

targetHost

Attribute: inventory.machines.<name>.deploy.targetHost

Configuration for the deployment of the machine

Type: null or string

Default:

null

interface.nix

description

Attribute: inventory.machines.<name>.description

Optional freeform description

Type: null or string

Default:

null

interface.nix

icon

Attribute: inventory.machines.<name>.icon

Under construction, will be used for the UI

Type: null or string

Default:

null

interface.nix

name

Attribute: inventory.machines.<name>.name

Name of the machine or service

Type: string

Default:

"‹name›"

interface.nix

tags

Attribute: inventory.machines.<name>.tags

List of tags for the machine.

The machine can be referenced by its tags in inventory.services

Example 
inventory.machines.machineA.tags = [ "tag1" "tag2" ];

services.borgbackup."instance_1".roles.client.tags = [ "tag1" ];

Note

Tags can be used to determine the membership of the machine in the services. Without changing the service configuration, the machine can be added to a service by adding the correct tags to the machine.

Type: list of string

Default:

[ ]

interface.nix

meta

Attribute: inventory.meta

This option has no description.

Type: submodule

interface.nix

description

Attribute: inventory.meta.description

Optional freeform description

Type: null or string

Default:

null

meta-interface.nix

icon

Attribute: inventory.meta.icon

Under construction, will be used for the UI

Type: null or string

Default:

null

meta-interface.nix

name

Attribute: inventory.meta.name

Name of the clan.

Needs to be (globally) unique, as this determines the folder name where the flake gets downloaded to.

Type: string

meta-interface.nix

modules

Attribute: inventory.modules

A mapping of module names to their path.

Each module can be referenced by its attributeName in the inventory.services attribute set.

Important

Each module MUST fulfill the following requirements to be usable with the inventory:

  • The module MUST have a README.md file with a description.
  • The module MUST have at least features = [ "inventory" ] in the frontmatter section.
  • The module MUST have a subfolder roles with at least one {roleName}.nix file.

For further information see: Module Authoring Guide.

Example 
buildClan {
    # 1. Add the module to the available inventory modules
    inventory.modules = {
      custom-module = ./modules/my_module;
    };
    # 2. Use the module in the inventory
    inventory.services = {
      custom-module.instance_1 = {
          roles.default.machines = [ "machineA" ];
      };
    };
};

Type: attribute set of path

Default:

"clanModules of clan-core"

interface.nix

services

Attribute: inventory.services

Services of the inventory.

  • The first <name> is the moduleName. It must be a valid clanModule name.
  • The second <name> is an arbitrary instance name.
Example 
#        ClanModule name. See the module documentation for the available modules.
#        ↓          ↓ Instance name, can be anything, some services might use it as a unique identifier.
services.borgbackup."instance_1" = {
  roles.client.machines = ["machineA"];
};

Note

Services MUST be added to machines via roles exclusively. See roles.<rolename>.machines or roles.<rolename>.tags for more information.

Type: attribute set of attribute set of (submodule)

Default:

{ }

interface.nix

config

Attribute: inventory.services.<name>.<name>.config

Configuration of the specific clanModule.

Note

Configuration is passed to the nixos configuration scoped to the module.

  clan.<serviceName> = { ... # Config }
Example

For services.borgbackup the config is the passed to the machine with the prefix of clan.borgbackup. This means all config values are mapped to the borgbackup clanModule exclusively (config.clan.borgbackup).

{
  services.borgbackup."instance_1".config = {
    destinations = [ ... ];
    # See the 'borgbackup' module docs for all options
  };
}

Note

The module author is responsible for supporting multiple instance configurations in different roles. See each clanModule's documentation for more information.

Type: attribute set of anything

Default:

{ }

interface.nix

enabled

Attribute: inventory.services.<name>.<name>.enabled

Enable or disable the complete service.

If the service is disabled, it will not be added to any machine.

Note

This flag is primarily used to temporarily disable a service. I.e. A 'backup service' without any 'server' might be incomplete and would cause failure if enabled.

Type: boolean

Default:

true

interface.nix

extraModules

Attribute: inventory.services.<name>.<name>.extraModules

List of additionally imported .nix expressions.

Supported types:

  • Strings: Interpreted relative to the 'directory' passed to buildClan.
  • Paths: should be relative to the current file.
  • Any: Nix expression must be serializable to JSON.

Note

The import only happens if the machine is part of the service or role.

Other types are passed through to the nixos configuration.

Example

To import the special.nix file

. Clan Directory
├── flake.nix
...
└── modules
    ├── special.nix
    └── ...

{
  extraModules = [ "modules/special.nix" ];
}

Type: list of (string or anything)

Default:

[ ]

interface.nix

machines

Attribute: inventory.services.<name>.<name>.machines

Attribute set of machines specific config for the service.

Will be merged with other service configs, such as the role config and the global config. For machine specific overrides use mkForce or other higher priority methods.

Example 
services.borgbackup."instance_1" = {
  roles.client.machines = ["machineA"];

  machines.machineA.config = {
    # Additional specific config for the machine
    # This is merged with all other config places
  };
};

Type: attribute set of (submodule)

Default:

{ }

interface.nix

config

Attribute: inventory.services.<name>.<name>.machines.<name>.config

Additional configuration of the specific machine.

See how service.<name>.<name>.config works in general for further information.

Type: attribute set of anything

Default:

{ }

interface.nix

extraModules

Attribute: inventory.services.<name>.<name>.machines.<name>.extraModules

List of additionally imported .nix expressions.

Supported types:

  • Strings: Interpreted relative to the 'directory' passed to buildClan.
  • Paths: should be relative to the current file.
  • Any: Nix expression must be serializable to JSON.

Note

The import only happens if the machine is part of the service or role.

Other types are passed through to the nixos configuration.

Example

To import the special.nix file

. Clan Directory
├── flake.nix
...
└── modules
    ├── special.nix
    └── ...

{
  extraModules = [ "modules/special.nix" ];
}

Type: list of (string or anything)

Default:

[ ]

interface.nix

meta

Attribute: inventory.services.<name>.<name>.meta

description

Attribute: inventory.services.<name>.<name>.meta.description

Optional freeform description

Type: null or string

Default:

null

interface.nix

icon

Attribute: inventory.services.<name>.<name>.meta.icon

Under construction, will be used for the UI

Type: null or string

Default:

null

interface.nix

name

Attribute: inventory.services.<name>.<name>.meta.name

Name of the machine or service

Type: string

Default:

"‹name›"

interface.nix

roles

Attribute: inventory.services.<name>.<name>.roles

This option has no description.

Type: attribute set of (submodule)

Default:

{ }

interface.nix

config

Attribute: inventory.services.<name>.<name>.roles.<name>.config

Additional configuration of the specific role.

See how service.<name>.<name>.config works in general for further information.

Type: attribute set of anything

Default:

{ }

interface.nix

extraModules

Attribute: inventory.services.<name>.<name>.roles.<name>.extraModules

List of additionally imported .nix expressions.

Supported types:

  • Strings: Interpreted relative to the 'directory' passed to buildClan.
  • Paths: should be relative to the current file.
  • Any: Nix expression must be serializable to JSON.

Note

The import only happens if the machine is part of the service or role.

Other types are passed through to the nixos configuration.

Example

To import the special.nix file

. Clan Directory
├── flake.nix
...
└── modules
    ├── special.nix
    └── ...

{
  extraModules = [ "modules/special.nix" ];
}

Type: list of (string or anything)

Default:

[ ]

interface.nix

machines

Attribute: inventory.services.<name>.<name>.roles.<name>.machines

List of machines which are part of the role.

The machines are referenced by their attributeName in the inventory.machines attribute set.

Memberships are declared here to determine which machines are part of the service.

Alternatively, tags can be used to determine the membership, more dynamically.

Type: list of string

Default:

[ ]
Example 
[
  "machineA"
]

interface.nix

tags

Attribute: inventory.services.<name>.<name>.roles.<name>.tags

List of tags which are used to determine the membership of the role.

The tags are matched against the inventory.machines.<machineName>.tags attribute set. If a machine has at least one tag of the role, it is part of the role.

Type: list of string

Default:

[ ]

interface.nix

tags

Attribute: inventory.tags

Tags of the inventory are used to group machines together.

It is recommended to use machine.tags to define the tags of the machines.

This can be used to define custom tags that are either statically set or dynamically computed.

Static Tags

Static Tag Example 
inventory.tags = {
  foo = [ "machineA" "machineB" ];
};

The tag foo will always be added to machineA and machineB.

Dynamic Tags

It is possible to compute tags based on the machines properties or based on other tags.

Danger

This is a powerful feature and should be used with caution.

It is possible to cause infinite recursion by computing tags based on the machines properties or based on other tags.

Dynamic Tag Example

allButFoo is a computed tag. It will be added to all machines except 'foo'

all is a predefined tag. See the docs of tags.all.

#  inventory.tags ↓       ↓ inventory.machines
inventory.tags = {config, machines...}: {
  #                                                        ↓↓↓ The "all" tag
  allButFoo = builtins.filter (name: name != "foo") config.all;
};

Warning

Do NOT compute tags from machine.tags this will cause infinite recursion.

Type: lazy attribute set of list of string

Default:

{ }

interface.nix

all

Attribute: inventory.tags.all

Predefined Tag

Will be added to all machines

inventory.machines.machineA.tags = [ "all" ];

Type: list of string

Default:

"[ <All Machines> ]"

interface.nix

machines

Attribute: machines

A mapping of machine names to their nixos configuration.

Example 
machines = {
  my-machine = {
    # Your nixos configuration
  };
};

Type: attribute set of module

Default:

{ }

interface.nix

meta

Attribute: meta

Global information about the clan.

Type: module

Default:

{ }

interface.nix

description

Attribute: meta.description

Optional freeform description

Type: null or string

Default:

null

meta-interface.nix

icon

Attribute: meta.icon

Under construction, will be used for the UI

Type: null or string

Default:

null

meta-interface.nix

name

Attribute: meta.name

Name of the clan.

Needs to be (globally) unique, as this determines the folder name where the flake gets downloaded to.

Type: string

meta-interface.nix

pkgsForSystem

Attribute: pkgsForSystem

A function that maps from architecture to pkg. ( string -> pkgs )

If specified this nixpkgs will be only imported once for each system. This improves performance, but all nixpkgs.* options will be ignored.

Returning null for a system will fallback to the default behavior of respecting the nixpkgs.* options.

Type: function that evaluates to a(n) (null or (attribute set))

Default:

"system: null"

interface.nix

specialArgs

Attribute: specialArgs

Extra arguments to pass to nixosSystem i.e. useful to make self available

Type: attribute set of raw value

Default:

{ }

interface.nix