Install
Table of Contents
Pre-install
Note
The cross-platform Fedora Media Writer is the official, tested, and supported method for the creation of bootable media. Instructions are available in the Fedora documentation.
Before installation, the following checks are recommended:
- Ensure SecureBoot is enabled.
- Ensure your BIOS is up-to-date by checking its manufacturer’s website.
- Disable booting from USB (some manufacturers allow firmware changes from live systems).
- Set a BIOS password to prevent tampering.
Terms of Use
secureblue includes a combination of software packages, each under its own licensing terms. The license of secureblue is the Apache License 2.0. The license of secureblue does not supersede the licenses of upstream code and content contained in secureblue images. By downloading secureblue you agree to the license terms of its use.
Copyright 2024-2025 The Secureblue Authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this software except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Installation
To install secureblue, you will use one of the following processes. Consult the table below for the right starting point for your use case. For more details on the available images, have a look at the list of available images before proceeding.
Image Type | Installation Process | Recommended Use Cases |
---|---|---|
Desktop | Direct installation with a secureblue ISO | Desktop/laptop end user |
Server | Installation using Ignition via Butane. | Cloud, containerized workloads |
Things to remember during installation:
- Select the option to encrypt the drive you’re installing to.
- Use a strong password when prompted.
- Select wheel group membership for your user when prompted.
Secureblue ISO (Desktop)
Note
nvidia-open images are recommended for systems with NVIDIA GPUs Turing or newer (GTX 16XX+, RTX 20XX+). These include the new open kernel modules from NVIDIA, not Nouveau. nvidia images are recommended for systems with NVIDIA GPUs Pascal or older. These include the closed kernel modules from NVIDIA.
ISO Verification
You should now have the ISO with its corresponding CHECKSUM file, the keyring file, and if you opted to use a torrent, the torrent file with its corresponding CHECKSUM file. Use following commands to verify the ISO (where ${IMAGE_NAME}
corresponds to the filename of the ISO you downloaded).
For all users
First command:
gpgv --keyring ./secureblue-keyring.gpg "${IMAGE_NAME}.iso-CHECKSUM"
Expected output:
gpgv: Signature made Wed 04 Jun 2025 12:49:39 AM PDT
gpgv: using EDDSA key 26B4463ED8F313BC7E3FBDF9D9223AF0F47B3E41
gpgv: Good signature from "secureblueadmin <secureblueadmin@proton.me>"
Second command:
sha256sum -c "${IMAGE_NAME}.iso-CHECKSUM"
Expected output:
IMAGE_NAME.iso: OK
sha256sum: WARNING: 8 lines are improperly formatted
For torrent users
First command:
gpgv --keyring ./secureblue-keyring.gpg "${IMAGE_NAME}.iso.torrent-CHECKSUM"
Expected output:
gpgv: Signature made Wed 04 Jun 2025 12:49:39 AM PDT
gpgv: using EDDSA key 26B4463ED8F313BC7E3FBDF9D9223AF0F47B3E41
gpgv: Good signature from "secureblueadmin <secureblueadmin@proton.me>"
Second command:
sha256sum -c "${IMAGE_NAME}.iso.torrent-CHECKSUM"
Expected output:
IMAGE_NAME.iso.torrent: OK
sha256sum: WARNING: 8 lines are improperly formatted
Ignition (Server)
Follow the Fedora CoreOS docs, Ignition docs, and Butane docs to configure initialization for your CoreOS instance(s).
You can use our example.butane as a starting point.
Post-install
- Essential
- Recommended
Subscribe to secureblue release notifications
Subscribing to release notifications is documented here.
Enroll SecureBoot key
Note
GNOME users on Nvidia images may notice that Gnome Software prompts them to create a new secureboot key. This prompt can and should be ignored, and the command below used instead.
The secureblue Secure Boot key should automatically enroll after installation, with the MOK password “secureblue”. If this fails or doesn’t appear for whatever reason, you can manually enroll the key with the command below.
ujust enroll-secureblue-secure-boot-key
Validation
To validate your secureblue setup, run:
ujust audit-secureblue
Read the FAQ
Lots of important stuff is covered in the FAQ. If you’re having an issue, it’s probably covered there already. AppImage toggles, GNOME extension toggles, Xwayland toggles, etc.
Kernel argument tuning
A stable set of kernel arguments is preinstalled with secureblue. However, it is recommended that you consult our Kargs article for guidance on tuning Kargs based on your use case.
Flatpak Permissions Tuning
Consult our Flatpak article for guidance on tuning Flatpak permissions.
Setup USBGuard
This will generate a policy based on your currently attached USB devices and block all others, then enable usbguard.
ujust setup-usbguard
Create a separate wheel account for admin purposes
Caution
If you do these steps out of order, it is possible to end up without the ability to administrate your system. You will not be able to use the traditional GRUB-based method of fixing mistakes like this, either, as this will leave your system in a broken state. However, simply rolling back to an older snapshot of your system, should resolve the problem.
Creating a dedicated wheel user and removing wheel from your primary user helps prevent certain privilege escalation attack vectors and password sniffing. We log in as admin to do the final step of removing the user account's wheel privileges in order to make the operation of removing those privileges depend on having access to your admin account, and the admin account functioning correctly first.’ You don't need to log in using your wheel user to use it for privileged operations. When logged in as your non-wheel user, Polkit will prompt you to authenticate as your wheel user as needed, or when requested by calling run0
.
run0
adduser admin
usermod -aG wheel admin
passwd admin
exit
reboot
- Log in as
admin
run0
gpasswd -d {your username here} wheel
reboot
Configure system DNS
The command below will interactively setup system DNS resolution for systemd-resolved (and optionally set the resolver for Trivalent via management policy). If you intend to use a VPN, use the system default state (network provided resolver). This will ensure your system uses the VPN provided DNS resolver to prevent DNS leaks. ESPECIALLY avoid setting the browser DNS policy in this case.
ujust dns-selector
Toggle MAC address randomization
Toggle system-wide MAC address randomization in NetworkManager between random
and permanent
using the command below. Disabling MAC randomization can help with network compatibility issues, especially in enterprise or captive portal environments. Enabling it improves privacy by preventing tracking across networks.
ujust toggle-mac-randomization
Bash environment lockdown
To mitigate LD_PRELOAD attacks, run:
ujust toggle-bash-environment-lockdown
LUKS Hardware-Unlock
There are two options available for hardware-based unlocking. You can either enroll FIDO2 or TPM2 for your LUKS volume. FIDO2 enrollment is preferable if you own a hardware security key. It's recommended that you choose only one of these, and not both at the same time.
LUKS FIDO2 Unlock
To enable FIDO2 LUKS unlocking with your FIDO2 security key, run:
ujust setup-luks-fido2-unlock
LUKS TPM2 Unlock
Warning
If you have an AMD CPU, check your firmware settings to make sure it is using a dedicated TPM device or a Pluton Chip. If not and it is using an fTPM (firmware TPM), skip this step. If you do not know what this means or are unsure, just skip this step.
To enable TPM2 LUKS unlocking, run:
ujust setup-luks-tpm-unlock
Type Y
when asked if you want to set a PIN.
Trivalent Flags
The included Trivalent browser has some additional settings in chrome://flags
you may want to set for additional hardening and convenience (can cause functionality issues in some cases).
You can read about these settings in the Trivalent post-install instructions.