SSS/GNU system - Manual & Documentation

Find the divine sayings, and the destined computer configurations, all my Guix, Scheme, SwayFX, and Emacs Lisp and more configurations here for learning you a fully Lisp machine with GNU/Linux for a great good.

Warning: parts of the code and settings might default to the Dutch language ( nl_NL.UTF-8 ).

I am currently working on the GNU operating system in order to create a secure libre Lisp workstation.

I refer to SSS lovingly as the modern Lisp machine. With this one obtains a computing style and programming environment that can be referred to as Lisp user space. This is a modern iteration of the Lisp machines of yore.

You can be aware of all the code that is running on your machine, which puts free GNU systems among the most secure operating systems on Earth.

Learning Lisps is really going down a rabbit hole, but trust me, you will come out with a better understanding of programming as a whole out the other end.

Lisp user space provides an introspective, hackable, and transactionable operating system that can be modified live in a REPL.

The lines between data and code fade, allowing insane flexibility and power.

Lisp user space is centered on accessible interfaces that are mostly text-based, and can be mostly used without a mouse, which makes it easier to use for people living with disabilities as well as power users.

All of the system can be inspected and most of it can be hacked live in a REPL, making it a pure expression of the libre software ethic, and an incredibly versatile tool for a skilled programmer.

In some ways this is a laboratory of experimentation for my computing environment. What I do with any other program that forms part of SSS is only meant to work for me. As such, I will try to maintain backwards compatibility and consistency, but I may introduce breaking changes without prior notice.

This configuration is somewhat biased towards containing a joe user who also acts as administrator for most of the time. This is trivial to change and should be easy to adapt to your needs. Your mileage may vary (YMMV).

Some commands in the Makefile are more geared towards joe since we assume a device is most frequently only tended to by one system administration most of the time. Some examples are make fr or make jr. Feel free to change this or contribute improvements to make this modular.

The system and home folders of users are managed independently of each other, in quite a loosely coupled manner.

GNU Guix is a package management tool for and distribution of the GNU system. Guix makes reproducibility easy and allows users to install, upgrade, or remove software packages, to roll back to a previous package set, to build packages from source, and generally assists with the creation and maintenance of software environments.

While you can install GNU Guix on top of an existing GNU/Linux system where it complements the available tools without interference, I encourage the use of Guix system, as standalone operating system distro, on top of which I have built the Supreme Sexp System (SSS).

I highly recommend refering to and studying the Guix reference manual, it's a super valuable source of knowledge: https://guix.gnu.org/manual/en/html_node/.

SSS attempts to stay as libre as possible, while also respecting your convenience.

This means, among other things that SSS:

• includes the OG Linux kernel (with proprietary blobs) so as to be more compatible with modern hardware
• includes non-guix software channel by default, so as to allow installation of convenient software to which few/no libre alternatives exist.

When keybindings (shortcurts) are defined, the following legend applies (a la Emacs):

This manual is written by hand with care and attention for detail.

I write my documents in Org format from Emacs and export them for your convenience to several other formats. A usual release of the manual happens as follows:

• Edit the SSS manual
• Run C-c # m from Emacs, which runs lib/sss-manual.el, exporting the Org document to several other formats (LaTEX, PDF, HTML, Markdown, etc.)

SSS supports several user customizations, more specifically:

Several color palettes, inspired by the great `ef-themes` by Protesilaos Stavrou, including ef-bio, ef-cyprus and ef-dream.

Find Prot's themes here: https://github.com/protesilaos/ef-themes

It is REQUIRED to include a per-host.scm in the root of this project, which is excluded from Git, and will determine certain settings for your own machine. Find here a reference configuration with what is required.

(use-modules (gnu)
             (gnu packages))

;; system language
(define sss-lang "en_US")

;; system timezone
(define sss-timezone "Europe/Amsterdam")

;; system keyboard layout
(define sss-keyboard-layout "us")

;; caps to control enabled
(define sss-keyboard-caps-to-ctrl
  #t)

;; system hostname
(define sss-hostname "gnusystem")

;; disk partitioning
(define sss-filesystems
  (list (file-system
         (device "/dev/nvme0n1p3")
         (mount-point "/")
         (type "ext4"))
        (file-system
         (device "/dev/nvme0n1p1")
         (mount-point "/boot/efi")
         (type "vfat"))))

;; packages that should only be installed in the current host
;; or (define sss-per-host-packages '())
(define sss-per-host-packages '(
                                ;; AMD non-free drivers
                                "amd-microcode" "amdgpu-firmware"
                                ;; Games
                                "prismlauncher" "steam")
  )

;; location where you cloned SSS Git repository
(define sss-clone-dir
  "$HOME/Ontwikkeling/Persoonlijk/sss")

;;
;; Define the active palette for all users accounts
;; You should reconfigure and ideally restart the system
;; for all changes to take effect
;;
;; Note: You could choose on a per-user basis to set a fixed palette
;; and not follow system wide, by just redefining this value
;;
;; Possible values are:
;;   - sss-palette-ef-bio
;;   - sss-palette-ef-cyprus
;;   - sss-palette-ef-dream
;;   - sss-palette-heavy-metal
;;   - sss-palette-solarized-light
;;   - sss-palette-ef-autumn
;;
(define-public sss-active-palette
  'sss-palette-ef-dream)

;; Nix packages to install
(define-public sss-nixpkgs
  '("yaml-language-server" "bash-language-server"
    "monaspace"
    "jdt-language-server"
    "nil"
    "black"
    "pyright"
    "marksman"
    "_1password-gui"
    "_1password-cli"
    "stack"
    "sbt"
    "scala_2_13"
    "firefox"
    "thunderbird"
    "postman"
    "vscode-langservers-extracted"
    "nwg-look"
    "krew"
    "mermaid-cli"
    "jetbrains.idea-community"))

;; Flatpak remotes to add to the user
(define sss-flatpak-user-remotes '((flathub . "https://dl.flathub.org/repo/flathub.flatpakrepo")))

;; Flatpak packages to install
(define sss-flatpak-pkgs '("app.drey.Warp" "com.usebottles.bottles"))

;; Additional Sway startup commands on per-host basis
(define sss-sway-extra-startups
'("swaymsg -- output eDP-1 scale 1.5"))

;; Additional Labwc startup commands on per-host basis
(define sss-labwc-extra-startups
'("wlr-randr --output eDP-1 --scale 1.5  >/dev/null 2>&1 &"))

It's possible you need to some manual installations, and temporary workarounds, in order to install sss on a brand-new Guix installation.

Some aspects will be dependent on the manner of installation and hardware. Below follows a simple startup guide.

On Hardware Requirements:

While SSS is designed to be lightweight and efficient, certain hardware configurations will provide a smoother experience. The following are recommended minimums:

• CPU: A modern x86-64 processor (Intel or AMD) is preferred. ARM64 is supported but may require additional configuration.
• RAM: 4GB of RAM is the absolute minimum. 8GB or more is highly recommended for a comfortable experience, especially if you plan to run memory-intensive applications or virtual machines.
• Disk Space: 30GB of disk space is a good starting point. Consider more if you plan to install a large number of packages, store many files, or use virtual machines extensively. SSDs are strongly recommended for optimal performance.
• Graphics: SSS leverages Wayland and Sway. Most modern graphics cards should work well. If you encounter issues, consult the Sway documentation for compatibility information.

Download and the Guix GNU/Linux distribution from the official Guix page: https://guix.gnu.org/download/ and make a bootable installation medium convenient for your use case.

If you are not familiar with the dd command which is present in all GNU/Linux distributions and in macOS, you can always feel free to use something like Rufus on Windows, or balenaEtcher, to flash this image into a USB, with which you can then boot your computer.

It is highly recommended to first become familiar with SSS and Guix via a throw-away virtual machine where you can experiment and do mistakes. After familiarity is acquired then a bare metal installation is the best.

SSS strives to be completely cross-architecture and should work well everywhere. That being said, as of the latest manual, x86-64 is the preferred architecture.

Nixpkgs contains a lot of software which we can leverage and manage from Guix.

SSS will automatically install and provide the Nix package manager for you.

SSS also provides some facilities to manage Nix from the comfort of your Guile Scheme.

You might need to activate and link the profile in order to be able to use, for the first time.

Assuming joe as user in question.

/nix/var/nix/profiles/per-user/ should be:

joe@guixvm ~ λ  ll /nix/var/nix/profiles/per-user/

drwxr-xr-x 2 joe  users  16K 29 dec 23:09 joe/
drwxr-xr-x 2 root root  4,0K 22 nov 13:23 root/

For this, make the directory an link it to your home.

sudo mkdir -p /nix/var/nix/profiles/per-user/joe
sudo chown -R joe:users /nix/var/nix/profiles/per-user/joe
ln -sfv /nix/var/nix/profiles/per-user/joe/profile $HOME/.nix-profile

It's possible you might need to logout and log back in to re-activate the profile.

You can switch your install to use nixpkgs-unstable with:

nix-channel --add https://nixos.org/channels/nixpkgs-unstable
nix-channel --update

You can install Nix packages by running:

nix -L profile install --impure nixpkgs#firefox

You can keep your Nix packages updated by running:

NIXPGS_ALLOW_UNFREE=1 nix profile upgrade --impure '.*'

The installed software will be available, for example at: $HOME/.nix-profile/bin/

SSS provides some scripts that allow you to maintain your Nix configuration and installed packages programatically with Lisp.

You can find these scripts and the list file at system/scripts in this repo and in the Makefile.

Installing all wanted Nix packages can be done with make npi for example and updating them with make npu.

SSS takes care of flatpak origins and installing and maintaining your flatpaks up to date, all programatically and with Lisp.

You can find these scripts and the list file at system/scripts in this repo and in the Makefile.

Installing all wanted Flatpak packages can be done with make fpi for example and updating them with make fpu.

Contributing to free software is a uniquely beautiful act because it embodies principles of generosity, collaboration, and empowerment.

We welcome everyone to feel invited to the SSS Project, and feel free to contribute, improve it and/or suggest improvements, brainstorm with me, make it more modular/flexible.

Find the backlog and project management of SSS here.

SSS favors modern technologies and thus makes use of Pipewire for all your GNU/Linux audio needs.

In practice this means that any user account in your system that wants to make use of audio, should have the (service home-dbus-service-type) and (service home-pipewire-service-type) services enabled for their account (yes per-user basis).

You will also want to set the RTC_USE_PIPEWIRE variable to true. This is already the case by default in SSS.

Most of the times, Sway will have set the correct resolution and scale (fractional) for your device. This also happens automatically when plugging in/out external monitors.

You might want to customize things though, here follow some examples of commands I use daily for this:

# Set fractional scaling to 1.5x , perfect for my Framework laptop 13,5"
swaymsg -- output eDP-1 scale 1.5
# Set resolution to 4k and scale 2x
swaymsg -- output Virtual-1 mode --custom 3840x2160 scale 2
# Set resolution and refresh rate
swaymsg -- output HDMI-A-1 mode --custom 1680x1050@50
# 1080p
swaymsg -- output Virtual-1 mode --custom 1920x1080 scale 1

SSS automatically loads at startup a matching wallpaper for the currently enabled theme.

This uses swww and thus can load animated images as well and do fancy transitions. If you have bugs loading wallpaper at startup, try reloading the wallpaper with s-S-b.

TODO: allow more dynamics and often changing of wallpapers, also random wallpaper script (but within theme)

Joe's account is automatically configured with a multi-user Git setup. See lib/git.scm. Currently this works on a per-directory basis, and is configured by default to my preferred settings. TODO: make this more configurable.

My settings are:

• $HOME/Ontwikkeling/Persoonlijk is where I keep my personal development projects. These are uploaded to Codeberg, and use their own gitconfig, email address, default git message, GPG key, and SSH keys.
• $HOME/Ontwikkeling/Werk is where I keep my work projects. These are uploaded to Github, and use their own gitconfig, email address, default git message, GPG key, and SSH keys.

Reproducibility and isolation of builds naturally leads to a little more disk usage than other systems. This is not a problem nowadays, with cheap storage.

That being said, here follow some useful reminders, every now and then clean:

• Guix generations
• Guix store
• Nix store
• Unused Steam games

You could run something like this:

sudo guix system delete-generations 1d
sudo guix gc
nix-store --gc

If you'd like to find the largest files in your disk, here’s an example command:

du -ah / | sort -rh | head -n 20

The real best way to manage your bluetooth is using the bluetoothctl shell. This is a little more manual and low-level, but it will allow your to programatically connect to your devices, setup shortcuts for "favourite" connections, and much more.

# Run bluetoothctl in a shell
user@host $ bluetoothctl
#
# Waiting to connect to bluetoothd...[bluetooth]# Agent registered
# [bluetooth]# hci0 new_settings: powered bondable ssp br/edr le secure-conn cis-central cis-peripheral 
# [bluetooth]# [CHG] Controller C8:A3:E8:76:98:80 Pairable: yes
# [bluetooth]# AdvertisementMonitor path registered
# [bluetooth]#

#  help

# then turn your bluethooth on:
#  power on
#
# [bluetooth]# Changing power on succeeded

# scan for devices around you:
#  scan on
#
# [bluetooth]# SetDiscoveryFilter success
# [bluetooth]# Discovery started
# [bluetooth]# [CHG] Controller C8:A3:E8:76:98:80 Discovering: yes
# [bluetooth]# [NEW] Device 52:B7:C5:C2:54:3A 52-B7-C5-C2-54-3A
# [bluetooth]# [NEW] Device 4B:C8:1D:17:55:A6 4B-C8-1D-17-55-A6
# [bluetooth]# [NEW] Device 27:9F:3F:70:13:71 27-9F-3F-70-13-71
# [bluetooth]# [NEW] Device E3:FE:C8:39:99:36 Wahoo KICKR 6F8D

# pair C0:23:8D:57:73:CF 

# exit

SSS comes equipped with libvirt and libvirt-manager (the GUI).

I'd recommend for most cases to simply use the GUI to create a new NAT network, and have your VMs be able to connect to the Internet.

If you want two-way traffic, and your machine is connected wirelessly to the network, you won’t be able to use a true network bridge.

In this case, the next best option is to use a virtual bridge with static routing and to configure a libvirt-powered virtual machine to use it (via the virt-manager GUI for example). This is similar to the default mode of operation of QEMU/libvirt, except that instead of using NAT (Network Address Translation), it relies on static routes to join the VM (virtual machine) IP address to the LAN (local area network). This provides two-way connectivity to and from the virtual machine, which is needed for exposing services hosted on the virtual machine.

A virtual network bridge consists of a few components/configurations, such as a TUN (network tunnel) interface, DHCP server (dnsmasq) and firewall rules (iptables). The virsh command, provided by the libvirt package, makes it very easy to create a virtual bridge. You first need to choose a network subnet for your virtual bridge; if your home LAN is in the ‘192.168.1.0/24’ network, you could opt to use e.g. ‘192.168.2.0/24’. Define an XML file, e.g. /tmp/virbr0.xml, containing the following:

<network>
  <name>virbr0</name>
  <bridge name="virbr0" />
  <forward mode="route"/>
  <ip address="192.168.2.0" netmask="255.255.255.0">
    <dhcp>
      <range start="192.168.2.1" end="192.168.2.254"/>
    </dhcp>
  </ip>
</network>

Then create and configure the interface using the virsh command, as root:

virsh net-define /tmp/virbr0.xml
virsh net-autostart virbr0
virsh net-start virbr0

The ‘virbr0’ interface should now be visible e.g. via the ‘ip address’ command. It will be automatically started every time your libvirt virtual machine is started.

If you configured your virtual machine to use your newly created ‘virbr0’ virtual bridge interface, it should already receive an IP via DHCP such as ‘192.168.2.15’ and be reachable from the server hosting it, e.g. via ‘ping 192.168.2.15’. There’s one last configuration needed so that the VM can reach the external network: adding static routes to the network’s router.

In this example, the LAN network is ‘192.168.1.0/24’ and the router configuration web page may be accessible via e.g. the http://192.168.1.1 page. On a router running the libreCMC firmware, you would navigate to the Network → Static Routes page (https://192.168.1.1/cgi-bin/luci/admin/network/routes), and you would add a new entry to the ‘Static IPv4 Routes’ with the following information:

‘Interface’ lan

‘Target’ 192.168.2.0

‘IPv4-Netmask’ 255.255.255.0

‘IPv4-Gateway’ server-ip

‘Route type’ unicast

where server-ip is the IP address of the machine hosting the VMs, which should be static.

After saving/applying this new static route, external connectivity should work from within your VM; you can e.g. run ‘ping gnu.org’ to verify that it functions correctly.

SSS supports specifying default applications to use for certain files, and also xdg-open, and customize allowed options, all in comfortable Scheme code.

Refer to the sss mime module at lib/ and the sss-mimeapps-list-file function to understand more how it works.

(define-public sss-mime-default-applications
'((application/pdf org.gnome.Evince google-chrome firefox)
  (text/html firefox emacsclient)))

The XDG MIME Applications specification builds upon the shared MIME database and desktop entries to provide default applications.

Added Associations indicates that the applications support opening that MIME type. For example: bar.desktop and baz.desktop can open JPEG images. This might affect the application list you see when right-clicking a file in a file browser.

Removed Associations indicates that the applications do not support that MIME type. For example, baz.desktop cannot open H.264 video.

Default Applications indicates that the applications should be the default choice for opening that MIME type. For example, JPEG images should be opened with foo.desktop. This implicitly adds an association between the application and the MIME type. If there are multiple applications, they are tried in order.

At ~/.config/mimeapps.list you get this:

[Default Applications]
application/pdf=evince.desktop;google-chrome.desktop;firefox.desktop
text/html=google-chrome.desktop;firefox.desktop

Q: I ran out of disk space, and have too much garbage in the system!

A: Check the Makefile of SSS and run a make full-gc followed by a make sr

Q: Grub install fails due to missing disk space / input-output error!

A: It's recommended to delete some old generations of the system (perhaps also a make full-gc) and to clean the dump file at: /sys/firmware/efi/efivars/dump*

Q: I have a strange error, where guix system reconfigure or guix home reconfigure fails, and some error about expected string ~`Derive String(['! This is also not consistently reproducible and happens in some machines, others not!

A: Sorry, your guix store is partially corrupted. There is some things you can do luckily. First of all backup your important data. Then try to identify the culprit, i.e. the file in the store which is being read and not successfully parsed.

You could first try to do a sudo guix gc --verify=repair,contents, but that may not help. If it does then great you are done! Otherwise try to find a way to disable the dependency on this in your config if possible. Proceed to delete all Guix home generations (except current), after which you should delete all system generations (except current) and do an intensive garbage collection (make full-gc).

You can optionally do a guix pull now to see if maybe a new version of things comes along and helps. In any case try to reconfigure (make jr / make sr) again and it should work, after which you can turn the "offender" back on.

Q: I am unable to generate a GPG key! I get errors about pin-item or pinentry!

A: Try with gpg --pinentry-mode loopback --full-gen-key. Otherwise try other options and check you have the right pinentry programs installed.

• GNU/Linux: A free and open-source operating system combining the GNU system and the Linux kernel.
• Lisp Machine: A type of computer optimized for running Lisp, a family of programming languages.
• GNU Guix: A functional package management tool and standalone distribution of the GNU system.
• REPL (Read Eval Print Loop): An interactive programming environment for evaluating code and seeing immediate results.
• TTY (TeleTYpewriter): A text terminal for interacting with a computer system.
• Scheme: A Lisp dialect often used for scripting in GNU Guix.
• Wayland: A protocol for a display server, often used as a modern alternative to X11.
• Sway: A Wayland compositor compatible with i3-style window management.
• PipeWire: A modern multimedia framework for managing audio and video streams.
• Elpaca: A package manager for Emacs that supports advanced configuration options.
• Libre: Free and open-source software that respects user freedom.

• SSS: Supreme Sexp System
• GNU: GNU's Not Unix
• OS: Operating System
• REPL: Read Eval Print Loop
• TTY: TeleTYpewriter
• X11: The X Window System
• DBus: Desktop Bus (inter-process communication system)
• RTC: Real-Time Communication

While we may not like thinking about these situations, life has an expiry date for us all, and as such we should prepare for a day when we are no more.

Instructions are crucial in this case because the computer systems we posess might hold valuable or sentimental information.

Without guidance, it could be difficult to figure out how to access these computers, specially a somewhat niche setup like SSS.

Our loved ones can hopefully thanks to this section of the manual understand how to use the computer, retrieve important files, or preserve their work.

Firstly, get a hold of as many passwords as you can and account information, before turning on the device.

Proceed to turn on the device. If immediately a password prompt appears, this is likely a system-wide BIOS password, which you will need to unlock to even use the computer.

Choose the boot option for Guix/GNU/Linux if the choice is presented. If multiple options are shown, just press ENTER to choose the default option or use the arrow keys to move around the GRUB boot menu. If the machine struggles to boot, something like Universal Rescue Disk could come in handy.

Once you boot into SSS (Guix + GNU + Linux), you will see a fast succession of letters in a black screen, wait a bit until you see appear something like:

This is the GNU system! login:

At this point you should type the username of the session you want to log into (generally this is short and all lowercase letters), followed by ENTER.

Then you will get a password prompt. Type the password and press ENTER. Don't worry if you don't see any * characters for the password, your typing worked, this is just a security measure.

If the details were not correct, you will get prompted to login again.

If they were correct, then you will enter the user's shell, at which point you could type gui followed by ENTER to start a graphical user interface.

You should have then booted into a more familiar environment. If the user you logged into has the Sway session, the keyboard bindings are documented in sections above. You could for example use Super+/ to open the fuzzy application finder (Super is often the "Windows" or "command" key).

Good luck!

SSS uses standard GNU/Linux user management tools. You should create users by tweaking the Scheme code of Guix config (config.scm) and optionally you can also create a Guix home file (home/<user>.scm).

When everything is in place, add a password to the user with sudo passwd <user>.