https://github.com/wagoodman/boxctl
An opinionated way to manage systemd-nspawn containers without relying on BTRFS. Works in tandem with machinectl and systemctl.
https://github.com/wagoodman/boxctl
containers machinectl systemd-nspawn
Last synced: 6 months ago
JSON representation
An opinionated way to manage systemd-nspawn containers without relying on BTRFS. Works in tandem with machinectl and systemctl.
- Host: GitHub
- URL: https://github.com/wagoodman/boxctl
- Owner: wagoodman
- Created: 2016-06-01T15:30:09.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2016-10-15T20:12:40.000Z (almost 9 years ago)
- Last Synced: 2025-04-11T00:43:54.112Z (6 months ago)
- Topics: containers, machinectl, systemd-nspawn
- Language: Shell
- Size: 13.7 KB
- Stars: 12
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Boxctl
Wrapper for machinectl and systemctl to manage systemd-nspawn OS containers with a
prescriptive way to cutover to new images and fallback to old ones (without depending
on BTRFS or ZFS). OverlayFS is used to maintain control over changes from the original
image. The goal of this wrapper is to remain as light-weight as possible, preferencing
the preservation of the systemd-nspawn-flavored approaches to running containers
over any features added in this wrapper script. This is not intended to replace
machinectl, but to instead to supplement it with a prescriptive workflow for
upgrading to new system containers while providing a valid fallback posture if
needed.
Note: this is a work in progress, so it is not stable yet.
## Dependencies
This package requires the tar-overlay package to function: https://github.com/wagoodman/tar-overlay
## Example
```
# assume a container filesystem is provided in the given tar file, stage this
# "image" (called 'foo-0.1') for future use.
boxctl stage-image
# Create a new container named "system1" that uses the 'foo-0.1' image
boxctl cutover-instance system1 foo-0.1
# Stop the container
boxctl poweroff system1
# Start the container
boxctl start system1
# Stage a new version of the container software
boxctl stage-image
# Stop the running system1 container, cutover to the new image, and start the
# container with a new instance of the foo-0.2 image
boxctl cutover-instance system1 foo-0.2
# Something is wrong and you've determined that you need to fallback to the previous
# version of the container filesystem (foo-0.1), with all changes from before the
# last cutover.
boxctl fallback-instance system1
```
## Motivation
Tools like systemd-nspawn and machinectl are great, as they provide operational
control over your containers without forcing you to use a particular image
management solution. However, it would be nice to "glue" nspawn to such a solution
when necessary, similar to Docker images --tar-overlay was written with this
case in mind. Boxctl is the "glue" to thinly bind the capabilities of nspawn and
friends with the "immutable image" approach of Docker without requiring Docker. In
this way a cutover/fallback approach is prescribed, preserving changes to the
filesystem of a container as if they were physical system or VM. This blends
together the usefulness of nspawn/machinectl to create and manage system containers
while preserving a few aspects gleaned from the application container approach.
## Usage
```
boxctl - wrapper for systemd-nspawn system container management
boxctl []
Container commands:
configure Enter the container without booting it (for making filesystem changes).
disable Ensure the system container does *not* start upon reboot of the host.
enable Ensure the system container starts upon reboot of the host.
list Show all running system containers.
login Enter a TTY session to the system container.
poweroff Shutdown the system container.
restart Power off then power on the system container.
start Power on the system container.
status Determine the operational condition of the system container.
terminate Forcefully kill the system container (not recommended).
Container image/instance commands:
cutover-instance Actively cutover to a new container instance.
delete-instance Delete the instance based off of the given image name.
fallback-instance Fallback to a previously used instance.
list-images Show avaliable images, current instance, and fallback instance.
reset Reset the current instance to the originally installed image.
stage-image Install a new image from the given tar.gz archive.
```