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.

FileWave Server: Appears to work but still unsupported at this time
FileWave Booster: Automated Booster upgrades seem to not like the OS being 13.0. 
FileWave IVS: Breaks filewave-ivs possibly due to Python version

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

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.

FileWave Server: Appears to work but still unsupported at this time
FileWave Booster: Automated Booster upgrades seem to not like the OS being 13.0
FileWave IVS: Breaks filewave-ivs possibly due to Python version

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. This step is here to just have a sanity check to make sure you haven't installed any additional repos that might not 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 and does not prevent you from upgrading to Debian 13.

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 dist-upgrade --autoremove -y

You may see a prompt like the below because we customize /etc/issue on some images. Just press enter for the question about /etc/issue 

Installing new version of config file /etc/debian_version ...

Configuration file '/etc/issue'
 ==> Modified (by you or by a script) since installation.
 ==> Package distributor has shipped an updated version.
   What would you like to do about it ?  Your options are:
    Y or I  : install the package maintainer's version
    N or O  : keep your currently-installed version
      D     : show the differences between the versions
      Z     : start a shell to examine the situation
 The default action is to keep your current version.
*** issue (Y/I/N/O/D/Z) [default=N] ?

You may also see a question like this and you can pick Yes here;

 There are services installed on your system which need to be restarted when certain libraries, such as libpam, libc, and libssl, are upgraded. 
 Since these restarts may cause  interruptions of service for the system, you will normally be prompted on each upgrade for the list of services 
 you wish to restart.  You can choose this option to avoid being prompted; instead, all necessary restarts will be done for you automatically so 
 you can avoid being asked questions on each library upgrade.

You may also see a question like this and you can just hit Enter to pick "Keep the local version currently installed" so that the SSHd configuration stays the same;

A new version (/tmp/tmp.ud6fJgwKB8) of configuration file /etc/ssh/sshd_config is available, but the version installed
currently has been locally modified. 

What do you want to do about modified configuration file sshd_config?

You may also see a question like this and again can just hit Enter to pick "Keep the local version currently installed" so that the NFS server configuration remains the same;

A new version (/usr/share/nfs-common/conffiles/nfs.conf) of configuration file /etc/nfs.conf is available, but the 
version installed currently has been locally modified.

What do you want to do about modified configuration file nfs.conf?

If you see any other questions asked that do not make sense then please reach out to Technical Support to ask and we will use those questions to improve this article.

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

You will be prompted with a Y/n and should type Y and then enter to continue;

root@filewave:~# sudo apt modernize-sources
The following files need modernizing:
  - /etc/apt/sources.list
  - /etc/apt/sources.list.d/filewave-release.list

Modernizing will replace .list files with the new .sources format,
add Signed-By values where they can be determined automatically,
and save the old files into .list.bak files.

This command supports the 'signed-by' and 'trusted' options. If you
have specified other options inside [] brackets, please transfer them
manually to the output files; see sources.list(5) for a mapping.

For a simulation, respond N in the following prompt.
Rewrite 2 sources? [Y/n] 
Modernizing /etc/apt/sources.list...
- Writing /etc/apt/sources.list.d/debian.sources

Modernizing /etc/apt/sources.list.d/filewave-release.list...
- Writing /etc/apt/sources.list.d/filewave-release.sources

Finally do one last update to ensure you see no errors;

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

And a final reboot and you are all done!

sudo reboot

Troubleshooting

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.

No comments to display

Back to top