Updated Install Ludus Guide
With some new and awesome changes within Ludus, I wanted to create a new post covering what it is, and using it. I will be making a post about installing GOAD shortly.
Ludus is a system to build easy to use cyber environments, or “ranges” for testing and development. Built on Proxmox, it enables advanced automation while still allowing easy manual modifications or setup of virtual machines and networks. It is implemented as a server that runs Packer and Ansible to create templates and deploy complex cyber environments from a single configuration file. It is accessed via the Ludus CLI (client), the WebUI, or the Proxmox web interface. Normal users should not need to access Ludus via SSH.
Links
Homepage Docs Install Ludus Changelog
Requirements
Ludus does have specific system requirements to be used. I’ve highlighted some specifics.
I’m installing mine on an HP EliteDesk DM running Debian 13) with:
- Intel i5-8500T@ 3.50 GHz
- 32GB RAM
- 1TB NVMe SSD
Install
To install ludus we will need to be the root user on our Debian machine
su -
Then we install pre requisites
apt update && apt install curl sudo ca-certificates
Now we install Ludus with
curl --proto '=https' --tlsv1.2 -sSf https://ludus.cloud/install | bash
We accept the license agreement
This will ask some questions, have you accept an EULA and go through some setup config. Most, if not all, can be kept default.
This will also prompt you to make an admin user.
Then will ask if you’re ready to install and proceed when you select yes.
[!note] This will take some time, so step away for a few. The machine may restart once or twice as well. With the newest install, it pauses for the reboot as to not drop the SSH connection.
Once you see the following, it should be installed.
We can view our install status, creds, and API key with
ludus-install-status
[!note] If running this headless, don’t forget to set the API key with
export LUDUS_API_KEY='API-KEY-HERE'
Adding License Key
If you get a license key or an NFR (Not For Resale) license, we we can add it during install or after install. Your key should look like:
46C1CA-B11C52-80E9E7-19E436-FDDG1B-V3
You will need to add the key to your Ludus Config file. Mine was under the default of /opt/ludus/config.yml. Inside there will be a spot for license_key: . Without a key it will be community. Remove community and paste in your key and save.
Once that is done we run the following to set the Web URL
LUDUS_URL=https://LUDUS_MACHINE_IP:8080
Then we restart the ludus service
systemctl restart ludus
systemctl restart ludus-admin
Sources
CLI
To view current sources we run:
ludus source list
We can see what is within a source such as blueprint, templates, and ansible, To view the catalog within a selected source we run:
ludus source list ludus-source-bsl --catalog
I’m only going to cover the official ludus source but you can find out more here on their docs.
Web UI
From the Web UI we can simply click on ‘Sources’ on the left and view, or add sources.
To view the catalog from that source, just select the source.
Templates
CLI
We can see what templates are included by default, and if they are built. To view this we run:
ludus templates list
To add a template we run
ludus source add ludus-source-bsl --templates TEMPLATE-NAME
Eg. Debian 13
ludus source add ludus-source-bsl --templates debian-13-x64-server-template
To build a template we run:
ludus templates build -n debian-13-x64-server-template
or we can build them all with:
ludus templates build
[!note] This will take some time, so step away for a few. The machine may restart once or twice as well. With the newest install, it pauses for the reboot as to not drop the SSH connection.
To check on the status, this will show us where it’s at in the process and when it’s finished. We can run:
ludus templates logs -f
I’m only covering what is included with the base ludus, but more info on Templates can be found here on their docs.
WebUI
Selecting Templates on the side panel will show us current templates and their status.
If we want to add more templates, we need to select Sources from the side panel then select our source.
Within here we can see blueprints to build, templates, and ansible roles. Selecting Templates, we can check the boxes of the templates we want to add and click install.
[!note] This will take some time, so step away for a few. This also may fail, but can be selected to be built again.
Ranges
CLI
Once your API key exported
export LUDUS_API_KEY='USER-API-KEY'
See what ranges you have access to, note the RANGE ID
ludus range accessible
View the status of the range
ludus range status -r RANGE_ID
Power
CLI
ludus power on/off --name all -r RANGE_ID # Power on/off all range VMs
WebUI
To power on/off the VMs, we either right-click anywhere within the range editor and select power on/off All VMs .
Or we can click the three dots in the top right, go to power, and select power on/off.
Conclusion
That’s it for now covering he basics of what Ludus is, installing it and the common usage. Be sure to check out my guide on installing Game of Active Directory for a great AD environment to test TTPs, APTs, and other tooling against.