Stanislaw Adaszewski efc1f4ce7f | 4年前 | |
---|---|---|
example | 4年前 | |
focker | 4年前 | |
scripts | 4年前 | |
.gitignore | 4年前 | |
README.md | 4年前 | |
requirements.txt | 4年前 | |
setup.py | 4年前 |
Focker is a FreeBSD image orchestration tool in the vein of Docker.
In order to use Focker you need a ZFS pool available in your FreeBSD installation.
Run:
pip install focker
Run:
git clone https://github.com/sadaszewski/focker.git
cd focker/
python setup.py install
or (if you want an uninstaller):
git clone https://github.com/sadaszewski/focker.git
cd focker/
python setup.py sdist
pip install dist/focker-0.9.tgz
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
/focker/images
/focker/jails
/focker/volumes
images
, jails
, and volumes
have corresponding ZFS datasets with canmount=off
so that they serve as mountpoint anchors for child entries.
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):
TAGS="freebsd-latest freebsd-$(freebsd-version | cut -d'-' -f1)"
VERSION="FreeBSD $(freebsd-version)"
SHA256=$(echo -n ${VERSION} | sha256)
NAME=${SHA256:0:7}
zfs create -o focker:sha256=${SHA256} -o focker:tags="${TAGS}" zroot/focker/images/${NAME}
bsdinstall jail /focker/images/${NAME}
zfs set readonly=on zroot/focker/images/${NAME}
zfs snapshot zroot/focker/images/${NAME}@1
At this point, Focker is ready to use.
focker
command syntaxThe focker
command is the single entrypoint to all of the Focker's functionality. The overview of its syntax is presented below as a tree where the focker
command is the root, the first level of descendants represents the choice of Level 1 mode (image
, jail
, volume
or compose
), the second level - the Level 2 mode (dependent on L1 mode) and the final third level lists required and optional arguments specific to the given combination of L1/L2 modes.
focker
|- image|img|im|i
| |- build|b
| | |- FOCKER_DIR
| | `- --tags|-t TAG [...TAG]
| |- tag|t
| | |- REFERENCE
| | `- TAG [...TAG]
| |- untag|u
| | `- TAG [...TAG]
| |- list|ls|l
| | `- --full-sha256|-f
| |- prune|p
| `- remove|r
| |- REFERENCE
| `- --remove-dependents|-R
|- jail|j
| |- create|c
| | |- IMAGE
| | |- --command|-c COMMAND (default: /bin/sh)
| | |- --env|-e VAR1:VALUE1 [...VARN:VALUEN]
| | |- --mounts|-m FROM1:ON1 [...FROMN:ONN]
| | `- --hostname|-n HOSTNAME
| |- start|s
| | `- REFERENCE
| |- stop|S
| | `- REFERENCE
| |- remove|r
| | `- REFERENCE
| |- exec|e
| | |- REFERENCE
| | `- [...COMMAND]
| |- oneshot|o
| | `- IMAGE
| | `- --env|-e VAR1:VALUE1 [...VARN:VALUEN]
| | `- --mounts|-m FROM1:ON1 [...FROMN:ONN]
| | `- [...COMMAND]
| |- list|ls|l
| | `- --full-sha256|-f
| |- tag|t
| | |- REFERENCE
| | `- TAG [...TAG]
| |- untag|u
| | `- TAG [...TAG]
| `- prune|p
| `- --force|-f
|- volume
| |- create
| | `- --tags|-t TAG [...TAG]
| |- prune
| |- list
| | `- --full-sha256|-f
| |- tag
| | |- REFERENCE
| | `- TAG [...TAG]
| `- untag
| `- TAG [...TAG]
`- compose
|- build
| `- FILENAME
`- run
|- FILENAME
`- COMMAND
Individual combinations are briefly described below:
The focker image
mode groups commands related to Focker images.
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.
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.
Removes one or more image tags.
Lists existing Focker images, optionally with full SHA256 checksums (instead of the default 7 first characters).
Greedily removes existing Focker images without tags and without dependents.
Removes the specified image.
The focker jail
mode groups commands related to Focker-managed jails.
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.
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
.
Stops the given jail specified by REFERENCE
. This command is equivalent to calling jail -r
.
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.
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
.
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