# Lumina Server Administration ## Introduction This manual describes the installation, management, and interaction with an on-the-premises IDA Pro Private 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. {% hint style="info" %} Refer to the [Lumina Server Installation Checklist](/extensions/lumina/admin/lumina-server/lumina-server-checklist.md) for a concise set of steps to follow. {% endhint %} ## Prerequisites After your purchase of Lumina server, go to the [customer portal](https://my.hex-rays.com/dashboard/download-center/downloads), 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). ### MySQL server 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. NOTE: The Lumina server requires a MySQL server [version 5.8 or newer](#index-column-size-too-large.-the-maximum-column-size-is-767-bytes). For illustration purposes, let’s assume the MySQL database the server will use, is called: `"lumina_db"`. ## Installation 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` binary: ``` CONNSTR="mysql;Server=127.0.0.1;Port=3306;Database=lumina_db;Uid=lumina;Pwd=" ``` ### Installation in a Teams setup When Lumina is installed in a Teams setup, 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: ``` VAULT_HOST="vault.acme.com:65433" ``` ### Supported platforms 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.) NOTE: 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. ### Supported architectures Lumina functionality in IDA Pro is **currently available only when analyzing binaries compiled for the following architectures**: * PC (x86/x64) * ARM * PPC * MIPS * RISC-V If a user loads a binary compiled for an unsupported architecture, the Lumina menu will not appear in IDA Pro and pushing or pulling metadata will not be possible. ### Activating the server license 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. ``` >/sbin/ifconfig enp4s0: flags=4163 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` Go to [Hex-Rays customer portal](https://my.hex-rays.com) and [activate your license for Lumina server](/getting-started/licensing.md#private-lumina-server-activation-for-admins). 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: * Lumina server certificate * `lumina_server_.hexlic` (license key, where LID is your license ID) ### Installing the server license Those need to be copied in the Lumina installation directory. As `root`: ``` >cd /opt/lumina >cp .../path/to/lumina_server.crt . >cp .../path/to/lumina_server.key . >cp .../path/to/lumina_server_.hexlic . >chown lumina:lumina lumina_server.crt lumina_server.key lumina_server_.hexlic >chmod 640 lumina_server.crt lumina_server.key lumina_server_.hexlic ``` ### Creating the initial database schema At this point, the server should be ready to run. NOTE: 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 as well as specify which user authentication will be used (either lumina or vault, we will use lumina in the example below): ``` >sudo -u lumina ./lumina_server --config-file lumina.conf \ --certchain-file lumina_server.crt \ --privkey-file lumina_server.key \ --recreate-schema lumina Hex-Rays Lumina Server v8.0 Hex-Rays (c) 2022-2024 2022-09-02 10:28:30 Database has been initialized; exiting. ``` If you see "Error: Cannot connect to lumina db" please refer to the [troubleshooting](#error-cannot-connect-to-lumina-db) section. ### Testing the server Now that the server is installed and has a database to work with, we can test that it works: ``` >sudo -u lumina ./lumina_server --config-file lumina.conf \ --certchain-file lumina_server.crt \ --privkey-file lumina_server.key Hex-Rays Lumina Server v8.0 Hex-Rays (c) 2022-2024 2022-09-22 12:14:37 Listening on 0.0.0.0:443... ``` Good, the server appears to run! (If you are observing more worrying messages than this one, please refer to the [troubleshooting](#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 lumina.service ``` …​and make sure it runs: ``` >ps aux | grep lumina_server lumina 78812 0.0 0.0 ... ``` or: ``` >systemctl status lumina.service ``` If you don’t see a running `lumina_server` process or systemctl reports a startup failure, 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 Lumina server, and in particular how to create the first (i.e., "administrator") user. ### **Creating the administrator** {% hint style="info" %} The very first user to log into the server becomes the first administrator. The administrator can create new administrators and otherwise manage the server. {% endhint %} Once the server is up and running, login to it using a username and password of your choice using the `lc` utility. {% hint style="info" %} `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`. {% endhint %} ``` >cd /opt/lumina >./lc -hlumina.acme.com -ualice -psecr3t info Hex-Rays Lumina Server v8.0 Lumina time: 2022-09-01 14:28:02, up since 2022-09-01 14:27:58 MAC address: Client name: alice *ADMIN* Client host: 127.0.0.1 ``` 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: ``` >./lc -hlumina.acme.com -ualice -psecr3t users LastActive Adm Login License User name Email ------------------- --- ----- --------------- --------- -------------- 2022-09-01 14:28:04 * alice AA-A11C-AC8E-01 Alice alice@acme.com # Shown 1 results ``` ## Useful environment variables To facilitate using `lc`, you may consider defining the following environment variables: ``` export LUMINA_HOST=lumina.acme.com export LUMINA_USER=alice export LUMINA_PASS=secr3t ``` After that, you can connect to the server effortlessly. For example, this command will print information about the server and the client: ``` >./lc info Hex-Rays Lumina Server v8.0 Lumina time: 2022-09-01 14:28:02, up since 2022-09-01 14:27:58 MAC address: Client name: alice *ADMIN* Client host: 127.0.0.1 ... ``` The Lumina server looks up an additional `LUMINA_RECV_HELO_TIMEOUT` environment variable, which can be used to set the timeout for client login phase (the time between the TLS handshake and the arrival of the first packet). The value is in milliseconds, and setting it to -1 disables the timeout. Note that when a client attempts to connect, the Lumina server creates a new thread and keeps it running for the entire duration of this timeout. Hence, for publicly exposed Lumina servers, it is advised to keep it as short as possible (e.g. 1000 ms). ## Lumina server command-line options | | | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | -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 \[lumina\|vault]​) | Drop & re-create schema using either lumina or vault user authentication. 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 | ## Troubleshooting ### 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_server.crt`: the certificate chain * `lumina_server.key`: the private key file * `lumina_server_.hexlic`: the license file where represents your lumina server license ID. 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_server.crt lumina_server.key lumina_server_.hexlic lumina.conf` * are not world-accessible: `chmod 640 lumina_server.crt lumina_server.key lumina_server_.hexlic 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 which 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: ``` ALTER USER lumina@localhost IDENTIFIED WITH mysql_native_password BY ''; ``` 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 negotiate a plain TCP connection to the MySQL server. #### Creating the user and database What follows is an example of creating a user + database, on a Debian system: ``` >sudo mysql -uroot -p [sudo] password for aundro: Enter password: Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 14306 Server version: 10.1.48-MySQL-0+deb9u2 Debian 9.13 Copyright (c) 2000, 2018, Oracle, MySQL Corporation Ab and others. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. MySQL [(none)]> create user lumina@localhost; Query OK, 0 rows affected (0.00 sec) MySQL [(none)]> set password for lumina@localhost = PASSWORD(''); Query OK, 0 rows affected (0.00 sec) MySQL [(none)]> grant all on *.* to lumina@localhost; Query OK, 0 rows affected (0.00 sec) MySQL [(none)]> ALTER USER lumina@localhost IDENTIFIED WITH mysql_native_password BY ''; Query OK, 0 rows affected (0.00 sec) MySQL [(none)]> create database lumina_db; Query OK, 1 row affected (0.00 sec) MySQL [(none)]> [Ctrl+C] Bye ``` #### "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 **version 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`. ## --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hex-rays.com/extensions/lumina/admin/lumina-server.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.