ociTools: init

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>

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>

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/
+    '';
+}
+

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"; }