Teams server

Introduction

This manual describes the installation, management, and interaction with the key server-side components of an IDA Teams deployment.

It is primarily intended for administrators, and will focus on the different servers that are part of IDA Teams:

The Hex-Rays Vault server
The Lumina server

While we will (at least superficially) make use of the command-line clients that are used to access/manage those servers, this manual will not offer a detailed explanation of their usage: there are dedicated documents for that (e.g., the hv user manual, the lc user manual, …).

Let’s get started

The first server to install, and the one that is at the center of an IDA Teams deployment, is the Hex-Rays Vault server.

It is recommended to have the hv user manual ready before proceeding.

Prerequisites

After your purchase of IDA Teams licenses, you have received an e-mail that contains links to a download area where you will find:

an installer for the IDA Teams server (also called the "Hex-Rays Vault server")
this guide
an installer for IDA
an ida.key

All those will be necessary, so please go ahead and download them.

You will also need root access on the host where you will be installing the server.

Installation

This chapter explains how to install two parts of IDA Teams: the vault server, and a client.

We recommend installing a client first, to be able to connect to the server immediately after installation. The very first user to connect to the server becomes the administrator.

Installing clients

There are 2 Hex-Rays Vault clients:

hv: a command-line client (which we’ll use in this document)
hvui: a GUI interface to the server

Vault clients are bundled with IDA Teams installers: simply run the IDA installer and follow the instructions. That will install IDA, and the 2 clients next to it.

Installing the server

The Hex-Rays Vault server can be installed on Linux servers. We have tested it on Debian and Ubuntu, but other major flavors of Linux should be fine too.

To install the server, run the Hex-Rays Vault installer as root and follow the instructions (the server will not require root permissions; only the installer does.)

If your Linux system is based on systemd (e.g., Debian/Ubuntu, Red-Hat, CentOS, …), it is recommended to let the installer create systemd units so that the server will start automatically at the next reboot.

Once the server is installed, it will be necessary to activate its license.

Activating the server license

In order for the Hex-Rays Vault server license to be activated, it must be bound to a Host ID (an Ethernet MAC address.)

From a command prompt, run /sbin/ifconfig, and lookup the "ether" address for the network interface through which the server will be accessible.

>/sbin/ifconfig
enp4s0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
        [...snipped...]
        ether bf:e2:91:10:58:d2  txqueuelen 1000  (Ethernet)
        [...snipped...]

In this case, our mac address is: bf:e2:91:10:58:d2

You will be able to activate both Hex-Rays Vault server and {lumsrv} in one activation if you have also the Host ID of your {lumsrv}.

Go to https://hex-rays.com/activate , and submit both the ida.key file and your MAC address. You will then receive another e-mail with instructions to download the following files:

hexvault.crt
hexvault.key
hexvault.lic

Those need to be copied in the Hex-Rays Vault installation directory. As root:

>cd /opt/hexvault
>cp .../path/to/hexvault.crt .
>cp .../path/to/hexvault.key .
>cp .../path/to/hexvault.lic .
>chown hexvault:hexvault hexvault.crt hexvault.key hexvault.lic
>chmod 640 hexvault.crt hexvault.key hexvault.lic

Creating the initial database

At this point, the server should be ready to run.

If your system is already in production and hosts files, skip this section. Using the --recreate-schema option as in the example below, will re-create an empty database and lose all history.

On the first install, you will need to initialize the database the server will use:

>sudo -u hexvault ./vault_server --config-file hexvault.conf \
                                 --vault-dir ./files \
                                 --recreate-schema
>2022-04-14 14:30:28 Vault Server v1.0 Hex-Rays (c) 2022-2024
>2022-04-14 14:30:28 Database initialized; exiting.

Testing the server

Now that the server is installed and has a database to work with, we can test that it works:

>sudo -u hexvault ./vault_server --config-file hexvault.conf \
                                 --certchain-file hexvault.crt \
                                 --privkey-file hexvault.key \
                                 --license-file hexvault.lic \
                                 --vault-dir ./files
>2022-04-14 14:35:47 Vault Server v1.0 Hex-Rays (c) 2022-2024
>2022-04-14 14:35:47 Using a license with 5 seats
>2022-04-14 14:35:47 Listening on 0.0.0.0:65433...

Good, the server appears to run! (If you are observing more worrying messages than this one, please refer to the troubleshooting section.)

At this point, you may want to either let the server run, or stop it (Ctrl+C will do) and restart it using systemd:

>systemctl restart hexvault.service

…and make sure it runs:

>ps aux | grep vault_server
hexvault  58246  0.0  0.0 ...

If you don’t see a running vault_server process, please refer to the systemd diagnostic tools (e.g., journalctl) for more info.

Initial configuration

This chapter explains how to perform the initial configuration of the vault server.

For the sake of the examples below, we’ll imagine the following fictional group of users:

Jane Smith, the department admin/IT head
Fred Bloggs, senior reverse engineer

In addition, we’ll assume:

the company name is Acme
the Hex-Rays Vault server has been installed on the company’s LAN, on the host hexvault.acme.com

Creating the administrator

The very first user to log into the server becomes the first administrator. S/he can create new administrators and otherwise manage the server.

Once the server is up and running, login to server using a username and password of your choice (hv is the vault client utility, it is installed as part of the client package.)

We will assume Jane installed IDA (and thus hv) in /home/jane/idateams

>cd /home/jane/idateams
>./hv -hhexvault.acme.com -ujane -psecr3t info

Hex-Rays Vault Server v1
Vault time: 2022-04-14 15:28:03, up since 2022-04-14 15:17:25
License user : Jane Smith, IDA Ultimate
License email: jane@acme.com
License: IDAULTTM; 1 users out of 5; expires on 2023-04-05
MAC address: xx:xx:xx:xx:xx:xx
Vault directory: /opt/hexvault/files
Client name: jane *ADMIN*
Client site:
Client host: 127.0.0.1
Client root:
Login time : 2022-04-14 15:28:03
Last active: 2022-04-14 15:28:03

Please note that there is no space between the command line switches and values.

Since Jane is the first user to login to the server, the credentials she provided, will be used to create the server’s primary administrator.

You can verify that you are the only user by checking the user list:

>./hv -hhexvault.acme.com -ujane -psecr3t users

LastActive Adm    Login       License          Email
---------- --- ------------ --------------- ------------
2022-04-14  *  jane          <>

You may also add information (like your real name) to your user record by issuing:

>./hv -hhexvault.acme.com -ujane -psecr3t user edit jane "Jane Smith" jane@acme.com 1 "" 48-XXXX-XXXX-XX
>./hv -hhexvault.acme.com -ujane -psecr3t users

LastActive Adm    Login       License          Email
---------- --- ------------ --------------- ------------
2022-04-14  *  jane         48-XXXX-XXXX-XX Jane Smith <jane@acme.com>

However, note that having to pass a user name, host name and a password on the command line each time will get very tedious very fast. The next chapter will show how we can make our lives easier.

hv credentials

In order to connect to the vault server, hv must at least have:

a username
a password
a hostname

For example:

$ hv -hhexvault.acme.com:65433 -uadmin -psecret users
LastActive Adm    Login        Email
---------- --- ------------ ------------
2022-06-27  *  admin
2022-06-22     alice       Alice <alice@acme.com>
Never          bob         Bob <bob@acme.com>
...

There are 3 ways to specify credentials (in decreasing order of priority):

providing them as command-line arguments (as in the example above)
storing them in environment variables
storing them in the registry+keychain (recommended)

All credentials, including usernames, are case-senstive, meaning that "Joe" and "joe" would be different users.

Command line

Passing credentials on the command line will always take precedence over environment variables and registry+keychain.

-uUSERNAME

specify username

-pPASSWORD

specify password

-hHOST

specify host (server:port) (if port is omitted, defaults to 65433)

-sSITENAME

specify site

--set

remember credentials. This option doesn’t require the credentials to be passed through the command line, credentials passed through environment variables will work as well

Environment variables

Credentials can also be passed through environment variables. They will take precedence over those possibly found in the registry+keychain.

VAULT_HOST