IncusOS Installation Guide

Overview

#

A BIOS update typically wipes the Secure Boot keys, which usually means a full IncusOS reinstall. This guide covers that process end to end on a Dell OptiPlex 3070.

Reference video: IncusOS installation walkthrough

Steps at a glance:

1. Prepare the BIOS
2. Build the installer image
3. Organize the installer files
4. Create the seed configuration files
5. Build the seed and flash the USB
6. Install IncusOS
7. Set the default Incus remote

1. Prepare the BIOS

#

On the original install, two BIOS changes were needed:

• Secure Boot keys: Delete some or all of the existing boot key certificates.
• SupportAssist: Disable the SupportAssist options.

Without the SupportAssist change, the Dell SupportAssist Pre-Boot System Performance Check runs on its own after the key changes and reboot. Once it finishes testing memory, it reports:

Hardware scan complete with no issues.
Your machine will restart and download cSOS for recovery.

Disabling SupportAssist in the BIOS stops this.

2. Build the Installer Image

#

Open the IncusOS Customizer and configure it as follows.

Image

#

Installation target

#

The size filters bracket the OptiPlex 3070’s 953.9 GiB disk. Adjust them for your hardware.

Configuration and authentication

#

• Default configuration: Check Apply default configuration.
• OIDC authentication: Leave unconfigured.
• TLS client certificate:

  • Reinstalling with an existing client cert: retrieve it on your workstation with:

    incus remote get-client-certificate

  • Otherwise: generate a new certificate in the UI.

Click Download when done.

3. Organize the Installer Files

#

Create this folder structure:

IncusOS_Install/
├── flasher_tool/
└── IncusOS_Files/

1. Move the downloaded IncusOS .img file into IncusOS_Files/.
2. Copy (don’t move) the same .img file into flasher_tool/.

You should now have two identical copies: a pristine original in IncusOS_Files/ and a working copy in flasher_tool/.

4. Create the Seed Configuration Files

#

Create the following files in flasher_tool/.

incus.yaml

#

Paste in your certificate and adjust values as needed:

version: "1"
apply_defaults: true
preseed:
  config:
    core.https_address: "[::]:8443"
  certificates:
    - name: system-admin
      type: client
      certificate: |
        INSERT CERTIFICATE HERE

install.yaml

#

version: "1"
force_install: true
force_reboot: true

If the installer reports that IncusOS is already installed, you’ll need a confirmation key in this file. See Installer says IncusOS is already installed.

network.yaml

#

Use the interface name found with ip link show (see Secure Boot blocks the installer):

config:
  interfaces:
    - name: "enp1s0"
      hwaddr: "enp1s0"
      addresses:
        - "192.168.0.34/24"
      routes:
        - to: "0.0.0.0/0"
          via: "192.168.0.1"
  dns:
    nameservers:
      - "8.8.8.8"

5. Build the Seed and Flash the USB

#

From a terminal in flasher_tool/:

1. Confirm a fresh copy of the original IncusOS .img file is present.

2. Delete any seed.tar left over from a previous attempt.

3. Create the seed archive:

   tar -cf seed.tar incus.yaml install.yaml

4. Run the flasher tool to produce the seeded image:

   ~/go/bin/flasher-tool --format img --seed ./seed.tar --image ./IncusOS_202607011621.img

5. Write the resulting .img file to a USB drive.

6. Install IncusOS

#

1. Plug the USB drive into the target machine.
2. Power on and press F12 repeatedly to open the boot menu.
3. Select the USB drive.
4. Let the installer run, and remove the USB drive when prompted.
5. The machine reboots automatically into IncusOS.
6. The server’s IP address is shown at the bottom of the screen once it boots.

7. Set the Default Incus Remote

#

On your workstation:

# Check the current default remote
incus remote get-default

# Make the IncusOS server the default
incus remote switch IncusOS

# Confirm the change
incus remote get-default

Troubleshooting

#

Secure Boot blocks the installer

#

If you can’t get past Secure Boot, wipe the internal drive from a live Linux session:

1. Disable Secure Boot in the BIOS.

2. Write a Linux Mint ISO to a USB drive and boot from it. Do not install Mint.

3. Open a terminal and find your network interface name (e.g. enp1s0). Note it for network.yaml:

   ip link show

4. Identify the internal drive:

   lsblk

   • Internal drive: usually /dev/nvme0n1 (NVMe) or /dev/sda (SATA)
   • USB drive: usually /dev/sdb or /dev/sdc

5. Wipe the internal drive completely, including partition tables and encryption headers:

   sudo wipefs -a /dev/nvme0n1

6. Write a fresh, blank GPT partition table:

   sudo parted /dev/nvme0n1 mklabel gpt

7. Shut down, remove the Mint USB, and insert the IncusOS installer USB.

8. Power on, press F2 to enter the BIOS, re-enable Secure Boot, and boot.

The system should now boot straight into the installer.

⚠️ wipefs and parted destroy all data on the target drive. Double-check the device name with lsblk first.

Installer says IncusOS is already installed

#

If booting the USB produces this error:

System check error: IncusOS is already installed on this system: to confirm
overwriting, add ForceInstallConfirmation=xxxxxx to the install seed and reboot.
IncusOS is unable to run until this problem is resolved.

1. Record the xxxxxx key.

2. Update install.yaml:

   version: "1"
   force_install: true
   force_install_confirmation: "xxxxxx"
   force_reboot: true

3. In flasher_tool/, delete the previously seeded .img and replace it with a fresh copy from IncusOS_Files/.

4. Repeat Step 5.

The key changes on every install attempt. The only way to get it is to boot the installer USB and read the error, then redo the seed with the new key.

Maintenance

#

Updating and rebooting

#

Automatic updates are disabled on this server, so updates run manually from the workstation with the incus client.

Network settings

#

incus admin os system network show
incus admin os system network edit
incus admin os system network confirm

Other commands

#

incus list

Web UI

#

• URL: https://192.168.0.34:8443/

The UI authenticates with a certificate, so there’s no username or password. The certificate imported successfully only into Firefox; importing it into Chrome didn’t work.