jail.nix/website/static-docs/advanced-configuration.md
Alex David 731ba22f60 Add experimental combinator handling
I have a few combinator ideas that I'd like to try adding but I still
haven't fully fleshed them out yet. In order to reduce breaking people's
setup, this introduces a new `experimental` flag on combinators that
separates them on the docs website to let users know that their design
may not be fully finalized yet.
2026-04-14 22:27:44 -07:00

84 lines
2.3 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`.
## suppressExperimentalWarnings
By default, jail.nix will emit an evaluation warning if you use an
[experimental combinator](combinators.md#experimental-combinators). Setting
this to true suppresses these warnings.