{"id":13629519,"url":"https://github.com/samuelkarp/runj","last_synced_at":"2025-04-04T07:06:39.753Z","repository":{"id":37255044,"uuid":"308210713","full_name":"samuelkarp/runj","owner":"samuelkarp","description":"runj is an experimental, proof-of-concept OCI-compatible runtime for FreeBSD jails.","archived":false,"fork":false,"pushed_at":"2024-06-13T20:49:15.000Z","size":544,"stargazers_count":634,"open_issues_count":15,"forks_count":33,"subscribers_count":41,"default_branch":"main","last_synced_at":"2025-03-28T06:05:11.617Z","etag":null,"topics":["containers","freebsd","freebsd-jail","jails","oci","open-containers"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samuelkarp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-29T03:48:24.000Z","updated_at":"2025-03-25T07:57:03.000Z","dependencies_parsed_at":"2024-04-09T18:55:34.967Z","dependency_job_id":"cc88bcbc-632d-4f22-8733-91be1fbed252","html_url":"https://github.com/samuelkarp/runj","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelkarp%2Frunj","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelkarp%2Frunj/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelkarp%2Frunj/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelkarp%2Frunj/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samuelkarp","download_url":"https://codeload.github.com/samuelkarp/runj/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247135144,"owners_count":20889421,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","freebsd","freebsd-jail","jails","oci","open-containers"],"created_at":"2024-08-01T22:01:12.636Z","updated_at":"2025-04-04T07:06:39.734Z","avatar_url":"https://github.com/samuelkarp.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# runj\n\nrunj is an experimental, proof-of-concept\n[OCI](https://opencontainers.org)-compatible runtime for FreeBSD jails.\n\n\u003e **Important**: runj is a proof-of-concept and the implementation has not been\n\u003e evaluated for its security.  Do not use runj on a production system.  Do not\n\u003e run workloads inside runj that rely on a secure configuration.  This is a\n\u003e personal project, not backed by the author's employer.\n\n## Status\n\n[![Build Status](https://api.cirrus-ci.com/github/samuelkarp/runj.svg?branch=main)](https://cirrus-ci.com/github/samuelkarp/runj)\n\nrunj is in early development and is functional, but has very limited features.\n\nrunj currently supports the following parts of the OCI runtime spec:\n\n* Commands\n  - Create\n  - Delete\n  - Start\n  - State\n  - Kill\n* Config\n  - Root path\n  - Process args\n  - Process environment\n  - Process terminal\n  - Hostname\n  - Mounts\n  - Hooks\n    - CreateRuntime\n    - Poststop\n\nrunj also supports the following experimental FreeBSD-specific extensions to the\nOCI runtime spec:\n\n* Config\n  - IPv4 mode\n  - IPv4 addresses\n\n## Getting started\n\n### OCI bundle\n\nTo run a jail with runj, you must prepare an OCI bundle.  Bundles consist of a\nroot filesystem and a JSON-formatted configuration file called `config.json`.\n\nExperimental FreeBSD-specific extensions may be added directly to the\n`config.json` if desired, or may optionally be added to a runj-specific file\nlocated in the bundle directory called `runj.ext.json`.\n\n#### Root filesystem\n\nThe root filesystem can consist either of a regular FreeBSD userland or a\nreduced set of FreeBSD-compatible programs.  For experimentation, \nstatically-linked programs from `/recovery` may be copied into your bundle.  You\ncan obtain a regular FreeBSD userland suitable for use with runj from\n`http://ftp.freebsd.org/pub/FreeBSD/releases/$ARCH/$VERSION/base.txz` (where\n`$ARCH` and `$VERSION` are replaced by your architecture and desired version\nrespectively).  Several `demo` convenience commands have been provided in runj\nto assist in experimentation; you can use `runj demo download` to retrieve a\nworking root filesystem from the FreeBSD website.\n\n#### Config\n\n`runj` supports a limited number of configuration parameters for jails.\nThe OCI runtime spec does not currently include support for FreeBSD, however\nrunj adds experimental support for some FreeBSD capabilities.  In the spirit of\n\"rough consensus and working code\", runj serves as a testbed for future\nproposals to extend the specification.  For now, the extensions are documented\n[here](docs/oci.md).\n\nYou can use `runj demo spec` to generate an example config file for your bundle.\n\nOnce you have a config file, edit the root path and process args to your desired\nvalues.\n\n#### Lifecycle\n\nCreate a container with `runj create $ID $BUNDLE` where `$ID` is the identifier\nyou picked for your container and `$BUNDLE` is the bundle directory with a valid\n`config.json`.\n\nStart your container with `runj start $ID`.  The process defined in the\n`config.json` will be started.\n\nInspect the state of your container with `runj state $ID`.\n\nSend a signal to your container process (or all processes in the container) with\n`runj kill $ID`.\n\nRemove your container with `runj delete $ID`.\n\n### containerd\n\nAlong with the main `runj` OCI runtime, this repository also contains an\nexperimental shim that can be used with containerd.  The shim is available as\n`containerd-shim-runj-v1` and can be used from the `ctr` command-line tool by\nspecifying `--runtime wtf.sbk.runj.v1`.\n\ncontainerd 1.5 or later is required as earlier versions do not have all the\nnecessary patches for FreeBSD support.  Additional functionality may be\navailable in a development build of containerd.  If you prefer to build from\nsource, you can find the latest commits in the\n[`main` branch of containerd](https://github.com/containerd/containerd/tree/main).\n\n#### OCI Image\n\nA base OCI image for FreeBSD 12.1-RELEASE on the `amd64` architecture is\navailable in the\n[Amazon ECR public gallery](https://gallery.ecr.aws/samuelkarp/freebsd).  You\ncan pull the image with the `ctr` tool like this:\n\n```\n$ sudo ctr image pull public.ecr.aws/samuelkarp/freebsd:12.1-RELEASE\n```\n\nIf you prefer to build your own image, need an image for a different\narchitecture, or want to try out a different version of FreeBSD, `runj` contains\na utility that can convert a FreeBSD root filesystem into an OCI image.  You\ncan download, convert, and import an image as follows:\n\n```\n$ runj demo download --output rootfs.txz\nFound arch:  amd64\nFound version:  12.1-RELEASE\nDownloading image for amd64 12.1-RELEASE into rootfs.txz\n[...output elided...]\n$ runj demo oci-image --input rootfs.txz\nCreating OCI image in file image.tar\nextracting...\ncompressing...\ncomputing layer digest...\nwriting blob sha256:f585dd296aa9697b5acaf9db7b40701a6377a3ccf4d29065cbfd3d2b80395733\nwriting blob sha256:413cc9413157f822242a4bb2c86ea50d20b8343964b5cf1d86182e132b51f78b\ntar...\n$ sudo ctr image import --index-name freebsd image.tar\nunpacking freebsd (sha256:5ac2e259d1e84a9b955f7630ef499c8b6896f8409b6ac9d9a21542cb883387c0)...done\n```\n\n#### Running containers with `ctr`\n\nWith containerd, `runj`, and the `containerd-shim-runj-v1` binary installed, you\ncan use the `ctr` command-line tool to run containers like this:\n\n```\n$ sudo ctr run \\\n    --runtime wtf.sbk.runj.v1 \\\n    --rm \\\n    public.ecr.aws/samuelkarp/freebsd:13.1-RELEASE \\\n    my-container \\\n    sh -c 'echo \"Hello from the container!\"'\nHello from the container!\n```\n\n`ctr` can also be used to test the experimental FreeBSD-specific extensions by\ncreating a `runj.ext.json` file as documented in [`oci.md`](docs/oci.md) and\npassing the path with `--runtime-config-path`.  For example, to run a container\ninteractively with access to the host's IPv4 networking stack (similar to the\n`--net-host` networking mode on Linux):\n\n```\n$ cat \u003c\u003cEOF \u003erunj.ext.json\n{\"network\":{\"ipv4\":{\"mode\":\"inherit\"}}}\nEOF\n$ sudo ctr run \\\n    --runtime wtf.sbk.runj.v1 \\\n    --rm \\\n    --tty \\\n    --runtime-config-path $(pwd)/runj.ext.json \\\n    public.ecr.aws/samuelkarp/freebsd:13.1-RELEASE \\\n    my-container \\\n    sh\n```\n\nNote that `containerd` and `runj` will not automatically create an\n`/etc/resolv.conf` file inside your container.  If your container image does not\ninclude one, you may need to add one yourself for name resolution to function\nproperly.  A very simple `/etc/resolv.conf` file using Google's public DNS\nresolver is as follows:\n\n```\nnameserver 8.8.8.8\n```\n\n## Implementation details\n\nrunj uses both FreeBSD's userland utilities for managing jails and jail-related\nsyscalls.  You must have working versions of `jail(8)`, `jls(8)`, `jexec(8)`,\nand `ps(1)` installed on your system.  `runj kill` makes use of the `kill(1)`\ncommand inside the jail's rootfs; if this command does not  exist (or is not\nfunctional), `runj kill` will not work.\n\n## Building\n\nrunj builds largely with standard `go build` invocations, except for the\n`integ-inside` integration test helper which must be statically linked.  A\n`Makefile` is available for use which correctly sets the expected build options.\n\nThe following targets are available:\n\n* `all` (or just `make` without additional arguments) - Build all binaries and\n  generate a `NOTICE` file.\n* `NOTICE` - Generate the `NOTICE` file based on included Go dependencies.\n* `install` - Install the runj binaries to the standard filesystem locations.\n* `lint` - Run `golangci-lint` which includes a number of linters.\n* `test` - Run all unit tests.\n* `integ-test` - Run integration tests.  Note that this target must be run as\n  root as it creates jails, creates and configures network interfaces, and\n  manipulates `pf` rules.  It also expects working Internet access to reach\n  `8.8.8.8` for verification of a working network.\n* `clean` - Remove built artifacts.\n\nrunj normally expects to be built from a `git` checkout so that appropriate\nrevision and module information is built in.  If building runj from an extracted\ntar instead, you may populate the `REV_OVERRIDE` file with an appropriate value\nas a substitute for the normal revision provided from `git`.\n\n## Contributing\n\nPlease see the [contribution policy](CONTRIBUTING.md).\n\n## Future\n\nResource limits on FreeBSD can be configured using the kernel's RCTL interface.\nrunj does not currently use this, but may add support for it via `rctl(8)` in\nthe future.\n\n## License\n\nrunj itself is licensed under the same license as the FreeBSD project.  Some\ndependencies are licensed under other terms.  The OCI runtime specification and\nreference code is licensed under the Apache License, 2.0; copies of that\nreference code incorporated and modified in this repository remain under the\noriginal license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelkarp%2Frunj","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamuelkarp%2Frunj","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelkarp%2Frunj/lists"}