Skip to content
DOCUMENTATION

UFLinux Settings

UFLinux Settings is a GTK4 application covering the system controls a desktop session needs. It is written in Rust with plain GTK4 and application-local CSS, uses your GTK theme, and does not depend on libadwaita, GNOME Settings, or the GNOME settings daemon.

Super + I opens the nine-page sidebar interface. Pages are built on demand and discarded when you leave them, so the UI stays small; image previews are bounded and arbitrary remote wallpapers are never downloaded.

The pages are Network, Sound, Audio, Displays, Power, Default apps, Date and time, Appearance, Screen capture and About. The Network page is split into Wi-Fi, Ethernet, Bluetooth and VPN tabs, and Sound and Audio split devices into Output and Input tabs. Tabs share one fixed frame, so switching them never resizes the window or the flyout, and a tab is built only once its hardware appears in a snapshot.

Each panel is a compact flyout version of its page, shown above the taskbar button. Escape, an outside click, or a repeated taskbar click dismisses it. The taskbar draws the flyout on the monitor that owns it.

Terminal window
uflinux-settings --page network # full window on one page
uflinux-settings --panel network --output DP-1
uflinux-settings --panel sound --output DP-1
uflinux-settings --panel power --output DP-1
uflinux-settingsctl status
uflinux-settingsctl volume -5
uflinux-settingsctl brightness 5
uflinux-settingsctl mute
uflinux-settingsctl power-profile balanced

--quick-settings is an alias for the Network panel. The GUI reuses its process and exits after its last window closes — no shell processes poll for status.

Controls for hardware you do not have are hidden rather than shown as unavailable. Use the arrow beside an input or output volume slider to pick which audio device it controls. Each panel links to the full page for advanced options.

Networking is ConnMan with iwd. There is no wpa_supplicant and no NetworkManager in the desktop dependency set, and no separate resolver manager — do not enable networking, dhcpcd, or another resolver alongside ConnMan.

The panel offers scans, radio-block status, personal and hidden networks, saved connections, reconnect/disconnect/forget, addressing, DNS and search domains, and proxy controls. Additional static routes use protocol 242 with a root-protected per-connection database; updates are serialised, rolled back on failure, and remove only exact UFLinux-owned routes. Routing tables are never flushed. Current IPv4 and IPv6 routes are visible in the UI.

Enterprise Wi-Fi supports EAP-TLS, PEAP/MSCHAPv2 and TTLS/PAP. Supply a valid CA, the expected server domain, and the matching identity/password or client certificate and key. Authentication happens in a protected iwd profile while ConnMan stays the connection controller. Profiles and imported certificates are machine-wide and root-readable; secrets are kept out of shared snapshots and preferences. Forgetting a connection removes its certificate files. UFLinux patches Alpine’s ConnMan 2.0-r4 package so iwd-managed enterprise connections are accepted; the separate connman-vpn package builds only the WireGuard backend and runs it as connman-vpnd.

The Bluetooth tab appears when an adapter is available and talks to BlueZ directly over the system bus: adapter power, scanning, pairing, unpairing, trusting and connecting devices, with signal and battery where the device reports them. Pairing uses BlueZ’s default agent-less flow, so devices that require an exchange of I/O capabilities can still fail to pair. The VPN tab manages connman-vpnd WireGuard tunnels: importing a client configuration creates the tunnel through the typed vpn-import request, and each listed tunnel can be connected, disconnected or removed. Private keys stay in the daemon and are never echoed into snapshots or preferences; the tab appears in quick settings only when at least one tunnel is configured.

Hotspots, tethering and virtual interfaces remain outside this UI.

ConnMan’s built-in SNTP client is the only clock synchronizer — no ntpd, chronyd or openntpd. Its persisted policy starts as automatic synchronization with a manual timezone. Clock mutation is restricted to root, so an ordinary user cannot bypass polkit by toggling synchronization directly. ConnMan adjusts the clock with adjtimex(), slewing small offsets and stepping large ones.

Settings shows the timeservers ConnMan would actually query — those announced by the active connection first, then the configured fallback list — and offers manual time only while automatic synchronization is off. The RTC uses UTC. The status you see comes from the kernel’s actual state, not from a successful DNS lookup.

Audio controls speak the PulseAudio client protocol to pipewire-pulse. PipeWire and WirePlumber are the audio stack; there is no PulseAudio server. Devices, profiles, ports, defaults, volume, balance, mute and per-application streams share state between the panel flyout and the full page, and subscriptions reconnect after a server restart. Input and output devices are on separate tabs; the arrow beside a volume slider picks the device.

Three profiles — Power saver, Balanced and Performance — map to TLP’s profile commands. Alpine 3.24 ships TLP 1.10.1; Balanced is the default. The selection persists across reboots and charger changes through /etc/tlp.d/90-uflinux-profile.conf, and the UI reports a profile only when TLP’s runtime record confirms it. Unsupported hardware tunables are left to TLP itself. Administrator overrides in /etc/tlp.conf take precedence over the drop-in and may override the saved boot selection; the UI then shows the profile actually in effect.

There is no power-profiles-daemon and no resident policy script. TLP’s OpenRC startup and udev hooks apply the chosen policy.

Configurable only in Settings → Power: choose Shut down, Suspend or Do nothing independently for AC and battery. Changes need administrator authorization, and Suspend is rejected where unavailable. The default short-press action is Shut down. Firmware-controlled long presses cannot be changed here.

The mapping is handled by uflinux-acpid, which invokes /bin/busybox acpid and accepts power-key press events only, with a bounded, debounced root hook. The hook reads the root-owned policy in /etc/uflinux/power.json, checks shutdown and sleep inhibitors, and asks elogind to act. Elogind’s HandlePowerKey=ignore drop-in prevents double handling; lid policy keeps elogind defaults. Installing another acpid or power-profile daemon conflicts with this package.

Ordinary suspend, restart and shutdown actions in the Start menu do not change this policy.

Display settings use the compositor’s output-management protocol for advertised resolution and refresh modes, fractional scale, transforms, placement and enablement. labwc tests a configuration before applying it: the session service requires confirmation within 15 seconds and restores the previous layout on timeout, caller loss, or output loss. Disabling the final display is rejected.

Confirmed layouts are saved by display identity and restored at login and on hotplug. Missing outputs, duplicate identities, unavailable modes and invalid saved layouts recover to a usable preferred-mode display.

Two honest limitations: VRR controls need protocol support and compatible hardware, and HDR is labwc’s global “use HDR where supported” request rather than a per-monitor activation report. Mirroring is not simulated by overlapping displays.

Backlight values and device hotplug refresh through filtered eudev events. DDC/CI brightness uses bounded asynchronous ddcutil operations against a connected DRM/EDID identity; unsupported monitors show an unavailable state, and hardware-button changes need a rescan because the protocol supplies no push event.

Configures uflinux-screencapture, the tool behind Print Screen: screenshot format and folder, clipboard copying, flash, cursor capture and delay, plus the recording target, quality preset, audio source and frame rate. Remaining recording options sit behind an Advanced expander. The page reports whether the gpu-screen-recorder backend was detected and can re-run that probe.

Hardware encoding needs a VA-API driver. The desktop meta ships the Mesa gallium driver plus both Intel VA-API drivers, so recording works out of the box on AMD and Intel GPUs.

Default applications use GIO/XDG associations and preserve unrelated mappings. About provides copyable system information and tolerates unavailable hardware data.

Process Role
uflinux-settingsd Headless session service. A sleeping Wayland worker handles output protocols; libpulse integrates asynchronously with GLib. Publishes the shared snapshot the desktop shell and panels read.
uflinux-settings The GTK4 UI. The only process that registers a polkit authentication agent.
uflinux-settings-system Root D-Bus helper, authorized per typed operation with polkit. Exits after 45 idle seconds.

The session D-Bus interface is org.uflinux.Settings1 at /org/uflinux/Settings, with GetState, typed Execute requests and Changed subscriptions. Unknown fields and requests larger than 256 KiB are rejected — this is a project interface, not a general command-forwarding API. uflinux-settingsctl request reads its request from standard input; never pass credentials as command arguments.

The system helper accepts only clocks, timezones and time synchronization, protected Wi-Fi profiles, exact additional routes, and identity-checked DDC brightness. No shell commands, no arbitrary paths. Wheel administrators authenticate with their own password; root stays locked. Authorization without an active local session can be denied — use doas on the console in that case.

User preferences live under ~/.config/uflinux plus your personal labwc, GTK and XDG files. Package upgrades preserve them.

Derived from docs/settings.md inUFlinux-project/uflinux3(b4f4817). Report documentation problems inUFlinux-project/docs.