Platform Notes - uhop/dotfiles GitHub Wiki

Platform Notes

Per-OS post-install details (fonts, video codecs, clipboard tools, and a Mac's sleep and FileVault settings for remote access). For bootstrap-time support tiers, per-distro quirks, and troubleshooting the initial install, see Distro Compatibility.

Ubuntu (Debian)

Fonts

Fonts on Linux (Ubuntu): see https://askubuntu.com/questions/3697/how-do-i-install-fonts

FiraCode Nerd Font is used for code (Visual Studio Code). It supports common programming ligatures. Hack Nerd Font is used as a monospaced font for terminals (e.g., gnome-terminal) and similar programs (git-gui, gitk, โ€ฆ).

These dotfiles assume that these fonts are preinstalled and use them as appropriate.

Video

Restricted soft on Ubuntu to play videos:

sudo apt install ubuntu-restricted-extras vlc libdvd-pkg
sudo dpkg-reconfigure libdvd-pkg

More on videos: https://www.omgubuntu.co.uk/2022/08/watch-bluray-discs-in-vlc-on-ubuntu-with-makemkv

Cut-and-paste

To support cut-and-paste in the micro editor:

  • Use the default ("external") for the clipboard option.
  • Install a proper command-line clipboard tool:
    • For Wayland: 
      sudo apt install wl-clipboard
    • For X11 (realistically only one could be installed): 
      sudo apt install xclip xsel
    • You may install all of them for a good measure: 
      sudo apt install wl-clipboard xclip xsel

Keyboard shortcuts

F10 doesn't work in a terminal: https://superuser.com/questions/1543538/f10-key-not-working-in-terminal-mc-ubuntu-19-10

Titan security key

See: https://support.google.com/titansecuritykey/answer/9148044?hl=en

A key should be registered only once. When I attempted to do so, I was misleadingly informed that "this device cannot be used to create passkeys". When it happened, press "Use other device", which will switch from the current computer to the key and now everything will go smoothly.

Windows on Ubuntu (LXD)

See the following articles:

Useful commands:

  • Start the win11 instance: 
    lxc start win11
    • Start and connect: 
      lxc start win11 --console=vga
  • Connect to the running instance: 
    lxc console win11 --type=vga

If RDP is enabled in Windows, you can use Remmina to connect. Usually it is a faster option. OTOH, connecting console allows to see the boot process and updates before Windows is loaded.

Docker

Periodically Docker system needs to be cleaned up. Use:

docker system prune -a

This will remove all unused containers, networks, images, and build cache.

To remove all and volumes not used by currently running containers:

docker system prune -a --volumes

To remove everything (see above) without asking confirmation use "force":

docker system prune -af --volumes

Time to time AppArmor interferes with Docker operations, which result in failures with "permission denied" errors. Frequently it can be helped with:

sudo aa-remove-unknown

Ubuntu on Mac

Enabling Fn keys:

Video driver:

Red Hat-like distros (Fedora, RHEL, CentOS, Rocky, Alma)

Supported since the osFamily/pkgManager refactor. The install-packages script uses dnf and enables EPEL (on non-Fedora distros) automatically.

Differences from Ubuntu

  • micro is not in default repos โ€” installed via brew instead.
  • doas/opendoas is not packaged โ€” passwordless sudo for maintenance commands is granted via /etc/sudoers.d/chezmoi (the %wheel group), written by run_onchange_after_install-sudoers.sh.tmpl. See Application Notes for details.
  • snap is not pre-installed โ€” the update script checks at runtime.
  • Fonts: same as Ubuntu (download Nerd Fonts to ~/.local/share/fonts/, run fc-cache -fv).

Non-privileged users

A privileged user installs system packages and brew first. Then any user can run chezmoi init --apply to get their personal shell environment (aliases, functions, completions, local scripts). The install-packages script detects when brew is read-only and skips brew bundle.

macOS

A Mac that other machines connect to must not sleep

A Mac with system sleep on answers ssh, playbash, and other network services only during its short maintenance wakes, so connections from other machines time out at random. "Wake for network access" does not help without a Bonjour Sleep Proxy (an Apple TV) on the LAN: a new connection does not wake the Mac.

Measured on a desktop Mac on Ethernet in October 2026: with sleep 1 it slept about 23 hours a day, waking for under a minute every 15 minutes or so. Four 60-second ssh attempts from another machine while it slept all timed out, and none of them woke it.

Check the setting (sleep is minutes of idle time before the system sleeps; 0 means never):

pmset -g

Turn system sleep off (display sleep is not affected):

sudo pmset -a sleep 0

This is a manual step: the dotfiles don't change power settings. Run the command once on every Mac that other machines connect to, and again after you reinstall macOS on it. It's listed under Setting up a new machine ยง Manual steps.

To restore it, run sudo pmset -a sleep 1. The cost is a few watts on average: Apple's environmental reports put a small desktop Mac at about 0.5 W asleep and 4 W idle, so roughly 30 kWh a year.

To see when a Mac slept and what woke it:

pmset -g log | grep -E 'Entering Sleep|DarkWake|Wake from'

A related symptom on the client: with ControlMaster auto in ~/.ssh/config, a shared connection to a Mac that has gone to sleep dies, and the next ssh prints muxclient: master hello exchange failed before it opens a new connection.

Unlock FileVault over ssh after a restart

With FileVault on, a restarted Mac answers nothing over the network until someone unlocks its disk, and macOS updates restart it. The ssh unlock below is the option for a restart nobody is there for.

On Apple silicon with macOS 26 or later and Remote Login on, you can unlock it from another machine with your macOS account password (box stands for the Mac's host name):

ssh box

Until the unlock, /etc/ssh and ~/.ssh sit on the locked data volume, so the server accepts only a password: keys don't work, and PasswordAuthentication no doesn't apply. After the password, the connection closes while macOS mounts the data volume and starts its services; then ssh works as usual, with keys. playbash and anything else that runs ssh with BatchMode=yes can't unlock. For more information, see man apple_ssh_and_filevault.

Not yet tried in practice (October 2026). The host key that the server shows before the unlock is unverified. A third-party unlock tool, fv-ssh-unlock, checks it against the booted Mac's key, which suggests they're the same. If ssh reports a changed host key at this step, compare it with the fingerprint recorded on the booted Mac before you type the password:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

For a restart you start yourself, sudo fdesetup authrestart restarts and skips the unlock once. Until then, the unlock key stays in memory, which weakens FileVault's protection (see man fdesetup).

GUI

Package managers

I use apt, snap, flatpak, brew and AppImageLauncher. Most GUI apps are installed with flatpak. They are installed manually using Win-A (Cmd-A) from Gnome.

  • flatpak
    • flatseal โ€” flatpak permission editor.
    • calibre โ€” an e-book manager.
    • gear lever โ€” an AppImage manager.
    • telegram โ€” a social network.
    • Web browsers (used for testing):
      • Brave
      • Chromium
      • Google Chrome
      • Microsoft Edge
    • Communications:
      • Slack
      • Zoom
    • steam โ€” the game launcher from Valve.
    • wezterm โ€” a modern terminal.
  • snap
    • code โ€” Visual Studio Code.
    • firefox โ€” a web browser (it comes preinstalled).
    • postman โ€” a tool for debugging network services.
      • It is available as a flatpak, but apparently it is completely unusable.
    • skype โ€” communications
      • It is available as a flatpak, but apparently it is completely unusable.
    • Note: if snap-store cannot be updated (because it is running) use: snap-store --quit && snap refresh snap-store
  • AppImages
โš ๏ธ **GitHub.com Fallback** โš ๏ธ