Skip to content

Getting Started

There are currently two ways to install the Enterprise server: online and offline. We highly recommend using the online installation where possible.

Requirements

Host System

Your host will need to be a system that meets the that meets the minimum Docker system requirements. We officially test Enterprise server deployments on Ubuntu and, as a result, highly recommend you use a Debian-based host. Red Hat is also known to work, but with some additional configuration (and some caveats).

Danger

On Linux hosts, we also require a host system that has a glibc of 2.29+ to run the management interface (manage_server). This means we do not support versions of Red Hat below 9, versions of Ubuntu below 19.04, versions of Debian below 11, or other systems that do not have access to a newer version of glibc.

Resources

The Enterprise server itself is fairly lightweight on resource usage. We expect the following to be sufficient for most use-cases:

  • Minimum: 2 CPU cores, 4 GB of memory, 20 GB of disk space, 100 Mb/s network connection
  • Recommended: 4 CPU cores, 8 GB of memory, 200 GB of disk space, 1 Gb/s network connection

Warning

Disk space and network connection requirements will vary heavily based on usage. Some of our customers have required upwards of 2-4 TB of space for large datasets or for smaller datasets over long periods of time. If you have chosen your initial deployment poorly, don't worry! We provide ways to migrate your data with a backup and restore.

Dependencies

Before installing and hosting the Enterprise server, you'll need the following:

  • Docker Engine version 19.03.0+
  • Docker Compose version 1.27.0+
    • Newer versions of Docker Desktop (version 3.2.1+) contain this functionality by default. If you are running a newer version of Docker that contains the compose command, you do not need to install Docker Compose separately.
  • A valid Binary Ninja Enterprise server license

Note

Beta support for deploying with Podman and podman-compose instead of Docker was added in our 3.4 release. You'll just need to use CONTAINER_ENGINE=podman manage_server for every command. We'll be making this more user-friendly in a future release when we move this feature out of beta.

Warning

We do not currently support other Docker alternatives like Kubernetes due to how heavily we rely on Docker Compose functionality. You may be able to generate a pod definition from podman, but this is completely untested and unsupported at this time.

Alternative container runtimes for Docker like RailCar should theoretically work fine, but have also not been tested and are not officially supported.

Connectivity

If you have any exisiting firewall rules in place, see the firewall section below for what should be required if you are having problems.

Installation

Note

The instructions below were written with the assumption that you will be deploying with Docker Compose using default settings. Please see the Customizing Docker Deployment documentation if you would like to customize aspects of your deployment such as using an external database, object store, etc.

Online Install

Extract manage_server, license.dat, and license-bundle.b64 to a new folder.

Then, run the following for an online installation:

# installs Docker, then installs the Enterprise server
sudo apt update && \
sudo apt install -y containerd docker.io docker-compose-v2 && \
./manage_server install

This will authenticate to our private Docker registry with your Enterprise server license, download the Enterprise server Docker images, and install the remaining required files:

  • Files in the keys directory are used for server verification (and can be replaced to customize SSL)
  • Files in the secrets directory are the newly generated credentials and identifiers for your server

Note

If you would like to use ARM64 images (e.g. if hosting on newer Apple hardware), pass the DOCKER_DEFAULT_PLATFORM=linux/arm64 environment variable when running ./manage_server install.

Warning

It is very important that server.key file is kept secret. Anyone with access to the contents can decrypt traffic to/from the server.

Offline Install

Assuming you have a local, offline package repository your host can pull from, the offline install process is identical to the online install process with the addition of an --offline switch to the end of the ./manage_server install command. If that isn't the case, please substitute the equivalent process you use for installing these packages (e.g. sudo dpkg -i) below:

# installs Docker, then installs the Enterprise server
sudo apt update && \
sudo apt install -y containerd docker.io docker-compose-v2 && \
./manage_server install --offline

This will unpack and install the necessary Docker images to run the Enterprise server. The license file above is the license.dat you received in the installation bundle. The required keys directory, server.key, and server.pem should already be present in your installation bundle as well.

Warning

It is very important that server.key file is kept secret. Anyone with access to the contents can decrypt traffic to/from the server.

Starting the Server

To start the server with default options, run ./manage_server start. You may need to specify some additional CLI switches if:

  • You need to run the server on a different port (-p <PORT>). This is usually only necessary if port 3535 is already occupied on your host or if port 3535 is blocked by a firewall between the Enterprise server and the Enterprise client.
  • You want to turn on host validation (--allowed-host <HOST>). This can be useful, in addition to firewall rules, if you intend to run the Enterprise server on the internet (which is not recommended).
  • You want to run in Swarm mode (--swarm[=STACK_NAME]).

For the first run, you will probably not want to use the --detach command, so you can see the auto-generated credentials. But, the option is highly recommended for subsequent runs so it will remain in the background and not be attached to your terminal.

Getting Your Credentials

When the server starts up, it will print auto-generated credentials to the terminal as part of the initial start. These should be in the first 20-30 lines of output and look something like this:

backend_1  | Successfully created admin user
backend_1  | Please log in and change the admin's email and password
backend_1  | Username: admin
backend_1  | Email: admin@localhost
backend_1  | Password: sMb8IadGOxFnXuGk
backend_1  | Successfully imported 3 licenses

Note

If you used the --detach CLI switch on your initial run, you can view the logs with ./manage_server logs and retrieve the auto-generated password that way.

Changing Your Credentials

If you want to change the admin credentials at this point, there are two options:

  1. Run ./manage_server change_password and specify new credentials
  2. Log in to https://your_host:3535/admin with your credentials and use the CHANGE PASSWORD link
    • Remember that the port may be different if it was explicitly set in step 1.

Testing Server Connectivity

At this point, the Enterprise server should be up and running. You should be able to log into the admin interface (at https://your_host:3535/) and connect an Enterprise client with the admin user and password from above. If one or both of these does not work, you'll want to troubleshoot that now before continuing. Checking the logs (which should either already be in your terminal, or available through ./manage_server logs) is the recommended place to start.

(Optional) Restart the Server

If you previously launched the server without the --detach flag, you may want to re-launch it now. A single Ctrl-C should stop the server gracefully. You can then re-launch it with ./manage_server start --detach (don't forget any other CLI flags you used previously!) and it will continue running in the background. If you need to stop the server at any point in the future, see the ./manage_server stop command.

Additional Configuration

At this point, your Binary Ninja Enterprise server is 100% functional and ready to use. There are, however, a few additional configuration options you may want to consider.

(Optional) Firewall Rules

The Enterprise server requires authentication and has some limited functionality for disallowing connections outside of specified IP addresses (with the --allow-host flag on the ./manage_server start command). It does not, however, have any more complicated methods of dealing with traffic. So, you may want to add firewall rules to control input to the Enterprise server host further.

The Enterprise server and clients do not require internet connectivity and can function in a completely offline environment. But, if you would like to use online updates from our servers, you will need to ensure they can access the following over HTTPS (port 443):

  • registry.enterprise.binary.ninja (server only)
  • Used for pulling updated docker images for the server containers
  • master.binary.ninja (client and server)
  • Used by clients to check if there are any available updates (unless the clients are configured to use the enterprise server for updates)
  • Used by the server to pull client updates, as well as server management binary updates
  • cdn.binary.ninja (client only)
  • Serves update files for clients
  • extensions.binary.ninja (client only)
  • Used to fetch official (made by v35) plugin info
  • github.com (client only)
  • Used to fetch community plugin info, as well as download community and official plugins

The Enterprise server and client themselves talk over HTTPS (port 3535 by default) and use web sockets for real-time, asynchronous communication (like chat and user positions). These will need to be allowed through any firewalls or WAFs or this functionality will not work.

Finally, if you configure any Single Sign-On (SSO) endpoints (see below) or webhooks, the server and clients will require access to those hosts, too, generally over HTTPS (usually port 443).

(Optional) Custom SSL Certificate

If you would like to use an SSL certificate other than the one we provide, see the configuration section on adding a Custom SSL Certificate. Or, you can run the Enterprise server behind a proxy (see below) that handles TLS for you.

(Optional) Add a Forward Proxy

See this page for an example of configuring Binary Ninja to work behind the Traefik proxy.

(Optional) Email Setup

In order for users to be able to use the self-service "Forgot Password" functionality, you'll need to configure the email settings in the web-based admin interface.

(Optional) Single Sign-On (SSO) Setup

In order for users to be able to use a Single Sign-On (SSO) provider (LDAP, OAuth2, OpenID Connect) to authenticate to the server with their client, you will need to set up SSO.

(Optional) Local Updates

If you would like to host Binary Ninja Enterprise client updates on your local Enterprise server, please see this page. This is incredibly useful if you're hosting the server on a network without internet access or have a lot of clients that are on the same network as the Enterprise server.

Note

Clients will need to check the "Use Enterprise Server For Updates" option in the "Updates" section of the Settings window within Binary Ninja to switch to using the Enterprise server for updates.