Skip to content

  • system.yaml v4 badge#

    Manage your whole system with one file.

    • Language:
    • Comes with blendOS:
    File Location
    󰉋 /
└── 󱀺 system.yaml

    To edit the file, just open it in your favorite text editor ( You will need root privileges.).

What is system.yaml?

system.yaml is a simple host system configuration. It allows you to tweak many essential aspects of the host quickly and easily.

system.yaml is... system.yaml is not...
...device-independent and transferrable ...advanced, config is quite simple.
...simple ...like NixOS
...deployable, via tracks ...the way to use most apps on blendOS

Reference#

Any options marked with a next to their name in the expanded view can be set by a track.

All values shown here are default values or examples. You can find the default value (as well as info and examples) in the tooltip ().

system.yaml
repo: 'https://pkg-repo.blendos.co' # (1)!

arch-repo: 'https://geo.mirror.pkgbuild.com' # (10)!

impl: 'https://github.com/USER/REPO/raw/BRANCH' # (2)!

track: 'plasma' # (3)!

packages: # (4)!
  - 'package_1'
  - 'package_2'

aur-packages: # (5)!
  - 'package_1-git'
  - 'package_2-bin'

services: # (6)!
  - 'service_1'

user-services: # (9)!
  - 'user-service_1'

package-repos: # (7)!
  - name: 'REPO_NAME'
    repo-url: 'REPO_URL'

commands: # (8)!
  - 'echo command_1'
  - 'echo command_2'

  1. repo

    Type: string

    Default Value: https://pkg-repo.blendos.co

    This option must be set.

    Sets the repo for the core blendOS packages.

  2. impl

    Type: string

    Default Value: https://github.com/blend-os/tracks/raw/main

    This option must be set.

    Sets the raw URL prefix (track files are appended to the prefix to make a URL).

    This must be set to ensure that the full URL will serve all available files with a Content-Type of text/plain.

    Example

    If the start of the file looks like this:

    repo: 'https://pkg-repo.blendos.co'

impl: 'https://github.com/blend-os/tracks/raw/main'

track: 'plasma'

...

    The fully generated URL would be:

    https://github.com/blend-os/tracks/raw/main/plasma.yaml

    which would redirect to:

    https://raw.githubusercontent.com/blend-os/tracks/main/plasma.yaml

    which serves the file with a Content-Type of text/plain.

  3. track

    Type: string

    This option must be set.

    Sets the track (a mini system.yaml), which must be a YAML file in the folder of the impl URL.

    Available options are determined by the impl URL.

    If you are creating a custom track that does not inherit anything, set this value to custom.

    Example

    If I have a track folder/repo with the following files:

    • track-1.yaml
    • track-2.yaml

    and I set my impl URL properly, I then have 2 track options:

    track: 'track-1'

    and

    track: 'track-2'

  4. packages

    Type: array

    A list of packages to install using pacman (includes any custom repos you have set).

  5. aur-packages

    Type: array

    A list of AUR packages to install using paru.

  6. services

    Type: array

    A list of services to start at boot using systemd.

  7. package-repos

    Type: object array

    Custom repos to add to pacman.conf.

    name: The repo's name parameter in pacman.conf (the value between [])

    repo-url: The repo's URL (no mirrorlists) (the Server variable from pacman.conf)

    Value Placement
    pacman.conf
    [name]
Server = repo-url
SigLevel = Never
    Example: Chaotic AUR

    To add the Chaotic AUR, the values here would be set to the following:

    The name parameter is used as $repo in these URLs, so do not change it from the maintainer's default!

    package-repos:
  - name: 'chaotic-aur'
    repo-url: 'https://cdn-mirror.chaotic.cx/$repo/$arch'

  8. commands

    Type: array

    A list of commands to be run as root at system build.

  9. user-services

    Type: array

    A list of services to start at system boot at the user level (systemctl --user).

  10. arch-repo

    Type: string

    Default Value: https://geo.mirror.pkgbuild.com

    This is not specified in the file, but is rather the default if no value is specified.

    The main Arch Linux repo to use in pacman.conf.

    Do not put a trailing / at the end of the URL.

    Do not do this:

    system.yaml
    arch-repo: 'https://geo.mirror.pkgbuild.com/'

    Do this:

    system.yaml
    arch-repo: 'https://geo.mirror.pkgbuild.com'

    You can find a list of mirror URLs by visiting cloudflaremirrors.com (and looking at the bullet list, this shows nearby mirrors) or the Arch mirrorlist. Only copy the first part of the URL (before $repo).

    Example

    If I want to use the University of Waterloo's mirror (🇨🇦):

    URL shown in the mirrorlist
    https://mirror.csclub.uwaterloo.ca/archlinux/$repo/os/$arch
    system.yaml
    arch-repo: 'https://mirror.csclub.uwaterloo.ca/archlinux'

Tracks#

Always use the .yaml extension when creating track files!

akshara always looks for files with the .yaml extension, not .yml.

Tracks are like mini system.yaml files that you can create. They can inherit other tracks, or be entirely custom. They can be used to set default values for a certain configuration, like a desktop.

Track layout#

A track is structured exactly like a system.yaml, repo and all (yes you must set the repo, impl, and track).

As an example of a custom track, let's look at the official blendos-base track:

blendos-base.yaml 
track: 'custom'

packages:
  - 'alsa-utils'
  - 'amd-ucode'
  - 'arch-install-scripts'
  - 'b43-fwcutter'
  - 'archlinux-keyring'
  - 'base-devel'
  - 'git'
  - 'bash'
  - 'bzip2'
  - 'coreutils'
  - 'file'
  - 'filesystem-blend'
  - 'findutils'
  - 'gawk'
  - 'gcc-libs'
  - 'gettext'
  - 'glibc'
  - 'grep'
  - 'gzip'
  - 'iproute2'
  - 'iputils'
  - 'licenses'
  - 'pacman'
  - 'pciutils'
  - 'procps-ng'
  - 'psmisc'
  - 'sed'
  - 'shadow'
  - 'systemd'
  - 'systemd-sysvcompat'
  - 'tar'
  - 'util-linux'
  - 'xz' 
  - 'bash'
  - 'bash-completion'
  - 'bind'
  - 'blend'
  - 'blend-settings'
  - 'brltty'
  - 'broadcom-wl-dkms'
  - 'btrfs-progs'
  - 'cryptsetup'
  - 'dhclient'
  - 'dmidecode'
  - 'dnsmasq'
  - 'dosfstools'
  - 'e2fsprogs'
  - 'efibootmgr'
  - 'espeakup'
  - 'exfatprogs'
  - 'f2fs-tools'
  - 'fatresize'
  - 'gpart'
  - 'gptfdisk'
  - 'grub'
  - 'hdparm'
  - 'hyperv'
  - 'intel-ucode'
  - 'irssi'
  - 'less'
  - 'libfido2'
  - 'libusb-compat'
  - 'linux-zen'
  - 'linux-zen-headers'
  - 'linux-atm'
  - 'linux-firmware'
  - 'linux-firmware-marvell'
  - 'man-db'
  - 'man-pages'
  - 'mc'
  - 'mdadm'
  - 'memtest86+'
  - 'mkinitcpio'
  - 'mkinitcpio-archiso'
  - 'mkinitcpio-nfs-utils'
  - 'modemmanager'
  - 'mtools'
  - 'nano'
  - 'nbd'
  - 'ndisc6'
  - 'nfs-utils'
  - 'nilfs-utils'
  - 'ntfs-3g'
  - 'openconnect'
  - 'openssh'
  - 'openvpn'
  - 'os-prober'
  - 'parted'
  - 'partimage'
  - 'pcsclite'
  - 'ppp'
  - 'pptpclient'
  - 'pv'
  - 'rsync'
  - 'smartmontools'
  - 'sof-firmware'
  - 'squashfs-tools'
  - 'sudo'
  - 'syslinux'
  - 'tcpdump'
  - 'tpm2-tss'
  - 'udftools'
  - 'usb_modeswitch'
  - 'usbmuxd'
  - 'usbutils'
  - 'vpnc'
  - 'wireless-regdb'
  - 'wireless_tools'
  - 'wpa_supplicant'
  - 'wvdial'
  - 'xfsprogs'
  - 'xl2tpd'
  - 'bluez'
  - 'networkmanager'
  - 'cups'
  - 'ttf-jetbrains-mono'

services:
  - 'cups'
  - 'bluetooth'
  - 'NetworkManager'

user-services:
  - 'blend-files'

Here, the track value is set to custom (no impl), indicating a fully custom track. This track is setting default values for whomever uses it.

Tracks can also inherit from eachother (see next section).

Inheritance#

Inherited tracks are the most common type of track. They can be used to tack on different desktops, additional drivers/programs, to another track.

An example of this is the official plasma track.

plasma.yaml 
impl: 'https://github.com/blend-os/tracks/raw/main'

track: 'blendos-base'

packages:
  - 'kde-system-meta'
  - 'kde-utilities-meta'
  - 'plasma'
  - 'plasma-workspace'
  - 'sddm'
  - 'waydroid'
  - 'waydroid-image'

services:
  - 'sddm'

commands:
  - 'rm -f /usr/share/applications/Waydroid.desktop'

All of our desktop tracks inherit blendos-base. If you're creating a new desktop/WM track do this as well.

To inherit a track, simply set an impl and a track value in your track file.

Example

my-awesome-track.yaml
impl: 'https://github.com/blend-os/tracks/raw/main'

track: blendos-base

packages:
  - 'some-desktop'

This track now inherits from blendos-base, and adds a desktop to it.

If you're creating a fully custom track and do not want to inherit, simply set your track to custom with no impl (as mentioned above).

Reinheritance

If your track inherits a track that inherits another track (reinheritance), issues may result, like certain sections of the file being ignored. This is due to an akshara bug we are still investigating.

Creating a track repo/webserver#

First, create a repo on your favorite git forge, and put all your track files in the root of it.

If you want to do this quickly, just fork our track repo!

Once that is done, you'll need to make your impl URL.

impl URL structures for common git forges

https://github.com/USER/REPO/raw/BRANCH

https://GITLAB-SERVER/USER/REPO/-/raw/BRANCH

  • GITLAB-SERVER: Your gitlab server (usually gitlab.com)

https://GITEA-SERVER/USER/REPO/raw/branch/BRANCH

  • GITEA-SERVER: Your Gitea/Forgejo server (codeberg.org is a popular one)

https://bitbucket.org/USER/REPO/raw/FULL_COMMIT_HASH/

  • FULL_COMMIT_HASH: The full hash of the latest commit (you can get this under Commits)
  • USER: Your username
  • REPO: The repo
  • BRANCH: Your branch (usually main or master)

If you're using a webserver, put all the files in one folder. Your impl URL is the URL to that folder.

Custom repositories#

Custom repositories in system.yaml are quite easy.

If we use the arch-mact2 repo as an example, the repo folder structure is like this:

mirror.funami.tech
󰉋 /
└── 󰉋 arch-mact2
    └── 󰉋 os
        └── 󰉋 x86_64
            └── <repo files>

We can replace some of these with values.

mirror.funami.tech
󰉋 /
└── 󰉋 $repo
    └── 󰉋 os
        └── 󰉋 $arch
            └── <repo files>

In system.yaml, $arch corresponds to your system's architecture (currently x86_64) and $repo corresponds to your name parameter.

These variables are parsed by pacman, so never remove or change them from your mirror URL.

Configuring this mirror in system.yaml would look like this:

system.yaml
package-repos:
  - name: 'arch-mact2'
    repo-url: 'https://mirror.funami.tech/$repo/os/$arch/'

Corresponding to this in pacman.conf:

pacman.conf
[arch-mact2]
Server = https://mirror.funami.tech/$repo/os/$arch
SigLevel = Never

Built with Material for MkDocs.