Install

Table of Contents

  1. Quick Start

  2. What is LME?

    2.1 Description

    2.2 How Does LME Work?

    2.3 What Firewall Rules Do I Need to Set Up?

  3. Prerequisites

    3.1 Estimated Installation Times

  4. Downloading and Installing LME

    4.1 Upgrading

    4.2 Downloading LME

    4.2.1 Update System Packages

    4.2.2 Download and Extract LME

    4.3 Install LME

    4.4 Verify Container Status

    4.5 Post-Installation Steps

    4.6 Deploying Agents

    4.7 Installing Sysmon (Windows Clients Only)

  5. Next Steps

    5.1 Retrieving Passwords

    5.2 Starting and Stopping LME

    5.3 Uninstall LME

    5.3.1 Complete Uninstall

    5.3.2 Optional Uninstall Steps

    5.4 Customizing LME

  6. Documentation

    6.1 Logging Guidance

    6.2 Reference

    6.3 Maintenance

    6.4 Agents

    6.5 Endpoint Tools

  7. Developer Notes

    7.1 Git Clone and Git Checkout Notes

    7.2 Non-Default Installation Notes

    7.3 Installation Details

    7.4 Notes on Folders, Permissions, and Service

    7.5 Other Post-Install Setup

1. Quick Start

Step 1: Install Logging Made Easy (LME)

  • To configure your IP address and settings, run the following commands and follow the prompts in install.sh:

    sudo apt update && sudo apt upgrade -y && sudo apt-get install -y jq curl
curl -s https://api.github.com/repos/cisagov/LME/releases/latest | jq -r '.assets[0].browser_download_url' | xargs -I {} sh -c 'curl -L -O {} && unzip -d ~/LME $(basename {})'
cd ~/LME
./install.sh

Step 2: Access LME Credentials

  • The LME installation scripts set the passwords for all LME container service accounts. To view and print the login credentials, reference Retrieving Passwords.

Step 3: Continue Setup

2. What is LME?

For a more detailed understanding of LME’s architecture, reference the LME Architecture Documentation.

2.1 Description

LME runs on Ubuntu 22.04 and 24.04, and Debian 12.10 (experimental). It uses Podman containers to provide:

  • Log Management
  • Endpoint Security
  • Monitoring
  • Alerting
  • Visualization Capabilities

LME integrates Wazuh, Elastic, and ElastAlert. This modular, flexible architecture supports scalable log storage, real-time search, and efficient threat detection–all designed to evolve with your organization’s logging needs.

2.2 How does LME Work?

Understanding LME from a user perspective involves three key components:

diagram

  • Collecting: Logs are collected via agents

    • Wazuh Agents: Enables Endpoint Detection and Response (EDR) on client systems, providing advanced security features (e.g., intrusion detection and anomaly detection). For more information, reference the Wazuh’s Agent Documentation.

    • Elastic Agents: Enhance log collection and management, allowing for greater control and customization in how data is collected and analyzed. Agents also feature a vast collection of integrations for many log types/applications. For more information, reference the Elastic’s Agent Documentation.

  • Viewing: Logs are viewable Kibana dashboards

    • Kibana is the visualization and analytics interface in LME, providing users with tools to visualize and monitor log data stored in Elasticsearch.

    • It enables the creation of custom dashboards and visualizations, allowing users to easily track security events, detect anomalies, and analyze trends.

    • Kibana’s intuitive interface supports real-time insights into the security posture of an organization, making it an essential tool for data-driven decision-making in LME’s centralized logging and security monitoring framework.

  • Alerting: Setting up notifications for log monitoring using Elastalert

    • ElastAlert is an open-source alerting framework, to automate alerting based on data stored in Elasticsearch.

    • It monitors Elasticsearch for specific patterns, thresholds, or anomalies, and generates alerts when predefined conditions are met.

    • This provides proactive detection of potential security incidents, enabling faster response and investigation.

    • ElastAlert’s flexible rule system allows for custom alerts tailored to your organization’s security monitoring needs, making it a critical component of the LME alerting framework.

2.3 What Firewall Rules Do I Need to Set Up?

Please reference our documentation around Cloud and firewall setup for more information on how you can expose these ports.

To collect logs, the following ports must be open on the LME server and accessible from all client systems:

  • Elasticsearch: 9200
  • Kibana: 443,5601
  • Wazuh: 1514,1515,1516,55000,514
  • Agent: 8220

Note: Kibana defaults to port 5601, but it’s also configured to listen on port 443 for HTTPS access.

3. Prerequisites

If you’re unsure whether your system meets the prerequisites for installing LME, reference our Prerequisites Documentation.

The main prerequisite is setting up hardware for your Ubuntu server, which should have at least:

  • Two (2) processors
  • 16 GB RAM
  • 128 GB of dedicated storage for LME’s Elasticsearch database

For Lower-Spec Systems:

If you need to run LME with less than 16 GB of RAM or minimal hardware:

  • Reference our Troubleshooting Guide to configure Podman quadlets for reduced memory usage

  • We recommend:

    • Elasticsearch: limit to 8 GB RAM
    • Kibana: limit to 4GB RAM

For Large Environments:

If your server will support hundreds of clients, you’ll need more resources and possibly a dedicated machine for Elasticsearch. Reference our documentation for an expanded dscussion around scaling LME or more information.

3.1 Estimated Installation Times

Here’s a reference timeline based on real-world installations. Actual times may vary depending on system resources and network speed.

MilestonesTimeTimeline
Download LME0:31.490:31.49
Set Environment0:35.941:06.61
Install Ansible1:31.942:38.03
Installing LME Ansible Playbook4:03.636:41.66
All Containers Active6:41.6613:08.92
Accessing Elastic0:38.9713:47.60
Post-Install Ansible Playbook2:04.3415:51.94
Deploy Linux Elastic Agent0:49.9516:41.45
Deploy Windows Elastic Agent1:32.0018:13.40
Deploy Linux Wazuh Agent1:41.9919:55.34
Deploy Windows Wazuh Agent1:55.0021:51.22
Download LME Zip on Windows2:22.4324:13.65
Install Sysmon1:04.3425:17.99
Windows Integration0:39.9325:57.27

4. Downloading and Installing LME

This section provides the procedures for downloading, configuring, and installing LME on an Ubuntu server. For visual learners, reference the LME Installation Video.

Note: LME has been extensively tested on Ubuntu 22.04. While it can run on other Unix-like systems, we recommend sticking with Ubuntu 22.04 for the best experience. Initial testing has been done on 24.04, and it is recommended as an alternative if you encounter issues setting up on 22.04.

4.1 Upgrading

If you are upgrading from an older version of LME to LME 2.0, reference our Upgrade Documentation.

4.2 Downloading LME

4.2.1 Update System Packages

To update your package list and install the necessary tools, run:

sudo apt update && sudo apt upgrade -y && sudo apt-get install -y jq curl

4.2.2 Download and Extract LME

To download the latest release of LME and extract it to ~/LME, run:

curl -s https://api.github.com/repos/cisagov/LME/releases/latest | jq -r '.assets[0].browser_download_url' | xargs -I {} sh -c 'curl -L -O {} && unzip -d ~/LME $(basename {})'

4.3 Install LME

  • To change directory to the LME directory in your home directory, run:

    cd ~/LME
./install.sh

  • This script will:

    • Prompt you to select an IP address for other machines to connect to
    • Attempt to auto-detect IPs, or allow you to enter one manually
    • Install Ansible (if not already installed)
    • Automatically run Ansible playbooks for your operating system

Note: The services may take several minutes to start. Please be patient.

4.4 Verify Container Status

  • To check that the containers are running and healthy, run:

    sudo -i podman ps --format "{{.Names}} {{.Status}}"

  • Expected output:

    lme-elasticsearch Up 20 minutes (healthy)
lme-elastalert2 Up 20 minutes
lme-wazuh-manager Up 20 minutes (healthy)
lme-kibana Up 19 minutes (healthy)
lme-fleet-server Up 14 minutes

Note: The Fleet server is the last one to start and may take extra time.

Note: If the output differs, reference the Troubleshooting Guide.

4.5 Post-Installation Steps

If you encounter any issues, reference the Post-Installation Troubleshooting Guide.

4.6 Deploying Agents

To populate the dashboards with data, you need to install agents. Detailed guides for deploying Wazuh and Elastic agents are available in the following documents:

4.7 Installing Sysmon (Windows Clients Only)

For Windows clients, installing Sysmon is essential to obtain comprehensive logs and ensure proper data visualization in the dashboards. Follow these steps to install Sysmon on each Windows client machine:

  • Download and unzip the LME folder on the Windows client.

  • Run the following command in an Administrator PowerShell session from inside the unzipped folder (reference github):

    .\scripts\install_sysmon.ps1

  • To temporarily set the PowerShell script execution policy to “Unrestricted” to allow the execution of downloaded scripts (if necessary), run:

    Set-ExecutionPolicy Unrestricted

5. Next Steps

Reference the Documentation Section for additional information.

5.1 Retrieving Passwords

  • To navigate to the LME directory, run:

    cd ~/LME

  • To view the service user passwords, run:

    ./scripts/extract_secrets.sh -p

NOTE: Manually changing these passwords in the encrypted file, or via others means (i.e., manually changing the elastic logon password in Kibana) will break connectivity between containers.

For more information about passwords, reference the Password Encryption Section.

5.2 Starting and Stopping LME

To manage the LME services, run the following commands:

  • Stop all LME services:

    sudo -i systemctl stop lme.service

  • Restart all LME services:

    sudo -i systemctl restart lme.service

  • Start all LME services:

    sudo -i systemctl start lme.service

5.3 Uninstall LME

Note: Dependencies will not be removed. You can consult the Ansible scripts to identify and remove the installed dependencies and created directories if desired.

Warning: This will delete all LME data and services.

5.3.1 Complete Uninstall

To do a complete uninstall, run the following commands:

  • Stop LME services:

    sudo systemctl stop lme*

  • Reset systemd service states:

    sudo systemctl reset-failed

  • Remove all Podman volumes:

    sudo -i podman volume rm -a

  • Remove all Podman secrets:

    sudo -i podman secret rm -a

  • Delete LME directories:

    sudo rm -rf /opt/lme /etc/lme /etc/containers/systemd

  • Reset Podman:

    Warning: Do not run this if you have other Podman containers).

    sudo -i podman system reset --force

    Warning: This will delete all LME data and services.

5.3.2 Optional Uninstall Steps

For optional uninstall steps, run the following commands:

  • Stop LME services:

    sudo systemctl stop lme*
sudo systemctl disable lme.service
sudo -i podman stop $(sudo -i podman ps -aq)
sudo -i podman rm $(sudo -i podman ps -aq)

  • Delete LME volumes:

    • To delete only LME volumes:

      sudo -i podman volume ls --format "{{.Name}}" | grep lme | xargs podman volume rm

    • To delete all volumes:

      sudo -i podman volume rm -a

5.4 Customizing LME

LME is actively maintained and regularly updated with new features and community-requested improvements. Below are a few common customization options to help tailor your LME deployment to your organization’s specific needs:

  • Alerting: Addi custom notifications for triggered alerts using elastalert2
  • Active Response: Create custom wazuh active response actions to automatically respond to a malicious event wazuh detects.
  • Backups: Customize backups of logs for your organizations own compliance needs.
  • Custom log types: Use elastic agents built in integrations ingest a log type specific to your organization.

6. Documentation

6.1 Logging Guidance

6.2 Reference

6.3 Maintenance

6.4 Agents

6.5 Endpoint Tools

To make best use of the agents, complement them with utilities that generate forensically relevant data to analyze and support detections. Consider adding them to Windows/Linux.

7. Developer Notes

7.1 Git Clone and Git Checkout

  • Git clone and git checkout your development branch on the server:

    git clone https://github.com/cisagov/LME.git
cd LME
git checkout YOUR_BRANCH_NAME_HERE

  • Once you’ve gotten your changes/updates added, please submit a pull request following our Guidelines

7.2 Non-Default Installation

  • If you installed LME in a custom directory, pass the CLONE_DIRECTORY variable to the playbook by running:

    ansible-playbook ./ansible/install_lme_local.yml -e "clone_dir=/path/to/clone/directory"

Note: If you have issues accessing a file or directory, please note permissions and notes on folder structure here.

  • This also assumes your user can sudo without a password. If you need to input a password when you sudo, run the following command with the -K flag and it will prompt you for a password:

    ansible-playbook -K ./ansible/install_lme_local.yml -e "clone_dir=/path/to/clone/directory"

  • In the BECOME password prompt, enter the password for your user you would normally give sudo, so the playbook is able to sudo as expected.

7.3 Installation Details

Below we’ve documented in more detail what exactly occurs during the installation and post-installation ansible scripts:

  • Setup /opt/lme and check for sudo access.
  • Configure other required directories/files.
  • Setup password information: Configures the password vault and other configurations for the service user passwords.
  • Setup Nix: nix is the open source package manager we use to install the latest version of Podman.
  • Set service user passwords: Sets the service user passwords that are encrypted according to the Security Model.
  • Install Quadlets: Installs quadlet files in the directories to be setup as systemd services.
  • Setup Containers for root: The containers listed in $clone_directory/config/containers.txt will be pulled and tagged.
  • Start lme.service: Kicks off the start of LME service containers.

7.4 Folders, Permissions, and Service

  • /opt/lme will be owned by root. All LME services will run and execute as unprivileged users. The active LME configuration is stored in /opt/lme/config.

    • To access any file at /opt/lme/, you’ll need to make sure you’re in a root shell (e.g. sudo -i su) or you run whatever command you’re wanting to access in that directory as root (e.g. sudo ls /opt/lme/config).

  • Other relevant directories are listed here:

    • /root/.config/containers/containers.conf: LME will setup a custom Podman configuration for secrets management via Ansible Vault
    • /etc/lme: Storage directory for the master password and user password vault
    • /etc/lme/pass.sh: the master password file
    • /etc/containers/systemd: Directory where LME installs its quadlet service files
    • /etc/systemd/system: Directory where lme.service is installed

  • The master password will be stored in /etc/lme/pass.sh and owned by root, while service user passwords will be stored in /etc/lme/vault/

  • lme.service is a kick start systemd service. It will always succeed and is designed so that the other lme services can be stopped and restarted by stopping/restarting lme.service.

    • To stop all of LME:

      sudo -i systemctl stop lme.service

    • To restart all of LME:

      sudo -i systemctl restart lme.service

    • To start all of LME:

      sudo -i systemctl start lme.service

7.5 Other Post-Install Setup

A few final steps are required to complete your setup:

  • Configure Elastic Fleet
  • Address minor Wazuh issues (this will be automated in a future release)
  • Set up custom LME dashboards
  • Set up Wazuh’s dashboards
  • Enable a read-only user role for analysts to connect and query LME data

Luckily, we’ve included a post-install script to streamline these steps. Before running it, ensure your Podman containers are up and healthy by running the following command:

sudo -i podman ps --format "{{.Names}} {{.Status}}"

The expected output:

lme-elasticsearch Up 49 minutes (healthy)
lme-wazuh-manager Up 48 minutes
lme-kibana Up 36 minutes (healthy)
lme-fleet-server Up 35 minutes
Last modified July 3, 2025: Update troubleshooting.md (cddb826)