Clean up combinator/permission naming

The term `combinator` was overloaded before, being used to refer both to
the functions that are exposed to help build a jail, and their return
value to be passed into `jail`/`basePermissions`. This commit renames
the latter to `Permission`.
This commit is contained in:
Alex David 2025-08-07 15:42:36 -07:00
commit 09edd097b9
4 changed files with 60 additions and 51 deletions

View file

@ -7,9 +7,9 @@ in rec {
doc = ''
Prevent the passed string from being automatically shell escaped.
`escape` and `noescape` aren't combinators, but they are useful helpers
to expose when defining jails and writing custom combinators, so they are
exposed with the rest of the combinators for convenience.
`escape` and `noescape` don't return `Permission`s, but they are useful
helpers to expose when defining jails and writing custom combinators, so
they are exposed with the rest of the combinators for convenience.
It is the caller's responsibility to ensure anything passed to this is
correctly escaped.
@ -38,9 +38,9 @@ in rec {
Use [noescape](#noescape) to prevent escaping.
`escape` and `noescape` aren't combinators, but they are useful helpers
to expose when defining jails and writing custom combinators, so they are
exposed with the rest of the combinators for convenience.
`escape` and `noescape` don't return `Permission`s, but they are useful
helpers to expose when defining jails and writing custom combinators, so
they are exposed with the rest of the combinators for convenience.
Example:
```nix
@ -57,7 +57,7 @@ in rec {
};
compose = {
sig = "[Combinator] -> Combinator";
sig = "[Permission] -> Permission";
doc = ''
Allows combinator composition.
@ -85,9 +85,9 @@ in rec {
};
include-once = {
sig = "String -> Combinator -> Combinator";
sig = "String -> Permission -> Permission";
doc = ''
Only run the passed combinator if include-once hasn't been previously
Only run the passed permission if include-once hasn't been previously
called with the specified key.
This is useful when writing your own combinators.
@ -129,7 +129,7 @@ in rec {
};
unsafe-add-raw-args = {
sig = "String -> Combinator";
sig = "String -> Permission";
doc = ''
Adds the raw string passed into it into the call to bubblewrap.
@ -142,7 +142,7 @@ in rec {
};
add-path = {
sig = "String -> Combinator";
sig = "String -> Permission";
doc = ''
Appends the passed string to `$PATH`.
'';
@ -152,7 +152,7 @@ in rec {
};
set-argv = {
sig = "[String] -> Combinator";
sig = "[String] -> Permission";
doc = ''
Overrides the current argv that is passed to the jailed executable.
@ -166,7 +166,7 @@ in rec {
};
add-runtime = {
sig = "String -> Combinator";
sig = "String -> Permission";
doc = ''
Adds arbitrary logic to run at runtime, before the jail starts.
@ -197,7 +197,7 @@ in rec {
};
add-cleanup = {
sig = "String -> Combinator";
sig = "String -> Permission";
doc = ''
Adds arbitrary logic to run when the jail exits.
@ -231,7 +231,7 @@ in rec {
};
wrap-entry = {
sig = "(String -> String) -> Combinator";
sig = "(String -> String) -> Permission";
doc = ''
Wraps the binary to be jailed in a bash script that will be the new
entrypoint to the jail.
@ -260,7 +260,7 @@ in rec {
};
add-pkg-deps = {
sig = "[Package] -> Combinator";
sig = "[Package] -> Permission";
doc = ''
Adds the packages' `bin` directory to `$PATH`.
'';
@ -270,7 +270,7 @@ in rec {
};
no-new-session = {
sig = "Combinator";
sig = "Permission";
doc = ''
Disables `--new-session`
@ -286,7 +286,7 @@ in rec {
};
set-env = {
sig = "String -> String -> Combinator";
sig = "String -> String -> Permission";
doc = ''
Sets the specified environment variable in the jail.
@ -298,7 +298,7 @@ in rec {
};
share-ns = {
sig = "String -> Combinator";
sig = "String -> Permission";
doc = ''
Removes the call to `--unshare-` for the provided namespace.
@ -314,7 +314,7 @@ in rec {
};
set-hostname = {
sig = "String -> Combinator";
sig = "String -> Permission";
doc = ''
Sets the hostname to use for the `network` combinator.
@ -334,7 +334,7 @@ in rec {
};
tmpfs = {
sig = "String -> Combinator";
sig = "String -> Permission";
doc = ''
Mounts a new tmpfs at the specified location.
'';
@ -344,7 +344,7 @@ in rec {
};
camera = {
sig = "Combinator";
sig = "Permission";
doc = ''
Allows access to webcams and other V4L2 video devices at `/dev/video*`.
'';
@ -360,7 +360,7 @@ in rec {
};
fwd-env = {
sig = "String -> Combinator";
sig = "String -> Permission";
doc = ''
Forwards the specified environment variable to the underlying process.
@ -376,7 +376,7 @@ in rec {
};
try-fwd-env = {
sig = "String -> Combinator";
sig = "String -> Permission";
doc = ''
Forwards the specified environment variable to the underlying process (if set).
'';
@ -386,7 +386,7 @@ in rec {
};
readonly = {
sig = "String -> Combinator";
sig = "String -> Permission";
doc = ''
Binds the specified path in the jail as read-only.
'';
@ -396,7 +396,7 @@ in rec {
};
readwrite = {
sig = "String -> Combinator";
sig = "String -> Permission";
doc = ''
Binds the specified path in the jail as read-write.
'';
@ -406,7 +406,7 @@ in rec {
};
ro-bind = {
sig = "String -> String -> Combinator";
sig = "String -> String -> Permission";
doc = ''
Binds the specified path on the host to a path in the jail as read-only.
@ -422,7 +422,7 @@ in rec {
};
rw-bind = {
sig = "String -> String -> Combinator";
sig = "String -> String -> Permission";
doc = ''
Binds the specified path on the host to a path in the jail as read-write.
@ -438,7 +438,7 @@ in rec {
};
readonly-runtime-args = {
sig = "Combinator";
sig = "Permission";
doc = ''
Binds any valid paths passed in as arguments to the jailed program at
runtime as read-only.
@ -457,7 +457,7 @@ in rec {
};
readwrite-runtime-args = {
sig = "Combinator";
sig = "Permission";
doc = ''
Binds any valid paths passed in as arguments to the jailed program at
runtime as read-write.
@ -476,7 +476,7 @@ in rec {
};
readonly-paths-from-var = {
sig = "String -> String -> Combinator";
sig = "String -> String -> Permission";
doc = ''
This binds multiple paths as read-only specified by a single runtime
environment variable.
@ -512,7 +512,7 @@ in rec {
};
mount-cwd = {
sig = "Combinator";
sig = "Permission";
doc = ''
Bind mounts the runtime working directory as read-write.
'';
@ -523,7 +523,7 @@ in rec {
};
gui = {
sig = "Combinator";
sig = "Permission";
doc = ''
Exposes everything required to get graphical applications to work.
@ -553,7 +553,7 @@ in rec {
};
wayland = {
sig = "Combinator";
sig = "Permission";
doc = ''
Exposes your wayland compositor to the jail.
'';
@ -568,7 +568,7 @@ in rec {
};
xwayland = {
sig = "Combinator";
sig = "Permission";
doc = ''
Safely allow X11 apps to render to a wayland compositor.
@ -598,7 +598,7 @@ in rec {
};
unsafe-x11 = {
sig = "Combinator";
sig = "Permission";
doc = ''
Exposes X11 to the jailed application.
@ -617,7 +617,7 @@ in rec {
};
pulse = {
sig = "Combinator";
sig = "Permission";
doc = ''
Exposes pulseaudio to the jailed application.
'';
@ -633,7 +633,7 @@ in rec {
};
pipewire = {
sig = "Combinator";
sig = "Permission";
doc = ''
Exposes pipewire to the jailed application.
'';
@ -648,7 +648,7 @@ in rec {
};
gpu = {
sig = "Combinator";
sig = "Permission";
doc = ''
Exposes the gpu to jailed application.
'';
@ -664,7 +664,7 @@ in rec {
};
time-zone = {
sig = "Combinator";
sig = "Permission";
doc = ''
Exposes your timezone.
'';
@ -679,7 +679,7 @@ in rec {
};
network = {
sig = "Combinator";
sig = "Permission";
doc = ''
Grants network access to the jail.
@ -706,7 +706,7 @@ in rec {
};
unsafe-dbus = {
sig = "Combinator";
sig = "Permission";
doc = ''
Exposes D-Bus to the jailed program.
@ -724,7 +724,7 @@ in rec {
};
bind-pkg = {
sig = "String -> Package -> Combinator";
sig = "String -> Package -> Permission";
doc = ''
Bind mounts the passed derivation at a specified location.
@ -739,7 +739,7 @@ in rec {
};
write-text = {
sig = "String -> String -> Combinator";
sig = "String -> String -> Permission";
doc = ''
Bind mounts a read-only text file at a path.
@ -758,7 +758,7 @@ in rec {
};
persist-home = {
sig = "String -> Combinator";
sig = "String -> Permission";
doc = ''
Persists the home directory across all jails with the specified name.

View file

@ -45,6 +45,15 @@
(docs: ''
# Combinators
jail.nix combinators are the building blocks to create `Permission`s,
which grant a program specific permissions at runtime.
These permissions can be passed into the third argument to `jail`
funciton, as well as
[`basePermissions`](../advanced-configuration/#basepermissions).
---
${docs}
'')
];

View file

@ -8,30 +8,30 @@ All configuration options on this page can be passed into `jail-nix.lib.extend`.
`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`
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-combinator = compose [
my-permission = compose [
(readonly "/foo")
(readonly "/bar")
];
];
};
# Now my-combinator is exposed in all the places the builtin combinators are exposed:
# 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-combinator
my-permission
]);
# Alternatively, using jail.combinators:
jailed-hello = jail "jailed-hello" pkgs.hello [
jail.combinators.my-combinator
jail.combinators.my-permission
];
```

View file

@ -66,7 +66,7 @@ following positional arguments:
be a derivation like `pkgs.hello`, or a string like
`"${pkgs.hello}/bin/hello"`. If a derivation is passed it will call
`nixpkgs.lib.getExe` on it to get the entrypoint.
* **combinators**: (List of **Combinators**) - The third argument allows you to
* **permissions**: (List of **Permissions**) - The third argument allows you to
control the permissions of the jail. By default, the wrapped program runs
with very few permissions and to get it to even work you will need to define
what you want it to have access to here. For convenience, if this argument is