NSL options

Everything under nsl in a NixOS configuration, generated from nix/module.nix. Start with the README if you have not.

nsl.enable

Whether to enable NSL, foreign Linux distributions in systemd-nspawn machines.

Type: boolean

Default:

false

Example:

true

Declared by:

• nix/module.nix

nsl.package

The nsl command line tool and bootstrap helper to use.

Type: package

Default: the nsl package from this flake

Declared by:

• nix/module.nix

nsl.defaultUser

Host user mirrored into every machine that does not set its own.

Type: null or string

Default:

null

Example:

"alice"

Declared by:

• nix/module.nix

nsl.imageServer

Image server to download root filesystems from. It must publish the simplestreams-style index at /meta/1.0/index-system and a SHA256SUMS next to each image.

Type: string

Default:

"https://images.linuxcontainers.org"

Declared by:

• nix/module.nix

nsl.machines

Machines to make available, each running in its own systemd-nspawn container.

Type: attribute set of (submodule)

Default:

{ }

Example:

{
  ubuntu.distro = "ubuntu";
  arch = {
    distro = "archlinux";
    packages = [ "base-devel" ];
  };
}

Declared by:

• nix/module.nix

nsl.machines.<name>.packages

Packages installed once during bootstrap, named as the machine’s own package manager names them. Adding packages later has no effect until the machine is rebuilt with nsl reset; install them from inside instead.

Type: list of string

Default:

[ ]

Example:

[
  "git"
  "build-essential"
]

Declared by:

• nix/module.nix

nsl.machines.<name>.aurPackages

AUR packages installed once during bootstrap with yay, which is itself built from the AUR first. Only for archlinux machines with a user, since makepkg refuses to run as root.

Type: list of string

Default:

[ ]

Example:

[
  "visual-studio-code-bin"
]

Declared by:

• nix/module.nix

nsl.machines.<name>.autoStart

Start this machine at boot. When false the machine is started on demand by nsl shell or nsl start.

Note that with this enabled the first nixos-rebuild switch after declaring the machine waits for the image download to finish.

Type: boolean

Default:

false

Declared by:

• nix/module.nix

nsl.machines.<name>.bindHome

Bind mount the mirrored user’s home directory from the host.

Type: boolean

Default: true when user is set

Declared by:

• nix/module.nix

nsl.machines.<name>.bindMounts

Additional host directories to bind mount into the machine.

Type: list of (submodule)

Default:

[ ]

Example:

[
  {
    hostPath = "/srv/data";
    mountPoint = "/data";
  }
]

Declared by:

• nix/module.nix

nsl.machines.<name>.bindMounts.*.hostPath

Directory on the host.

Type: string

Declared by:

• nix/module.nix

nsl.machines.<name>.bindMounts.*.mountPoint

Where it appears inside the machine.

Type: string

Default: hostPath

Declared by:

• nix/module.nix

nsl.machines.<name>.bindMounts.*.readOnly

Mount read-only.

Type: boolean

Default:

false

Declared by:

• nix/module.nix

nsl.machines.<name>.distro

Distribution to install, as named by the image server index.

Type: one of “almalinux”, “archlinux”, “centos”, “debian”, “fedora”, “kali”, “nixos”, “opensuse”, “rockylinux”, “ubuntu”

Example:

"debian"

Declared by:

• nix/module.nix

nsl.machines.<name>.extraBootstrap

Shell commands run as root inside the machine at the end of bootstrap. Runs once, like packages.

Type: strings concatenated with “\n”

Default:

""

Example:

"locale-gen en_US.UTF-8"

Declared by:

• nix/module.nix

nsl.machines.<name>.image

Root filesystem tarball to import instead of downloading one. Use this to pin an image, or to bootstrap without network access. The tarball must unpack to a root filesystem containing /etc/os-release and an init at /sbin/init.

Type: null or absolute path

Default:

null

Example:

pkgs.fetchurl { url = "..."; hash = "..."; }

Declared by:

• nix/module.nix

nsl.machines.<name>.nspawn

Settings merged into systemd.nspawn.<name>, taking precedence over what NSL generates. See systemd.nspawn(5).

Type: attribute set of attribute set of anything

Default:

{ }

Example:

{
  execConfig = {
    Capability = "CAP_NET_ADMIN";
  };
}

Declared by:

• nix/module.nix

nsl.machines.<name>.privateNetwork

Give the machine its own network namespace, connected to the host by a virtual ethernet link, instead of sharing the host’s network.

This needs systemd.network.enable on the host and is less well tested than the shared default.

Type: boolean

Default:

false

Declared by:

• nix/module.nix

nsl.machines.<name>.privateUsers

Run the machine in its own user namespace, so its root is not the host’s root. Bind mounts are then id-mapped, which the filesystem holding them must support.

Type: boolean

Default:

false

Declared by:

• nix/module.nix

nsl.machines.<name>.release

Release to install. Run nsl images <distro> to see what the image server currently offers; it only keeps the last few daily builds of each release.

Type: string

Default: the current release of distro

Example:

"trixie"

Declared by:

• nix/module.nix

nsl.machines.<name>.shell

Login shell of the mirrored user. This is a path inside the machine, not on the host.

Type: string

Default:

"/bin/bash"

Declared by:

• nix/module.nix

nsl.machines.<name>.user

Host user to mirror inside the machine. A user with the same name, uid, gid and home directory is created at bootstrap and given passwordless sudo. Set to null for a machine with only root.

Type: null or string

Default:

config.nsl.defaultUser

Example:

"alice"

Declared by:

• nix/module.nix

nsl.machines.<name>.variant

Image variant, the fourth column of the image server index. The default variant is the one NSL is built for; cloud images run cloud-init and are not useful here.

Type: string

Default:

"default"

Declared by:

• nix/module.nix

nsl.users

Host users allowed to start, stop and enter NSL machines without authenticating. Users mirrored into a machine are granted this anyway.

Type: list of string

Default:

[ ]

Declared by:

• nix/module.nix