NixOS modules

NixOS has modules to have non-intrusive extensions. Modules are made to avoid manipulating the core of NixOS while allowing the user to separate their configuration.nix file into multiple sub-file which are specific to a device or a service configuration. Such separation permits the creation of services which can be tested for a while before being merged in the main line of NixOS.

This page describes how you can create a module. If you want a pratical view, you should have a look into this small tutorial.

Vocabulary

• Declaration: All options which are used with the mkOption function are declared. Declared options should at least have a description attribute which contains a multiple-line text for describing the effect of the option.
• Definition: All options which are set to plain values are considered as definitions. The plain value may vary depending on the expected type of the option.
• Use: All result of options which are used to compute values of other option are option usages.
• Properties: These are option definition modifiers. Properties may change the influence of an option definition in the computation of an option result.

To find all files which are defining or declaring an option, you may refer to the generated NixOS manual or to the man page of configuration.nix.

Syntax

Modules are declared with the following syntax:

{
  imports = [
    # list of path to other modules.
  ];

  options = {
    # attribute set of option declarations.
  };

  config = {
    # attribute set of option definitions.
  };
}

Another syntax exists for cases where no option declaration are necessary:

{
  require = [
    # list of path to other modules.
  ];

  # attribute set of option definitions.
}

Both of the previous syntax can be refined with an attribute set argument added on top:

{config, pkgs, ...}:

{
  # ...
}

The following arguments can be retrieved from this attribute set:

• config: The configuration of the entire system.
• options: All option declarations refined with all definition and declaration references.
• pkgs: The attribute set extracted from the Nix package collection and enhanced with the nixpkgs.config option.
• modulesPath: The location of the module directory of NixOS.

For more information, you should refer to NixOS sources, with more insight into nixos/lib/eval-config.nix.

More computation or organisation can be necessary to enhance modules. In which case, you can add a let .. in .. statement between the argument and the attribute set.

{config, pkgs, ...}:

let
  # intermediate result.
in

{
  # ...
}

Example Module

put into hello.nix in the same folder as your configuration.nix.

{ lib, pkgs, config, ... }:
with lib;                      
let
  cfg = config.services.hello;
in {
  options.services.hello = {
    enable = mkEnableOption "hello service";
    greeter = mkOption {
      type = types.string;
      default = "world";
    };
  };

  config = lib.mkIf cfg.enable {
    systemd.services.hello = {
      wantedBy = [ "multi-user.target" ];
      serviceConfig.ExecStart = "${pkgs.hello}/bin/hello -g'Hello, ${escapeShellArg cfg.greeter}!'";
    };
  };
}

Add the following to your configuration.nix

{
  imports = [ ./hello.nix ];
  ...
  services.hello = {
    enable = true;
    greeter = "Bob";
  };
}

Compatibility Issues with Different Nixpkgs Versions

Module options between Nixpkgs revisions can sometimes change in incompatible ways.

For example, the option services.nginx.virtualHosts.*.port in nixpkgs-17.03 was replaced by services.nginx.virtualHosts.*.listen in nixpkgs-17.09. If configuration.nix has to accommodate both variants, options can be inspected:

{ options, ... }: {
  services.nginx.virtualHosts.somehost = { /* common configuration */ }
    // (if builtins.hasAttr "port" (builtins.head options.services.nginx.virtualHosts.type.getSubModules).submodule.options
          then { port = 8000; }
          else { listen = [ { addr = "0.0.0.0"; port = 8000; } ]; });
}

References

• NixOS Documentation

Related Work

• Debian Config::Model:

target configuration upgrades by abstracting the option of the configuration. Each file is a tree structure where leaves are values defined with an interpreted type. The interpreters are defined for each meta-configuration files name *.conf. Configuration files does not seems to interact with each other to make consistent configuration. They provide an UI for editing their configuration file.