Upgrading the Enterprise Server

For Enterprise servers that have an active internet connection, the intended way to upgrade the server is via the install or update command in manage_server. Please see the documentation of those commands for more information.

If you have an offline installation, there are two choices. The first is to use the license recovery page on our website with the email address that has been registered to your Enterprise server license. This will cause a new set of download links to be sent to the email address we have on file. You will want to use the manage_server that came with the new bundle to install the images that were emailed to you and then start the server. Don't forget to copy over any extra Docker configuration overrides you might have made!

The second choice is to use an internet-connected machine to perform the install or update command, then use docker save to save each of the images that were downloaded. You can then copy the new version of manage_server and the images you saved to your offline machine as above. This method is more cumbersome, but preferable if you don't have access to the email account that the Enterprise server license is registered to.

Client Compatibility

In general, Binary Ninja assumes users will only change versions in a positive direction. This same assumption holds for Enterprise as well. While an older client or server may work with a newer client or server, we only test for and guarantee compatibility within a version pair.

These are the stable versions that are expected to work together and have been tested prior to release:

Client Version	Server Version
3.0.3233	1.0.174
3.1.3469	1.0.176
3.2.3814	1.1.162
3.3.4077	1.1.187
3.4.4271	1.2.264
3.5.4526	1.2.293
4.0.4911	1.2.308
4.1.5747	1.2.332
4.2.6455	1.2.342
5.0.7290	1.2.352
5.1.8005	1.2.359
5.1.8104	1.2.360

Note

If you are using clients from the dev channel, the above may not be guaranteed to be compatible. Generally speaking, we expect you to be running the latest version of the dev channel on both the client and the server to guarantee compatibility. We don't often break things (intentionally or otherwise), but when we do, it will come without warning.

If you encounter a problem with compatibility, and you are using a combination from the list above, please report it to us either via email (enterprise@vector35.com), GitHub, or Slack (if you've chosen to set up a support channel with us).

Updating Your License

Note

If you are using your own server.pem and server.key as described here, you should not replace either of those files with the ones provided by us.

If you just need to update your license (e.g. because you've extended support) or license bundle (e.g. because you've added more seats), simply:

1. Use the get_bundle command in the management interface or the license recovery page to obtain the new license files (license.dat and license-bundle.b64), server certificate (server.pem), and server key (server.key)
2. Stop the Enterprise server with ./manage_server stop (don't forget --swarm, if you've deployed in Swarm mode)
3. Overwrite the old files with the new ones
4. Start the Enterprise server again with ./manage_server start (don't forget any flags you might want, like --detach or --swarm)

When the server starts back up, it should seamlessly switch to the new licenses that have been provided and you should be back up and running.

Version-Specific Considerations

Occasionally, a change from an older version of Enterprise to a newer version has some caveats or extra required steps to follow. Please check the instructions below to see if any of these apply to your upgrade.

Enterprise 1.1 to 1.2+

Warning

We do not recommend upgrading a server before version 1.1 to version 1.2+. We highly recommend upgrading to the 1.1 series first. Not doing so may risk data loss.

Version 1.2 of the Enterprise server completely changed how we store your data. Instead of being stored in a Docker volume as a flat filesystem, data is now stored in a Minio block storage system. Additionally, we now run a script on start that ensures ownership and permissions of your files match the UID and GID that you have provided (these default to the user on the host that is running manage_server).

Because of these changes, you will need to run ./manage_server install twice. The first time you do, it will pull the new versions of the 4 original container images and the latest version of manage_server. The second time, it will pull the new object_store container image. If you are performing this update for an offline install, you can use the new get_bundle command instead of the second install if you prefer.

Because the first run of the new server may be applying new permissions to all of your existing files, the first run could take a significant amount of time depending on how many files there are. A message should be printed in manage_server logs from each container when this process starts and completes. The process is only run if permissions and ownership are not already set correctly to begin with.

The data migration should be completely, 100% automatic the first time you launch with a version 1.2+ container. In the extremely unlikely event that this didn't happen, the following should cause the migration to happen again:

1. Stop the Enterprise server with ./manage_server stop (don't forget --swarm, if you've deployed in Swarm mode)
2. Mount the data volume (something like docker run -v binaryninja_enterprise_data:/data ubuntu:latest will work if you're online, which will mount the volume into a new container at /data)
3. Remove the .object-migration file from the volume
4. Start the Enterprise server again with ./manage_server start (don't forget any flags you might want, like --detach or --swarm)

The data migration should start as soon as the backend and object_store containers come back up.

Enterprise 1.0 to 1.1+

Two major changes in the server were completed between these releases that may impact an upgrade:

1. The SQLite database was upgraded to a full PostgreSQL database hosted in a separate container.
2. The Docker service definition file template is now written to disk when the manage_server binary is run. Additionally, the install command is now aliased as update.

You should not have to do anything to address the first change: It should be detected and handled automatically during the upgrade. If it isn't, running the following command from within the backend container (using docker exec -it <CONTAINER_ID> /bin/sh) should complete the migration manually:

python manage.py migrate -v 0 --database legacy_sqlite

The second change should also not require you to do anything, but if the docker-compose.yml file is missing, running manage_server install again (remembering any parameters you need to specify) should ensure that it gets created.