Allow overriding jail base permissions

This commit is contained in:
Alex David 2025-08-07 15:29:16 -07:00
commit f18f1cf701
8 changed files with 154 additions and 74 deletions

View file

@ -0,0 +1,64 @@
# 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-combinator`
combinator:
```nix
jail = jail-nix.lib.extend {
inherit pkgs;
additionalCombinators = builtinCombinators: with builtinCombinators; [
my-combinator = compose [
(readonly "/foo")
(readonly "/bar")
];
];
};
# Now my-combinator is exposed in all the places the builtin combinators are exposed:
jailed-hello = jail "jailed-hello" pkgs.hello (c: with c; [
my-combinator
]);
# Alternatively, using jail.combinators:
jailed-hello = jail "jailed-hello" pkgs.hello [
jail.combinators.my-combinator
];
```
## 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.
Example:
```nix
jail = jail-nix.lib.extend {
inherit pkgs;
basePermissions = builtinCombinators: with builtinCombinators; [
(unsafe-add-raw-args "--proc /proc")
(unsafe-add-raw-args "--dev /dev")
(unsafe-add-raw-args "--tmpfs /tmp")
(unsafe-add-raw-args "--tmpfs ~")
(unsafe-add-raw-args "--clearenv")
(unsafe-add-raw-args "--die-with-parent")
(readonly "/nix/store")
(readonly "/bin/sh")
(fwd-env "LANG")
(fwd-env "HOME")
(fwd-env "TERM")
];
};
```

View file

@ -16,6 +16,8 @@ configuration:
}
```
---
## Initializing
The core functionality of jail.nix is a `jail` function that wraps derivations
@ -37,29 +39,23 @@ jail = jail-nix.lib.init pkgs;
You can set more options in the initialization with `jail-nix.lib.extend`.
You must pass in an instantiated nixpkgs attribute `pkgs`.
For example, the below snippet creates a `jail` function where `my-combinator`
is passed to jail definitions.
This takes in a single attribute set as an argument. The only required key is
`pkgs` which must be an instantiated nixpkgs.
Example:
```nix
pkgs = import nixpkgs { system = "x86_64-linux"; };
jail = jail-nix.lib.extend {
inherit pkgs;
additionalCombinators = baseCombinators: with baseCombinators; [
my-combinator = compose [
(readonly "/foo")
(readonly "/bar")
];
];
};
jailed-hello = jail "jailed-hello" pkgs.hello (c: with c; [
my-combinator
]);
# Other configuration options here...
};
```
For a full list of options see [Advanced Configuration](advanced-configuration).
---
## Usage
Once you have an [initialized](#initializing) `jail` function, it takes the
@ -77,6 +73,8 @@ following positional arguments:
a function, jail.combinators will be passed in, and the return value will be
used.
---
## Examples
### Provide jail.nix as a module arg in a Nixos configuration: