Lumen Documentation

The recommended way to run Lumen is via Docker Compose. This method uses precompiled images and handles the database setup automatically.

1. Ensure docker-engine and docker-compose are installed.
2. Custom TLS (Optional): If using a custom TLS certificate, copy your .p12 or .pfx private key to the ./dockershare directory. Set the password for this key in your .env file using the PKCSPASSWD variable.
3. Custom Configuration (Optional): If you have a custom Lumen configuration, copy it to ./dockershare/config.toml.
4. Run the stack:

   docker-compose up

5. Note on TLS: If TLS is enabled in your config.toml, a hexrays.crt file will be generated in ./dockershare. You must copy this file to your IDA Pro installation directory to enable communication.

To build Lumen manually, you need a Rust toolchain and a PostgreSQL database.

1. Clone the repository:

   git clone https://github.com/naim94a/lumen.git
   cd lumen

2. Install the Rust toolchain from https://rustup.rs/.
3. Database Setup:
   • Install PostgreSQL.
   • Install diesel-cli with the postgres feature:

     cargo install diesel_cli --no-default-features -Fpostgres

   • Run migrations using the provided configuration:

     diesel --config-file common/diesel.toml \
        --database-url postgres://postgres:password@localhost/lumen \
        migration run

4. Build the release binary:

   cargo build --release

# Run migrations
diesel --config-file common/diesel.toml --database-url postgres://postgres:password@localhost/lumen migration run

# Build
cargo build --release

Once built, you can start the Lumen server by specifying a configuration file.

./lumen -c config.toml

You can deploy the Lumen stack using Docker Compose. The setup includes a PostgreSQL database service (db) and the Lumen application service (lumina). The lumina service depends on the db service being healthy before it starts.

To run the stack, ensure you have a .env file or environment variable set for PKCSPASSWD (used for PKCS#12 certificate passwords) and execute:

docker-compose up

When running via Docker Compose, the lumina service uses the following environment variables:

• PKCSPASSWD: The password for the PKCS#12 certificate. This should be passed from your host environment.
• DATABASE_URL: The connection string for the PostgreSQL database. The default is postgres://lumina:1@db/lumina.

The database service (db) uses these credentials:

• POSTGRES_USER: lumina
• POSTGRES_DB: lumina
• POSTGRES_PASSWORD: 1

The limits section controls various timeout durations for the server. If not provided, the following default values are used:

• command_timeout: Maximum time to wait on an idle connection between commands (Default: 3600s).
• pull_md_timeout: Maximum time allowed for all PULL_MD queries (Default: 240s).
• hello_timeout: Maximum time to wait for a HELO message (Default: 15s).
• tls_handshake_timeout: Maximum time allowed until the TLS handshake completes (Default: 10s).

limits = {
  command_timeout = 60,
  pull_md_timeout = 120,
  hello_timeout = 5,
  tls_handshake_timeout = 5
}

The database section defines how the server connects to its data store. It requires connection information and TLS settings for the database connection itself.

Key fields:

• connection_info: A string containing the connection details.
• use_tls: Boolean indicating if TLS should be used for the database connection.
• server_ca: (Optional) Path to the server's CA certificate.
• client_id: (Optional) Path to the client identity/certificate.

database = {
  connection_info = "host=localhost user=lumen dbname=lumen",
  use_tls = true,
  server_ca = "/path/to/ca.crt"
}

If an API server is enabled, it is configured via the optional api_server section.

Key fields:

• bind_addr: The SocketAddr the web server listens on.

api_server = { bind_addr = "127.0.0.1:3000" }

The lumina section of the configuration defines the core server behavior. You can specify the binding address, enable TLS, and control feature limits like function history retrieval.

Key fields:

• bind_addr: The SocketAddr the server listens on.
• use_tls: (Optional) Boolean to enable/disable TLS.
• tls: (Optional) A TlsIdentity object containing the server_cert path.
• server_name: (Optional) The server name.
• allow_deletes: (Optional) Boolean to allow delete operations.
• get_history_limit: (Optional) Limits the number of function histories returned per function. Setting this to None or Some(0) disables the feature.

lumina = {
  bind_addr = "0.0.0.0:8080",
  use_tls = true,
  tls = { server_cert = "/path/to/cert.pem" },
  get_history_limit = 50
}

Use push_funcs to upload function metadata and scores to the database. This method performs an upsert: if a function with the same checksum and db_id already exists, it updates the name, metadata, rank, and timestamp.

Note: The method automatically chunks large requests into groups of 3000 to avoid PostgreSQL binding limits. It returns a Vec<bool> indicating whether each function in the request was newly created.

// user: RpcHello, funcs: PushMetadata, scores: &[u32]
let is_new_vec: Vec<bool> = db.push_funcs(user, funcs, &scores).await?;