Skip to content

Upgrading the Enterprise Server

The best way to upgrade your Enterprise server will depend partly on how it was installed. Please see the appropriate section below for your installation.

Warning

Please also be advised that there may be limitations on what client versions can access your server. See the Client Compatibility section below for more information.

Online Upgrade

For Enterprise servers that have an active internet connection:

  1. Run manage_server update
  2. Run manage_server start

See the documentation for both commands for more information. Don't any required command-line switches based upon your configuration.

Note

An updated copy of the Enterprise server can also be obtained via the Binary Ninja license recovery page or the Binary Ninja customer portal.

Offline Upgrade

There are three different ways of upgrading an offline Enterprise server installation. All should end up in the same place, so which you choose is simply a matter of preference.

Using License Recovery

The first choice is to use the Binary Ninja license recovery page to get an updated copy of the Enterprise server sent to the registered email address. Once you fill out and submit the form:

  1. Download the binaryninja_enterprise_server.zip matching your server's host platform.
  2. Download the images.tar matching your server's host architecture.
  3. Move these files to the offline host.
  4. Replace manage_server with the one from the .zip
    • Remember to ensure this is owned by the correct user and is executable for them!
    • On macOS, you may need to use xattr -d com.apple.quarantine ./manage_server if it refuses to execute because it is a downloaded file.
  5. Use manage_server update --offline to perform the update.
    • If images.tar is not in the current directory, you may need to specify its location with -i <path/to/images.tar>.
  6. Re-start the server with manage_server start.
    • Don't forget any flags you might need to specify the port or other configuration you might need!

Using Customer Portal

The second choice is to log into the Binary Ninja customer portal to download an updated copy of the Enterprise server if the license is assigned to you:

  1. Log into the Portal.
  2. Click the license in the License Summary (or within the Manage Licenses page).
  3. Download the binaryninja_enterprise_server.zip matching your server's host platform.
  4. Download the images.tar matching your server's host architecture.
  5. Move these files to the offline host.
  6. Replace manage_server with the one from the .zip
    • Remember to ensure this is owned by the correct user and is executable for them!
    • On macOS, you may need to use xattr -d com.apple.quarantine ./manage_server if it refuses to execute because it is a downloaded file.
  7. Use manage_server update --offline to perform the update.
    • If images.tar is not in the current directory, you may need to specify its location with -i <path/to/images.tar>.
  8. Re-start the server with manage_server start.
    • Don't forget any flags you might need to specify the port or other configuration you might need!

Using manage_server

The third choice is to use manage_server on an internet-connected machine to update and download the new images for you. This is most helpful in the situation where you aren't the 'owner' of the license of the server, and thus can't use the previous two options.

You will, however, need a copy of the Enterprise server license or manage_server will not be capable of authenticating to download the updates.

To do this:

  1. On the internet-connected host, run manage_server update, which will update manage_server itself and download the new server images.
  2. Use manage_server get_bundle to download all of the files required for offline deployment.
  3. Move enterprise_bundle.tar to your offline host and un-tar it, which should create an enterprise_server folder with all of the required files.
  4. Replace manage_server with the one from the enterprise_server folder from step 3.
    • Remember to ensure this is owned by the correct user and is executable for them!
    • On macOS, you may need to use xattr -d com.apple.quarantine ./manage_server if it refuses to execute because it is a downloaded file.
  5. Use manage_server update --offline -i <path/to/images.tar> to perform the update (images.tar should be inside the enterprise_server folder from step 3).
  6. Re-start the server with manage_server start.
    • Don't forget any flags you might need to specify the port or other configuration you might need!

Client Compatibility

Binary Ninja assumes users will typically 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) or GitHub.

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):

  1. Use one of the online or offline upgrade methods above 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. Re-start the Enterprise server with manage_server start (again, 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 need 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.