From efc1f4ce7fb7b1ff91c16d8d1c9bd583ab9b8b35 Mon Sep 17 00:00:00 2001 From: Stanislaw Adaszewski Date: Tue, 28 Apr 2020 08:29:13 +0200 Subject: [PATCH] Documentation. --- README.md | 50 +++++++++++++++++++++++++++++++++----------------- 1 file changed, 33 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index b08a1f2..00207e3 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ pip install dist/focker-0.9.tgz ### Setting up ZFS -Upon first execution of the `focker` command, Focker will automatically create the necessary directories and ZFS datasets. You just need to exclude the unlikely case that you are already using /focker in your filesystem hierarchy. The layout after initialization will look the following: +Upon first execution of the `focker` command, Focker will automatically create the necessary directories and ZFS datasets. You just need to exclude the unlikely case that you are already using `/focker` in your filesystem hierarchy. The layout after initialization will look the following: ``` /focker @@ -50,7 +50,7 @@ Upon first execution of the `focker` command, Focker will automatically create t ### Preparing base image -To bootstrap the images system you need to install FreeBSD in jail mode to a ZFS dataset placed in /focker/images and provide two user-defined properties - `focker:sha256` and `focker:tags`. One way to achieve this would be the following: +To bootstrap the images system you need to install FreeBSD in jail mode to a ZFS dataset placed in `/focker/images` and provide two user-defined properties - `focker:sha256` and `focker:tags`. One way to achieve this would be the following (using Bash shell): ```bash TAGS="freebsd-latest freebsd-$(freebsd-version | cut -d'-' -f1)" @@ -139,49 +139,65 @@ focker Individual combinations are briefly described below: -#### focker image +#### focker image|img|im|i The `focker image` mode groups commands related to Focker images. -##### build FOCKER_DIR [--tags TAG [...TAG]] +##### build|b FOCKER_DIR [--tags TAG [...TAG]] Build a Focker image according to the specification in a Fockerfile present in the specified FOCKER_DIR. Fockerfile syntax is very straightforward and explained below. -##### tag REFERENCE TAG [...TAG] +##### tag|t REFERENCE TAG [...TAG] Applies one or more tags to the given image. REFERENCE can be the SHA256 of an image or one of its existing tags. It can be just a few first characters as long as they are unambiguous. -##### untag TAG [...TAG] +##### untag|u TAG [...TAG] Removes one or more image tags. -##### list [--full-sha256|-f] +##### list|ls|l [--full-sha256|-f] Lists existing Focker images, optionally with full SHA256 checksums (instead of the default 7 first characters). -##### prune +##### prune|p Greedily removes existing Focker images without tags and without dependents. -##### remove REFERENCE +##### remove|r REFERENCE Removes the specified image. -#### focker jail +#### focker jail|j -##### create +The `focker jail` mode groups commands related to Focker-managed jails. -##### start +##### create|c IMAGE [--command|-c COMMAND] [--env|-e VAR1:VALUE1 [...VARN:VALUEN]] [--mounts|-m FROM1:ON1 [...FROMN:ONN]] [--hostname|-n HOSTNAME] -##### stop +Creates a new Focker-managed jail. A jail consists of a clone of the given `IMAGE` and an entry in `/etc/jail.conf`. The configuration entry uses `exec.prestart` and `exec.start` to specify how the runtime environment (mounts and environmental variables) should be set up. It also calls `COMMAND` as last in `exec.start`. If not specified `COMMAND` defaults to `/bin/sh`. The hostname can be specified using the `HOSTNAME` parameter. Mounts and environment variables are provided as tuples separated by a colon (:). The environmental variable specification consists of variable name followed by variable value. The mount specification consists of the "from path", followed by the "on path". "From path" can be a local system path or a volume name. -##### remove +##### start|s REFERENCE -##### exec +Starts the given jail specified by `REFERENCE`. `REFERENCE` can be the SHA256 of an existing jail or one of its existing tags. It can be just a few first characters as long as they are unambiguous. This command is equivalent of calling `jail -c`. -##### oneshot +##### stop|S REFERENCE -##### list +Stops the given jail specified by `REFERENCE`. This command is equivalent to calling `jail -r`. + +##### remove|r REFERENCE + +Removes the given jail specified by `REFERENCE`. The jail is stopped if running, any filesystems mounted under its root directory are unmounted, its ZFS dataset and entry in `/etc/jail.conf` are removed. + +##### exec|e REFERENCE [...COMMAND] + +Executes given `COMMAND` (or `/bin/sh` if not specified) in the given running jail specified by `REFERENCE`. This command is the equivalent of calling `jexec`. + +##### oneshot|o IMAGE [--env|-e VAR1:VALUE1 [...VARN:VALUEN]] [--mounts|-m FROM1:ON1 [...FROMN:ONN]] [...COMMAND] + +Create a new one-time Focker-managed jail. The syntax and logic is identical to `focker jail create`, the difference being that the hostname cannot be specified and that the jail will be automatically removed when the `COMMAND` exits. + +Example: `focker jail oneshot freebsd-latest -e FOO:bar -- ls -al` + +##### list|ls|l ##### tag