FAQ

Table of contents

Project information

Why secureblue?

secureblue is a collaborative effort to ship a maximally secure Linux operating system. It leverages bootable container technology to build on top of Fedora Atomic, avoiding the need to become a distro in the traditional sense. secureblue has benefitted massively by not being a distro, and instead shipping as bootable OCI container images. This has meant a ton of overhead is taken care of for us by Fedora. We don’t need general repos or packaging, except for a handful of specific packages (Trivalent, hardened_malloc, etc). The Fedora Atomic ecosystem is also rich in tooling and automation (see: BlueBuild), plus the backdrop of robust container technology that already exists. All of this has largely enabled us to focus our energy on improving secureblue’s hardening and UX, developing Trivalent, and building out userspace SELinux policies.

Is secureblue immutable?

“Immutable” is an old misnomer for atomic systems. It gives the impression that users can’t modify or tinker with their system, which is not the case. While directories like /usr are mounted read-only by default, settings and configurations can be easily overriden with changes in /etc, which is not mounted read-only. This is in addition to the fact that /usr is mutated with every deployment that is staged and booted via any rpm-ostree operation (like upgrading, installing a new package, etc). As such, secureblue is not immutable.

Why not upstream your changes?

When possible, we do upstream our changes. In particular, we have contributed several findings and fixes to KDE. However, it’s important to note that many of the changes we make are not possible to upstream, generally due to upstream not desiring them. This is for good reason. Many of the changes secureblue makes will necessarily break someone’s use case by default. Otherwise, secureblue could just submit all of our changes upstream to Fedora. Take AppImage support as an example. AppImages depend on the suid-root, deprecated, unmaintained fuse2 interface. They also encourage users to follow the security antipattern of downloading and executing binaries from the browser. Yet, since AppImages are widely used, Fedora can’t remove support for them. secureblue is willing to make these kinds of changes by default to improve security, with mechanisms available for users to re-enable support if needed for their use cases.

Is this an install script?

No. secureblue is not an install script, nor an add-on to a Fedora installation, nor a distro in the traditional sense. It is a set of bootable container images shipped via GitHub’s container registry. These images are rebuilt daily and pushed to GitHub’s container registry. These images are then pulled in by rpm-ostree, which stages updates as a pending deployment for the next boot. To view information about your current local deployments and remotes, run rpm-ostree status.

Another security project has a feature that’s missing in secureblue, can you add it?

First, check our features list to see whether it already lists an equivalent or better feature. If it doesn’t, open a new GitHub issue.

How do I get notified of new releases?

To subscribe to release notifications, on the secureblue GitHub page, click “Watch”, and then “Custom”, and select Releases like so:

GitHub screenshot

If you prefer to use an Atom feed, supported by many RSS clients, you can use the feed provided by GitHub.

What do the GitHub releases involve?

Substantial testing for new changes is done in the staging and next branches. However, once a commit is merged into live, a new set of builds is immediately generated and deployed. As such, the GitHub releases are an informational measure to track progress and communicate changes to users. This is only the case for the secureblue main repo, it isn’t the case for Trivalent. For Trivalent, GitHub releases correspond to RPM releases to the RPM repo.

System information

Why is Flatpak included? Should I use Flatpak?

Consult our Flatpak article.

Should I use Electron apps? Why don’t they work well with hardened_malloc?

Consult this discussion

Should I use Firejail?

No, use bubblejail if there’s no Flatpak available for an app that you want to sandbox. Note that this requires enabling unconfined user namespaces, which is a security degradation.

Why am I being asked to enroll a Secure Boot key?

As part of a move to unify our supply chain, secureblue moved to our own kernel signing system. This was done for both practical and security advantages, and paved the way towards further kernel security improvements in the future. This change included a transition to a new secureblue Secure Boot key. You must enroll this new key to prevent issues when loading kernel modules:

ujust enroll-secureblue-secure-boot-key

Why does secureblue include Homebrew?

Homebrew is a cross-platform package manager, originally for macOS that allows users on Atomic systems to install CLI tools without layering and rebooting their system. It also brings with it a recent independent security audit and subsequent actions taken in response to security findings uncovered by that audit.

Does secureblue use “linux-hardened”?

“linux-hardened” is the brand name for a specific set of kernel patches and builds on top of the mainline kernel, used by some distributions. secureblue doesn’t use this kernel. Instead, we apply runtime configuration changes on top of Fedora’s kernel. We can accomplish much but not all of what linux-hardened accomplishes using this approach. In the future, we plan to build our own kernel with patches on top of Fedora’s kernel, including the OpenPAX patches. However, even today there are some important ways in which our approach is preferable. For example, linux-hardened completely disables unprivileged user namespaces. This means that to use flatpaks or chromium-based browsers, suid-root binaries are required. This is a significant security degradation. secureblue on the other hand implements SELinux-confined unprivileged user namespaces, restricting them by default but allowing them for Flatpaks and Trivalent to enable their operation without suid-root.

Why are upgrades so large?

This is an issue with rpm-ostree image-based systems generally, and not specific to secureblue. Ideally, upgrades would come in the form of a zstd-compressed container diff, but it’s not there yet. Check out this upstream issue for more information.

Usage

How do I update the system?

All system updates are automatic, running on at least a daily cadence. This includes automatic updates for rpm-ostree, brew, flatpak, and podman. If the system is over 1 week out of date (for example in the event of update failures), the user will be notified and pointed to the right command to run to manually upgrade.

How do I disable automatic updates?

Caution

Disabling automatic updates is a security degradation. You will no longer automatically receive security updates.

How do I whitelist a module?

secureblue prevents numerous modules from loading to reduce attack surface. If there’s a particular module you need, run ujust override-enable-module mod_name. To undo this, run ujust override-reset-module mod_name.

How do I install software?

  1. Check if it’s already installed using rpm -qa | grep x
  2. For GUI packages, you can install the Flatpak if available using the Software store or using flatpak install. You can browse this catalogue of Flatpaks to discover the available packages.
  3. For CLI packages, you can install from brew if available using brew install. You can browse this catalogue of Homebrew Formulaes to discover the available formulaes.
  4. If a package isn’t available via the other two options, or if a package requires greater system integration, rpm-ostree install can be used to layer rpms directly into your subsequent deployments.

You can add the unfiltered Flathub repo with ujust enable-flathub-unfiltered.

How do I install my VPN?

To install a standalone VPN app, use ujust install-vpn. Alternatively, you can download a WireGuard profile config from your VPN provider’s website and import it via the system network settings menu. Below are the steps for GNOME.

  1. Navigate to the “Network” tab in GNOME settings. Gnome Settings screenshot
  2. Click the “+” button to add a new VPN connection. Gnome Settings screenshot
  3. Click “Import from file…” and use the file chooser to select the VPN config file you downloaded from your VPN provider. Gnome Settings screenshot
  4. Click the “Add” button, and your VPN will now be accessible through the system network settings. Gnome Settings screenshot

Note

If you get an error that says "Cannot Import VPN", that is likely because the name of the WireGuard configuration file is too long. GNOME Settings will only accept WireGuard configuration files with filenames 15 characters or less.

How do I install Steam?

ujust install-steam

How do I enable anti-cheat support?

Note

Kernel-level anti-cheat solutions are generally unsupported on desktop Linux.

Anti-cheat solutions typically require process tracing to work - the ability to monitor syscalls (and other signals) from other processes. On Linux, process tracing is controlled by the kernel.yama.ptrace_scope kernel parameter. By default, secureblue doesn’t allow ptrace attachment at all, addressing basic security concerns. The command below toggles between this restrictive default setting where ptrace_scope is set to 3, breaking anti-cheat software, and a much less restrictive setting where ptrace_scope is set to 1, which allows parent processes to trace child processes, enabling some anti-cheat solutions to work.

ujust toggle-anticheat-support

The ujust above is aliased as toggle-ptrace-scope. You must reboot your computer after running it.

How do I install Docker?

ujust install-docker

Similarly, you can uninstall Docker with:

ujust uninstall-docker

How do I install additional fonts?

You can either layer fonts with rpm-ostree install (if they’re packaged as an RPM) or add them to your user’s local font directory at $HOME/.local/share/fonts.

If you install fonts in $HOME/.local/share/fonts, it is recommended to run the following command afterward to ensure the fonts have the correct SELinux labels:

restorecon -Rv $HOME/.local/share/fonts

How do I enable printing?

To enable printing using CUPS, run ujust toggle-cups. Note that this enables printing support, but still leaves printer discovery disabled for security reasons. The CUPS printer discovery service increases attack surface significantly and has a recent history of severe vulnerabilities.

Why am I unable to start containers?

Software such as Podman and Distrobox need to be able to create user namespaces to work without root. The privilege to do so is denied by default in secureblue, but can be granted by running the following command:

ujust toggle-container-domain-userns-creation

Trying to start a container without first enabling the ability toggled by the ujust above will result in an OCI permission denied error, but beware that enabling it results in a security degradation. Consult our user namespaces article for more details.

How do I enable userns for other apps?

The following command will toggle the ability of processes in the unconfined SELinux domain to create user namespaces. It’s necessary for any apps that require this feature, such as: browsers other than Trivalent, many Electron apps, and bubblejail.

ujust toggle-unconfined-domain-userns-creation

Attempting to bubblewrap a program without first enabling the ability toggled by the ujust above will result in a bwrap: Creating new namespace failed: Permission denied error, but beware that enabling it results in a security degradation. Consult our user namespaces article for more details.

Why are Bluetooth kernel modules disabled? How do I enable them?

Bluetooth has a long and consistent history of security issues. However, if you still need it, run:

ujust set-bluetooth-modules on

How do I provision signed Distroboxes?

ujust distrobox-assemble

How do I customize secureblue?

If you want to add your own customizations on top of secureblue that go beyond installing packages, you are advised strongly against forking. Instead, create a repo for your own image by using the BlueBuild template, then change your base-image to a secureblue image. This allows you to apply your customizations to secureblue in a concise and maintainable way, without the need to constantly sync with upstream. For local development, building locally is the recommended approach.

How do I add a repo?

The process of adding a repository to secureblue is the same as on Fedora

How do I install proprietary codecs?

There is no need, they are already included in the image.

How do I install KDE Connect?

Due to an rpm-ostree bug, layering the kde-connect package currently does not work. As a workaround, you can layer the kde-connect-nautilus package which will pull KDE Connect while bringing minimal additional dependencies. After you do that, you have to permanently enable the ‘kdeconnect’ service in the firewall configuration in order for devices to recognize and be recognizable via KDE Connect.

How do I change my DE?

Choose whatever you like from the available options by running ujust rebase-secureblue.

How do I enable kernel modules?

Some functionality requires you to enable extra kernel modules that are disabled by default in secureblue. Modules can be enabled by running ujust override-enable-module. For instance, mounting SMB shares requires the cifs and netfs kernel modules. To load them, simply run ujust override-enable-module cifs and ujust override-enable-module netfs then reboot.

Which filters are included in Trivalent adblocking? How do I add a new filter?

Trivalent comes preloaded with EasyList, EasyPrivacy, Fanboy Annoyance, and a wide set of regional filter lists covering Europe, Asia, the Middle East, and more. It also includes Anti-Adblock Filters to bypass detection. You can see the full list here: Trivalent filter sources. If you want to add a new filter, open an issue or submit a pull request in the same repository.

Why aren’t YouTube ads blocked, and how can I watch YouTube without ads?

Trivalent’s subresource filter cannot perform script injection or observe and alter what happens inside YouTube’s video player, so it can’t reliably intercept the scripts and dynamic behavior YouTube uses to serve ads. To avoid ads you need a tool capable of doing that. Common options are FreeTube Electron Flatpak, Pipeline Piped proxy Flatpak, and the YouTube PWA paired with uBlock Origin‑Lite. Consider creating a separate profile for the Youtube PWA, so you can continue browsing extensionless for your usual profile.

How do I configure GRUB?

As of Fedora 41, GRUB configuration is now static for Atomic desktops, not dynamic (why?). This means that changes to the main config file at /boot/grub2/grub.cfg are expected to come from upstream, not from manual configuration or tools like grub2-mkconfig. However, /boot/grub2/grub.cfg contains two if statements that check if files /boot/grub2/user.cfg and/or /boot/grub2/console.cfg exist and will then load in any manual configuration made in these files. user.cfg is intended for general configuration, whereas console.cfg is intended for graphics related configuration, however you can use either file for either purpose or use one for both if you wish. You can find information about manual grub configuration here.

Please note, the instructions provided by the Arch Wiki article for manually adding a menu entry for Windows are incorrect. The Wiki states you need to provide a hints_string as a parameter for the search function, however this is not required and will cause GRUB to error. You only need to provide the UUID for the partition that holds the Windows boot EFI file.

Troubleshooting

Something broke! How do I rollback?

Each rpm-ostree operation generates and stages a new deployment, which includes the creation of a new GRUB entry at position 0. To boot into the previous deployment, simply select the GRUB entry at position 1. As a preventative measure, you can ensure you always have a known-good deployment available by pinning an existing deployment.

Why can’t I install new KDE themes?

The functionality that provides this, called GHNS, is disabled by default due to the risk posed by the installation of potentially damaging or malicious scripts. This has caused real damage.

If you still want to enable this functionality, run:

ujust toggle-ghns

Why doesn’t my Xwayland app work?

Xwayland is disabled by default on GNOME, KDE Plasma, and Sway. Some apps haven’t migrated to Wayland yet, and will often say so when started from the terminal by complaining about not being able to find X11. Since enabling Xwayland is a security degradation, you are encouraged to find alternatives for those apps. If you decide you still need Xwayland, run:

ujust toggle-xwayland

Why I can’t install nor use any GNOME user extensions?

This is because support for installing & using them has been intentionally disabled by default in secureblue. Only GNOME system extensions are trusted, if they are installed.

To enable support for installing GNOME user extensions, you can run ujust command:

ujust toggle-gnome-extensions

An app I use won’t start due to a malloc issue. How do I fix it?

My clock is wrong, and it’s not getting automatically set. How do I fix this?

If your system time is off by an excessive amount due to rare conditions like a CMOS reset, your network will not connect. A one-time manual reset will fix this. This should never be required except under very rare circumstances.

For more technical detail, see issue #268

My fans are really loud, is this normal?

During rpm-ostree operations, it’s normal. Outside of that, make sure you followed the post-install instructions.

On secureblue half of my CPU cores are gone. Why is this?

mitigations=auto,nosmt is set on secureblue. This means that if your CPU is vulnerable to attacks that utilize Simultaneous Multithreading, SMT will be disabled. There are several other kargs secureblue sets that may also trigger this behavior, including nosmt=force, and l1tf=full,force.

Why don’t my AppImages work?

AppImages depend on fuse2, which is unmaintained and depends on a SUID root binary. For this reason, fuse2 support is removed by default. It’s strongly recommended that you find alternative mechanisms to install your applications (Flatpak, Distrobox, etc.). If you can’t find an alternative and still need fuse2, you can add it back by layering something that depends on it.

For example:

rpm-ostree install funionfs

Why don’t KDE Vaults work?

Similar to the AppImage FAQ, the KDE Vault default backend cryfs depends on fuse2. For this reason, it’s recommended that you migrate to an alternative that doesn’t depend on fuse2, for example fscrypt. If you don’t want to do so, you can add fuse2 back by layering something that depends on it, as described in the AppImage FAQ.

Why won’t Trivalent start when Bubblejailed?

bubblejail shouldn’t be used on Trivalent, there are issues reported with the pairing and removing the bubblejail config after it is applied can be difficult. It should also be noted that applying additional sandboxing may interfere with chromium’s own internal sandbox, so it may end up reducing security.

Why won’t Trivalent start on Nvidia?

On some Nvidia machines, Trivalent defaults to the X11 backend. Since secureblue disables Xwayland by default, this means that you will need to run ujust toggle-xwayland and reboot, for Trivalent to work.

Why don’t some websites that require JIT/WebAssembly work in Trivalent even with the JavaScript Optimizations toggle enabled?

This is an upstream bug that prevents JavaScript Optimizations settings from being applied to iframes embedded within a parent website. As a result, WebAssembly may not function on services that use a separate URL for their content delivery network or other included domains, such as VSCode Web (https://github.dev). To make VSCode Web work properly, you need to manually allow JavaScript optimizations for the CDN by adding https://[*.]vscode-cdn.net to your list of trusted websites.

There is also currently a bug where the optimizations permission doesn’t apply to a tab even after reloading, only after closing and re-opening the tab does the optimizations toggle properly apply.

Why don’t extensions work in Trivalent?

Extensions in Trivalent are disabled by default, for security reasons, it is not advised to use them. If you want content/ad blocking, that is already built into Trivalent and enabled by default. If you require extensions, you can re-enable them by disabling the Disable Extensions toggle under chrome://settings/security, then restart your browser (this toggle is per-profile).

If the extension you installed doesn’t work, it is likely because it requires WebAssembly (WASM) for some cryptographic library or some other optimizations (this is the case with the Bitwarden extension). Currently, WebAssembly is available without JIT through an interpreter called DrumBrake (which can be toggled at chrome://flags/#jitless-wasm) so allowing JIT should ideally not be needed, though some extensions do not always work with DrumBrake (for example Bitwarden sometimes has issues) and JIT may need to be enabled anyway.
To re-enable JavaScript JIT and WASM for an extension, visit chrome://extensions, under the extension with the issues, go Details -> Site Settings, then scroll to JavaScript optimization & security and flip to allow. If the extension continues to not work, try reinstalling the extension.

Why does Trivalent log me out of all sites by default?

It shouldn’t, this is a bug related to Chromium’s Network Service Sandbox where cookies are either cleared or become inaccessible when the browser is closed. If you experience this, navigate to chrome://settings/security, at the bottom you will see a Hardening section and within it a toggle Network Service Sandbox, flip this to off and restart your browser.

Please note that the Network Service Sandbox is no longer enabled by default. Users should keep in mind that enabling this setting may result in issues with cookie persistence. Also note that this is a global toggle, which means that all your browser profiles will be affected if the setting is toggled.

Why doesn’t DRM content (spotify, netflix etc.) work in Trivalent?

DRM-protected content is available in trivalent, however it is disabled by default. Visit chrome://settings/content/protectedContent and select “Sites can play protected content”.

Why is my splash screen disabled on KDE?

The KDE splash screen is currently broken if XWayland is disabled (which is the default on secureblue), due to an upstream bug. secureblue automatically disables it for every user to work around this. If you don’t want the splash screen to be automatically disabled, run the following command:

systemctl disable --user disable-kde-splash.service

Why is my virtual machine integration broken?

In order to use SPICE integration with a secureblue guest, such as the shared clipboard and automatic display resolution setting, you must enable XWayland:

ujust toggle-xwayland

Why can’t I see any network services? (e.g. printers, Google Cast, file servers, IoT)

For applications to automatically discover other devices on your network such as fritz.box, sonos.local, fuchsia.local or epson.local, you need to enable the Avahi mDNS stack and allow it through your firewall.

Caution

mDNS is insecure by design and allows any device on your local network to announce any name or service. Its implementations also have a history of security vulnerabilities. Avoid it where possible, such as by assigning static IPs to local devices, and only expose the mDNS port on trusted networks.

Enabling Avahi

avahi-daemon.service and avahi-daemon.socket are masked and disabled by default. To undo this, run these commands in a root terminal, which you can access by running run0:

# systemctl unmask avahi-daemon.socket
# systemctl unmask avahi-daemon.service
# systemctl enable --now avahi-daemon.socket
# systemctl enable --now avahi-daemon.service

Allowing mDNS through your firewall

For Avahi to work, you must modify your firewall zone to allow mDNS traffic. But, if you modify the default zone (typically FedoraWorkstation), then mDNS will be open for all current and future connections unless specified. Instead, create a custom zone:

# firewall-cmd --new-zone=allow-mdns --permanent
# firewall-cmd --zone=allow-mdns --add-service=mdns --permanent
# firewall-cmd --reload

Then, modify only your current connection to use the new zone. Find your current connection:

# nmcli connection show

Then, change the zone for the connection (using the UUID from above) to allow-mdns.

# nmcli connection modify uuid ${UUID} connection.zone allow-mdns

Then apply your connection changes to the active device as shown by nmcli, such as wlp1s0:

# nmcli device reapply ${DEVICE}

Why is my DNS broken when using a VPN?

Some third-party VPN clients depend on systemd‑resolved directly, rather than sending their connection information to NetworkManager. If your VPN is broken, consider importing the configuration, instead of using the Mullvad GUI or wg-quick. Several desktops, including GNOME, let you do this in Network Settings. Or, you can use the command line:

run0 nmcli connection import type wireguard file /path/to/vpn.conf

Optionally, you can then find the connection’s name and set it to autoconnect:

nmcli connection show
run0 nmcli connection modify "Proton US123" connection.autoconnect yes

If this is not an option, such as for Tailscale (which directly conflicts with secureblue’s default DNS), you can switch back to systemd‑resolved which is the default in Fedora.

ujust dns-selector resolver resolved