runc#

OCaml bindings for runc, the OCI container runtime.

Provides typed representations of the OCI runtime specification (config.json) and functions to invoke runc commands for container lifecycle management.

Installation#

Install with opam:

$ opam install runc

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install runc

Usage#

Run a command in a rootfs#

Point runc at an OCI bundle (a directory with a config.json and a root filesystem) and run it:

let run () =
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun _sw ->
  let runc = Runc.Command.create ~env () in
  let container = Runc.Command.run ~id:"hello" ~bundle:"./bundle" runc in
  match Runc.Command.state runc container with
  | `Stopped code -> Fmt.pr "exit %d@." code
  | `Running | `Created ->
      (match Runc.Command.kill runc container Sys.sigterm with
      | Ok () -> ()
      | Error m -> Fmt.epr "kill: %s@." m);
      match Runc.Command.delete ~force:true runc container with
      | Ok () -> ()
      | Error m -> Fmt.epr "delete: %s@." m

Build the bundle#

The bundle's config.json is an OCI runtime configuration. Use Runc.Config to assemble it from typed parts and serialize:

let process = Runc.Process.v [ "/bin/echo"; "hello" ]
let root = Runc.Root.v "rootfs"
let config = Runc.Config.v ~process ~root ()
let json = Runc.Config.to_json config
(* write `json` to `./bundle/config.json` and extract a rootfs tar into
   `./bundle/rootfs` before calling Runc.Command.run *)

Lifecycle API#

Runc.Command.create ~env ?state_dir () -- wrap the runc CLI.
Runc.Command.run ~id ~bundle t -- create and start a container in one step.
Runc.Command.start, kill, delete, state, list for fine-grained control over containers that were created without starting.

OCI config modules#

Runc.User -- User specification (uid, gid)
Runc.Mount -- Mount specification with common defaults
Runc.Namespace -- Linux namespace types
Runc.Capability / Runc.Capabilities -- Linux capabilities
Runc.Rlimit -- Resource limits
Runc.Process -- Process specification (argv, env, cwd, user, caps)
Runc.Root -- Root filesystem specification
Runc.Linux -- Linux-specific configuration (namespaces, seccomp, cgroups)
Runc.Config -- Top-level OCI runtime configuration with to_json / of_json

runc - Reference OCI runtime
OCI Runtime Spec - The specification
OBuilder - OCaml build sandbox using runc
Albatross - MirageOS unikernel orchestration

Licence#

ISC License. See LICENSE.md for details.

Configure Feed