{"id":16803862,"url":"https://github.com/wagoodman/boxctl","last_synced_at":"2025-04-11T00:44:03.282Z","repository":{"id":81985668,"uuid":"60189130","full_name":"wagoodman/boxctl","owner":"wagoodman","description":"An opinionated way to manage systemd-nspawn containers without relying on BTRFS. Works in tandem with machinectl and systemctl.","archived":false,"fork":false,"pushed_at":"2016-10-15T20:12:40.000Z","size":14,"stargazers_count":12,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-11T00:43:54.112Z","etag":null,"topics":["containers","machinectl","systemd-nspawn"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wagoodman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-01T15:30:09.000Z","updated_at":"2023-04-19T11:42:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"9965927c-82b4-46a9-a479-35eb9514183d","html_url":"https://github.com/wagoodman/boxctl","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/wagoodman%2Fboxctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wagoodman%2Fboxctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wagoodman%2Fboxctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wagoodman%2Fboxctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wagoodman","download_url":"https://codeload.github.com/wagoodman/boxctl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248322604,"owners_count":21084336,"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","machinectl","systemd-nspawn"],"created_at":"2024-10-13T09:43:39.527Z","updated_at":"2025-04-11T00:44:03.275Z","avatar_url":"https://github.com/wagoodman.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Boxctl\nWrapper for machinectl and systemctl to manage systemd-nspawn OS containers with a\nprescriptive way to cutover to new images and fallback to old ones (without depending\non BTRFS or ZFS). OverlayFS is used to maintain control over changes from the original\nimage. The goal of this wrapper is to remain as light-weight as possible, preferencing\nthe preservation of the systemd-nspawn-flavored approaches to running containers\nover any features added in this wrapper script. This is not intended to replace\nmachinectl, but to instead to supplement it with a prescriptive workflow for\nupgrading to new system containers while providing a valid fallback posture if\nneeded.\n\n\u003cb\u003e\u003ci\u003eNote: this is a work in progress, so it is not stable yet.\u003c/i\u003e\u003c/b\u003e\n\n## Dependencies\nThis package requires the tar-overlay package to function: https://github.com/wagoodman/tar-overlay\n\n## Example\n\n```\n# assume a container filesystem is provided in the given tar file, stage this\n# \"image\" (called 'foo-0.1') for future use.\nboxctl stage-image \u003cpath-to-'foo-0.1.tar'\u003e\n\n# Create a new container named \"system1\" that uses the 'foo-0.1' image\nboxctl cutover-instance system1 foo-0.1\n\n\u003cby this point the container has been started and is now running\u003e\n\n# Stop the container\nboxctl poweroff system1\n\n# Start the container\nboxctl start system1\n\n# Stage a new version of the container software\nboxctl stage-image \u003cpath-to-'foo-0.2.tar'\u003e\n\n# Stop the running system1 container, cutover to the new image, and start the\n# container with a new instance of the foo-0.2 image\nboxctl cutover-instance system1 foo-0.2\n\n\u003cby this point the container has been started and is now running with the foo-0.2 image\u003e\n\n# Something is wrong and you've determined that you need to fallback to the previous\n# version of the container filesystem (foo-0.1), with all changes from before the\n# last cutover.\nboxctl fallback-instance system1\n\n\u003cby this point the container has been restarted and is now running with the original foo-0.1 image instance\u003e\n```\n\n## Motivation\nTools like systemd-nspawn and machinectl are great, as they provide operational\ncontrol over your containers without forcing you to use a particular image\nmanagement solution. However, it would be nice to \"glue\" nspawn to such a solution\nwhen necessary, similar to Docker images --tar-overlay was written with this\ncase in mind. Boxctl is the \"glue\" to thinly bind the capabilities of nspawn and\nfriends with the \"immutable image\" approach of Docker without requiring Docker. In\nthis way a cutover/fallback approach is prescribed, preserving changes to the\nfilesystem of a container as if they were physical system or VM. This blends\ntogether the usefulness of nspawn/machinectl to create and manage system containers\nwhile preserving a few aspects gleaned from the application container approach.\n\n## Usage\n\n```\nboxctl - wrapper for systemd-nspawn system container management\n\n    boxctl \u003ccommand\u003e \u003cinstance-name\u003e [\u003cimage-name\u003e]\n\nContainer commands:\n    configure \u003cname\u003e   Enter the container without booting it (for making filesystem changes).\n    disable \u003cname\u003e     Ensure the system container does *not* start upon reboot of the host.\n    enable \u003cname\u003e      Ensure the system container starts upon reboot of the host.\n    list \u003cname\u003e        Show all running system containers.\n    login \u003cname\u003e       Enter a TTY session to the system container.\n    poweroff \u003cname\u003e    Shutdown the system container.\n    restart \u003cname\u003e     Power off then power on the system container.\n    start \u003cname\u003e       Power on the system container.\n    status \u003cname\u003e      Determine the operational condition of the system container.\n    terminate \u003cname\u003e   Forcefully kill the system container (not recommended).\n\nContainer image/instance commands:\n    cutover-instance \u003cname\u003e \u003cimage-name\u003e   Actively cutover to a new container instance.\n    delete-instance \u003cname\u003e \u003cimage-name\u003e    Delete the instance based off of the given image name.\n    fallback-instance \u003cname\u003e               Fallback to a previously used instance.\n    list-images                     Show avaliable images, current instance, and fallback instance.\n    reset \u003cname\u003e \u003cimage-name\u003e       Reset the current instance to the originally installed image.\n    stage-image \u003ctar-path\u003e          Install a new image from the given tar.gz archive.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwagoodman%2Fboxctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwagoodman%2Fboxctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwagoodman%2Fboxctl/lists"}