Downloading and Installing LME

LME now includes Ansible scripts to automate the installation process, making deployment faster and more efficient. Our installation guide video is coming soon. When the video is released, you will find the link to it here. These steps will guide you through setting up LME on your Ubuntu 22.04 server, ensuring a smooth and secure deployment.

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.

Please ensure you follow all the configuration steps required below.

Upgrading: If you are upgrading from an older version of LME to LME 2.0, please see our upgrade documentation.

Downloading LME:

The following steps assume you're starting from a downloaded or cloned directory of LME on your Ubuntu 22.04 server.

We suggest you install the latest release version of LME using the following commands:

1. Install Requirements

sudo apt update && sudo apt install curl jq unzip -y

2. Download and Unzip the latest version of LME This will add a path to ~/LME with all required files.

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 {})'

Developer Note: if you're looking to develop LME, its suggested you git clone rather than downloading, please see our DEV docs

Configuration

The configuration files are located in /config/. These steps will guide you through setting up LME

1. Certificates and Passwords

• instances.yml defines the certificates to be created.
• Shell scripts will initialize accounts and generate certificates. They run from the quadlet definitions lme-setup-accts and lme-setup-certs.

2. Podman Quadlet Configuration

• Quadlet configuration for containers is located in /quadlet/. These map to the root systemd unit files but execute as non-privileged users.

3. Environment Variables

• Only edit the /config/lme-environment.env file to set required environment variables.

*USER REQUIRED EDITS:* The only file users needs to touch is creating /config/lme-environment.env, which sets up the required environment variables.

This should be the IP address that your agents will use to connect to this server.

Get your IP address via the following command:

hostname -I | awk '{print $1}'

Setup the config via the following steps:

#change directory to ~/LME or whatever your download directory is above
cd ~/LME 
cp ./config/example.env ./config/lme-environment.env

In the new lme-environment.env file, update the following values:

#your host ip as found from the above command
IPVAR=127.0.0.1 #your hosts ip 

Automated Install

You can run this Ansible installer for a fully automated install.

sudo apt update && sudo apt install -y ansible
# cd ~/LME/lme-2-arch # Or path to your clone of this repo
ansible-playbook ./ansible/install_lme_local.yml

This assumes that you have the repo in ~/LME/.

If you don't, you can pass the CLONE_DIRECTORY variable to the playbook.

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

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, you can run it 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.

Steps performed in automated install:

1. Setup /opt/lme and check for sudo access. Configure other required directories/files.
2. Setup password information: Configures the password vault and other configuration for the service user passwords.
3. Setup Nix: nix is the open source package manager we use to install the latest version of podman.
4. Set service user passwords: Sets the service user passwords that are encrypted according to the security model.
5. Install Quadlets: Installs quadlet files in the directories described below to be setup as systemd services.
6. Setup Containers for root: The containers listed in $clone_directory/config/containers.txt will be pulled and tagged.
7. Start lme.service: Kicks off the start of LME service containers.

Notes on folders, permissions, and service:

1. /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)

2. 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

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

4. 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.

For example, 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