Lumina server
Last updated
Was this helpful?
IDA 9.0
Last updated
Was this helpful?
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.
After your purchase of Lumina server, go to the , where you will find an installer for the Lumina server. Please go ahead and download it.
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.)
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 server certificate
lumina_server.hexlic (license key)
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.
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:
-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
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.
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
Go to and . During that process, you will need to provide the MAC address of the device where the Lumina server will be running. Once the activation is complete, you'll be able 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.