Appendix A. nix-on-droid configuration options

Activation scripts for the Nix-on-Droid environment.

Any script should respect the DRY_RUN variable, if it is set then no actual action should be taken. The variable DRY_RUN_CMD is set to echo if dry run is enabled. Thus, many cases you can use the idiom $DRY_RUN_CMD rm -rf /.

Any script block should also respect the VERBOSE variable, and if set print information on standard out that may be useful for debugging any issue that may arise. The variable VERBOSE_ARG is set to --verbose if verbose output is enabled. The variable VERBOSE_ECHO is set to echo if verbose output is enabled, otherwise falling back to true. So it can be used like $VERBOSE_ECHO "any message".

Type: attribute set

Default: { }

Declared by:

Activation scripts for the Nix-on-Droid environment that need to be run last.

Any script should respect the DRY_RUN variable, if it is set then no actual action should be taken. The variable DRY_RUN_CMD is set to echo if dry run is enabled. Thus, many cases you can use the idiom $DRY_RUN_CMD rm -rf /.

Any script block should also respect the VERBOSE variable, and if set print information on standard out that may be useful for debugging any issue that may arise. The variable VERBOSE_ARG is set to --verbose if verbose output is enabled. The variable VERBOSE_ECHO is set to echo if verbose output is enabled, otherwise falling back to true. So it can be used like $VERBOSE_ECHO "any message".

Type: attribute set

Default: { }

Declared by:

Activation scripts for the Nix-on-Droid environment that need to be run first.

Any script should respect the DRY_RUN variable, if it is set then no actual action should be taken. The variable DRY_RUN_CMD is set to echo if dry run is enabled. Thus, many cases you can use the idiom $DRY_RUN_CMD rm -rf /.

Any script block should also respect the VERBOSE variable, and if set print information on standard out that may be useful for debugging any issue that may arise. The variable VERBOSE_ARG is set to --verbose if verbose output is enabled. The variable VERBOSE_ECHO is set to echo if verbose output is enabled, otherwise falling back to true. So it can be used like $VERBOSE_ECHO "any message".

Type: attribute set

Default: { }

Declared by:

Extra options passed to proot, e.g., extra bind mounts.

Type: list of string

Default: [ ]

Declared by:

List of packages to be installed as user packages.

Type: list of package

Default: [ ]

Declared by:

Path to /bin/sh executable.

Type: string (read only)

Declared by:

Set of files that have to be linked in /etc.

Type: attribute set of (submodule)

Default: { }

Example:

{
  example-configuration-file = {
    source = "/nix/store/.../etc/dir/file.conf.example";
  };
  "default/useradd".text = "GROUP=100 ...";
}

Declared by:

Whether this /etc file should be generated. This option allows specific /etc files to be disabled.

Type: boolean

Default: true

Declared by:

Path of the source file.

Type: path

Declared by:

Name of symlink (relative to /etc). Defaults to the attribute name.

Type: string

Declared by:

Text of the file.

Type: null or strings concatenated with "\n"

Default: null

Declared by:

Backup file extension.

If a file in /etc already exists and is not managed by Nix-on-Droid, the activation fails because we do not overwrite unknown files. When an extension is provided through this option, the original file will be moved in respect of the backup extension and the activation executes successfully.

Type: null or string

Default: null

Example: ".bak"

Declared by:

List of additional package outputs to be installed as user packages.

Type: list of string

Default: [ ]

Example:

[
  "doc"
  "info"
  "devdoc"
]

Declared by:

Text to show on every new shell created by Nix-on-Droid.

Type: null or strings concatenated with "\n"

Default:

''
  Welcome to Nix-on-Droid!
  If nothing works, open an issue at https://github.com/nix-community/nix-on-droid/issues or try the rescue shell.
''

Declared by:

Environment variables to always set at login.

The values may refer to other environment variables using POSIX.2 style variable references. For example, a variable parameter may be referenced as $parameter or ${parameter}. A default value foo may be given as per ${parameter:-foo} and, similarly, an alternate value bar can be given as per ${parameter:+bar}.

Note, these variables may be set in any order so no session variable may have a runtime dependency on another session variable. In particular code like

environment.sessionVariables = {
  FOO = "Hello";
  BAR = "$FOO World!";
};

may not work as expected. If you need to reference another session variable, then do so inside Nix instead. The above example then becomes

environment.sessionVariables = {
  FOO = "Hello";
  BAR = "${config.environment.sessionVariables.FOO} World!";
};

Type: attribute set

Default: { }

Example:

{
  EDITOR = "emacs";
  GS_OPTIONS = "-sPAPERSIZE=a4";
}

Declared by:

Path to /usr/bin/env executable.

Type: string (read only)

Declared by:

On activation move existing files by appending the given file extension rather than exiting with an error.

Type: null or string

Default: null

Example: "backup"

Declared by:

Home Manager configuration, see https://nix-community.github.io/home-manager/options.html.

Type: null or (submodule)

Default: null

Declared by:

Extra specialArgs passed to Home Manager. This option can be used to pass additional arguments to all modules.

Type: attribute set

Default: { }

Example: { inherit emacs-overlay; }

Declared by:

Extra modules.

Type: list of raw value

Default: [ ]

Example: [ { home.packages = [ nixpkgs-fmt ]; } ]

Declared by:

Whether to enable using the system configuration's pkgs argument in Home Manager. This disables the Home Manager options nixpkgs.* .

Type: boolean

Default: false

Example: true

Declared by:

Whether to enable installation of user packages through the environment.packages option. .

Type: boolean

Default: false

Example: true

Declared by:

Additional verbatim entries to be appended to /etc/hosts. For adding hosts from derivation results, use networking.hostFiles instead.

Type: strings concatenated with "\n"

Default: ""

Example: "192.168.0.1 lanlocalhost"

Declared by:

Files that should be concatenated together to form /etc/hosts.

Type: list of path

Default: Hosts from networking.hosts and networking.extraHosts

Example: [ "${pkgs.my-blocklist-package}/share/my-blocklist/hosts" ]

Declared by:

Locally defined maps of hostnames to IP addresses.

Type: attribute set of list of string

Default: { }

Example:

{
  "127.0.0.1" = [ "foo.bar.baz" ];
  "192.168.0.2" = [ "fileserver.local" "nameserver.local" ];
};

Declared by:

This option specifies the Nix package instance to use throughout the system.

Type: package

Default: pkgs.nix

Declared by:

Extra config to be appended to /etc/nix/nix.conf.

Type: strings concatenated with "\n"

Default: ""

Declared by:

The default Nix expression search path, used by the Nix evaluator to look up paths enclosed in angle brackets (e.g. <nixpkgs>).

Type: list of string

Default: [ ]

Declared by:

A system-wide flake registry.

Type: attribute set of (submodule)

Default: { }

Declared by:

Whether the from reference needs to match exactly. If set, a from reference like nixpkgs does not match with a reference like nixpkgs/nixos-20.03.

Type: boolean

Default: true

Declared by:

The flake input from is rewritten to.

Type: null or (attribute set)

Default: null

Example: nixpkgs

Declared by:

The flake reference to be rewritten.

Type: attribute set of (string or signed integer or boolean or package)

Example:

{
  id = "nixpkgs";
  type = "indirect";
}

Declared by:

The flake reference from is rewritten to.

Type: attribute set of (string or signed integer or boolean or package)

Example:

{
  owner = "my-org";
  repo = "my-nixpkgs";
  type = "github";
}

Declared by:

A list of URLs of substituters. The official NixOS and Nix-on-Droid substituters are added by default.

Type: list of string

Default: [ ]

Declared by:

A list of public keys. When paths are copied from another Nix store (such as a binary cache), they must be signed with one of these keys. The official NixOS and Nix-on-Droid public keys are added by default.

Type: list of string

Default: [ ]

Declared by:

The configuration of the Nix Packages collection. (For details, see the Nixpkgs documentation.) It allows you to set package configuration options.

If null, then configuration is taken from the fallback location, for example, ~/.config/nixpkgs/config.nix.

Note, this option will not apply outside your Nix-on-Droid configuration like when installing manually through nix-env or in your Home Manager config.

If you want to apply it both inside Home Manager and outside you need to include something like

{ pkgs, config, ...}:

{
  # for Nix-on-Droid
  nixpkgs.config = import ./nixpkgs-config.nix;

  # for Home Manager
  home-manager.config.nixpkgs.config = import ./nixpkgs-config.nix;
  # -or-
  home-manager.config =
    { pkgs, ... }:
    {
      # for Home Manager
      nixpkgs.config = import ./nixpkgs-config.nix;
      # for commands like nix-env
      xdg.configFile."nixpkgs/config.nix".source = ./nixpkgs-config.nix;
    };
}

in your Nix-on-Droid configuration.

Type: null or (nixpkgs config)

Default: null

Example:

{
  allowBroken = true;
}

Declared by:

List of overlays to use with the Nix Packages collection. (For details, see the Nixpkgs documentation.) It allows you to override packages globally. This is a function that takes as an argument the original Nixpkgs. The first argument should be used for finding dependencies, and the second should be used for overriding recipes.

If null, then the overlays are taken from the fallback location, for example, ~/.config/nixpkgs/overlays.

Like nixpkgs.config this option only applies within the Nix-on-Droid configuration. See nixpkgs.config for a suggested setup that works both internally for Nix-on-Droid or Home Manager and externally.

Type: null or (list of (nixpkgs overlay))

Default: null

Example:

[ (self: super: {
    openssh = super.openssh.override {
      hpnSupport = true;
      withKerberos = true;
      kerberos = self.libkrb5;
    };
  };
) ]

Declared by:

It is occasionally necessary for Nix-on-Droid to change configuration defaults in a way that is incompatible with stateful data. This could, for example, include switching the default data format or location of a file.

The state version indicates which default settings are in effect and will therefore help avoid breaking program configurations. Switching to a higher state version typically requires performing some manual steps, such as data conversion or moving files.

Type: one of "19.09", "20.03", "20.09", "21.05", "21.11", "22.05", "22.11", "23.05", "23.11", "24.05"

Declared by:

Colorscheme used for the terminal. Acceptable attribute names are: `background`, `foreground`, `cursor` and `color0`-`color15`.

Type: lazy attribute set of string

Default: { }

Example:

{
  background = "#000000";
  foreground = "#FFFFFF";
  cursor = "#FFFFFF";
}

Declared by:

Font used for the terminal.

Type: null or path

Default: null

Example: "${pkgs.terminus_font_ttf}/share/fonts/truetype/TerminusTTF.ttf"

Declared by:

The time zone used when displaying times and dates. See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for a comprehensive list of possible values for this setting. If null, the timezone will default to UTC.

Type: null or string without spaces

Default: null

Example: "America/New_York"

Declared by:

Gid. This value should not be set manually except you know what you are doing.

Type: signed integer

Default: "$(id -g)"

Declared by:

Group name.

Type: string (read only)

Declared by:

Path to home directory.

Type: path (read only)

Declared by:

Path to login shell.

Type: path

Default: ${pkgs.bashInteractive}/bin/bash

Declared by:

Uid. This value should not be set manually except you know what you are doing.

Type: signed integer

Default: "$(id -u)"

Declared by:

User name.

Type: string (read only)

Declared by: