diff --git a/combinators.nix b/combinators.nix index 7247070..47c4c48 100644 --- a/combinators.nix +++ b/combinators.nix @@ -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. diff --git a/website/flake.nix b/website/flake.nix index 7397a7e..bdd0ff0 100644 --- a/website/flake.nix +++ b/website/flake.nix @@ -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} '') ]; diff --git a/website/static-docs/advanced-configuration.md b/website/static-docs/advanced-configuration.md index babe995..ce0d444 100644 --- a/website/static-docs/advanced-configuration.md +++ b/website/static-docs/advanced-configuration.md @@ -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 ]; ``` diff --git a/website/static-docs/index.md b/website/static-docs/index.md index 91ade98..01f4af8 100644 --- a/website/static-docs/index.md +++ b/website/static-docs/index.md @@ -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