tulilirockz/nuspawn

Wrapper for Systemd-Nspawn and Machinectl written in Nushell

888888ba           .d88888b                                           8b
88    `8b          88.    "'                                          `8b
88     88 dP    dP `Y88888b. 88d888b. .d8888b. dP  dP  dP 88d888b.     `8b
88     88 88    88       `8b 88'  `88 88'  `88 88  88  88 88'  `88     .8P
88     88 88.  .88 d8'   .8P 88.  .88 88.  .88 88.88b.88' 88    88    .8P
dP     dP `88888P'  Y88888P  88Y888P' `88888P8 8888P Y8P  dP    dP    8P
                             88
                             dP

A Nushell wrapper over systemd-nspawn and machinectl initially inspired by the the nspawn nspawnhub wrapper script meant to make usage easier and more integrated with nspawn.org (nspawnhub)

We aim to make this as self-contained with as few dependencies as possible, using just the nushell and few binaries like machinectl, gpg and GNU tar (optionally).

Version Requirements

This project, as of release 0.7.5, requires nushell 0.93 and systemd v256 to work properly due to utility functions and unprivileged systemd-nspawn containers, it will work fine on other versions, but youll need to confirm every time you run your container

Usage

Initializing your first container

nuspawn remote list # Table of all the available distros

# This should be the minimum necessary to pull your image, from there you can use machinectl.
nuspawn init
machinectl start debian-sid-tar
machinectl login debian-sid-tar

# Advanced usage example: Importing a nspawn configuration to the container and verifiying using the nspawnhub gpg key
nuspawn init debian sid --name "mydebbox" --config=./distrobox-like.nspawn.ini

Composing machines

You can also declare your Nspawn machines in YAML manifests to have them automatically configured by running nuspawn compose create $MANIFEST_PATH

# Version is required due to future breaking changes, it will not let you use old versions on newer versions, not letting you just break the application
version: '0.7'

# Notice that you can declare multiple machines here!
machines: 
  - name: debox
    image: debian
    tag: sid
    type: raw
    config: null # Configuration file copied from $PWD/$FILE
    nspawnhub_url: null # You can also specify a custom URL for a specific image
    env: # Environment variables for init_commands
      - DEBIAN_FRONTEND=noninteractive
    init_commands: # Will run when creating the container, not when logging in through machinectl login 
      - rm -f /etc/apt/apt.conf.d/docker-gzip-indexes /etc/apt/apt.conf.d/docker-no-languages
      - apt update -y && apt upgrade -y 
      - apt install -y cockpit
    inline_config: | # Will be copied to /etc/systemd/nspawn/$MACHINE.nspawn before anything runs, more info in `systemd.nspawn(5)`
      [Network]
      VirtualEthernet=no
    properties: # Systemd service properties, see `systemd.exec(5)`
      - MemoryMax=2G

More examples in the example/ directory.

Config

You can configure your machines through the config subcommands, by editing, applying, or removeing nspawn configurations

nuspawn init debian sid --name debox # You can also specify --config=(path) to set up a configuration when initializing
nuspawn config list # To check every configuration already applied to images
nuspawn config apply ./example/config/distrobox-like.ini debox # Creates a configuration for the machine after install
nuspawn config edit debox # Will open nano (by default) for editing the machine's configuration file
nuspawn config show debox # Shows every property specified in your configuration in a fancy table
nuspawn config remove debox # Removes any configuration set for `[email protected]`

Inspecting images

You can fetch images locally without adding them to the systemd-nspawn machine directory by using nuspawn fetch

nuspawn fetch debian sid # From here you can either extract a tarball, or use mount.ddi to check the image contents

nuspawn fetch --extract --type=tar debian sid .

nuspawn fetch --type=raw debian sid .
systemd-dissect ./debian-sid-raw.raw

Deleting machines

~/opt/tulilirockz/nuspawn/src> nuspawn remove debox
Do you wish to delete all your local images? [N]:

You can also Prune, which will delete every image from your system, including configurations if specified.

~/opt/tulilirockz/nuspawn/src> nuspawn prune
[nuspawn] THIS COMMAND WILL CLEAR ALL IMAGES IN LOCAL STORAGE, type YES if you agree to delete everything
Do you wish to delete all your local images? [N]:

Installing

Most of the packaging is still yet to be done, tracking issue at #3

Fedora/OpenSUSE/RHEL (RPM)

Available in my COPR @ tulilirockz/nuspawn!

Debian/Ubuntu (DEB)

TODO!

Arch Linux (PKGBUILD)

TODO!

Alpine Linux / Chimera / PostmarketOS (APK)

TODO! (maybe), since like... they dont exactly have systemd in them, right?

NixOS/Nix (Nix)

Nix Profile

nix profile install github:tulilirockz/nuspawn#

Flake

{
  inputs = {
    #...
    nuspawn = {
      url = "github:tulilirockz/nuspawn";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    #...
  }
  outputs = {
    #...
    # Install the NuSpawn binary in your NixOS configuration by using inputs.nuspawn.packages.${pkgs.system}.nuspawn in environment.systemPackages
    #...
  }
}

Standalone Installation

You should be able to install this project by using the install.nu script on your system. If you want to live dangerously, you can run:

curl -fsSL "https://raw.githubusercontent.com/tulilirockz/nuspawn/main/install.nu" | nu

It is NOT recommended to do that, though!

Known Issues

Networking

If you are trying to run your container and cant seem to get networking working, make sure that your configuration doesnt have the VirtualEthernet option enabled, like this:

[Network]
VirtualEthernet=no

nuspawn's Issues

feat: assemble command

For creating OS tarballs with predefined recipes!

Like just a nushell script that it runs and sets up a nspawn config to go with it

Try implementing this in the distrobox project

This would be awesome as just a distrobox extension or something, like having distrobox-main being podman, distrobox-nspawn-something as nspawn commands and everything else.

feat: from-directory and from-url in nuspawn init / compose

Would be nicer to have granular control over where the images come from, like, instead of specifically depending on nspawnhub.org or some mirror, would be nice to be able to use something from a directory (absolute directory), or a tarball served on a URL!

feat: templates for default configurations

Something like "bind-home.nspawn", "gui+home.nspawn", these things would be awesome to have by default as a nuspawn template command

feat: more packaging

Packaging for:

• RPMs (copr)
• Deb (ppa + standalone package)
• Arch (AUR pkgbuild)

feat: use from-ini if user has nu_plugin_formats

Dynamically use that if the user uses that, else just parse the machine info normally.

feat: command for resizing raw images

Raw images usually get out of space errors if you don't truncate their FS, maybe having a script for resizeing a raw file would be cool! Using systemd-repart or something like that + truncate +2G or something

feat: create Manpage

Maybe with some MD to Grok converter or something. It would be awesome to have a TLDR page and a Manpage for this project (just so that people dont need to use the --help options always.

fear: profiles

"-p" or "--profile" options for default configurations, distrobox-like by default :p

refactor: extern for proper typing

Would be nice to have externs for Tar, MachineCTL and Systemd-nspawn so that users will get proper errors with nice typing!

Something like:

extern machinectl [machine: string, whatever: bool]

feat: make machinectl optional

Making this optional would make this a true wrapper over systemd-nspawn, without machinectl or anything below it! We can already do that with just the systemctl transient units, I believe the hard part is really just creating the machine transient services to run systemd-nspawn on.

feat: vmspawn integration with the nspawnhub raw disks

Should be implemented somethng like "nuspawn vm init" or something like that!