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.
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
:
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:
Testing the server
Now that the server is installed and has a database to work with, we can test that it works:
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:
…and make sure it runs:
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
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:
You may also add information (like your real name) to your user record by issuing:
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:
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