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:
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:
- Download the
binaryninja_enterprise_server.zip
matching your server's host platform. - Download the
images.tar
matching your server's host architecture. - Move these files to the offline host.
- 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.
- 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>
.
- If
- 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:
- Log into the Portal.
- Click the license in the License Summary (or within the Manage Licenses page).
- Download the
binaryninja_enterprise_server.zip
matching your server's host platform. - Download the
images.tar
matching your server's host architecture. - Move these files to the offline host.
- 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.
- 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>
.
- If
- 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:
- On the internet-connected host, run
manage_server update
, which will updatemanage_server
itself and download the new server images. - Use
manage_server get_bundle
to download all of the files required for offline deployment. - Move
enterprise_bundle.tar
to your offline host and un-tar
it, which should create anenterprise_server
folder with all of the required files. - Replace
manage_server
with the one from theenterprise_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.
- Use
manage_server update --offline -i <path/to/images.tar>
to perform the update (images.tar
should be inside theenterprise_server
folder from step 3). - 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):
- Use one of the online or offline upgrade methods above to obtain the new license files (
license.dat
andlicense-bundle.b64
), server certificate (server.pem
), and server key (server.key
) - Stop the Enterprise server with
manage_server stop
(don't forget--swarm
, if you've deployed in Swarm mode) - Overwrite the old files with the new ones
- 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:
- Stop the Enterprise server with
./manage_server stop
(don't forget--swarm
, if you've deployed in Swarm mode) - 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
) - Remove the
.object-migration
file from the volume - 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:
- The SQLite database was upgraded to a full PostgreSQL database hosted in a separate container.
- The Docker service definition file template is now written to disk when the
manage_server
binary is run. Additionally, theinstall
command is now aliased asupdate
.
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.