You will receive announcements about new versions of Sandfly from the mailing list, if you are subscribed. Additionally, you can check our website and other media outlets for announcements about new versions.

To update a Sandfly Docker/Podman deployment, read and complete the following steps.

Step 1: Pause Scheduled Tasks

Log in to the Sandfly User Interface (UI). In the sidebar menu, select Scanning > Schedules, and then deactivate all active schedules.

This step automatically cancels active Trickle schedules and ensures no other scheduled tasks are started during the upgrade. Make note of which schedules were deactivated, as they need to be reactivated once the upgrade is finished. See Deactivating and Deleting Schedule for details.

Step 2: Ensure All Tasks Have Completed

In the Sandfly UI, open the Task queues page (click its button in the Top Bar, or in the sidebar menu, select Scanning > Task queues), and confirm all of the following:

• The task queues are empty: the Scan tasks table shows "No tasks in any queue." and the Tasks column of the Queues card shows 0 (zero) for every queue.
• There are no Trickle schedules in progress: the Trickle schedules card shows "No schedules are running." If it lists any schedules, first double-check that Step 1 was completed and then manually cancel any remaining Trickle schedules with their Stop buttons, as Trickle schedules can also be started manually.

Do not stop nodes in the middle of scans because doing so can leave orphaned files on the remote hosts. If the nodes are allowed to finish active tasks, everything cleans up correctly.

Step 3: Download the Update

Download the latest version from the following URL:

• https://github.com/sandflysecurity/sandfly-setup/releases/latest🡵

For a checksum verification of the downloaded file, its sha256 hash is provided to the right of the package name.

If the Sandfly systems are air-gapped, download the archive from a device that has internet access and then transfer the file to the Sandfly hosts as appropriate for your environment.

Once the archive is on the Sandfly hosts, untar it over the existing sandfly-setup directory:

Step 4: Container Image Cleanup

Once all tasks have completed, run the scripts to stop and delete all containers on the Server and Node instances.

Run the following command on the Server and all Nodes.

On the Server:

cd ~/sandfly-setup/setup
./clean_docker.sh

* Sandfly server is running on this system. Stopping...
727666a8a5ac
* Sandfly server stopped.
* Postgres is running on this system. Stopping...
waiting for server to shut down....
4f69e512b4ce
* Postgres server stopped.

* Done.

Untagged: quay.io/sandfly/sandfly:6.0.0
Deleted: sha256:49e804cb9fb43d88a7b62b0b4351b114b94fdf053ef050f3ad13f3066d485d9a
Deleted: sha256:ee213f8397dda0a7b5a3f337325653c8c2fcf80ea4c9d90d29be0a55d170b4ea
...
Untagged: postgres:18.4
Deleted: sha256:36e92b0342c51750d731d85ff4d759333d6827dd54f35e7039b5336b873d7168
Deleted: sha256:46ef34af46fa5ddeb5ed850d7891e9c33680966901e959f4efb637dd61c3a7a9
...
Total reclaimed space: 0B

On every host being used as a Node:

cd ~/sandfly-setup/setup
./clean_docker.sh

* Stopping node container 865c0500124e
865c0500124e
865c0500124e
* Stopping node container 3b9a82446aae
3b9a82446aae
3b9a82446aae

* Done.
...

A large list of container hashes will be displayed; once it is complete, the script will return to the command prompt. This indicates the script has completed and the containers have been removed.

Step 5: Run Start Scripts on Server and Nodes

On the Server and all Nodes, run the applicable start script. It will load the latest version of Sandfly and run it.

On the Server:

cd ~/sandfly-setup/start_scripts/
./start_sandfly.sh

*** Starting Postgres.
** Loading images from local archive:
** ../../docker_images/sandfly-docker-images-6.0.0.tgz
** There will be a slight delay before further output...
15f1c8eb1ab1: Loading layer  81.25MB/81.25MB
cc99cbebc90a: Loading layer  12.29kB/12.29kB
...
Loaded image: postgres:14.24
*** Moving Postgres 18 data to 18/docker within the volume

Based on 2 CPUs and 2014860kB total RAM, we will start
Postgres with the following settings:
...
Network 'sandfly-net' created successfully
Subnet: 172.18.0.0/16 Gateway: 172.18.0.1
Subnet: fd5d:be77:9dda::/64 Gateway: fd5d:be77:9dda::1

57d56ef332c3ed88f496d09642bb1666929c68a9b1bac324a4371d7582fe5216
*** Starting Sandfly Server.
...
Network 'sandfly-net' already exists:
Subnet: 172.18.0.0/16 Gateway: 172.18.0.1
Subnet: fd5d:be77:9dda::/64 Gateway: fd5d:be77:9dda::1

56d3d2b0fd387694469175e3f985403e3c0e778e566659f7534f5bccff5333bc

On every host being used as a Node, including when the Node is on the Server:

cd ~/sandfly-setup/start_scripts/
./start_node.sh

Network 'sandfly-net' already exists:
Subnet: 172.18.0.0/16 Gateway: 172.18.0.1
Subnet: fd5d:be77:9dda::/64 Gateway: fd5d:be77:9dda::1

c2d1ca4720cbef7da2da2a57259e672ac22666edbe276c40814d084660397a96

On the Node host(s), the start script can be run multiple times to start additional containers depending on the RAM and CPU capacity of the host.

Step 6: Verification

Run the docker ps command on the Server and Node(s) to verify all containers are running.

On the Server:

docker ps

CONTAINER ID   IMAGE                           COMMAND                  CREATED          STATUS          PORTS     NAMES
55d3d2b0cd38   quay.io/sandfly/sandfly:6.0.0   "/opt/sandfly/start_…"   32 seconds ago   Up 32 seconds   0.0.0.0:80->8000/tcp, [::]:80->8000/tcp, 0.0.0.0:443->8443/tcp, [::]:443->8443/tcp   sandfly-server
55d56ef338c3   postgres:18.6                        "docker-entrypoint.s…"   44 seconds ago   Up 44 seconds   5432/tcp   sandfly-postgres

On every host used as a Node:

docker ps

CONTAINER ID   IMAGE                           COMMAND                  CREATED          STATUS          PORTS     NAMES
553691952cc1   quay.io/sandfly/sandfly:6.0.0   "/opt/sandfly/start_…"   6 seconds ago    Up 6 seconds         happy_tornados                                                            
c2d8ca4720cc   quay.io/sandfly/sandfly:6.0.0   "/opt/sandfly/start_…"   8 seconds ago   Up 7 seconds         laughing_napier

You can now log back in to the UI. To confirm the version number and/or public keys, in the sidebar menu, select Settings > About Sandfly.

If the Server start script showed the note "Sandfly is using Postgres 14", see Upgrading PostgreSQL 14 to PostgreSQL 18.

Step 7: Resume Your Schedules

Finally, reactivate your previously enabled schedules, and Sandfly will resume from its previous state.

Upgrading PostgreSQL 14 to PostgreSQL 18 (Sandfly 6.0 and Later)

Installations that still use PostgreSQL 14 should upgrade the database to PostgreSQL 18 (see the v6.0.0 upgrade notes). To see which version your installation uses, check the Postgres Version field on the Settings > About Sandfly page.

We strongly recommend that you make a backup first (see the Backup and Restore Guide), because the PostgreSQL 14 data is deleted after a successful upgrade.

1. Shut down Sandfly on the Server:
   sandfly server

   cd ~/sandfly-setup/start_scripts/
   ./shutdown_sandfly.sh

2. Run the upgrade script, and confirm when it asks:
   sandfly server

   cd ~/sandfly-setup/setup/util_scripts/
   ./upgrade_postgres.sh

3. Start Sandfly again:
   sandfly server

   cd ~/sandfly-setup/start_scripts/
   ./start_sandfly.sh

If the upgrade fails, the database is restored to PostgreSQL 14 and Sandfly starts as before. If the upgrade is interrupted, the start script stops with an error; run upgrade_postgres.sh again to complete it.