Skip to content

Latest commit

 

History

History
439 lines (303 loc) · 15 KB

README.md

File metadata and controls

439 lines (303 loc) · 15 KB
Raw

Ashlinux

An immutable Arch based distribution utilizing btrfs snapshots

Ashlinux-logo

Table of contents

What is Ashlinux?

Ashlinux is a modern distribution based on Arch Linux. Unlike Arch it uses an immutable (read-only) root filesystem. Software is installed and configured into individual snapshot trees, which can then be deployed and booted into. It doesn't use it's own package format or package manager, instead relying on pacman from Arch.

This has several advantages:

  • Security

    • Running an application even with elevated permissions cannot replace system libraries with malicious versions

  • Stability and reliability

    • Due to the system being mounted as read only, it's not possible to accidentally overwrite system files
    • If the system runs into issues, you can easily rollback the last working snapshot within minutes
    • Atomic updates - Updating your system all at once is more reliable
    • Thanks to the snapshot feature, Ashlinux can ship cutting edge software without becoming unstable
    • Ashlinux needs little maintenance, as it has a built in fully automatic update tool that creates snapshots before updates and automatically checks if the system upgraded properly before deploying the new snapshot

  • Configurability

    • With the snapshots organised into a tree, you can easily have multiple different configurations of your software available, with varying packages, without any interference
    • For example: you can have a single Gnome desktop installed and then have 2 snapshots on top - one with your video games, with the newest kernel and drivers, and the other for work, with the LTS kernel and more stable software, you can then easily switch between these depending on what you're trying to do
    • You can also easily try out software without having to worry about breaking your system or polluting it with unnecessary files, for example you can try out a new desktop environment in a snapshot and then delete the snapshot after, without modifying your main system at all
    • This can also be used for multi-user systems, where each user has a completely separate system with different software, and yet they can share certain packages such as kernels and drivers
    • Ashlinux allows you to install software by chrooting into snapshots, therefore you can use software such as the AUR to install additional packages
    • Just like Arch Linux, Ashlinux is very customizable. You can choose exactly which software you want to use

  • Thanks to it's reliabilty and automatic upgrades, Ashlinux is well suitable for single use or embedded devices

  • It also makes for a good workstation or general use distribution utilizing development containers and flatpak for desktop applications

Ashlinux compared to other similar distributions

  • NixOS - compared to nixOS, Ashlinux is a more traditional system with how it's setup and maintained. While nixOS is entirely configured using the Nix programming language, Ashlinux uses Arch's pacman package manager. Ashlinux consumes less storage, and configuring your system is faster and easier (less reproducible however), it also gives you more customization options. Ashlinux is FHS compliant, ensuring proper software compatability.
    • Ashlinux allows declarative configuration using Ansible, for somewhat similar functionality to NixOS
  • Fedora Silverblue/Kinoite - Ashlinux is more customizable, but does require more manual setup. Ashlinux supports dual boot, unlike Silverblue.
  • OpenSUSE MicroOS - Ashlinux is a more customizable system, but once again requires a bit more manual setup. MicroOS works similarly in the way it utilizes btrfs snapshots. Ashlinux has an official KDE install, but also supports other desktop environments, while MicroOS only properly supports Gnome. Ashlinux supports dual boot.

Installation

  • Ashlinux is installed from the official Arch Linux live iso available on https://archlinux.org/
  • If you run into issues installing packages during installation, make sure you're using the newest arch iso, and if needed update the pacman keyring
  • You need an internet connection to install Ashlinux
  • Currently Ashlinux ships 3 installation profiles, one for minimal installs and two for desktop, one with the Gnome desktop environment and one with KDE Plasma, but support for more DE's will be added
  • The installation script is easily configurable and adjusted for your needs (but it works just fine without any modifications)

Install git first - this will allow us to download the install script

pacman -Sy git

Clone repository

git clone "https://github.com/Ashlinux/Ashlinux"
cd Ashlinux

Partition and format drive

  • If installing on a BIOS system, use a dos (MBR) partition table
  • On EFI you can use GPT
  • The EFI partition has to be formatted to FAT32 before running the installer (mkfs.fat -F32 /dev/<part>)
lsblk  # Find your drive name
cfdisk /dev/*** # Format drive, make sure to add an EFI partition, if using BIOS leave 2M free space before first partition

Run installer

python3 main.py /dev/<partition> /dev/<drive> /dev/<efi part> # Skip the EFI partition if installing in BIOS mode

Post installation setup

  • Post installation setup is not necessary if you install one of the desktop editions (Gnome or KDE)
  • A lot of information for how to handle post-install setup is available on the ArchWiki page
  • Here is a small example setup procedure:
    • Start by creating a new snapshot from the base image using ash clone 0
    • Chroot inside this new snapshot (ash chroot <snapshot>) and begin setup
      • Start by adding a new user account: useradd username
      • Set the user password passwd username
      • Now set a new password for root user passwd root
      • Now you can install additional packages (desktop environments, container technologies, flatpak) using pacman
      • Once done, exit the chroot with exit
      • Then you can deploy it with ash deploy <snapshot>

Additional documentation

Base image

  • The snapshot 0 is reserved for the base system image, it cannot be changed and can only be updated using ash base-update

Snapshot Management

Show filesystem tree

ash tree
  • The output can look for example like this:
root - root
├── 0 - base image
└── 1 - multiuser system
    └── 4 - applications
        ├── 6 - MATE full desktop
        └── 2*- Plasma full desktop

  • The asterisk shows which snapshot is currently selected as default

  • You can also get only the number of the currently booted snapshot with

ash current

Add descritption to snapshot

  • Snapshots allow you to add a description to them for easier identification
ash desc <snapshot> <description>

Delete a tree

  • This removes the tree and all it's branches
ash del <tree>

Custom boot configuration

  • If you need to use a custom grub configuration, chroot into a snapshot and edit /etc/default/grub, then deploy the snapshot and reboot

chroot into snapshot

  • Once inside the chroot the OS behaves like regular Arch, so you can install and remove packages using pacman or similar
  • Do not run ash from inside a chroot, it could cause damage to the system, there is a failsafe in place, which can be bypassed with --chroot if you really need to (not recommended)
  • The chroot has to be exited properly with exit, otherwise the changes made will not be saved
  • If you don't exit chroot the "clean" way with exit, it's recommended to run ash tmp to clear temporary files left behind
ash chroot <snapshot>
  • You can enter an unlocked shell inside the current booted snapshot with
ash live-chroot
  • The changes made to live session are not saved on new deployments

Other chroot options

  • Runs a specified command inside snapshot
ash run <snapshot> <command>
  • Runs a specified command inside snapshot and all it's branches
ash tree-run <tree> <command>

Clone snapshot

  • This clones the snapshot as a new tree
ash clone <snapshot>

Create new tree branch

  • Adds a new branch to specified snapshot
ash branch <snapshot to branch from>

Clone snapshot under same parent

ash cbranch <snapshot>

Clone snapshot under specified parent

  • Make sure to sync the tree after
ash ubranch <parent> <snapshot>

Create new base tree

ash new

Deploy snapshot

  • Reboot to boot into the new snapshot after deploying
ash deploy <snapshot>

Update base which new snapshots are built from

ash base-update
  • Note: the base itself is located at /.snapshots/rootfs/snapshot-0 with it's specific /var files and /etc being located at /.snapshots/var/var-0 and /.snapshots/etc/etc-0 respectively, therefore if you really need to make a configuration change, you can mount snapshot these as read-write and then snapshot back as read only

Package management

Software installation

  • Run ash deploy <snapshot> and reboot after installing new software for changes to apply (unless using live install, more info below)
  • Software can also be installed using pacman in a chroot
  • AUR can be used under the chroot
  • Flatpak can be used for persistent package installation
  • Using containers for additional software installation is also an option. An easy way of doing this is with distrobox
ash install <snapshot> <package>
  • After installing you can sync the newly installed packages to all the branches of the tree with
  • Syncing the tree also automatically updates all the snapshots
ash sync <tree>
  • If you wish to sync without updating (could cause package duplication in database) then use
ash force-sync <tree>
  • ash also supports installing packages without rebooting
ash install --live <snapshot> <package>

Removing software

  • For a single snapshot
ash remove <snapshot> <package or packages>
  • Recursively
ash tree-rmpkg <tree> <pacakge or packages>

Updating

  • It is advised to clone a snapshot before updating it, so you can roll back in case of failure

  • To update a single snapshot

ash upgrade <snapshot>
  • To recursively update an entire tree
ash tree-upgrade <tree>

  • This can be configured in a script (ie. a crontab script) for easy and safe automatic updates

  • If the system becomes unbootable after an update, you can boot last working deployment (select in grub menu) and then perform a rollback

ash rollback
  • Then you can reboot back to a working system

Extras

Fixing pacman corrupt packages / key issues

  • Arch's pacman package manager sometimes requires a refresh of the PGP keys
  • To fix this issue we can simply reinstall they arch keyring
ash install <snapshots> archlinux-keyring

Dual boot

  • Ashlinux supports dual boot using the GRUB bootloader
  • When installing the system, use the existing EFI partition
  • to configure dual boot, we must begin by installing the os-prober package:
ash install <snapshot> os-prober
  • Now we have to configure grub
ash chroot <snapshot>
echo 'GRUB_DISABLE_OS_PROBER=false' >> /etc/default/grub
exit
  • Now just deploy the snapshot to reconfigure the bootloader
ash deploy <snapshot>

Updating ash itself

  • sometimes it may be necessary to update ash itself
  • this can be done in a few steps:
git clone "https://github.com/Ashlinux/Ashlinux"
cd Ashlinux
cp astpk.py ash
chmod +x ash
cp ./ash /var/astpk/ash  # Copy new ash to /var, accessible from all snapshots
ash trun <snapshot> cp /var/astpk/ash /usr/local/sbin/ash  # Copy over new ash
ash clone 0
ash run <clone of 0> cp /var/astpk/ash /usr/local/sbin/ash  # Now we update snapshot 0 in a clone
btrfs sub del /.snapshots/rootfs/snapshot-0  # Here we manually replace snapshot 0 with the updated snapshot
btrfs sub snap -r /.snapshots/rootfs/snapshot-<clone of 0> /.snapshots/rootfs/snapshot-0
ash del <clone of 0>  # Remove temporary snapshot

Debugging ash

  • sometimes it may be necessary to debug ash
  • copy ash to any location:
cp /usr/local/sbin/ash astpk.py
  • the following command is useful as it shows outputs of commands when running astpk.py:
sed -i -e s,\ 2\>\&1\>\ \/dev\/null,,g astpk.py

If you have modified the original ash file (possible but not recommended), please make sure to revert it back when done!

Known bugs

  • When running ash without arguments - IndexError: list index out of range
  • Running ash without root permissions shows permission denied errors instead of an error message
  • Swap partition doesn't work, it's recommended to use a swapfile or zram instead
  • Docker has issues with permissions, to fix run
sudo chmod 666 /var/run/docker.sock
  • When using a graphical interface for network manager to connect to a network, network passwords aren't remembered in a new deployment
  • We can solve this by updating /etc with the changes made
sudo ash etc-update

Contributing

  • Code and documentation contributions are welcome
  • Bug reports are a good way of contributing to the project too
  • Before submitting a pull request test your code and make sure to comment it properly

Community

  • Please feel free to join us on Discord for further discussion and support!
  • Happy worry-free snapshotting!

Project is licensed under the AGPLv3 license