diff --git a/combinators.nix b/combinators.nix index 5b00ed5..71b0a4d 100644 --- a/combinators.nix +++ b/combinators.nix @@ -190,10 +190,10 @@ RUNTIME_ARGS+=(--bind /foo /foo) fi ${"''"} + ``` If you create any resources in add-runtime that you want to automatically clean up when the jail exits use [add-cleanup](#add-cleanup). - ``` ''; __functor = _: runtime: state: state // { runtime = "${state.runtime}\n${runtime}\n"; } diff --git a/website/flake.nix b/website/flake.nix index 7a37da7..7397a7e 100644 --- a/website/flake.nix +++ b/website/flake.nix @@ -7,6 +7,16 @@ pkgs = import nixpkgs { system = "x86_64-linux"; }; lib = pkgs.lib; + repo = rec { + rev = if self ? rev then self.rev else lib.warn "Repo is dirty, links will not work!" "???"; + shortRev = lib.substring 0 8 rev; + urls = { + base = "https://git.sr.ht/~alexdavid/jail.nix"; + commit = "https://git.sr.ht/~alexdavid/jail.nix/commit/${rev}"; + file = file: lineNr: "https://git.sr.ht/~alexdavid/jail.nix/tree/${rev}${file}#L${toString lineNr}"; + }; + }; + formatCombinatorDoc = name: combinatorObj: let attrPos = builtins.unsafeGetAttrPos "__functor" combinatorObj; file = lib.removePrefix (toString ./..) attrPos.file; @@ -14,7 +24,7 @@ ## ${name} **${name} :: ${combinatorObj.sig}** - ${if self ? rev then "[Source](https://git.sr.ht/~alexdavid/jail.nix/tree/${self.rev}${file}#L${toString attrPos.line})" else ""} + [Source](${repo.urls.file file attrPos.line}) ${combinatorObj.doc} @@ -32,21 +42,38 @@ (lib.filterAttrs (_: v: !(v ? deprecated && v.deprecated))) (lib.mapAttrsToList formatCombinatorDoc) (lib.concatStringsSep "\n\n") - (docs: "# Combinators\n\n${docs}") + (docs: '' + # Combinators + + ${docs} + '') ]; mkdocsSettings = { site_name = "jail-nix"; - repo_url = "https://git.sr.ht/~alexdavid/jail.nix"; + repo_url = repo.urls.base; theme = { name = "readthedocs"; hljs_languages = [ "nix" ]; }; + # Copyright is placed directly into the page within a

tag. + # Concatenating with

here is super janky, but good enough for + # now. + copyright = lib.concatStringsSep "

" [ + '' + Copyright © 2025 Alex David /// + CC BY-NC-SA 4.0. + '' + '' + This documentation was generated from the jail.nix repo, + commit ${repo.shortRev}. + '' + ]; }; in { packages.x86_64-linux.default = pkgs.runCommand "website" { buildInputs = [ pkgs.mkdocs ]; } '' - mkdir -p docs - cp ${../README.md} docs/index.md + cp -r ${./static-docs} docs + chmod -R +w docs echo ${lib.escapeShellArg combinatorDocs} > docs/combinators.md echo ${lib.escapeShellArg (builtins.toJSON mkdocsSettings)} > mkdocs.yml mkdocs build diff --git a/website/static-docs/index.md b/website/static-docs/index.md new file mode 100644 index 0000000..1e12c7d --- /dev/null +++ b/website/static-docs/index.md @@ -0,0 +1,125 @@ +# Getting Started + +## Installation + +It is currently recommended to install jail.nix as a flake input to your +configuration: + +```nix +# flake.nix +{ + inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11"; + inputs.jail-nix.url = "sourcehut:~alexdavid/jail.nix"; + outputs = { nixpkgs, jail-nix, ... }: { + # ... + }; +} +``` + +## Initializing + +The core functionality of jail.nix is a `jail` function that wraps derivations +in a bubblewrap jail. To set it up, you need to initialize the library with a +version of nixpkgs. + +This is done by either calling `jail-nix.lib.init` for a basic setup, or +`jail-nix.lib.extend` for advanced configuration. + +### Basic configuration + +For a simple working `jail` function, call `jail-nix.lib.init` with an instantiated nixpkgs: +```nix +pkgs = import nixpkgs { system = "x86_64-linux"; }; +jail = jail-nix.lib.init pkgs; +``` + +### Advanced configuration + +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. + +```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 +]); +``` + +## Usage + +Once you have an [initialized](#initializing) `jail` function, it takes the +following positional arguments: + +* **name**: (String) - the nix store name of wrapper script that is generated. +* **executable to wrap**: (String or Derivation) - An entrypoint to jail, this can + 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**: (Function returning a list of **Combinators**) - 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, + this is a function that passes all the available combinators. + +## Examples + +### Provide jail.nix as a module arg in a Nixos configuration: + +It may be more ergonomic to provide the jail function as a module argument in +your Nixos configurations: + +```nix +# flake.nix +{ + inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11"; + inputs.jail-nix.url = "sourcehut:~alexdavid/jail.nix"; + outputs = { nixpkgs, jail-nix, ... }: { + nixosConfigurations.my-nixos-host = nixpkgs.lib.nixosSystem { + system = "x86_64-linux"; + modules = [ + ({ pkgs, ... }: { _module.args.jail = jail-nix.lib.init pkgs; }) + + # Now all modules have `jail` passed into them: + ({ jail, ... }: { + environment.systemPackages = [ + (jail "jailed-hello" pkgs.hello (c: [])) + ]; + }) + ]; + }; + }; +} +``` + +### Using jail.nix to jail a flake package +```nix +# flake.nix +{ + inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11"; + inputs.jail-nix.url = "sourcehut:~alexdavid/jail.nix"; + outputs = { nixpkgs, jail-nix, ... }: { + packages.x86_64-linux = + let + pkgs = import nixpkgs { system = "x86_64-linux"; }; + jail = jail-nix.lib.init pkgs; + in { + my-jailed-package = jail "jailed-hello" pkgs.hello (c: []); + }; + }; +} +```