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