> For the complete documentation index, see [llms.txt](https://cybersec.th4ntis.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cybersec.th4ntis.com/lab-setup/ludus.md).

# Ludus

## About

[Ludus](https://docs.ludus.cloud/docs/intro/) 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](https://ludus.cloud/)
* [Docs](https://docs.ludus.cloud/docs/intro/)
* [Install Ludus](https://docs.ludus.cloud/docs/quick-start/install-ludus/)
* [Changelog](https://ludus.cloud/changelog)

## Requirements

Ludus does have specific system requirements to be used. I've highlighted some specifics.

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2F8UYKcQpxjZJllLGoKH7o%2Fimage.png?alt=media&amp;token=710b9255-dd79-4861-bc3e-a95effd457c2" alt=""><figcaption></figcaption></figure>

I'm installing mine on an HP EliteDesk DM running [Debian 13](https://www.debian.org/download)) 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
```

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FxPzpnGWxIw8CNB7A1wYb%2Fimage.png?alt=media&amp;token=04b7bd0b-d13c-426e-bf5d-1cf1d4233e72" alt=""><figcaption></figcaption></figure>

Now we install Ludus with

```
curl --proto '=https' --tlsv1.2 -sSf https://ludus.cloud/install | bash
```

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2F2Cra1mYvDQrEgKl1V7Sj%2Fimage.png?alt=media&amp;token=6962e822-210d-42d9-a48d-2f5ef7bbf14e" alt=""><figcaption></figcaption></figure>

We accept the license agreement

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FjppTpC04qJWK7MUHMsDN%2Fimage.png?alt=media&amp;token=e95af4f3-12fc-4772-b717-707849f616fd" alt=""><figcaption></figcaption></figure>

This will ask some questions, have you accept an EULA and go through some setup config. Most, if not all, can be kept default.

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FUmuNLOYsTQq3Smx456VX%2Fimage.png?alt=media&amp;token=499cd447-bd72-402a-8e42-aac04b830001" alt=""><figcaption></figcaption></figure>

This will also prompt you to make an admin user.

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FA6kCW0ERonSxumTtvtUQ%2Fimage.png?alt=media&amp;token=c5c3c8d1-4959-48dd-9459-1dbd02354ba4" alt=""><figcaption></figcaption></figure>

Then will ask if you're ready to install and proceed when you select yes.

{% hint style="info" %}
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.
{% endhint %}

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2Fv7SycxuNMafFGWyrMLgX%2Fimage.png?alt=media&amp;token=de25a0a9-9057-4554-8458-0305e040811c" alt=""><figcaption></figcaption></figure>

Once you see the following, it should be installed.

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FWUU4TemSjWBjc3DEb1DI%2Fimage.png?alt=media&amp;token=40cb83fb-856a-4c88-b0dd-77886be52b07" alt=""><figcaption></figcaption></figure>

We can view our install status, creds, and API key with

```
ludus-install-status
```

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FF9dmEwi0BvkrTeSb7o9b%2Fimage.png?alt=media&amp;token=edb92d3b-a312-43f3-91f3-a7c6726a69de" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If running this headless, to set the API key with:
{% endhint %}

```
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
```

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FlwypN4xwp0AtqQ4M6W0c%2Fimage.png?alt=media&amp;token=2627a792-2eb7-4a24-a56a-6e23a3e01614" alt=""><figcaption></figcaption></figure>

I'm only going to cover the official ludus source but you can find out more [here on their docs](https://docs.ludus.cloud/docs/using-ludus/sources/).

### Web UI

From the Web UI we can simply click on 'Sources' on the left and view, or add sources.

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2F66AIfOIEqyrOkjbDRemv%2Fimage.png?alt=media&amp;token=57d114c3-300f-4839-932a-9715308b9eb3" alt=""><figcaption></figcaption></figure>

To view the catalog from that source, just select the source.

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FL81Hbn8KWsa4arWPPdLa%2Fimage.png?alt=media&amp;token=513baa0a-1fac-4628-9aae-c8d44b2de953" alt=""><figcaption></figcaption></figure>

## Templates

### CLI

We can see what templates are included by default, and if they are built. To view this we run:

```
ludus templates list
```

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2F4sqC3bQ52sxXKw7R5XAm%2Fimage.png?alt=media&amp;token=5b6ba43c-db97-4b79-9558-e45ead97120a" alt=""><figcaption></figcaption></figure>

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
```

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FOuXXrtmA97JlQSZDkwQl%2Fimage.png?alt=media&amp;token=1267f3e5-d080-41e4-b1c7-f1eb52c0bc09" alt=""><figcaption></figcaption></figure>

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
```

{% hint style="info" %}
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.
{% endhint %}

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2F18VuXGaG8nkfMEBlusH0%2Fimage.png?alt=media&amp;token=d70582b8-46da-4126-8716-58452f34c7ed" alt=""><figcaption></figcaption></figure>

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
```

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FpAkCurA0u5t9JijQ3gvo%2Fimage.png?alt=media&amp;token=e62a0111-ed52-4873-b2ca-bc4dbfd15545" alt=""><figcaption></figcaption></figure>

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FxjtB4j78RNg5wnHyqf6C%2Fimage.png?alt=media&amp;token=645797ec-174c-4243-8b8a-206649a1f695" alt=""><figcaption></figcaption></figure>

I'm only covering what is included with the base ludus, but more info on Templates can be found [here on their docs](https://docs.ludus.cloud/docs/using-ludus/templates).

### WebUI

Selecting `Templates` on the side panel will show us current templates and their status.

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2F2ChhY9yMsbSUWux21xXW%2Fimage.png?alt=media&amp;token=ad137e7a-e91c-49b6-9c8a-be3747fe5ca9" alt=""><figcaption></figcaption></figure>

If we want to add more templates, we need to select `Sources` from the side panel then select our source.

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FufOfmXzL8lgZPOJ08DML%2Fimage.png?alt=media&amp;token=eb1cd8e1-596f-46f5-994a-0ba58d1887ba" alt=""><figcaption></figcaption></figure>

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.

{% hint style="info" %}
This will take some time, so step away for a few. This also may fail, but can be selected to be built again.
{% endhint %}

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FPxYVTROkHALSTYVV7cxj%2Fimage.png?alt=media&amp;token=78882f9a-ce20-4a6c-96d5-98ab534747e6" alt=""><figcaption></figcaption></figure>

## 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
```

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2Fww7cJxT22to9LfAVk0rg%2Fimage.png?alt=media&amp;token=df2eb1eb-8e57-4829-ac6c-2865cf3be319" alt=""><figcaption></figcaption></figure>

## Power

### CLI

```bash
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` .&#x20;

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FXQLPAx04j0EpjYoomQ0B%2Fimage.png?alt=media&amp;token=fbde1f69-9af6-4ed0-9ef1-416760e0432c" alt=""><figcaption></figcaption></figure>

Or we can click the three dots in the top right, go to power, and select power on/off.

<figure><img src="https://667808901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTdW22AGCceN8oUXfdlKI%2Fuploads%2FI2B3F8PSnXy4bLMTqIf8%2Fimage.png?alt=media&amp;token=ecb04577-a23c-4c35-863e-7f00cef4be7e" alt=""><figcaption></figcaption></figure>
