Merge pull request #35 from ValShaped/dev

Rwfus v0.4.2

Author: ValShaped

.shellcheckrc

@@ -1,2 +1,4 @@
 source-path=SCRIPTDIR/
 source-path=SCRIPTDIR/rwfus_include
+# Disable unassigned variable lint
+disable=2154

documentation/naming-conventions.md

@@ -6,7 +6,10 @@ There are three kinds of variable used in this project:
 - `local_variables`
     - These are used to store temporary information, and are used as if they're scoped. They're not scoped. Bash isn't a programming language.
     - When possible, use these with the local keyword.
+- `cf_Global`
+    - These are variables *set by config.sh* for use in other scripts. Please do not set them outside config.sh.
 - `Global_Configuration_Variables`
-    - These are used to store information that needs to be easily accessible by everything. Generally related to the config file.
+    - These are used to store information that needs to be easily accessible by everything. Generally set by info.sh
+
 - `GLOBAL_STATE_FLAGS`
-    - These are used when a variable needs to persist between runs of a single function, and carry information about the so-called-program state
+    - These are used when a variable needs to persist between runs of a non-reentrant function, and carry information about the so-called-program state

documentation/rwfus.conf.md

@@ -0,0 +1,76 @@
+# /etc/opt/rwfus.conf
+
+### Common
+| Field               | Explanation      | Default                                              |
+|---------------------|------------------|------------------------------------------------------|
+| `Directories`       | Overlay paths    | /usr /etc/pacman.d /var/lib/pacman /var/cache/pacman |
+| `Base_Directory`    | Install path     | /opt/rwfus                                           |
+### Service
+| Field               | Explanation      | Default                                              |
+|---------------------|------------------|------------------------------------------------------|
+| `Stop_Units`        | Units to stop    | var-cache-pacman.mount                               |
+| `Mask_Units`        | Units to mask    | pacman-cleanup.service                               |
+| `Restart_Units`     | Units to restart | usr-local.mount polkit.service                       |
+### Overlay
+| Field               | Explanation                                  | Default                  |
+|---------------------|----------------------------------------------|--------------------------|
+| `Upper_Directory`   | Source for overlay's files                   | /opt/rwfus/mount/upper   |
+| `Work_Directory`    | OverlayFS requires space for temporary files | /opt/rwfus/mount/work    |
+### Disk
+| Field               | Explanation                  | Default                                  |
+|---------------------|------------------------------|------------------------------------------|
+| `Mount_Options`     | Btrfs mount options          | loop,compress                            |
+| `Mount_Directory`   | Path to mount disk into      | /opt/rwfus/mount                         |
+| `Disk_Image_Path`   | Path to disk image           | /opt/rwfus/rwfus.btrfs                   |
+| `Disk_Image_Size`   | Maximum size of image        | 8G                                       |
+### Configurator
+| Field               | Explanation                  | Default                                  |
+|---------------------|------------------------------|------------------------------------------|
+| `Systemd_Directory` | Systemd units go here        | /etc/systemd/system                      |
+| `Service_Directory` | `rwfusd` script goes here    | /opt/rwfus/service                       |
+| `Install_Directory` | Where `rwfus -I` installs to | /home/.steamos/offload/usr/local/bin     |
+| `Logfile`           | Log file path                | /var/log/rwfus.log                       |
+
+# Additional Configuration
+| Field         | Type        | Default             | Reason not included in config file                |
+|---------------|-------------|---------------------|---------------------------------------------------|
+| `Config_File` | Config path | /etc/opt/rwfus.conf | Can't find config file if this option is changed. |
+
+
+# Examples
+```conf
+# Generated by Rwfus v0.4.1
+
+[Common]
+# All other paths, if left unspecified, derive from this one
+Base_Directory     /opt/rwfus
+Directories        /usr /etc/pacman.d /var/lib/pacman /var/cache/pacman
+
+[Service]
+# Units to [Stop|Mask|Restart] while Rwfus is running
+Stop_Units         var-cache-pacman.mount
+Mask_Units         pacman-cleanup.service
+Restart_Units      usr-local.mount
+
+[Overlay]
+# Where the overlayfs upperdirs and lowerdirs go
+Upper_Directory    /opt/rwfus/mount/upper
+Work_Directory     /opt/rwfus/mount/work
+
+[Disk]
+# Btrfs mount options. Make sure you keep `loop`
+Mount_Options      loop,compress
+Mount_Directory    /opt/rwfus/mount
+# Path to the disk image
+Disk_Image_Path    /opt/rwfus/rwfus.btrfs
+Disk_Image_Size    8G
+
+[Configurator]
+# Where systemd expects units to be
+Systemd_Directory  /etc/systemd/system
+# Storage directory for the daemon script and service-unit
+Service_Directory  /opt/rwfus/service
+Install_Directory  /home/.steamos/offload/usr/local/bin
+# The path to the logfile
+Logfile            /var/log/rwfus.log
+```

readme.md

@@ -1,16 +1,25 @@
 ## Rwfus: Read-Write OverlayFS for your Steam Deck!
 ---
 
-Like a vinyl couch cover for your filesystem, Rwfus covers your Deck's /usr/ directory (and some others) allowing you to initialize and use pacman (the Arch Linux package manager) on the Steam Deck without losing packages when the next update comes out.
+Like a vinyl couch cover for your filesystem, Rwfus covers your Deck's /usr/ directory (and some others) allowing you to initialize and use* pacman (the Arch Linux package manager) on the Steam Deck without losing packages when the next update comes out.
 
 Directories covered in a default installation:
-Directory         | Contents
----               | ---
-/etc/pacman.d     | `pacman` configuration
-/usr              | Programs and libraries
-/var/cache/pacman | Package cache
-/var/lib/pacman   | Package metadata
+| Directory         | Contents               |
+| ----------------- | ---------------------- |
+| /etc/pacman.d     | `pacman` configuration |
+| /usr              | Programs and libraries |
+| /var/cache/pacman | Package cache          |
+| /var/lib/pacman   | Package metadata       |
 
+### * Jank warning
+
+Due to the way Valve's firmware updates work, doing `pacman -S[y[y]]u` at any time will lead to complications when the next firmware update is installed. I highly advise avoiding `-Su`, `-Syu`, and `-Syyu` altogether on a Steam Deck with read-only rootfs. It may lead to bad behavior.
+
+Rwfus is, right now, a proof of concept (hence the 0.x version number, and being written in Bash.)
+I made it to install a couple user-mode packages (nano-syntax-highlighting and yakuake specifically.)
+It is not production-ready software, and in using Rwfus, you accept that I am not liable if your Deck catches fire.
+
+Rwfus will allow you to install *any* package, but not everything will let your Deck survive an update. In particular, `glibc` will crash your Deck after an update, requiring the SteamOS recovery image and some knowledge of Linux and/or Rwfus' internals to fix.
 
 ### Installation:
 
@@ -20,15 +29,14 @@ Directory         | Contents
 
 Then you're all set! Remember to periodically run `pacman -Sy` to update your repos
 
-### Jank warning
-
-Due to the way Valve's firmware updates work, doing `pacman -S[y[y]]u` at any time will lead to complications when the next firmware update is installed. I highly advise avoiding `-Su`, `-Syu`, and `-Syyu` altogether on a Steam Deck with read-only rootfs. It may lead to bad behavior.
-
 ### Usage:
 
 ```
+Rwfus v0.4.1
+Carry Pacman across SteamOS updates!
+
 USAGE:
-    rwfus [FLAGS] [OPTIONS] [--] [DIRECTORY]...
+    ./rwfus [FLAGS] [OPTIONS]
 
 FLAGS:
     -h, --help          Show this help text, then exit
@@ -45,7 +53,7 @@ FLAGS:
         --mount*        Mount Rwfus's disk image
         --umount*       Unmount Rwfus's disk image
 
-    -I, --install-bin*  Put /usr/local/bin/rwfus into a [...]/usr/local/bin folder
+    -I, --install-bin*  Put ./rwfus into a [...]/usr/local/bin folder
     -R, --remove-bin*   Remove Rwfus from a [...]/usr/local/bin folder
 
     -t, --test          Use fake directory targets when performing operations
@@ -55,17 +63,13 @@ FLAGS:
 
     OPTIONS:
     -l, --logfile <path>    Specify the location of Rwfus's log file
-                                Default: /tmp/rwfus.XXXX.log (where X is random)
+                                Default: /var/log/rwfus.log (where X is random)
     -c, --config <path>     Specify a configuration file to use
                                 Default: /opt/rwfus/
         --backup <dest>*    Backup Rwfus's disk image to (file path) <dest>
         --restore <src>*    Restore Rwfus's disk image from (file path) <src>
 
     * options marked with a star require root, unless the --test flag is set.
-
-ARGS:
-    <DIRECTORY>...          List of directories to create overlays for
-                                Defaults: /usr /etc/pacman.d /var/lib/pacman /var/cache/pacman
 ```
 
 #### Examples:

rwfus

@@ -49,7 +49,7 @@ $Name v$Version
 $Description
 
 USAGE:
-    $0 [FLAGS] [OPTIONS] [--] [DIRECTORY]...
+    $0 [FLAGS] [OPTIONS]
 
 FLAGS:
     -h, --help          Show this help text, then exit
@@ -83,10 +83,6 @@ FLAGS:
         --restore <src>*    Restore $Name's disk image from (file path) <src>
 
     * options marked with a star require root, unless the --test flag is set.
-
-ARGS:
-    <DIRECTORY>...          List of directories to create overlays for
-                                Defaults: $cf_Directories
 EOF
 }
 
@@ -236,10 +232,14 @@ for operation in ${Operation:=$Default_Operation}; do
             config --load
             state=$(service_state)
             echo "$state"
-            if [[ "$state" =~ "active" ]]; then
-                disable_service
+            if [[ "$state" == "active"* ]]; then
+                service disable
                 $operation "$disk_path"
-                enable_service
+                case "$operation" in
+                    "backup_disk"|"restore_disk")
+                        service enable
+                    ;;
+                esac
             else
                 $operation "$disk_path"
             fi

rwfus_include/config.sh

@@ -2,7 +2,7 @@
 # shellcheck shell=bash
 : <<LICENSE
       config.sh: Rwfus
-    Copyright (C) 2022 ValShaped ([email protected])
+    Copyright (C) 2022-2023 ValShaped ([email protected])
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -46,23 +46,38 @@ CF_DEFAULT=(
     #   /etc/pacman.d /var/lib/pacman /var/cache/pacman : store pacman state
     [cf_Directories]="/usr /etc/pacman.d /var/lib/pacman /var/cache/pacman"
     # Default directories (These can be changed in the config file. Run `rwfus --gen-config` to generate an example file.)
-    [cf_Base_Directory]="/opt/${Name@L}"         # Where all the files will go
-    [cf_Service_Directory]=""                    # Where generated service will go
-    [cf_Disk_Image_Path]=""                      # Where the disk image will go
-    [cf_Mount_Directory]=""                      # Where the disk image will be mounted
-    [cf_Upper_Directory]=""                      # Where the overlayfs upper dirs will go
-    [cf_Work_Directory]=""                       # Where the overlayfs work dirs will go
-    [cf_Disk_Image_Size]="8G"                    # Size to make the disk image, when resizing
+    #   Note: Items have been intentionally left blank.
+    #   See function change_base below.
+    #   Where all the files will go
+    [cf_Base_Directory]="/opt/${Name@L}"
+    #   Where generated service will go
+    [cf_Service_Directory]=""
+    #   Where the disk image will go
+    [cf_Disk_Image_Path]=""
+    #   Where the disk image will be mounted
+    [cf_Mount_Directory]=""
+    #   Where the overlayfs upper dirs will go
+    [cf_Upper_Directory]=""
+    #   Where the overlayfs work dirs will go
+    [cf_Work_Directory]=""
     # Systemd-related things
-    [cf_Systemd_Directory]="/etc/systemd/system" # Where systemd expects units to be
-    [cf_Restart_Units]="usr-local.mount"         # Units to restart when daemon starts
-    [cf_Stop_Units]="var-cache-pacman.mount"     # Units to stop when daemon starts and restart when daemon stops
-    [cf_Mask_Units]="pacman-cleanup.service"     # Units to mask when daemon starts and unmask when daemon stops.
-
-    [cf_Mount_Options]="loop,compress"   # Make sure you keep 'loop', so it creates a loop device
+    #   Where systemd expects units to be
+    [cf_Systemd_Directory]="/etc/systemd/system"
+    #   Units to restart when daemon starts
+    [cf_Restart_Units]="usr-local.mount polkit.service"
+    #   Units to stop when daemon starts and restart when daemon stops
+    [cf_Stop_Units]="var-cache-pacman.mount"
+    # Units to mask when daemon starts and unmask when daemon stops.
+    [cf_Mask_Units]="pacman-cleanup.service"
+    # Disk-related things
+    #   Make sure you keep 'loop', so it creates a loop device
+    [cf_Mount_Options]="loop,compress"
+    # Size to make the disk image, when resizing
+    [cf_Disk_Image_Size]="8G"
+
+    #   SteamOS Offload offloads /usr/local to /home/.steamos/offload/usr/local
+    #   Beware! This will be considered read-only to overlayfs, so adding stuff while rwfus is enabled is not recommended.
 
-    # # SteamOS Offload offloads /usr/local to /home/.steamos/offload/usr/local
-    # # Beware! This will be considered read-only to overlayfs, so adding stuff while rwfus is enabled is not recommended.
     [cf_Install_Directory]="/home/.steamos/offload/usr/local/bin"
 )
 
@@ -108,6 +123,9 @@ CF_TESTPATHS="cf_Base_Directory cf_Service_Directory cf_Mount_Directory
               cf_Upper_Directory cf_Work_Directory cf_Install_Directory
               cf_Systemd_Directory cf_Disk_Image_Path cf_Config_File cf_Logfile"
 
+# shellcheck disable=SC2034
+CF_CONFIGURATIOR=true
+
 # This function loads the default config. Run `rwfus --gen-config` to generate an example file.
 function load_defaults {
     for cf_option in "${!CF_DEFAULT[@]}"; do
@@ -119,12 +137,12 @@ function load_defaults {
 # Derive subdirs of the cf_Base_Directory
 function change_base {
     # Subdirs of cf_Base_Directory
-    export cf_Service_Directory="$cf_Base_Directory/service"   # Where service will go
+    export cf_Service_Directory="$cf_Base_Directory/service"        # Where service will go
     export cf_Disk_Image_Path="$cf_Base_Directory/${Name@L}.btrfs"  # Where the disk image will go
-    export cf_Mount_Directory="$cf_Base_Directory/mount"       # Where the disk image will be mounted
+    export cf_Mount_Directory="$cf_Base_Directory/mount"            # Where the disk image will be mounted
     # Subdirs of cf_Mount_Directory
-    export cf_Upper_Directory="$cf_Mount_Directory/upper"      # Where the overlayfs upper dirs will go
-    export cf_Work_Directory="$cf_Mount_Directory/work"        # Where the overlayfs work dirs will go
+    export cf_Upper_Directory="$cf_Mount_Directory/upper"           # Where the overlayfs upper dirs will go
+    export cf_Work_Directory="$cf_Mount_Directory/work"             # Where the overlayfs work dirs will go
 }
 
 function enable_testmode {
@@ -157,7 +175,7 @@ function construct_config {
         for cf_option in ${CF_SECTION[$section]}; do
             # Comment line
             #Variable         Value
-            printf "%b%-18s %-24s\n" \
+            printf "%b%-18s %-1s\n" \
                 "${CF_COMMENT[$cf_option]}" \
                 "${CF_REQUIRE[$cf_option]-"#"}${cf_option:3}" \
                 "${!cf_option}"
@@ -190,10 +208,11 @@ function load_config {
         # also filter lines which don't contain any non-space characters.
         local expression='^[[:space:]]*[^\[\#[:space:]]+'
         if [[ "$var" =~ $expression ]]; then
-            CF_REQUIRE["$var"]=true                  # Save the loaded option
-            val="$(echo "$val" | cut -f1 -d# | xargs)" # chop off inline comments
             local cf_var="cf_$var"
-            CF_REQUIRE["$cf_var"]="" # Mark option loaded
+            if [ "$CF_CONFIGURATOR" ]; then
+                CF_REQUIRE["$cf_var"]=""               # Save the loaded option
+            fi
+            val="$(echo "$val" | cut -f1 -d# | xargs)" # chop off inline comments
             export "$cf_var"="${val}"
             printf "> %s: \"%s\"\n" "$var" "${!cf_var}"
             if [[ "$cf_var" = "cf_Base_Directory" ]]; then
@@ -206,7 +225,6 @@ function load_config {
     done < "$config_file"
     CONFIG_LOADED=true
     if [ "$TESTMODE" ]; then enable_testmode ./test; fi
-    echo
 }
 
 function config {

rwfus_include/disk.sh

@@ -1,7 +1,8 @@
+#!/bin/false
 # shellcheck shell=bash
 : <<LICENSE
       disk.sh: Rwfus
-    Copyright (C) 2022 ValShaped ([email protected])
+    Copyright (C) 2022-2023 ValShaped ([email protected])
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -22,6 +23,13 @@ LICENSE
 source "$IncludeDir/testlog.sh"
 
 function mount_disk {
+    # Wait up to 3 seconds!!? for disk to become available
+    for _i in {1..3}; do
+        if [ ! -f "$cf_Disk_Image_Path" ]
+        then sleep 1
+        else break
+        fi
+    done
     # Set mount options, if none are specified
     mount -vo "${cf_Mount_Options:=loop}" -- "$cf_Disk_Image_Path" "$cf_Mount_Directory" && \
     btrfs filesystem resize max "$cf_Mount_Directory"
@@ -98,6 +106,19 @@ function mount_all {
         printf "Could not mount disk.\n"
         return 255;
     fi
+    # Check for the presence of glibc
+    # Glibc will cause the Deck to fail boot.
+    # FIXME: instead of looking for glibc, dynamically detect a failed boot
+    if [ -f "${cf_Upper_Directory}/usr/include/gnu/libc-version.h" ]; then
+        printf "GLibC has been installed inside %s's overlay.\
+        \nYour Deck will likely not survive a SteamOS update.\
+        \nIn an attempt to preserve your Deck, %s has not mounted any overlays.\
+        \n\033[1mThis is not a bug. It is an intentional safety measure.\033[0m\
+        \nThe disk, however, has remained mounted, in case you want to remedy this.\
+        \nYou may unmount it with \033[1m%s --umount\033[0m\n"\
+        "${Name}" "${Name}" "${Name@L}"
+        return 254;
+    fi
     for target in $cf_Directories; do
         local escaped; escaped=$(systemd-escape -p -- "$target")
         local lower="$target"

rwfus_include/info.sh

@@ -3,4 +3,4 @@
 export Name="Rwfus"
 export Description="Carry Pacman across SteamOS updates!"
 export Repository="https://github.com/ValShaped/rwfus"
-export Version="0.4.1"
+export Version="0.4.2"