# LMC Exporter Installation

## Overview

LMC Exporter is distributed as a precompiled application and does not require source compilation by end users.

This article describes:

-   Supported runtime environments
-   Tar archive installation
-   License configuration and validation
-   Runtime configuration
-   Post-installation validation
-   Common troubleshooting steps

## Prerequisites

### Supported Runtime Platforms

<table><caption class="sr-only">Supported Runtime Platforms</caption><thead><tr><th scope="col">Platform</th><th scope="col">Archive platform</th><th scope="col">Architecture</th></tr></thead><tbody><tr><td>Red Hat Enterprise Linux 8</td><td><code>el8</code></td><td><code>x86_64</code></td></tr><tr><td>Red Hat Enterprise Linux 9</td><td><code>el9</code></td><td><code>x86_64</code></td></tr></tbody></table>

Use the archive supplied for your operating system. The examples below use `el8`; replace it with `el9` throughout on Enterprise Linux 9. Do not use either archive on Oracle Linux 7; contact support for platform availability.

### Runtime Requirements

The target host must provide:

-   Access to the required RTDS installation under an account permitted to read its shared memory
-   Matching runtime libraries: libcurl, OpenSSL (1.1 on EL8 or 3 on EL9), the C++ runtime, and standard system libraries
-   Access to the appropriate shared-memory environment
-   Valid Shared Memory server keys
-   A valid local LMC Exporter license, or access and credentials for a licensing Gateway
-   Network connectivity for Prometheus scraping when HTTP metrics mode is enabled

NoteImportant

LMC Exporter is supplied as a precompiled package. No compiler, source code, build tools, or manual compilation steps are required.

## Installation

### Obtain and Verify the Distribution Archive

Download the supplied `lmc_exporter-v0.19.0-el8-x86_64.tar.gz` and its `.sha256sum` file through your customer distribution channel. Keep both files in the same directory and verify the checksum before extraction:

```
sha256sum -c lmc_exporter-v0.19.0-el8-x86_64.tar.gz.sha256sum
```

### Extract the Distribution Archive

For a new installation under `/opt`:

```
sudo tar -xzf lmc_exporter-v0.19.0-el8-x86_64.tar.gz -C /opt
```

NoteExisting installations

Do not extract the whole archive over an existing installation: it contains a default configuration. Follow the [upgrade procedure](https://portal.cjcit.io/knowledge-base/lmc_exporter/0.19/deployment-operations/operations/#upgrade-to-0190) to preserve configuration and licensing state.

### Archive Structure

```
particle_horizon/
├── SOFTWARE/
│   └── lmc_exporter-v0.19.0-el8-x86_64/
│       ├── bin/lmc_exporter-el8
│       ├── BUILD_INFO.txt
│       └── licenses/
├── local_config/lmc_exporter/lmc_exporter.toml
├── local_data/lmc_exporter/
├── logs/lmc_exporter/
└── systemd/lmc-exporter.service
```

Create the active-install link expected by the service and by the examples in this documentation:

```
sudo ln -s SOFTWARE/lmc_exporter-v0.19.0-el8-x86_64 /opt/particle_horizon/lmc_exporter
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 --version
```

The command should report `lmc_exporter v0.19.0`. If a runtime library is missing, have your system administrator provide the matching platform libraries before continuing.

## License Setup and Validation

### Create a Configuration File

Edit `/opt/particle_horizon/local_config/lmc_exporter/lmc_exporter.toml`, supplied in the archive. Replace the example target with your application and shared-memory key. Use absolute paths for licenses and credentials so they work in both terminal and service runs.

### Choose a Licensing Mode

Local-file licensing remains the default. Configure the path to the local license:

Update the configuration file with the path to your license key:

```
license_file = "/opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic"
```

Alternatively, the exporter can acquire online entitlement from a licensing Gateway:

```
license_mode = "gateway"
gateway_endpoints = ["https://gateway.example:8443"]
gateway_auth_mode = "mtls"
gateway_tls_ca_file = "/etc/lmc-exporter/gateway-ca.pem"
gateway_tls_cert_file = "/etc/lmc-exporter/client.pem"
gateway_tls_key_file = "/etc/lmc-exporter/client-key.pem"
gateway_state_directory = "/var/lib/lmc-exporter"
```

Gateway mode also requires a `component_instance_id` for every target. See [Gateway Licensing](https://portal.cjcit.io/knowledge-base/lmc_exporter/0.19/configuration/gateway-licensing/) for complete configuration, state-directory, and entitlement-counting requirements.

### Local License Validation Process

During startup, LMC Exporter validates:

1.  License fingerprint
2.  Digital signature
3.  License expiration status

Validation occurs before any LMC shared-memory discovery or metrics collection begins.

NoteImportant

If local validation fails, or Gateway does not grant the complete configured workload, LMC Exporter will not start.

### License Expiration Grace Period

<table><caption class="sr-only">License Expiration Grace Period</caption><thead><tr><th scope="col">Condition</th><th scope="col">Behavior</th></tr></thead><tbody><tr><td>License valid</td><td>Startup proceeds normally</td></tr><tr><td>From the expiry instant until, but not including, 36 hours after expiry</td><td>Startup proceeds with warning messages</td></tr><tr><td>At or after 36 hours past expiry</td><td>Startup is blocked</td></tr></tbody></table>

For running instances:

-   Warning messages continue throughout the grace period.
-   Once the grace period expires, the exporter exits during the next enforcement check.

## Runtime Configuration

### Example Configuration

```
context_id = "shmApp"
pool_name = "pool"

app = "ads"
server_keys = ["82"]

metrics_interval_seconds = 30

metrics_http_enabled = true
metrics_bind_address = "0.0.0.0"
metrics_port = 9464
metrics_path = "/metrics"

license_file = "/opt/particle_horizon/local_data/lmc_exporter/lmc_exporter.lic"
```

### Common Configuration Settings

<table><caption class="sr-only">Common Configuration Settings</caption><thead><tr><th scope="col">Setting</th><th scope="col">Description</th></tr></thead><tbody><tr><td><code>context_id</code></td><td>LMC context identifier</td></tr><tr><td><code>pool_name</code></td><td>Shared-memory pool name</td></tr><tr><td><code>app</code></td><td>Target application name</td></tr><tr><td><code>instance</code></td><td>Optional application instance</td></tr><tr><td><code>server_keys</code></td><td>Target LMC server keys</td></tr><tr><td><code>metrics_interval_seconds</code></td><td>Metric refresh interval</td></tr><tr><td><code>metrics_http_enabled</code></td><td>Enables HTTP metrics endpoint</td></tr><tr><td><code>metrics_bind_address</code></td><td>HTTP listener address</td></tr><tr><td><code>metrics_port</code></td><td>HTTP listener port</td></tr><tr><td><code>metrics_path</code></td><td>Metrics endpoint path</td></tr><tr><td><code>license_file</code></td><td>License file location</td></tr></tbody></table>

## Validation

### Start the Exporter

Run as the account that has access to the target shared memory and the configured license or Gateway credentials:

```
/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 --config /opt/particle_horizon/local_config/lmc_exporter/lmc_exporter.toml
```

Stop the foreground process before starting the service so that the listener port and Gateway state lock are available.

### Verify Metrics Availability

```
curl "http://127.0.0.1:9464/metrics?server_key=82"
```

Example application routing:

```
curl "http://127.0.0.1:9464/metrics?app=ads&instance=<resolved-instance>"
```

## Service Management

The archive supplies a systemd unit but does not install or start it. Copy the unit after configuring the exporter:

```
sudo cp /opt/particle_horizon/systemd/lmc-exporter.service /etc/systemd/system/lmc-exporter.service
sudoedit /etc/systemd/system/lmc-exporter.service
```

Set `User` and `Group` to the existing account and group permitted to access the target shared memory. The template uses `particle_horizon`; use it only if that account exists and has the required access. Ensure the account can read the configuration, binary, license, and credentials, and owns the private Gateway state directory when Gateway mode is used.

For the EL8 example, verify these service paths:

```
ExecStart=/opt/particle_horizon/lmc_exporter/bin/lmc_exporter-el8 --config /opt/particle_horizon/local_config/lmc_exporter/lmc_exporter.toml
WorkingDirectory=/opt/particle_horizon/lmc_exporter
```

Replace the shipped relative `license_file` with the absolute path shown above. If the installation root differs from `/opt/particle_horizon`, adjust the service and configuration paths together.

For timestamp metrics, the exporter process timezone must match the source application’s timezone. If that differs from the host timezone, set the standard `TZ` environment variable in the service’s `[Service]` section (for example, `Environment=TZ=Europe/London` for a source using that timezone). See [timestamp guidance](https://portal.cjcit.io/knowledge-base/lmc_exporter/0.19/configuration/metric-configuration/#timestamp-metrics).

```
sudo systemctl daemon-reload
sudo systemctl enable --now lmc-exporter
sudo systemctl status lmc-exporter
sudo journalctl -u lmc-exporter -n 100 --no-pager
```

After configuration or credential changes, restart with `sudo systemctl restart lmc-exporter`. Run `sudo systemctl daemon-reload` first if you changed the unit. Stop the exporter with `sudo systemctl stop lmc-exporter`.

## Troubleshooting

### License Validation Failure

#### Symptoms

The exporter exits during startup before any LMC discovery occurs.

#### Resolution

Verify:

-   The configured license file exists
-   The license has not been modified
-   The license signature is valid
-   The license has not exceeded the grace period

### License Expired

#### Symptoms

Startup warning messages indicate license expiration.

#### Resolution

Replace the license before the 36-hour grace period expires.

### HTTP Endpoint Returns 503

#### Symptoms

```
HTTP 503 Service Unavailable
```

#### Resolution

The target subtree may not yet be fully synchronized.

Verify:

-   Server key configuration
-   Application configuration
-   LMC connectivity
-   Target availability

### No Metrics Returned

#### Symptoms

Metrics endpoint responds successfully but contains no application metrics.

#### Resolution

Verify:

-   Correct application configuration
-   Target selection
-   Application-specific metric mappings are configured for the target application