Optimize installer: preflight checks, tuned conf, doctor, faster default

Layers a few things on top of the initial scaffold:

- Default to sunshine-bin (precompiled, ~seconds) instead of building from
  source. --from-source restores the old behavior.
- Add lib/preflight.sh: catches the gotchas before any work is done —
  Wayland session, NVIDIA driver responsive, nvidia-drm.modeset, amdgpu
  loaded, pipewire-pulse present, SSH-without-session warning.
- Add lib/config.sh: writes a tuned ~/.config/sunshine/sunshine.conf with
  per-vendor encoder settings (NVENC P1+ll+cbr, VAAPI ultralowlatency,
  QuickSync veryfast), KMS capture, pulse audio sink. Uses a
  "# managed-by: omarchy-moonlight" marker; removing it hands ownership
  back to the user and the installer won't touch the file again.
- Add lib/verify.sh: post-install verification of every step
  (cap_sys_admin set, group resolves, udev rule present, /dev/uinput
  exists, encoder reachable, service active, :47990 listening). Same
  checks are reachable standalone via --doctor.
- Install runtime helpers (pipewire-pulse, vulkan-tools, libva-utils)
  alongside Sunshine for diagnostics + audio.
- Uninstall handles both sunshine + sunshine-bin and the -bin moonlight
  variant.
- README documents the tuning table, the new flags, and the modeset
  troubleshooting path.
This commit is contained in:
2026-05-18 10:17:11 -06:00
parent a9dcbc1db8
commit d6b0919149
7 changed files with 339 additions and 35 deletions

View File

@@ -26,18 +26,22 @@ Then:
## What it does
- Installs `sunshine` and `moonlight-qt` from the AUR via `yay`
- Adds your user to the `input` group
- Drops a `/etc/udev/rules.d/60-uinput.rules` if no equivalent rule exists (so Sunshine can use `/dev/uinput` for virtual gamepad/keyboard/mouse)
- Runs `setcap cap_sys_admin+p` on the `sunshine` binary so KMS screen capture works without root
- Installs GPU-vendor encoder packages:
- NVIDIA: `nvidia-utils`, `libva-nvidia-driver`
- AMD: `libva-mesa-driver`, `mesa-vdpau`, `vulkan-radeon`
- Intel: `intel-media-driver`, `vulkan-intel`
- Opens Sunshine's LAN ports on `firewalld` / `ufw` if either is active (skips silently otherwise)
- Enables `sunshine.service` under systemd `--user` and turns on `loginctl enable-linger` so the host is reachable without a graphical login
In order, each step is "check, then act" — re-running is safe:
Re-running is safe — every step is "check, then act."
1. **Preflight** — confirms Wayland session, GPU driver is loaded, `nvidia-drm.modeset=1` isn't explicitly disabled (would silently break KMS capture), pipewire-pulse is present for audio.
2. **Packages** — installs `sunshine-bin` (precompiled, fast) and `moonlight-qt` from the AUR via `yay`. Plus runtime helpers: `pipewire-pulse`, `vulkan-tools`, `libva-utils`. Use `--from-source` to build Sunshine from source instead.
3. **GPU encoder support**:
- NVIDIA: `nvidia-utils`, `libva-nvidia-driver`
- AMD: `libva-mesa-driver`, `mesa-vdpau`, `vulkan-radeon`
- Intel: `intel-media-driver`, `vulkan-intel`
4. **Permissions**:
- Adds you to the `input` group
- Drops `/etc/udev/rules.d/60-uinput.rules` if no equivalent rule exists (lets Sunshine use `/dev/uinput` for virtual gamepad/keyboard/mouse)
- `setcap cap_sys_admin+p` on the `sunshine` binary so KMS screen capture works without root
5. **Tuned config** — writes `~/.config/sunshine/sunshine.conf` for low-latency LAN streaming. Per-vendor encoder settings (NVENC P1+`ll`, VAAPI ultralowlatency, QuickSync veryfast). Marked with `# managed-by: omarchy-moonlight`; remove that marker to take ownership and the installer will never touch it again.
6. **Firewall** — opens Sunshine's ports on `firewalld` / `ufw` if either is active. Skips silently otherwise.
7. **Service** — enables `sunshine.service` under `systemd --user` and turns on `loginctl enable-linger` so the host is reachable without an active graphical login.
8. **Verify** — runs the same checks as `--doctor` to confirm everything's actually wired up (cap_sys_admin set, group resolved, web UI listening on :47990, encoder reachable).
## Flags
@@ -46,15 +50,24 @@ Re-running is safe — every step is "check, then act."
./install.sh --no-firewall # skip firewall rules
./install.sh --no-moonlight # host-only (no client)
./install.sh --no-sunshine # client-only (no host)
./install.sh --no-config # leave Sunshine to generate its own default config
./install.sh --from-source # build Sunshine from source (slower; uses 'sunshine' AUR pkg)
./install.sh --doctor # run only the verification checks (no install)
```
### Use the precompiled Sunshine package
The doctor flag is the fastest way to debug a degraded install — it'll tell you exactly which piece (group, cap, udev, encoder, service, port) is broken.
The default uses `sunshine` from the AUR, which builds from source (slow on first install). To use the precompiled `sunshine-bin` instead:
### Tuned defaults written to sunshine.conf
```bash
SUNSHINE_PKG=sunshine-bin ./install.sh
```
| Setting | Value | Why |
|---|---|---|
| `capture` | `kms` | Correct backend for Wayland; uses DRM directly. |
| `encoder` (NVIDIA) | `nvenc` + `nvenc_preset=p1`, `nvenc_tune=ll`, `nvenc_rc=cbr` | P1 minimizes encode latency; low-latency tune disables look-ahead; CBR keeps bitrate predictable over LAN. |
| `encoder` (AMD) | `vaapi` + `amd_usage=ultralowlatency`, `amd_rc=cbr` | Mirrors the NVIDIA choices on AMD's encoder. |
| `min_threads` | `4` | Helps keep up at high bitrates / 4K. |
| `audio_sink` | `pulse` | Captures from PipeWire's Pulse compat layer. |
Anything else (resolution, bitrate, paired clients, app launchers) is set via the web UI.
## Uninstall
@@ -74,17 +87,19 @@ SUNSHINE_PKG=sunshine-bin ./install.sh
## Diagnostics
```bash
./install.sh --doctor # run all checks
systemctl --user status sunshine
journalctl --user -u sunshine -f
getcap "$(readlink -f "$(command -v sunshine)")" # should include cap_sys_admin
id -nG | tr ' ' '\n' | grep -x input # confirm group membership
getcap "$(readlink -f "$(command -v sunshine)")" # should include cap_sys_admin
id -nG | tr ' ' '\n' | grep -x input # confirm group membership
```
If Moonlight pairs but the stream is black:
- Confirm you're in the `input` group **in a freshly logged-in session** (not just listed in `/etc/group`).
- Confirm `getcap` shows `cap_sys_admin` on the sunshine binary.
- Check `journalctl --user -u sunshine` for `KMS` / `DRM` errors. On NVIDIA, ensure the proprietary driver is active (`nvidia-smi`).
- Check `journalctl --user -u sunshine` for `KMS` / `DRM` errors.
- On NVIDIA: confirm the proprietary driver is active (`nvidia-smi`) and that `nvidia-drm.modeset=1` is in effect. If you have an older driver (≤555) and modeset isn't on, add `nvidia-drm.modeset=1` to your kernel cmdline and reboot.
## Remote access (planned)
@@ -100,9 +115,12 @@ omarchy-moonlight/
├── lib/
│ ├── common.sh # logging, sudo, idempotency helpers
│ ├── detect.sh # GPU vendor, session type, hostname
│ ├── packages.sh # yay -S sunshine moonlight-qt + GPU encoders
│ ├── preflight.sh # pre-install sanity checks (driver, modeset, audio, session)
│ ├── packages.sh # yay -S sunshine-bin moonlight-qt + GPU encoders
│ ├── permissions.sh # input group, uinput udev, setcap cap_sys_admin
│ ├── config.sh # writes tuned sunshine.conf (managed-by marker)
│ ├── firewall.sh # ufw/firewalld detection + port opening
── service.sh # systemctl --user enable + loginctl enable-linger
── service.sh # systemctl --user enable + loginctl enable-linger
│ └── verify.sh # post-install checks (also reused by --doctor)
└── files/ # (reserved — drop-in config files if needed later)
```

View File

@@ -10,14 +10,20 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/lib/common.sh"
# shellcheck source=lib/detect.sh
source "$SCRIPT_DIR/lib/detect.sh"
# shellcheck source=lib/preflight.sh
source "$SCRIPT_DIR/lib/preflight.sh"
# shellcheck source=lib/packages.sh
source "$SCRIPT_DIR/lib/packages.sh"
# shellcheck source=lib/permissions.sh
source "$SCRIPT_DIR/lib/permissions.sh"
# shellcheck source=lib/config.sh
source "$SCRIPT_DIR/lib/config.sh"
# shellcheck source=lib/firewall.sh
source "$SCRIPT_DIR/lib/firewall.sh"
# shellcheck source=lib/service.sh
source "$SCRIPT_DIR/lib/service.sh"
# shellcheck source=lib/verify.sh
source "$SCRIPT_DIR/lib/verify.sh"
usage() {
cat <<EOF
@@ -30,11 +36,14 @@ Options:
--no-firewall Skip firewall configuration
--no-moonlight Don't install moonlight-qt (host-only setup)
--no-sunshine Don't install sunshine (client-only setup)
--no-config Don't write a tuned sunshine.conf
--from-source Build Sunshine from source (equivalent to SUNSHINE_PKG=sunshine)
--doctor Run only the post-install verification checks
-h, --help Show this help
Environment overrides:
SUNSHINE_PKG AUR package to use for Sunshine (default: sunshine)
Set to 'sunshine-bin' for the precompiled build.
SUNSHINE_PKG AUR package to use for Sunshine (default: sunshine-bin)
Set to 'sunshine' to build from source instead.
EOF
}
@@ -42,6 +51,8 @@ AUTOSTART=1
FIREWALL=1
INSTALL_SUNSHINE=1
INSTALL_MOONLIGHT=1
WRITE_CONFIG=1
DOCTOR_ONLY=0
while [[ $# -gt 0 ]]; do
case "$1" in
@@ -49,6 +60,9 @@ while [[ $# -gt 0 ]]; do
--no-firewall) FIREWALL=0 ;;
--no-moonlight) INSTALL_MOONLIGHT=0 ;;
--no-sunshine) INSTALL_SUNSHINE=0 ;;
--no-config) WRITE_CONFIG=0 ;;
--from-source) export SUNSHINE_PKG=sunshine ;;
--doctor) DOCTOR_ONLY=1 ;;
-h|--help) usage; exit 0 ;;
*) err "Unknown option: $1"; usage; exit 2 ;;
esac
@@ -64,6 +78,14 @@ main() {
detect_all
info "Host: $HOSTNAME_SHORT GPU: $GPU_VENDOR Session: $SESSION_TYPE"
if [[ $DOCTOR_ONLY -eq 1 ]]; then
verify_install
exit $(( VERIFY_FAILURES > 0 ? 1 : 0 ))
fi
step "Preflight checks"
preflight_all
if [[ $INSTALL_SUNSHINE -eq 1 ]]; then
step "Installing Sunshine and GPU encoder support"
install_sunshine
@@ -74,6 +96,13 @@ main() {
ensure_uinput_udev_rule
set_sunshine_capabilities
if [[ $WRITE_CONFIG -eq 1 ]]; then
step "Writing tuned sunshine.conf"
write_sunshine_config
else
info "Skipping sunshine.conf (--no-config)"
fi
if [[ $FIREWALL -eq 1 ]]; then
step "Configuring firewall for Sunshine ports"
open_sunshine_ports
@@ -98,6 +127,10 @@ main() {
info "Skipping Moonlight install (--no-moonlight)"
fi
if [[ $INSTALL_SUNSHINE -eq 1 ]]; then
verify_install
fi
step "Done"
print_next_steps
}

61
lib/config.sh Normal file
View File

@@ -0,0 +1,61 @@
#!/usr/bin/env bash
# Write a tuned ~/.config/sunshine/sunshine.conf for low-latency LAN streaming.
# Only overwrites if (a) no config exists, or (b) our managed marker is present.
SUNSHINE_CONF_DIR="$HOME/.config/sunshine"
SUNSHINE_CONF="$SUNSHINE_CONF_DIR/sunshine.conf"
MANAGED_MARKER="# managed-by: omarchy-moonlight"
write_sunshine_config() {
mkdir -p "$SUNSHINE_CONF_DIR"
if [[ -f "$SUNSHINE_CONF" ]] && ! grep -qF "$MANAGED_MARKER" "$SUNSHINE_CONF"; then
ok "Existing sunshine.conf is user-managed — leaving it alone"
info " To re-apply tuned defaults, delete $SUNSHINE_CONF and re-run install.sh"
return 0
fi
local encoder_block
case "$GPU_VENDOR" in
nvidia)
encoder_block=$'encoder = nvenc\nnvenc_preset = p1\nnvenc_tune = ll\nnvenc_rc = cbr\nnvenc_coder = auto'
;;
amd)
encoder_block=$'encoder = vaapi\namd_quality = speed\namd_rc = cbr\namd_usage = ultralowlatency'
;;
intel)
encoder_block=$'encoder = quicksync\nqsv_preset = veryfast\nqsv_coder = auto'
;;
*)
encoder_block=$'# encoder auto-detected by Sunshine'
;;
esac
info "Writing tuned $SUNSHINE_CONF (GPU: $GPU_VENDOR)"
cat >"$SUNSHINE_CONF" <<EOF
$MANAGED_MARKER
# Generated by omarchy-moonlight install.sh on $(date -Iseconds)
# Delete this marker line to take ownership; the installer will then leave the file alone.
#
# Tuned for low-latency LAN streaming on Hyprland/Wayland with KMS capture.
# Tune further via the web UI at https://localhost:47990
sunshine_name = ${HOSTNAME_SHORT}
# Capture: KMS (DRM) — the right choice on Wayland.
capture = kms
# Encoder tuned for $GPU_VENDOR
$encoder_block
# Threading — more threads helps high-bitrate H.265/AV1.
min_threads = 4
# Use the PipeWire pulse compatibility layer for audio.
audio_sink = pulse
# Keyboard / mouse / gamepad pass-through via /dev/uinput.
# (Requires user to be in the 'input' group; install.sh handles this.)
EOF
ok "Wrote sunshine.conf"
}

View File

@@ -1,17 +1,20 @@
#!/usr/bin/env bash
# Install Sunshine, Moonlight, and GPU-specific hardware-encode dependencies.
# Default to source build (canonical AUR package). Override with SUNSHINE_PKG=sunshine-bin
# in the environment for the precompiled build (much faster install).
: "${SUNSHINE_PKG:=sunshine}"
# Default to the precompiled AUR build for a fast install (~seconds instead of
# the ~10 minute source compile). Override with SUNSHINE_PKG=sunshine to build
# from source.
: "${SUNSHINE_PKG:=sunshine-bin}"
: "${MOONLIGHT_PKG:=moonlight-qt}"
install_sunshine() {
# Ensure runtime deps useful for capture/diagnostics across vendors.
yay_install pipewire-pulse vulkan-tools libva-utils
yay_install "$SUNSHINE_PKG"
}
install_moonlight() {
# moonlight-qt is in the AUR (also a -bin variant). yay handles both.
yay_install moonlight-qt
yay_install "$MOONLIGHT_PKG"
}
install_gpu_encoder_packages() {

98
lib/preflight.sh Normal file
View File

@@ -0,0 +1,98 @@
#!/usr/bin/env bash
# Preflight: catch problems before we install anything.
# Fail fast and loud, with remediation hints.
preflight_all() {
preflight_session
preflight_remote_session
preflight_gpu
preflight_kms_modeset
preflight_audio
}
preflight_session() {
if [[ "${SESSION_TYPE:-}" != "wayland" ]]; then
warn "Session type '$SESSION_TYPE' — KMS capture works at the DRM level so it can still succeed,"
warn "but this installer's defaults assume Hyprland on Wayland."
else
ok "Wayland session detected"
fi
}
preflight_remote_session() {
# Sunshine's user service needs the local Wayland session to be reachable.
# If we're over pure SSH (no forwarded DBUS / WAYLAND_DISPLAY), the service start
# at the end of the install will fail. Warn now so the user knows.
if [[ -n "${SSH_CONNECTION:-}" && -z "${WAYLAND_DISPLAY:-}" && -z "${DISPLAY:-}" ]]; then
warn "Running over SSH without a graphical session. Packages will install,"
warn "but the systemd --user service will only come up cleanly once you log in"
warn "to Hyprland on the console. That's fine — just log in afterwards."
fi
}
preflight_gpu() {
case "$GPU_VENDOR" in
nvidia)
if ! command -v nvidia-smi >/dev/null 2>&1; then
warn "nvidia-smi not found yet — nvidia-utils will be installed shortly."
return 0
fi
if ! nvidia-smi -L >/dev/null 2>&1; then
err "nvidia-smi exists but can't talk to the driver. Driver not loaded?"
err "Check: 'lsmod | grep nvidia' and 'dmesg | grep -i nvidia'"
exit 1
fi
ok "NVIDIA driver responsive ($(nvidia-smi -L | head -n1))"
;;
amd)
if ! lsmod | grep -q '^amdgpu'; then
warn "amdgpu kernel module not loaded. Hardware encode (VAAPI) will likely fail until it is."
else
ok "amdgpu kernel module loaded"
fi
;;
intel)
ok "Intel GPU — will install intel-media-driver"
;;
esac
}
preflight_kms_modeset() {
# KMS capture needs nvidia-drm.modeset=1 on NVIDIA. Driver 560+ defaults to 1,
# but if the user is on something older or has explicitly set 0, capture will fail.
[[ "$GPU_VENDOR" == "nvidia" ]] || return 0
# Cmdline check is read-only and reliable when explicitly set.
if grep -q 'nvidia-drm.modeset=1' /proc/cmdline; then
ok "nvidia-drm.modeset=1 set on kernel cmdline"
return 0
fi
if grep -q 'nvidia-drm.modeset=0' /proc/cmdline; then
err "nvidia-drm.modeset=0 is set on the kernel cmdline. KMS capture WILL fail."
err "Remove it (e.g., from /boot/loader/entries/*.conf or /etc/kernel/cmdline + reinstall-kernels)"
err "and reboot before running this installer."
exit 1
fi
# Not on cmdline — check the runtime parameter. On 560+ this defaults to Y.
# /sys file is root-readable; modinfo gives the default without sudo.
local default=""
if command -v modinfo >/dev/null 2>&1; then
default="$(modinfo -F parm nvidia_drm 2>/dev/null | awk -F: '/^modeset:/ {print $2}' | head -n1 || true)"
fi
if [[ -n "$default" ]]; then
info "nvidia_drm modeset default per modinfo: ${default## }"
fi
warn "nvidia-drm.modeset=1 not explicitly set on cmdline."
warn "Modern drivers (≥560) default to enabled, so this is usually fine — but if KMS"
warn "capture fails after install, add 'nvidia-drm.modeset=1' to your kernel cmdline."
}
preflight_audio() {
# Sunshine captures audio via the PulseAudio API; on Omarchy that's pipewire-pulse.
if pkg_installed pipewire-pulse; then
ok "pipewire-pulse present (audio capture path OK)"
else
warn "pipewire-pulse is not installed. Audio capture may not work until it is."
fi
}

87
lib/verify.sh Normal file
View File

@@ -0,0 +1,87 @@
#!/usr/bin/env bash
# Post-install verification — confirm each piece is actually wired up.
# Prints a checklist; non-fatal so the user sees the whole picture.
VERIFY_FAILURES=0
_check() {
local name="$1"; shift
if "$@" >/dev/null 2>&1; then
ok "$name"
else
err "$name"
VERIFY_FAILURES=$((VERIFY_FAILURES + 1))
fi
}
verify_install() {
step "Verifying install"
_check "sunshine binary on PATH" command -v sunshine
local bin
bin="$(command -v sunshine 2>/dev/null || true)"
if [[ -n "$bin" ]]; then
bin="$(readlink -f "$bin")"
if getcap "$bin" 2>/dev/null | grep -q cap_sys_admin; then
ok "sunshine has cap_sys_admin (KMS capture ready)"
else
err "sunshine missing cap_sys_admin — KMS capture will fail"
VERIFY_FAILURES=$((VERIFY_FAILURES + 1))
fi
fi
if id -nG "$USER" | tr ' ' '\n' | grep -qx input; then
ok "user '$USER' resolves with 'input' group in current shell"
else
warn "user '$USER' is NOT in 'input' group in this shell session."
warn " /etc/group is correct; you need to log out + back in (or 'newgrp input')."
fi
if grep -rqs 'KERNEL=="uinput"' /etc/udev/rules.d /usr/lib/udev/rules.d /run/udev/rules.d 2>/dev/null; then
ok "uinput udev rule present"
else
err "uinput udev rule missing"
VERIFY_FAILURES=$((VERIFY_FAILURES + 1))
fi
if [[ -c /dev/uinput ]]; then
ok "/dev/uinput exists"
else
warn "/dev/uinput not present yet — may appear on next reboot or 'modprobe uinput'"
fi
case "$GPU_VENDOR" in
nvidia)
if nvidia-smi --query-gpu=encoder.stats.sessionCount --format=csv,noheader >/dev/null 2>&1; then
ok "NVENC interface reachable via nvidia-smi"
else
warn "Could not query NVENC via nvidia-smi (driver may need a reboot after install)"
fi
;;
amd)
if command -v vainfo >/dev/null 2>&1 && vainfo 2>/dev/null | grep -qi 'VAEntrypointEncSlice\|VAProfileH264'; then
ok "VAAPI encoder profiles available"
else
warn "VAAPI encoder profiles not confirmed (install libva-utils to verify with 'vainfo')"
fi
;;
esac
if systemctl --user is-active --quiet sunshine.service; then
ok "sunshine.service is active"
if ss -ltn 2>/dev/null | grep -q ':47990 '; then
ok "web UI listening on :47990"
else
warn "web UI port 47990 not yet listening (service may still be starting)"
fi
else
warn "sunshine.service is not active"
warn " Inspect: journalctl --user -u sunshine -n 50 --no-pager"
fi
if [[ $VERIFY_FAILURES -gt 0 ]]; then
warn "$VERIFY_FAILURES check(s) failed — see ${BOLD}README.md${RESET}${YELLOW} 'Diagnostics' for fixes."
else
ok "All checks passed."
fi
}

View File

@@ -38,13 +38,17 @@ if loginctl show-user "$USER" -p Linger --value 2>/dev/null | grep -qx yes; then
fi
step "Removing packages"
if pacman -Qi sunshine >/dev/null 2>&1; then
as_root pacman -Rns --noconfirm sunshine
elif pacman -Qi sunshine-bin >/dev/null 2>&1; then
as_root pacman -Rns --noconfirm sunshine-bin
fi
if [[ $KEEP_MOONLIGHT -eq 0 ]] && pacman -Qi moonlight-qt >/dev/null 2>&1; then
as_root pacman -Rns --noconfirm moonlight-qt
for pkg in sunshine sunshine-bin; do
if pacman -Qi "$pkg" >/dev/null 2>&1; then
as_root pacman -Rns --noconfirm "$pkg"
fi
done
if [[ $KEEP_MOONLIGHT -eq 0 ]]; then
for pkg in moonlight-qt moonlight-qt-bin; do
if pacman -Qi "$pkg" >/dev/null 2>&1; then
as_root pacman -Rns --noconfirm "$pkg"
fi
done
fi
step "Removing udev rule (if we wrote one)"