Skip to main content

Migrating a Debian 12 FileWave Appliance to Debian 13

Please note that this is here for testing purposes. FileWave QA has NOT tested FileWave with Debian 13 for production use. We are working on transitioning to Debian 13 with FileWave 16.3.0 at the end of 2025. This notice will be removed when we do so. This guide is published to get feedback from others and develop this process to be as safe as possible.

What

This guide explains how to upgrade a FileWave appliance running Debian 12 (“bookworm”) to Debian 13 (“trixie”). It focuses on the operating system upgrade process only — additional steps may be required for applications, services, or integrations you have installed. This is meant for the FileWave Appliances, but the idea should be able to apply to your Debian instance running FileWave or any other solutions.

For production appliances, we recommend:

  1. Take a full VM snapshot or backup before starting.

  2. Perform the upgrade in a staging environment first if you have one.

  3. Schedule downtime in case of post-upgrade adjustments.

When/Why

You should use this guide when:

  • Your FileWave appliance is currently on Debian 12, and you want to move to Debian 13 to take advantage of updated security patches, improved package support, and upstream enhancements.

Upgrading ensures long-term security compliance and keeps your system in a supported state for both Debian and FileWave.

How

Before proceeding, you may want to read the Debian 13 Release Notes if you are curious.

1. (Optional) Use screen to Avoid SSH Disconnects

For all of the steps below you would be logged in via VMWare or HyperV console sessions which are safer than an SSH session. If you use SSH then be sure to use this step so you can reconnect if needed to a lost session. The steps below are very easy but fully explained which makes this document seem longer. If at any step you feel lost or stuck please reach out to Technical Support to ask questions.

sudo apt-get install -y screen && screen

If you were to disconnect and were doing an SSH session using the above command you could reconnect and type;

screen -ls

This would show you;

There is a screen on:
    1234.pts-0.servername  (Detached)
1 Socket in /run/screen/S-user.

And then you could reconnect with;

screen -r 1234

And then you can keep working with your prior session. 

2. Check Free Disk Space

Run:

df -h

A minimum of 5 GiB free is required.

If needed, free space with:

sudo apt clean
sudo apt autoremove

And if you still need space consider expanding the disk: Expanding the Disk on a FileWave Appliance - Debian

3. Identify 3rd-Party Repositories

Just in case you have any added that might need to be adjusted for Trixie. You'll want to see if you have anything there that should be considered. In my Linode lab I found that they add an Akamai repo that did not initially have a Trixie option. 

ls /etc/apt/sources.list.d

On the IVS I have the below repo which is not specific to Bookwork or Trixie so it's fine that it is there and doesn't need to change.

root@filewave:/etc# cat /etc/apt/sources.list.d/filewave-release.list
deb [arch=amd64 signed-by=/etc/apt/keyrings/filewave.gpg] https://fwdl.filewave.com/debian/apt-repo main main

4. Update Current Distribution

In this step you will upgrade all the software to the latest Debian 12 version and then reboot the server to be sure that is what is running when you get to the next step;

sudo apt-get update && sudo apt-get dist-upgrade --autoremove -y

Reboot after the updates install;

sudo reboot

When you reconnect make sure to run screen again if you are using SSH to connect;

screen

5. Update Debian Repository to “trixie”

In this step we're changing any bookworm references to trixie for the sources used by apt which is the software that handles updates on Debian;

sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

6. Update All 3rd-Party Repositories

The line below assumes the repository supports Debian 13 (“trixie”). For instance on the IVS nothing would happen here unless you have additional repos installed. 

sudo find /etc/apt/sources.list.d -type f -exec sed -i 's/bookworm/trixie/g' {} \;

Afterward, run this to have it learn all of the Trixie updates that are available:

sudo apt-get update

Resolve any missing repository errors before continuing. If you get stuck on this step where it throws errors you should reach out to Technical Support to ask for advice. 

7. Upgrade to Debian 13

Say Yes to restarting services when prompted, and keep existing configuration files unless you know you need the defaults.

sudo apt-get update && sudo apt-get dist-upgrade --autoremove -y

Reboot after the Trixie updates install;

sudo reboot

8. Modernize Debian Sources

This will create /etc/apt/sources.list.d/debian.sources and /etc/apt/sources.list.d/debian-backports.sources.

sudo apt modernize-sources

9. Errors Updating after going to Trixie

When updating Debian after going to Trixie, apt update fails for trixie-backports with an error about “missing Signed-By” or “NO_PUBKEY”. Edit the /etc/apt/sources.list (or .list file in /etc/apt/sources.list.d/) for the trixie-backports line and change it to look like:

deb [signed-by=/usr/share/keyrings/debian-archive-keyring.gpg] http://deb.debian.org/debian trixie-backports main contrib non-free-firmware

Save the file, then run:

sudo apt update

You should not see the error any more. 

Related Content

Digging Deeper

The upgrade path from Debian 12 to Debian 13 is generally smooth for systems that are close to “vanilla” Debian. The biggest potential issues come from:

  • Third-party repositories: These must have a trixie branch. If not, you may need to comment them out temporarily.

  • Custom applications: Each application’s compatibility with Debian 13 should be verified before upgrading.

  • Kernel changes: Debian 13 may introduce new kernel defaults — test in a lab environment if you have kernel-level drivers or modules.

Back to top