Updates and recovery

Manual home

Updates and recovery

This page covers SteamOS updates, the NVIDIA driver and recovery. The tools this project adds are updated by their own shortcut, SteamOS NVIDIA Installer Update in Desktop Mode; see Installer updates.

Update from Steam

Use Steam's normal system update interface. Keep at least 9 GiB free on /home for repair and leave the PC powered until it finishes. Check space with:

df -h / /home /tmp

The updater prepares the other SteamOS slot, then rebuilds the pinned NVIDIA driver and optional xpadneo for its kernel. It also puts this project's other parts back into that slot, and if one of them cannot be restored the update is canceled and the working system stays selected. Driver compilation adds time. Reboot when the update finishes, then check your display, audio, controller and a game.

OS updates keep the currently pinned driver version. A Steam client update is separate from a SteamOS update; check the OS version in system settings.

Check the Gamescope build after an update

The Gamescope build this project ships is selected by asking the build itself. At installation and at update repair it is run inside the new system with the flags that system's own Game Mode session would pass it, with no display and a time limit, and it is kept only when it accepts all of them. The gamescope package SteamOS has installed and the SteamOS release are not part of that decision. If an OS update changes the way the session starts Gamescope so that our build no longer accepts those flags, the update still succeeds, but the new slot keeps SteamOS's own Gamescope instead of ours. This is deliberate. A newer Gamescope from Valve does not stand our build aside by itself: on SteamOS 3.9.2 Preview, with Valve's gamescope 3.16.30-2 installed, our build was kept and worked. While SteamOS's own Gamescope is in use, the corrections this project carries are not applied, so the corrupted Game Mode menus that release 0.2.0 clears can appear again. Nothing on screen announces the change, so read the recorded selection after the reboot:

cat /usr/lib/steamos-nvidia/gamescope/status.txt

A line beginning capture-backport means this project's Gamescope is in use. A line beginning stock means it is not, and the corrections it carries, including the menu fix, are not applied on that build. The capture color correction is a backport, so a newer Gamescope from SteamOS may already carry that part. The menu fix is this project's own change and is in no SteamOS build, so on stock the corrupted menus can come back and stay until a build that the new session accepts is released. That is why this check is worth running after an OS update rather than treating it as a formality. The same line appears in the diagnostic report as Experimental Gamescope selection. If the file does not exist at all, the image was built without this project's Gamescope artifact, usually by the base only build command, so there is nothing to select. Report the whole line together with your SteamOS version.

Keeping extra drives mounted across updates

SteamOS replaces /etc on every update. It keeps a backup and a short list of exceptions, and /etc/fstab is not on that list, so mount entries added there are gone after the next update. Changing the driver has the same effect, because it ends in the same Valve migration step. Nothing in this project changes that.

Describe each extra drive as a systemd mount unit instead. Valve's list does keep /etc/systemd/system/*.mount and the symlink that enables it, so a unit survives updates untouched.

Write the unit

Find the drive's UUID and filesystem:

lsblk -o NAME,SIZE,FSTYPE,LABEL,UUID

Choose a mount point under /var/mnt. On SteamOS /mnt is a symlink to /var/mnt, and systemd refuses a mount path that passes through a symlink with Mount path /mnt/... is not canonical. The unit's file name must be the mount point path, escaped:

systemd-escape --path --suffix=mount /var/mnt/games

That prints var-mnt-games.mount. The file belongs to root, so create it with an editor started by sudo, for example sudo nano /etc/systemd/system/var-mnt-games.mount, and put your own UUID and filesystem type in it:

[Unit]
Description=Extra game drive

[Mount]
What=/dev/disk/by-uuid/PUT-YOUR-UUID-HERE
Where=/var/mnt/games
Type=ext4
Options=nofail,noatime

[Install]
WantedBy=multi-user.target

nofail keeps a missing or unreadable drive from holding up the boot. systemd creates the mount point directory itself. Enable and check it:

sudo systemctl daemon-reload
sudo systemctl enable --now var-mnt-games.mount
systemctl status var-mnt-games.mount

Options beginning with x-systemd., such as x-systemd.automount, x-systemd.device-timeout and x-systemd.growfs, work only in /etc/fstab and are ignored inside a unit. Their unit equivalents are separate settings; see man systemd.mount.

A share on your network

A share from another machine follows the same rule, with one addition. The unit survives the update, but the credentials file it points at is an ordinary file, and if you keep it in /etc it is removed with everything else. The mount then fails with a message that says nothing about an update:

error 2 (No such file or directory) opening credential file /etc/samba/credentials

Keep the credentials outside /etc. A file on /home is the simplest choice, because /home is a separate partition that updates do not replace.

sudo install -m 600 -o root -g root /dev/null /home/deck/.smb-credentials
sudo nano /home/deck/.smb-credentials

The password is stored in that file as plain text, so use an account that exists only for this share rather than the account you administer the server with:

username=YOUR-USER
password=YOUR-PASSWORD
domain=WORKGROUP

Then write the unit. For a share mounted at /var/mnt/nas the file is /etc/systemd/system/var-mnt-nas.mount:

sudo nano /etc/systemd/system/var-mnt-nas.mount

[Unit]
Description=Files from the NAS
After=network-online.target
Wants=network-online.target

[Mount]
What=//PUT-YOUR-SERVER-HERE/PUT-YOUR-SHARE-HERE
Where=/var/mnt/nas
Type=cifs
Options=credentials=/home/deck/.smb-credentials,uid=1000,gid=1000,file_mode=0664,dir_mode=0775,nofail
TimeoutSec=30

[Install]
WantedBy=multi-user.target

In What= the first part is the address of the machine holding the share, for example 192.168.0.10, and the second is the share name that machine offers. If you want a different mount point, change Where= and rename the file to match, using the systemd-escape command above.

After and Wants on network-online.target keep the mount from being tried before the network is ready. uid=1000 and gid=1000 give the deck account ownership of the mounted files. Enable it as you would a local drive, with your own unit name:

sudo systemctl daemon-reload
sudo systemctl enable --now var-mnt-nas.mount
systemctl status var-mnt-nas.mount

If you would rather keep the credentials in /etc, add a keep drop-in naming that one file, for example /etc/atomic-update.conf.d/50-credentials.conf containing the single line /etc/samba/credentials. That is a much narrower exception than preserving the whole of fstab.

Recover entries already lost

Before it removes your /etc changes, SteamOS copies them aside. Only the files you had edited are kept, not the whole directory. The quickest place to look is the plain copy of the last update:

cat /etc/previous/fstab

SteamOS leaves a README in /etc/previous explaining that directory. Earlier updates are kept as archives instead, space permitting, and only the five newest are retained:

ls -l /var/lib/steamos-atomupd/etc_backup/
tar -xJf /var/lib/steamos-atomupd/etc_backup/DATE.tar.xz -O etc/fstab

Copy the lines you need into a unit rather than restoring the whole file.

The other option, and why it is not the first choice

Valve's keep list can be extended with a drop-in. A file such as /etc/atomic-update.conf.d/50-fstab.conf containing the single line /etc/fstab makes the whole file survive, and the drop-in survives with it. It works, but Valve's own example file warns that a preserved file shadows every later change the system makes to it and can prevent updates. For fstab it also freezes the SteamOS partition entries at their current layout. Prefer a mount unit.

What was tested

Both methods were measured on SteamOS, once through a driver change and once through a normal OS update from 3.8.16 to 3.8.28. In both runs a plain fstab entry and an unprotected file in /etc were lost, while a mount unit stayed enabled and mounted and a file protected by a drop-in survived.

A third run repeated the measurement through a driver change, this time with a CIFS share from another machine on the same network. The unit and a credentials file on /home survived and the share was mounted again at the next boot with no manual step. An unprotected credentials file in /etc and a CIFS line in fstab were lost, while a credentials file in /etc named by a keep drop-in survived.

Update stops near the end

A download error at the end of setup can come from driver repair, even when the network download succeeded. Read the repair log:

sudo tail -n 80 /var/log/steamos-nvidia-repatch.log

For a support request, save the full log instead of photographing scrolling text:

sudo cat /var/log/steamos-nvidia-repatch.log > ~/steamos-nvidia-repatch.txt

Check the first failure: insufficient space, an unavailable package, signature failure or a compiler error need different fixes. Follow Troubleshooting. Do not manually create completion markers or mark a partially repaired boot slot valid.

If the installed system cannot start

Keep the working installer USB. Boot it to reach the recovery desktop and copy logs or back up files from the installed disk. If you have a usable text console, try Ctrl+Alt+F4, log in as deck and collect diagnostics.

The Upgrade SteamOS (NVIDIA) - keeps games & data shortcut can reinstall the OS while retaining the data partition on a recognized SteamOS layout. It is not a substitute for a backup. Install SteamOS (NVIDIA) to Disk erases the selected disk.

The repair checks the staged slot before enabling it. Automatic recovery from power loss or a failed graphical boot is not guaranteed; the optional Safe Graphics session must be selected manually and does not provide automatic recovery.

After an interrupted update

If power was lost during an update and the previous system still boots, check the installed OS version and save the update logs. Let any active update finish before starting another attempt through Steam's update interface.

The new slot is selected only after repair succeeds. Do not manually mark an incomplete slot valid. If retrying fails, save the system journal as well as the repair log, because the failure can happen before NVIDIA repair starts:

sudo journalctl -b --no-pager > ~/steamos-update-journal.txt

Check log timestamps against the failed attempt. An older successful repair log does not confirm that the latest update completed. Review logs before sharing.

Change the driver version

On the installed system, open Change NVIDIA Driver from Desktop Mode's desktop shortcut or application menu. Choose a driver version or return to the previous system. The installer USB is not a supported target.

The version list has three columns:

Column	Meaning
Version	The exact driver package version to install.
GPU families (NVIDIA)	GeForce families listed in NVIDIA's support information.
Your GPU	Whether the release lists all detected NVIDIA graphics cards, and whether this project has run it. A green row means both: NVIDIA documents your GPU in that driver's range and this project built and tested that exact version. A yellow row means only the first.

Versions with incompatible GPUs or unavailable support information are hidden. The hardware match does not guarantee compatibility with every kernel or display feature. GTX 10xx and older cards are not supported by this installer.

Those are two different claims and the list keeps them apart. NVIDIA's support information says which GPUs a driver covers; it says nothing about whether that driver was ever booted with these tools. Only the version an image was built and accepted with carries the tested marker, and the text above the list names it. As newer drivers appear, the tested version eventually drops out of the ten newest package sets; when nothing offered has been tested here, the list says so instead of leaving you to work it out.

The manager checks the ten newest complete package sets each time you open the version list. New drivers appear once their packages and GPU support information are available. Choose and confirm a version to install it; the manager does not install new releases automatically.

The operation opens a terminal for your normal sudo password and live output. No password is stored. Downloads and driver compilation can leave the window looking paused; wait for completion instead of starting another operation.

Preparation runs as a system service and continues if the terminal closes. Reopen a terminal and use the status command below if needed. A successful operation offers Restart or Later. The installer USB is not a supported target for this manager.

If steamos-nvidia-driver is installed, it can prepare a different NVIDIA version without recreating the installer USB. It requires the normal self-healing update mode, a recognized A/B installation and a read-only root filesystem.

Check the exact package version before starting:

steamos-nvidia-driver plan 610.57.04-1

The version above is an example, not a request to downgrade or reinstall it. Choose the full package version you intend to test. The command prints the pinned package URLs without changing the system. Support libraries retain their existing pins; unsupported dependencies cause installation to stop.

Leave space on /home for a root partition copy plus 12 GiB, normally about 17 GiB in total. Finish pending OS updates and reboot first. Do not start another update or turn off the PC during preparation.

Start the operation as a system service so it can continue if the terminal closes:

sudo systemd-run --unit=steamos-driver-change --collect /usr/bin/steamos-nvidia-driver install 610.57.04-1
sudo journalctl -fu steamos-driver-change

Preparation overwrites the inactive OS slot, not your currently running slot. It copies the same SteamOS release with a new filesystem identifier, migrates settings and builds the requested driver. Games on /home remain in place. The previous inactive installation is replaced by this operation.

Check the result before rebooting:

sudo steamos-nvidia-driver status

Only a ready result means the new slot was prepared and selected. After reboot, check graphics, a game, audio and suspend/resume. Future OS updates will rebuild the newly selected driver version.

To return to the previous slot:

sudo steamos-nvidia-driver rollback

Reboot after the command succeeds. Before the first reboot, the same command cancels selection of the prepared slot. After booting it, the tool validates the previous system and selects it. A later update may replace that slot; the tool refuses a stale rollback record. This is not automatic recovery from a graphical boot failure. Use a working console or SSH if Game Mode cannot be displayed.

On failure, save the service journal and /var/log/steamos-nvidia-repatch.log. A failed repair leaves the target disabled. Do not manually mark it valid.

Older images without this command can still be rebuilt with --driver SPEC. Regular OS updates do not automatically choose a newer NVIDIA driver.

If the image was built with --hold-updates, Steam intentionally reports the system as up to date. If it was built with --no-hold-updates, stock OS updates remove the added NVIDIA driver. The normal build mode includes repair.

Beta and Preview testing

A build made with --experimental-beta selects beta; --experimental-preview selects Preview. These are different channels. Check the OS version and update channel after first setup. Leave the PC powered while NVIDIA is compiled, even if the progress estimate stops changing near the end.

Use a separate test disk and keep the stable installer. Main is not selected by either option. An unfamiliar update format is rejected before our repair hook is installed; do not bypass that check by manually marking the new slot valid.

This project's Gamescope build is not tied to a SteamOS line. On Preview it is kept when it accepts the flags that system's Game Mode session passes it, and that was measured on SteamOS 3.9.2 Preview with Valve's gamescope 3.16.30-2 installed, where our build ran and the menu fix was in effect. That is one measurement on one machine, and a later Preview release can still change the way the session starts Gamescope, after which our build stands aside and the corrupted menus can come back there. Read the recorded selection after first setup:

cat /usr/lib/steamos-nvidia/gamescope/status.txt

A line beginning stock means this project's build is not in use. The 3.9 line is not excluded: on SteamOS 3.9.2 Preview, with Valve's gamescope 3.16.30-2 installed, this project's build was kept and worked.