License ActivationLoading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The Linux installer is a self-unpacking binary. You may need to set file permissions to executable before running it:
lmadmin or lmgrd require LSB support installed:
If you decided to use 'lmgrd' instead of 'lmadmin', in addition you will have to:
The Linux installer does not configure the server to start automatically. If your distribution uses SysV style init, check the [install_dir]/examples/service/lmadmin script. For a systemd service script example, check [install_dir]/examples/systemd/
If you used 'lmgrd' instead of 'lmadmin' (and thus don't have the examples/ directory), you can find an example SysV-style script here and systemd-style script here.
See also "Installing lmadmin License Server Manager as an Operating System Service" in the License Administration Guide.
This manual describes the installation, management, and interaction with an on-the-premises IDA Pro Lumina server.
It is primarily intended for administrators, and will focus on the Lumina server component, that can be purchased for IDA Pro.
While we will (at least superficially) make use of the lc command-line client that is used to access/manage the server, this manual will not offer a detailed explanation of its usage: that is the role of the lc user manual.
We recommend having the lc user manual ready before starting the installation and configuration of the Lumina server.
you have received an e-mail that contains links to a download area where you will find, among other things:
an installer for the Lumina server
this guide
a lumact.key
ida.key and lumact.key may contain the same licenses information.
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 Lumina server (to install the server, not to run it).
The Lumina server stores its data in a MySQL DBMS server. It is therefore necessary to have valid credentials to such a server, as well as a fresh, empty database.
For illustration purposes, let’s assume the MySQL database the server will use, is called: "lumina_db".
At installation-time, the Lumina server installer will need information about the MySQL instance the Lumina server will be using (host, port, username, password). Eventually, that information will end up in the lumina.conf file, sitting next to the lumina_server_pro binary:
The Lumina 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 {lumina} 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.
In order for the Lumina 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
lumina.crt
lumina.key
lumina.lic
Those need to be copied in the {lumina} installation directory. As root:
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 data.
For the Lumina server to work, it needs to have a proper database schema to work with (at this point, the MySQL database (i.e., "lumina_db") must already exist but is still empty.)
That is why, on the first install, you will need to initialize the database the server will use:
Now that the server is installed and has a database to work with, we can test that it works:
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 lumina_server_pro process, please refer to the systemd diagnostic tools (e.g., journalctl) for more info.
This chapter explains how to perform the initial configuration of the Lumina server, and in particular how to create the
first (i.e., "administrator") user.
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 it using a username and password of your choice using the lc utility.
lc is the Lumina command-line administration client, which comes with the Lumina server installer. We will assume the server has been installed in /opt/lumina/, and thus lc is present in /opt/lumina/lc.
Since Alice 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:
To facilitate using lc, you may consider defining the following environment variables:
After that, you can connect to the server effortlessly. For example, this command will print information about the server and the client:
The following files shouldn’t be readable by everyone on the system, but only by root and lumina:
lumina.conf: this file file holds the connection string to the database the server will use, and might contain credentials.
lumina.crt: the certificate chain
lumina.key: the private key file
lumina.lic: the license file
As a precaution, the Lumina server will refuse to start if these files are readable by unauthorized users.
Please make sure they:
have lumina:lumina ownership: chown lumina:lumina lumina.crt lumina.key lumina.lic lumina.conf
are not world-accessible: chmod 640 lumina.crt lumina.key lumina.lic lumina.conf
Before the first --recreate-schema command can succeed, it is necessary to create the MySQL database, as well as the user that it will be accessed as.
Some recent Linux distributions ship versions of MySQL that use the "caching_sha2_password" password-checking plugin (as opposed to the traditional "native password" one.)
In order for the Lumina server to able to use this strategy, it would have to ship with a libmysqlclient.so file that is linked against libssl.so.3.
Unfortunately, this library is not yet available on all of the various [versions of] distributions that we currently support, and introducing this dependency would significantly reduce the diversity of platforms on whith the Lumina server can run.
Consequently (for now) we have opted for another approach: the "lumina" MySQL user should use MySQL's "native password" strategy. This can be accomplished by issuing the following command in a MySQL prompt:
Once libssl.so.3 is more generally available, {lumina} will not require this particular fine-tuning anymore.
What follows is an example creating a user + database, on a Debian system:
The Lumina server cannot create its schema due to a particularly stringent limit on "index prefix sizes" in older versions of MySQL.
This limit was increased in MySQL version 5.8, and thus this is the minimum version the Lumina server can work with.
In this case, edit the configuration file, by default /opt/lumina/lumina.conf and replace Server=localhost by Server=127.0.0.1 in CONNSTR.
The Lumina server is a "functions metadata" repository.
It is a place where IDA users can push, and pull such metadata, to ease their reverse-engineering work: metadata can be extracted from existing projects, and re-applied effortlessly to new projects, thereby reducing (sometimes dramatically) the amount of time needed to analyze binaries.
The Lumina server associates "function metadata" to functions, by means of a (md5) hash of those functions: whenever it wants to push information to, or pull information from the server, IDA will first have to compute hashes of the functions it wants to retrieve metadata for, and send those hashes to the Lumina server.
Similarly, when IDA pushes information to the Lumina server, it will first compute hashes for the corresponding functions, extract the metadata corresponding to those from the .idb file, and send those hash+metadata pairs to the server.
Metadata about functions can include:
function name
function address
function size
function prototype
function [repeatable] comments
instruction-specific [repeatable] comments
anterior/posterior (i.e., "extra") comments
user-defined "stack points" in the function’s frame
the function frame description and stack variables
instructions operands representations
When a user pushes metadata about a function whose md5 hash isn’t present in the database, the Lumina server will simply create a new record for it.
However, when a user pushes metadata about a function whose md5 hash (and associated metadata) is already present in the database, the Lumina server will attempt to "score" the quality of the old metadata and the quality of the new metadata. If the score of the new metadata is higher, the new function metadata will override the previous one.
When a user asks IDA to push all functions to the Lumina server, IDA will automatically skip some functions: those that still have a "dummy" name (e.g., sub_XXXX), or that are below a certain size threshold (i.e., 32 bytes) will be ignored.
The Lumina server retains a history of the metadata associated to functions. Using the lc utility, it is possible to dig into that history, and view changes (detailed diffs, too.)
It’s worth pointing out that when pushing metadata to the Lumina server, IDA will not push the binary file itself. Only the following metadata about the file itself will be sent:
the name of the input file
the name of the IDB file
a md5 hash of the input file
The Lumina server cannot therefore be used as a backup/repository for binary files & IDBs
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, …).
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.
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.
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.
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.
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.
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}.
hexvault.crt
hexvault.key
hexvault.lic
Those need to be copied in the Hex-Rays Vault installation directory. As root:
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:
Now that the server is installed and has a database to work with, we can test that it works:
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.
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
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.
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)
All credentials, including usernames, are case-senstive, meaning that "Joe" and "joe" would be different users.
Credentials can be stored in the registry (and keychain) like so:
For this operation to succeed, at least a user and host must be provided
Once that is done, commands will become cleaner:
To be able to connect to the vault server, users need to be added to the server. That can be done with the user add command:
Then, we need to set the user’s password, using the passwd command:
To facilitate user management, sometimes it makes sense to make user groups. All users of a group then can be granted or denied access to certain files on the server.
Let’s add a few groups:
Using the groups command, we can see the new groups are still empty:
We can now add group members:
This chapter explains in detail how to perform regular administrator tasks.
If you want to limit access to the files that will be stored on the vault server, you can specify who can access what. By default, the permission table grants all users access to all files:
You will need to prepare a new permission table and put it into a file. The permission table consists of lines with the following format:
where:
ACTION one of "grant" or "deny"
CATEGORY one of "user" or "group"
WHO name of the user or group to match
PERM one of "list", "read", "write"
PATH path pattern that the rule is for
Below is a sample permission table:
We’ll assume the server has been in use for a while, and holds some files in the directories subdir-for-fred/, local-secret/, and subdir/for/idbs/.
The permissions have the following order:
Adding the read permission also adds the list permission.
Adding the write permission also adds the list and read permissions.
Removing the read permission also removes the write permission.
Removing the list permission also removes the read and write permissions.
Once the permission table is ready and stored in a file, we can install it:
After setting the permissions, it is a good idea to verify them. For example, this is how we can get a full list of files that fred can see, with the rw or r- prefixes, depending on the permissions:
Or we could limit our check to a particular file:
The empty output means that fred cannot see local-secret even though it exists.
Currently, there is no dedicated procedure to back up the vault contents. It can be done by temporarily stopping the vault server and making a copy of the sqlite3 database as well as the files. The server must be stopped only during the backup of the sqlite3 database and then can be immediately restarted. It is ok to let the server run when making copies of the vault files. In the worst case some additional files will get copied in the backup, which normally will not cause problems. Since we never modify vault files but always create new revisions, there is no danger of copying inconsistent data.
Alternatively, it is possible to use sqlite3 backup functionality to make a backup of the database. Vault files can be copied using any Linux command (e.g. rsync or tar).
Switching to the newest versions of the Hex-Rays Vault server is recommended in order for the team to benefit from its improvements and new features.
The upgrade procedure consists of the following steps:
stopping the server. E.g., sudo systemctl stop hexvault if you are using systemd to manage the server.
putting the new server instead of the old one
restarting the server. E.g., sudo systemctl start hexvault
In this case, the server complains that the database schema is outdated. This may happen as we will keep improving the Hex-Rays Vault server, and new versions might require an upgrade of the database schema in order to be able to work correctly.
Note that the Hex-Rays Vault server will not perform that upgrade automatically. That is on-purpose, to give you a chance to backup the database before proceeding.
Let’s tell the server to upgrade to the latest schema:
Once this is done, you should be able to restart the server in a normal way, and resume work.
We plan to introduce additional functionalities like:
obliteration of files
periodic vault self-verification
periodic backups
usage stats
This chapter explains how to solve typical problems with the vault server.
By default, the vault server listens on the TCP port 65433 on all interfaces. Please ensure that this port is enabled in your firewalls.
The vault server uses secure TLS connections with the clients. The TLS layer requires the certificate (.crt) and private key (.key) files. Usually, they are attached to the email message with the activation information.
A lost admin password can be reset by following these steps:
Stop the running server
Launch the server with the --set-admin command line switch
Start the server
In practice it may look like this:
The uppercase USERNAME and PASSWORD placeholders should be replaced by the desired values. The user name and the password are separated by a colon.
The specified user must exist. If sh/e was not an admin before, s/he will be promoted to an admin by this command.
If you do not know any valid users of the vault, use the sqlite3 command line utility to list the users. They are stored in the users table.
The following command:
can be used to retrieve MD5 checksums of the specified files.
PATH path pattern to retrieve checksums from
REVISION optional file revision. If not specified, the checksum of the last revision is reported
The following files shouldn’t be readable by everyone on the system, but only by root and hexvault:
hexvault.conf: this file file holds the connection string to the database the server will use, and might contain credentials.
hexvault.crt: the certificate chain
hexvault.key: the private key file
hexvault.lic: the license file
As a precaution, the Hex-Rays Vault server will refuse to start if these files are readable by unauthorized users.
Please make sure they:
have hexvault:hexvault ownership: chown hexvault:hexvault hexvault.crt hexvault.key hexvault.lic hexvault.conf
are not world-accessible: chmod 640 hexvault.crt hexvault.key hexvault.lic hexvault.conf
There are no special precautions to take: restoring the sqlite3 database and vault files from a backup should be enough.
In addition to the Hex-Rays Vault server, IDA Teams users can make use of a private, on-the-premises Lumina server (unlike the Hex-Rays Vault server, the Lumina server isn’t a strictly necessary component of an IDA Teams deployment.)
A Lumina server will have to be configured to point to the Hex-Rays Vault server
After your purchase of IDA Teams licenses, you have received an e-mail that contains links to a download area where you will find, among other things:
an installer for the Lumina server
this guide
a lumact.key , if you didn’t activate Lumina server during the Hex-Rays Vault server activation
lumina.crt, lumina.key and lumina.lic you recieved during the activation of Lumina server with Hex-Rays Vault server
ida.key and lumact.key may contain the same licenses information.
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 Lumina server (to install the server, not to run it).
The Lumina server stores its data in a MySQL DBMS server. It is therefore necessary to have valid credentials to such a server, as well as a fresh, empty database.
The Lumina server requires a MySQL server version 5.8 or newer.
For illustration purposes, let’s assume the MySQL database the server will use, is called: "lumina_db".
In an IDA Teams setup, the Lumina server must have access to a running Hex-Rays Vault server in order to work: indeed, all user management is done through the Hex-Rays Vault server.
Please make sure the Hex-Rays Vault server is properly installed & running.
At installation-time, the Lumina server installer will need information about the MySQL instance the Lumina server will be using (host, port, username, password). Eventually, that information will end up in the lumina.conf file, sitting next to the lumina_server_teams binary:
In addition to information about the MySQL database in which the Lumina server will store the metadata, the installer asks for the host+port pair where to find a running Hex-Rays Vault server to which user authentication will be delegated.
That information will also end up in the lumina.conf file:
The Lumina 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 Lumina 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.
If you already requested Lumina server activation with Hex-Rays Vault server, you can skip this part.
In order for the Lumina 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
lumina.crt
lumina.key
lumina.lic
Those need to be copied in the Lumina installation directory. As root:
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 data.
For the Lumina server to work, it needs to have a proper database schema to work with (at this point, the MySQL database (i.e., "lumina_db") must already exist but is still empty.)
That is why, on the first install, you will need to initialize the database the server will use:
If you see "Error: Cannot connect to lumina db" please refer to troubleshooting section.
Now that the server is installed and has a database to work with, we can test that it works:
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 lumina_server_teams process, please refer to the systemd diagnostic tools (e.g., journalctl) for more info.
Hex-Rays Vault authentication
The Lumina server delegates authentication to the Hex-Rays Vault server. That is where the primary source of users information is located.
Consequently, it is the exact same set of users, with the exact same credentials as those that are able to use the Hex-Rays Vault server, that will be able to make use of the Lumina server.
Assuming Alice was registered in the Hex-Rays Vault server (and has admin rights), she should be able to use the lc utility to perform operations on the Lumina server.
lc is the Lumina command-line administration client, which comes with the Lumina server installer. We will assume the server has been installed in /opt/lumina/, and thus lc is present in /opt/lumina/lc.
"shadow" copy of users in the Lumina server
Although the authority for user management & authentication is the Hex-Rays Vault server, the Lumina server will need to "shadow" that information for its own database to be in a coherent state.
Every time a user opens a new connection to the Lumina server it will in turn perform a call to the Hex-Rays Vault server to authenticate the user against the provided credentials.
Depending on the success of that latter call, a "shadow" of the user will be recorded, updated, or deleted from the Lumina server’s database.
Not everything is copied to the Lumina server’s shadow users table; in particular, the password hash isn’t.
Useful environment variables
To facilitate using lc, you may consider defining the following environment variables:
After that, you can connect to the server effortlessly. For example, this command will print information about the server and the client:
Lumina server command-line options
The server complains about a "world-accessible" file, and exits
The following files shouldn’t be readable by everyone on the system, but only by root and lumina:
lumina.conf: this file file holds the connection string to the database the server will use, and might contain credentials.
lumina.crt: the certificate chain
lumina.key: the private key file
lumina.lic: the license file
As a precaution, the Lumina server will refuse to start if these files are readable by unauthorized users.
Please make sure they:
have lumina:lumina ownership: chown lumina:lumina lumina.crt lumina.key lumina.lic lumina.conf
are not world-accessible: chmod 640 lumina.crt lumina.key lumina.lic lumina.conf
MySQL
Before the first --recreate-schema command can succeed, it is necessary to create the MySQL database, as well as the user that it will be accessed as.
"Authentication plugin 'caching_sha2_password' cannot be loaded"
Some recent Linux distributions ship versions of MySQL that use the "caching_sha2_password" password-checking plugin (as opposed to the traditional "native password" one.)
In order for the Lumina server to able to use this strategy, it would have to ship with a libmysqlclient.so file that is linked against libssl.so.3.
Unfortunately, this library is not yet available on all of the various [versions of] distributions that we currently support, and introducing this dependency would significantly reduce the diversity of platforms on whith the Lumina server can run.
Consequently (for now) we have opted for another approach: the "lumina" MySQL user should use MySQL’s "native password" strategy. This can be accomplished by issuing the following command in a MySQL prompt:
Once libssl.so.3 is more generally available, Lumina will not require this particular fine-tuning anymore.
MySQL TLS connections
For the same reasons as the caching_sha2_password issue, the Lumina server does not use TLS connections and thus will negociate a plain TCP connection to the MySQL server.
Creating the user and database
What follows is an example creating a user + database, on a Debian system:
"Index column size too large. The maximum column size is 767 bytes."
The Lumina server cannot create its schema due to a particularly stringent limit on "index prefix sizes" in older versions of MySQL.
This limit was increased in MySQL 5.8, and thus this is the minimum version the Lumina server can work with.
"Error: Cannot connect to lumina db"
In this case, edit the configuration file, by default /opt/lumina/lumina.conf and replace Server=localhost by Server=127.0.0.1 in CONNSTR.
The Lumina server is a "functions metadata" repository.
It is a place where IDA users can push, and pull such metadata, to ease their reverse-engineering work: metadata can be extracted from existing projects, and re-applied effortlessly to new projects, thereby reducing (sometimes dramatically) the amount of time needed to analyze binaries.
While the workflow with the Hex-Rays Vault server and associated tools (hv, hvui and IDA’s diff/merge modes) are extremely powerful for working on multiple revisions of the same binaries, the Lumina server in turn eases the replication of past efforts to new projects.
In effect, the Lumina server offers another "dimension" to collaborative reverse-engineering efforts.
The Lumina server associates "function metadata" to functions, by means of a (md5) hash of those functions: whenever it wants to push information to, or pull information from the server, IDA will first have to compute hashes of the functions it wants to retrieve metadata for, and send those hashes to the Lumina server.
Similarly, when IDA pushes information to the Lumina server, it will first compute hashes for the corresponding functions, extract the metadata corresponding to those from the .idb file, and send those hash+metadata pairs to the server.
Metadata about functions can include:
function name
function address
function size
function prototype
function [repeatable] comments
instruction-specific [repeatable] comments
anterior/posterior (i.e., "extra") comments
user-defined "stack points" in the function’s frame
the function frame description and stack variables
instructions operands representations
When a user pushes metadata about a function whose md5 hash isn’t present in the database, the Lumina server will simply create a new record for it.
However, when a user pushes metadata about a function whose md5 hash (and associated metadata) is already present in the database, the Lumina server will attempt to "score" the quality of the old metadata and the quality of the new metadata. If the score of the new metadata is higher, the new function metadata will override the previous one.
When a user asks IDA to push all functions to the Lumina server, IDA will automatically skip some functions: those that still have a "dummy" name (e.g., sub_XXXX), or that are below a certain size threshold (i.e., 32 bytes) will be ignored.
The Lumina server retains a history of the metadata associated to functions. Using the lc utility, it is possible to dig into that history, and view changes (detailed diffs, too.)
It’s worth pointing out that when pushing metadata to the Lumina server, IDA will not push the binary file itself. Only the following metadata about the file itself will be sent:
the name of the input file
the name of the IDB file
a md5 hash of the input file
The Lumina server cannot therefore be used as a backup/repository for binary files & IDBs (that would be the role of the Hex-Rays Vault server)
A site represents a mapping of the server files to the local filesystem. Normally each computer has a site associated with it. A site has the following attributes:
A site name
A host name
The path to a folder on the filesystem (a.k.a., "root directory")
Path filters (optional)
Root directory
The root directory is the essential attribute of a site. It denotes where all files from the vault server will be mapped to the local disk. Everything inside the root directory can potentially be uploaded to the vault server and shared with other team members.
The vault server cannot manage files located outside the root directory. However, this limitation is straightforward to overcome: create a symbolic link (or, on Windows, a junction point) from the root directory to the directory of your choice. This will make the target of the symbolic link visible as part of the root directory.
The vault server keeps track of each site’s state: what files have been downloaded to the local disk, what files have been checked out for editing, etc. This simplifies the housekeeping tasks, especially for big repositories with millions of files. Even for them, downloading the latest files or reconciling the local disk with the server, are almost instantaneous.
The host name is a security feature that prevents from using a site on a wrong computer. Since the server keeps track of the files downloaded to each site, using a wrong site may lead to an inconsistent mapping between the server and local disk. However, if the user does not want this protection, it is possible to erase the host name in the site definition.
Sites can be edited from the "Sites" view.
Path filters
By default all server files are visible, but for servers that manage gigabytes of data this can be problematic: it may be undesirable for users to download all files to their local computer.
Site filters provide a mechanism that lets users restrict the set of files their IDA Teams client works with. Users who want to work on some specific projects can set a filter that restricts the visibility only to selected subdirectories.
Each site has its own filters, that con be modified at any time. Filters do not directly affect any files on the local disk, or on the server: they are strictly about visibility.
Site filters are meant simplify a user’s life by letting them focus on specific projects. Since they can be modified by users, they should not be considered a security measure: that would be the role of the permissions system, which can only be managed by Hex-Rays Vault server administrators.
The purpose of site filters is to create a subset of the full set of files provided by the server. Site filters don’t directly affect what locally-available files (i.e., present in the site’s rootdir, but not tracked by the server) are visible by IDA Teams clients.
There is another mechanism to specify what files should not be added to the vault. See .hvignore for more info.
Examples
An empty filter
Hide all files, except those in malware/
Show all files, except those from the pentesting team
Show all files but those from the pentesting team, except their produced documents
On Microsoft Windows, IDA Teams will store certain bits of information in the registry (host name, user name, site name.)
On macOS and Linux, it will use a pseudo-registry file, located at $HOME/.idapro/hvui.reg.
While hosts, user names & site names are persisted to the registry, passwords are stored securely in the operating system’s keychain.
On Windows, the Windows Credential Store is used (therefore requiring Windows 7 or newer)
On macOS, the macOS Keychain is used
On Linux, the "Secret service" is used (through libsecret-1)
Welcome to the Hex-Rays Admin Guide, designed to support system administrators in managing and configuring servers for IDA add-ons and floating licenses. Inside, you'll find in-depth guides for:
Please check this document for a detailed lmadmin installation guide with screenshots.
The Windows lmadmin installer will offer you to install lmadmin executable as a service. It is recommended to enable this option as it will ensure that lmadmin is always running and can serve license requests from IDA clients.
If you used 'lmgrd' instead of 'lmadmin', you'll have to manually instruct Windows to register 'lmgrd' as a service.
The OS X lmadmin installer does not configure the server to start automatically.
Check the [install_dir]/examples/service/ directory for a sample startup script or [install_dir]/examples/launchd/ for a launchd example plist.
For the sample plist file to work, the UserName and GroupName key values need to be changed from "nobody" to a production UserName and GroupName.
If you use 'lmgrd' instead of 'lmadmin' (and thus don't have the examples/ directory), you can find an example script or a launchd plist below.
For macOS earlier than 10.13, plist files should be placed in /System/Library/LaunchDaemons rather than in /System/Library/LaunchAgents. The naming convention for plist files is com.apple.filename.plist.
For macOS 10.13 or later, either location works, and there are no restrictions for plist file naming.
See also "Installing lmadmin License Server Manager as an Operating System Service" in the License Administration Guide.
Floating license versions of IDA use FlexNet License Manager from Flexera to ensure license compliance.
A license server is required for floating license versions. It needs to be installed on a dedicated machine in your network which is accessible over TCP/IP from the workstations that will run IDA.
The license server consists of two parts:
The license server manager Called 'lmadmin', it is provided by Flexera. If you do not already have the FlexNet license server manager installed, download and install it from the links below.
We also provide the now-deprecated, console-only 'lmgrd' server. This is the predecessor to 'lmadmin', and provide only a subset of its features.
The vendor daemon Called 'hexrays(.exe)', it is provided by Hex-Rays. This binary needs to be placed next to the license server manager executable, 'lmadmin(.exe)' (or 'lmgrd(.exe)')
You also can use another path, but you will need to edit the VENDOR line in the license file sent to you during the activation.
Please choose the platform where your license server will be running. It does not have to be for the same platform as IDA; any license server can manage IDA versions for different OSes.
FNLS is FlexNet Licensing Service, required when locking to a VM UUID.
The recommended server is 'lmadmin', which provides a web-based UI for configuring and managing the license server. If you do not yet have one installed (e.g. from using other FlexNet-bases software), please download the installer above and run it on the server machine.
Installing on Windows
Installing on Linux
Installing on OS X
Starting from v11.15, the lmadmin installer no longer bundles JRE (Java Runtime Environment) required by the installer engine, so please make sure that JRE 1.8 or later is installed before running it. For more information see the License Administration Guide.
The 'lmadmin' installer is an InstallAnywhere installer which uses Java. The lmadmin server itself does not use or require Java. You can uninstall JRE after installing lmadmin.
You should not run the 'lmadmin' server as administrator (Windows) or root (Linux/OS X), as this is not recommended. What's more, at least on Linux/OS X, the embedded HTTP server will simply refuse to start if it is being run as root.
Download the hexrays daemon from the table above and put it next to the lmadmin executable. Mark it as executable ("chmod +x hexrays") on Linux/OS X.
Start lmadmin if it's not running
open a Web browser and go to http://<servername>:8090/
Click on "Administration", login with user "admin" and password "admin". Change password if requested or see next step.
Click on "User Configuration", then click "Edit" next to "Administrator", and change the password to a secure value (you can change the username too)
Now that the license server & its companion 'hexrays(.exe)' are installed, it is time to request the FlexLM floating license that corresponds to the IDA license you possess.
That floating license needs to be locked to the machine the license server will be running on (not the machines IDA will run on). To request the license file for the first time, you will need a Host ID (an Ethernet MAC address).
You can use the following means of getting the host ID:
Using lmadmin (recommended)
Open the lmadmin UI (go to http://servername:8090 in the browser)
Go to the Administration tab ? System Information
Copy the string to the right from the "Ethernet Address" entry (pick a permanent one if there are several).
Using lmutil
Download the lmutil tool
From console/command prompt, run "lmutil lmhostid"
Copy the first entry from the list (without quotes)
Using system utilities
On Windows: from command prompt, run "ipconfig /all | more", then take "Physical Address" value for the physical Ethernet card.
On Linux/OS X: from command prompt, run "ifconfig | more", then take "ether" value for the physical Ethernet card.
Please choose a MAC for a physical card which is always present.
If you want to use locking to a VM UUID, please download the FNLS package above and follow the directions in readme.txt.
Once you have the Host ID, submit it to our activation page together with the ida.key from an IDA install:
You will receive the .lic file (it's a plain text file) by email. Save it on disk and use it the following way:
If using lmadmin:
Go to Administration tab, Vendor Daemon Configuration.
Click "Import License" and browse to the saved .lic file.
Make sure the "hexrays" daemon binary is installed in proper location (e.g. "hexrays.exe" in lmadmin's directory). If you are using another path, edit the VENDOR line in the .lic file before submitting:
If using lmgrd:
You will need to pass the filename to the .lic file on the commandline using the -c switch. See the License Administration Guide for details.
NOTE: If you have multiple .key files and want to activate them with the same host id, submit each of them for activation. Our server will keep track of all licenses activated for the same host id and will prepare a combined .lic file for them. In other words, just use the latest .lic file you received from the server. There is no need to install multiple .lic files.
NOTE: once a Host ID is submitted, it is fixed in our database and can be changed only by a manual request to support@hex-rays.com. You can, however, request the .lic file again by entering the same Host ID.
On Windows, you can just run IDA and open a file. On the first run this will produce an interactive dialog where you can enter the license server's name. You can also set the environment variable like for Linux and OS X.
To tell IDA the location of the license server you can either use an environment variable:
or a settings file:
Checking out a license requires two TCP connection: one to the license server, and one to the vendor daemon. If you're using a firewall, you need to make sure that both connections are not blocked both on the server and the client (IDA workstation).
The default port range used by the license server is 27000-27009. The vendor daemon uses a dynamic port by default, so it changes on every run. To change or fix the ports, you can use the Web UI, or edit the .lic file.
The port for the license server can be changed in "Server Configuration" tab, "License Server Configuration" section. The vendor daemon port can be changed in the Vendor Daemon Configuration tab, settings for the "hexrays" daemon. You may need to restart the vendor daemon and/or license server for the changes to take effect.
The license server port can be specified on the SERVER line, e.g.:
The vendor daemon port can be specified on the VENDOR line, e.g.:
You will need to re-import the .lic file (for lmadmin) or restart the server (for lmgrd) after editing it.
If you change the license server port from the default, you will need to specify it in IDA's server path, e.g.: 29000@servername.
By default our licenses allow borrowing for offline use for up to 4320 hours (this can be disabled or limited by the server administrator).
Since IDA 7.2, borrowing can be performed directly in IDA (menu Help, Floating Licenses), but you can also use the below procedure.
To borrow a license, run the lmborrow utility on the client before running IDA:
enddate is the date the license is to be returned in dd-mmm-yyyy format. time is optional and is specified in 24-hour format (hh:mm) in the local time. If time is unspecified, the borrow period lasts until the end of the day. For example:
Note: make sure to actually check out the necessary license(s) before disconnecting from the network. For example, open a file in IDA (to check out IDA's license) and decompile a function (to check out the decompiler's license).
To check the status of borrowed licenses, run:
To perform early return of the borrowed license at the end of your offline work, reconnect your system to the network and run:
Where feature is the name of the borrowed feature that is listed in the "lmborrow -status" output. For example:
You can also set the LM_BORROW environment variable manually instead of using lmutil. Please see the License Administration Guide for more information.
You may run the license server in a virtual machine. We do not recommend it, because the MAC address of the VM network adapter is often changed when moving or cloning the VM. However, some cloud providers offer more permanent identifiers:
It is possible to lock the license server to an Amazon EC2 instance. For this please attach an Elastic Network Interface (ENI) to the instance and specify its MAC address as the host ID. Locking to the EIP is not supported at this time.
If the cloud provider offers a permanent MAC address or a public IPv4 address, you can use it as the host ID. The IP must be exposed directly to the guest OS (no NAT/VPN or similar translation) and be the first in the adapter list.
Use lmutil lmhostid -internet to confirm that the global IP is exposed to the guest before using it for activation.
See also the License Administration Guide(Chapter 16: Licensing in a Cloud-Computing Environment) for more info.
Use the FNLS package to enable VM UUID locking. Make sure you use output of lmutil lmhostid -uuid for locking.
You can download FNLS from here:
Running the server in Docker is not supported.
Please see the License Administration Guide. Contact us if you have any questions or problems.
The Lumina server requires a MySQL server .
Go to , 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:
If you see "Error: Cannot connect to lumina db" please refer to section.
Good, the server appears to run! (If you are observing more worrying messages than this one, please refer to the section.)
For the same reasons as the issue, the Lumina server does not use TLS connections and thus will negociate a plain TCP connection to the MySQL server.
Go to , 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:
Good, the server appears to run! (If you are observing more worrying messages than this one, please refer to the section.)
storing them in
storing them in (recommended)
Passing credentials on the command line will always take precedence over and .
Credentials can also be passed through environment variables. They will take precedence over those possibly found in the .
Unless environment variables or command-line arguments are provided, hv will look for credentials in (and for passwords.)
The user, host (and optional site) will be persisted in , while the password will be saved to .
In order to keep the various commands' syntax as clear as possible, we will assume that the user has stored credentials (in either the or ) for the rest of this manual.
We recommend persisting credentials using .
if you login to the server using {hvui} and save the login information, it will end up in the , and thus hv will then be able to use that information as well.
Groups are especially useful for .
performing a of the database
, upgrading the database schema to the new version if needed
Right after putting the new Hex-Rays Vault server binary into place, it is recommended to make sure it runs fine. To do that, we’ll run the server manually :
Please ensure you performed a of the database before issuing this command.
The hexvault.lic file is tied to the MAC address of the first network interface. If they do not match, the server will not start. To change the MAC address, please contact
Go to , 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:
Good, the server appears to run! (If you are observing more worrying messages than this one, please refer to the section.)
| -p … (--port-number …) | Port number (default 443) |
|---|
| Microsoft® Windows® x64 | ||
|---|---|---|
| Linux x64 (LSB Certified) | ||
|---|---|---|
| macOS® (universal2) | ||
|---|---|---|
Check how to install and manage Teams server to streamline collaborative work.
Discover how to set up and maintain your on-premises Lumina server.
Get guidance on installing and managing the floating license server to efficiently handle users access to IDA.
-p … (--port-number …) | Port number (default 443) |
-i … (--ip-address …) | IP address to bind to (default to any) |
-c … (--certchain-file …) | TLS certificate chain file |
-k … (--privkey-file …) | TLS private key file |
-v (--verbose) | Verbose mode |
(--recreate-schema …) | Drop & re-create schema. Note that THIS WILL ERASE ALL DATA |
(--upgrade-schema) | Upgrade database schema; then quit. Only necessary when upgrading to a newer version of the Lumina server. |
-C … (--connection-string …) | Connection string |
-l … (--log-file …) | Log file |
-f … (--config-file …) | Config file |
-D … (--badreq-dir …) | Directory holding dumps of requests causing internal errors |
| specify username |
| specify password |
| specify host (server:port) (if port is omitted, defaults to 65433) |
| specify site |
| 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 |
| the server host name |
| the server port |
| the username to connect to the server |
| the user’s password |
| the site to use (most commands need a site to operate) |
-p … (--port-number …) | Port number (default 65433) |
-i … (--ip-address …) | IP address to bind to (default to any) |
-c … (--certchain-file …) | TLS certificate chain file |
-k … (--privkey-file …) | TLS private key file |
-v (--verbose) | Verbose mode |
(--upgrade-schema) | Upgrade database schema; then quit |
-C … (--connection-string …) | Connection string |
-l … (--log-file …) | Log file |
-L … (--license-file …) | License file |
-f … (--config-file …) | Config file |
(--recreate-schema) | Drop & re-create schema; then quit THIS WILL ERASE ALL DATA |
(--set-admin …) | Set admin password; requires username:password |
-d … (--vault-dir …) | Directory for vault files |
-e … (--log-level …) | Log level |
-i … (--ip-address …) | IP address to bind to (default to any) |
-c … (--certchain-file …) | TLS certificate chain file |
-k … (--privkey-file …) | TLS private key file |
-v (--verbose) | Verbose mode |
(--recreate-schema …) | Drop & re-create schema. Note that THIS WILL ERASE ALL DATA |
(--upgrade-schema) | Upgrade database schema; then quit. Only necessary when upgrading to a newer version of the Lumina server. |
-C … (--connection-string …) | Connection string |
-l … (--log-file …) | Log file |
-f … (--config-file …) | Config file |
-D … (--badreq-dir …) | Directory holding dumps of requests causing internal errors |
How to install IDA floating licenses on a Windows server
exemplary script
launchd plist
License Administration Guide
general server usage guide from Flexera
Upgrade Guide
if you already have a license server configured and are upgrading to a new IDA version
Installation Guide
if you're installing the server for the first time (this guide covers installing server on Windows but some parts of it also apply to other platforms). See also instructions below.
Troubleshooting Guide
if you're having issues using IDA with the license server or during installation/configuration
installer
zip package
lmgrd binary (command-line based server)
lmgrd.exe binary
Hex-Rays daemon
hexrays.exe binary
Utilities
lmtools
lmutil
FNLS1
installer
tgz package
lmgrd binary (command-line based server)
lmgrd binary
Hex-Rays daemon
hexrays binary
Utilities
lmutil
FNLS1
installer
tgz package
lmgrd binary (command-line based server)
lmgrd binary
Hex-Rays daemon
hexrays binary
Utilities
lmutil
License Administration Guide