diff options
| -rw-r--r-- | doc/functions.xml | 1 | ||||
| -rw-r--r-- | doc/functions/ocitools.xml | 76 | ||||
| -rw-r--r-- | pkgs/build-support/oci-tools/default.nix | 78 | ||||
| -rw-r--r-- | pkgs/top-level/all-packages.nix | 2 |
4 files changed, 157 insertions, 0 deletions
diff --git a/doc/functions.xml b/doc/functions.xml index 3b60f46d81d..96bd95958ea 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -20,4 +20,5 @@ <xi:include href="functions/appimagetools.xml" /> <xi:include href="functions/prefer-remote-fetch.xml" /> <xi:include href="functions/nix-gitignore.xml" /> + <xi:include href="functions/ocitools.xml" /> </chapter> diff --git a/doc/functions/ocitools.xml b/doc/functions/ocitools.xml new file mode 100644 index 00000000000..4500c41a34a --- /dev/null +++ b/doc/functions/ocitools.xml @@ -0,0 +1,76 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="sec-pkgs-ociTools"> + <title>pkgs.ociTools</title> + + <para> + <varname>pkgs.ociTools</varname> is a set of functions for creating + containers according to the + <link xlink:href="https://github.com/opencontainers/runtime-spec">OCI + container specification v1.0.0</link>. Beyond that it makes no assumptions + about the container runner you choose to use to run the created container. + </para> + + <section xml:id="ssec-pkgs-ociTools-buildContainer"> + <title>buildContainer</title> + + <para> + This function creates a simple OCI container that runs a single command + inside of it. An OCI container consists of a <varname>config.json</varname> + and a rootfs directory.The nix store of the container will contain all + referenced dependencies of the given command. + </para> + + <para> + The parameters of <varname>buildContainer</varname> with an example value + are described below: + </para> + + <example xml:id='ex-ociTools-buildContainer'> + <title>Build Container</title> +<programlisting> +buildContainer { + cmd = with pkgs; writeScript "run.sh" '' + #!${bash}/bin/bash + ${coreutils}/bin/exec ${bash}/bin/bash + ''; <co xml:id='ex-ociTools-buildContainer-1' /> + + mounts = { + "/data" = { + type = "none"; + source = "/var/lib/mydata"; + options = [ "bind" ]; + }; + };<co xml:id='ex-ociTools-buildContainer-2' /> + + readonly = false; <co xml:id='ex-ociTools-buildContainer-3' /> +} + + </programlisting> + <calloutlist> + <callout arearefs='ex-ociTools-buildContainer-1'> + <para> + <varname>cmd</varname> specifies the program to run inside the container. + This is the only required argument for <varname>buildContainer</varname>. + All referenced packages inside the derivation will be made available + inside the container + </para> + </callout> + <callout arearefs='ex-ociTools-buildContainer-2'> + <para> + <varname>mounts</varname> specifies additional mount points chosen by the + user. By default only a minimal set of necessary filesystems are mounted + into the container (e.g procfs, cgroupfs) + </para> + </callout> + <callout arearefs='ex-ociTools-buildContainer-3'> + <para> + <varname>readonly</varname> makes the container's rootfs read-only if it is set to true. + The default value is false <literal>false</literal>. + </para> + </callout> + </calloutlist> + </example> + </section> +</section> diff --git a/pkgs/build-support/oci-tools/default.nix b/pkgs/build-support/oci-tools/default.nix new file mode 100644 index 00000000000..18b238033ff --- /dev/null +++ b/pkgs/build-support/oci-tools/default.nix @@ -0,0 +1,78 @@ +{ lib, writeText, runCommand, writeReferencesToFile }: + +{ + buildContainer = + { args + , mounts ? {} + , os ? "linux" + , arch ? "x86_64" + , readonly ? false + }: + let + sysMounts = { + "/proc" = { + type = "proc"; + source = "proc"; + }; + "/dev" = { + type = "tmpfs"; + source = "tmpfs"; + options = [ "nosuid" "strictatime" "mode=755" "size=65536k" ]; + }; + "/dev/pts" = { + type = "devpts"; + source = "devpts"; + options = [ "nosuid" "noexec" "newinstance" "ptmxmode=0666" "mode=755" "gid=5" ]; + }; + "/dev/shm" = { + type = "tmpfs"; + source = "shm"; + options = [ "nosuid" "noexec" "nodev" "mode=1777" "size=65536k" ]; + }; + "/dev/mqueue" = { + type = "mqueue"; + source = "mqueue"; + options = [ "nosuid" "noexec" "nodev" ]; + }; + "/sys" = { + type = "sysfs"; + source = "sysfs"; + options = [ "nosuid" "noexec" "nodev" "ro" ]; + }; + "/sys/fs/cgroup" = { + type = "cgroup"; + source = "cgroup"; + options = [ "nosuid" "noexec" "nodev" "realatime" "ro" ]; + }; + }; + config = writeText "config.json" (builtins.toJSON { + ociVersion = "1.0.0"; + platform = { + inherit os arch; + }; + + linux = { + namespaces = map (type: { inherit type; }) [ "pid" "network" "mount" "ipc" "uts" ]; + }; + + root = { path = "rootfs"; inherit readonly; }; + + process = { + inherit args; + user = { uid = 0; gid = 0; }; + cwd = "/"; + }; + + mounts = lib.mapAttrsToList (destination: { type, source, options ? null }: { + inherit destination type source options; + }) sysMounts; + }); + in + runCommand "join" {} '' + set -o pipefail + mkdir -p $out/rootfs/{dev,proc,sys} + cp ${config} $out/config.json + xargs tar c < ${writeReferencesToFile args} | tar -xC $out/rootfs/ + ''; +} + diff --git a/pkgs/top-level/all-packages.nix b/pkgs/top-level/all-packages.nix index a39687a80f6..8b008ffe0af 100644 --- a/pkgs/top-level/all-packages.nix +++ b/pkgs/top-level/all-packages.nix @@ -391,6 +391,8 @@ in nix-gitignore = callPackage ../build-support/nix-gitignore { }; + ociTools = callPackage ../build-support/oci-tools { }; + pathsFromGraph = ../build-support/kernel/paths-from-graph.pl; pruneLibtoolFiles = makeSetupHook { name = "prune-libtool-files"; } |