jail.nix/website/static-docs/advanced-configuration.md
Alex David b0a8a22983 Pull remaining default perms into base combinator
`base-permissions.nix` was the source of truth for all of the base
combinators, but it was not documented well anywhere.

To make this easier and more obvious for users, this commit pulls all
remaining custom permissions into a new `base` combinator which is
included by default. This way there is no more undocumented permissions
included by default, they are all documented in the `Default included
combinators` section of the docs.

This should also make it easier to override base permissions because
users can now just specify `base` instead of all of the
`unsafe-add-raw-args` calls unless they really want to change them.
2025-10-10 16:28:45 -07:00

78 lines
2 KiB
Markdown

# Advanced Configuration
All configuration options on this page can be passed into `jail-nix.lib.extend`.
## additionalCombinators
`additionalCombinators` takes in a list of custom combinators to expose under
`jail.combinators` and in jail definitions. If passed a funciton, jail.nix will
inject the builtin combinators.
For example, this creates a `jail` function that exposes a `my-permission`
combinator:
```nix
jail = jail-nix.lib.extend {
inherit pkgs;
additionalCombinators = builtinCombinators: with builtinCombinators; [
my-permission = compose [
(readonly "/foo")
(readonly "/bar")
];
];
};
# Now my-permission is exposed in all the places the builtin combinators are exposed:
jailed-hello = jail "jailed-hello" pkgs.hello (c: with c; [
my-permission
]);
# Alternatively, using jail.combinators:
jailed-hello = jail "jailed-hello" pkgs.hello [
jail.combinators.my-permission
];
```
## basePermissions
By default, jail.nix comes with a base set of permissions that all jails
inherit by default. This configuration option allows you to override these.
The goal of the base permissions are to provide a reasonably secure default
with enough permissions to have most software behave correctly.
If you override this, you may want to take a look at the [default included
combinators](combinators.md#default-included-combinators).
For example, here is the default set of base permissions:
```nix
jail = jail-nix.lib.extend {
inherit pkgs;
basePermissions = combinators: with combinators; [
base
bind-nix-store-runtime-closure
fake-passwd
];
};
```
However if you wanted to bind in your entire nix store rather than using the
bind-nix-store-runtime-closure combinator you could do that like so:
```nix
jail = jail-nix.lib.extend {
inherit pkgs;
basePermissions = combinators: with combinators; [
base
(readonly "/nix/store")
fake-passwd
];
};
```
## bubblewrapPackage
This configuration option allows you to override what bubblewrap package
jail.nix uses for its jails. The default value is `pkgs.bubblewrap`.