Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Handbook

Welcome to the TeamSBC handbook. This is a users and administrators guide about using and managing your TeamSBC installations. Read more about the intended audience or the introduction about TeamSBC.

If you like it here, be sure to join the community.

Intended Audience

TeamSBC is currently for tinkerers. It is not in a stable form yet but starting to be. If you have opinions about operating systems and how they should be put together, especially for single board computers, then you are more than welcome to join the community and share.

Community

Bugs and Feature Requests

Bugs and feature requests should be submitted to the dedicated distribution bugtracker on GitHub.

Discussions

Long-form discussions about project direction and large changes takes place on GitHub Discussions.

You can also join the #teamsbc:fedora.im Matrix channel for more casual chat.

Social Media

Project updates are also published on social media, if that’s your preferred way of keeping up. Here’s a list of TeamSBC’s official media accounts.

Introduction

Thank you for your interest in TeamSBC. In this chapter we will go over what TeamSBC is and how it is structured.

You can read this chapter to learn:

  • What TeamSBC is.
  • How TeamSBC relates to Fedora.
  • The goals of TeamSBC.
  • Where the name TeamSBC comes from.

What is TeamSBC?

TeamSBC is a Linux distribution.

Relation to Fedora

TeamSBC is a Fedora Remix. This means that it takes its packages from Fedora but then layers its own on top. TeamSBC makes its own decisions on service configuration, what services are used for what, and what should be installed on a system.

Differences with Fedora

If you are a Fedora user or have used it previously then it’s useful to know that there are differences and of course what those differences are.

systemd

TeamSBC prefers to use systemd functionality when possible. This leads to a smaller and more integrated system.

systemd-boot

TeamSBC uses systemd-boot as its bootloader; this means it only works on UEFI capable systems.

systemd-homed

Fedora doesn’t use systemd-homed by default. TeamSBC has it set up and prefers to use it whenever possible to manage local users. See managing users for more information on how to use systemd-homed.

systemd-networkd

Fedora uses NetworkManager to manage networks, TeamSBC uses systemd-networkd. See managing networks for how this works.

sudo

TeamSBC does not include sudo by default instead you can use run0.

Goals of TeamSBC

To provide an integrated, simplistic, minimal, and upstream based approach to running your favorite single board computers in a reliable and safe way.

What does the name mean?

The name comes from what the distribution targets. SBC stands for Single Board Computer, these are small computers such as the Raspberry Pi series of devices, various Radxa boards, or others. The team part comes from, well, team.

Variants

TeamSBC ships in variants. Variants allow for people to pick the flavour they prefer for maintaining their devices. Currently TeamSBC ships a single variant: Lhotse. However, we keep room for more in the future.

Lhotse

The lhotse variant is package-based. This is probably the type of setup that you are most familiar with if you’ve previously used any other Linux distributions.

Installation

TeamSBC builds and provides specific disk images that are optimized for specific devices. Disk images are provided for each variant. Before starting any installation pick the variant you want to use and familiarize yourself with its concepts.

Installation on single board computers involves downloading the appropriate image for the device you have and then copying the disk image onto its storage. Usually a micro SD card.

Installation Steps

Installation steps are the same for all TeamSBC variants.

  1. Find the image for your device in the supported devices list and download it on your system.
  2. Unpack the image, unxz teamsbc-46-lhotse-rpi4.raw.xz.

If you wish this is the time to perform offline provisioning on the disk image.

Tip

When testing out in a virtual machine; point your preferred virtual machine manager at the disk image and run, otherwise continue on.

microSD

Most Single Board Computers have some form of external storage, commonly a microSD card. Put a microSD card into a card reader attached to your computer. After this you can write the downloaded image directly onto the microSD card. This method applies to most Single Board Computers that have microSD storage.

  1. Find the device for your microSD card (let’s say it’s /dev/sde).
  2. Write the image onto the microSD card, dd if=teamsbc-46-lhotse-rpi4.raw of=/dev/sde bs=4M conv=fsync status=progress.

After the image has been written to your microSD card you can unmount your card and plug it into your device to boot from.

Supported Devices

Find the device you want to run TeamSBC on in the following list. If your device is not listed that means we don’t produce images for it. You might want to file a request to see if it can be a supported device in the future.

Virtual Machine

To run TeamSBC on virtual machines we provide the virt image type for the lhotse variant. You can download the latest built images from the following URLs:

Stable

x86_64
aarch64

Experimental

x86_64
aarch64

Single Board Computers

Raspberry Pi 4

To run TeamSBC on the Raspberry Pi 4 we provide the rpi4 image type for the lhotse variant. You can download the latest built images from the following URLs.

Stable

aarch64

Experimental

aarch64

Raspberry Pi 5

To run TeamSBC on the Raspberry Pi 5 we provide the rpi5 image type for the lhotse variant. You can download the latest built images from the following URLs.

Stable

aarch64

Experimental

aarch64

Provisioning

Setting up your device with credentials and configuration so it can be used immediately is what is called provisioning. There are multiple ways to do so.

When building customized images you can perform the above steps during the build process. Provisioning such as described here is for per-deployment configuration while doing customized builds is for configuration to be used in multiple deployments.

Good examples of per-deployment configuration is setting passwords or network credentials while multiple deployments might involve the packages installed on the systems. Use your own judgement.

Online Provisioning

The standard process of setting up your device is through guided prompts provided by systemd-firstboot during the first time your device boots. To do so you will need to connect a monitor or serial to your device.

During the boot process you will be prompted for the timezone and root password for your device. After those have been filled in the boot will continue and you can login to your device to do any further customization and configuration you might want to do.

Offline Provisioning

Warning

If you provision your image offline using systemd tooling (as documented here) you must create the .autorelabel file in the filesystem root of the image. This is due to a bug in systemd where it assigns the wrong SELinux contexts to certain files. This will incur an additional reboot when you boot your image for the first time. See auto-relabeling for how to do so.

If you want the device to finish its boot without having to connect peripherals to it you can also pre-customize the image before flashing it onto your storage media.

To prevent the online provisioning through systemd-firstboot you want to set at least the timezone and the root password on an image before writing it to your storage media.

You can use the systemd-firstboot --image to do so:

$ sudo systemd-firstboot \
  --image teamsbc-46-lhotse-rpi4.raw \
  --prompt-root-password \
  --prompt-timezone

More options are available to be configured, but they won’t hold the boot process from continuing.

When doing offline provisioning you likely want to enable the sshd service on the system as well so you can login after it comes online. You can do so with:

$ sudo systemctl \
  --image teamsbc-46-lhotse-rpi4.raw \
  enable sshd.service

Auto Relabeling

Due to the handling of SELinux labeling in systemd-related tooling you will need to touch the .autorelabel file in the filesystem root of your image if you have performed any of the above actions. This will incur a reboot during the first boot of your system and take some time.

You can instruct the image to relabel all contexts with the following command:

$ touch autorelabel
$ sudo systemd-dissect --copy-to teamsbc-46-lhotse-rpi4.raw autorelabel /.autorelabel
$ rm autorelabel

For more information you can read the related TeamSBC Bug or systemd bug.

Basics

This section covers fundamental system administration tasks on TeamSBC.

Privilege Escalation

TeamSBC does not include sudo. Instead you can use run0 to run commands as root.

$ run0 hostnamectl set-hostname mydevice

Managing Services

Services are managed through systemctl.

Starting and stopping a service

$ run0 systemctl start sshd.service
$ run0 systemctl stop sshd.service

Enabling and disabling a service

Enabling a service means it will start automatically on boot. Disabling it removes that behavior.

$ run0 systemctl enable sshd.service
$ run0 systemctl disable sshd.service

Checking service status

$ systemctl status sshd.service

Viewing Logs

System logs are managed by journald and can be viewed with journalctl.

Viewing logs for a specific service

$ journalctl -u sshd.service

Following logs in real time

$ journalctl -f

Viewing logs from the current boot

$ journalctl -b

System Information

Hostname

$ hostnamectl

Time and timezone

$ timedatectl

To change the timezone:

$ run0 timedatectl set-timezone Europe/Amsterdam

Updating

Note

This section applies to the Lhotse variant.

Keeping your system up to date is important for security and stability. TeamSBC uses dnf for package management.

Checking for updates

$ dnf check-update

Updating the system

$ run0 dnf upgrade

Rebooting after updates

Some updates require a reboot to take effect, most notably kernel and systemd updates. You can check if a reboot is needed with:

$ needs-restarting -r

Automatic updates

If you want your system to apply updates automatically you can enable dnf-automatic.

$ run0 dnf install dnf-automatic
$ run0 systemctl enable --now dnf-automatic-install.timer

Installing Applications

Note

This section applies to the Standard variant.

The Standard variant is package-based and uses dnf for package management.

Searching for packages

$ dnf search htop

Installing a package

$ run0 dnf install htop

Removing a package

$ run0 dnf remove htop

Listing installed packages

$ dnf list --installed

Users

You are able to manage users in more traditional ways through the shadow-utils provided tooling (useradd, passwd, etc) but TeamSBC intends for you to manage users through systemd-homed.

The preferred way in TeamSBC to manage local users is by using systemd-homed. This allows for portable, encrypted home directories for each user which get unlocked on user login. TeamSBC is configured to allow local and remote logins to systemd-homed managed users by default.

Managing Users

Adding a user

$ run0 homectl create $username

Removing a user

Removing users is a destructive action. Their home area will be destroyed and thus all data in there will be gone forever. Think twice if this is what you want and consider making a backup of the relevant home area.

If you are certain you want to remove the user you can use the following command. There is no confirmation prompt, the user will be gone immediately.

$ run0 homectl remove $username

Inspecting a user

$ run0 homectl inspect $username

Networking

TeamSBC uses systemd-networkd for network configuration instead of NetworkManager. Network configuration files are placed in /etc/systemd/network/.

Checking network status

$ networkctl

For detailed information about a specific interface:

$ networkctl status eth0

Wired networking

A default configuration for wired networking using DHCP is provided out of the box. To configure a static IP address create a .network file in /etc/systemd/network/:

[Match]
Name=eth0

[Network]
Address=192.168.1.100/24
Gateway=192.168.1.1
DNS=192.168.1.1

After creating or modifying network configuration files restart systemd-networkd:

$ run0 systemctl restart systemd-networkd.service

Wi-Fi

Wi-Fi is managed through wpa_supplicant alongside systemd-networkd.

Connecting to a network

Create a wpa_supplicant configuration for your wireless interface:

$ run0 wpa_passphrase "MyNetwork" "MyPassword" > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf

Enable and start the wpa_supplicant service for your interface:

$ run0 systemctl enable --now wpa_supplicant@wlan0.service

Then create a .network file in /etc/systemd/network/ for the wireless interface:

[Match]
Name=wlan0

[Network]
DHCP=yes

DNS

DNS is handled by systemd-resolved. You can check the current DNS configuration with:

$ resolvectl status

Build Your Own

Note

This page is a work in progress.

If you want to build customized images with your own package selection or configuration you can use the image definitions in the artifacts repository as a starting point. See the build system documentation for more information on how images are built.

Packages

TeamSBC layers its own packages on top of Fedora. Package specs are maintained in the packages repository. Packages are built in GitHub Actions and uploaded to the repositories on merge to main.

Common Packages

The common repository contains packages that are used by all TeamSBC variants:

  • teamsbc-release
  • teamsbc-repos
  • teamsbc-config
  • teamsbc-selinux

Artifacts

TeamSBC publishes built artifacts on artifacts.teamsbc.net. These include disk images for all supported devices and variants.

Structure

Artifacts are organized by branch, Fedora version, and architecture:

artifacts.teamsbc.net/
  main/
    latest/
      45/
        aarch64/
        x86_64/
      46/
        aarch64/
        x86_64/

Downloading Artifacts

You can find download links for all supported devices on the installation page or browse the artifacts storage directly.

Building Artifacts

Artifact definitions and build instructions live in the artifacts repository. See the build system documentation for how to build them locally.

Infrastructure

Domains

TeamSBC largely uses two separate domains to serve content.

teamsbc.org (and its subdomains) are used to serve text content such as the homepage and documentation. teamsbc.net is used to serve binary data such as our artifacts, packages, and other large files.

Build System

TeamSBC uses image-builder to produce disk images. Image definitions are maintained in the artifacts repository. Artifacts are also built there through GitHub Actions.

Building Locally

You can build artifacts locally using the provided Makefile in the artifacts repository.

Since TeamSBC often uses the latest features of image-builder there is a chance that they might not yet be in a released version. The default suggestion is to build with the upstream container:

$ make build-in-container VERSION=46 TYPE=lhotse-virt

If you don’t or can’t use containers you can replace build-in-container with build and your locally installed image-builder will be used. In that case make sure you have image-builder installed:

$ run0 dnf install image-builder

Testing

Testing of TeamSBC is currently done manually. If you would like to help improve test coverage or work on automated testing please join the community.

Manual Testing

When testing changes you can use the virtual machine images to boot and verify your changes without needing physical hardware.