From 0683e4af4abc534c960519e6639038d6f30a249c Mon Sep 17 00:00:00 2001
From: Ralph Schmieder <rschmied@cisco.com>
Date: Tue, 20 May 2025 21:19:25 +0200
Subject: [PATCH] Add autostart script and documentation (#63)

Add a script to be deployed on CML that allows labs marked with "(autostart)" in their descriptions to be started as soon as the CML server boots up.
---
 scripts/cml-autostart/README.md    |  87 ++++++++++++++++++++
 scripts/cml-autostart/autostart.sh | 124 +++++++++++++++++++++++++++++
 2 files changed, 211 insertions(+)
 create mode 100644 scripts/cml-autostart/README.md
 create mode 100644 scripts/cml-autostart/autostart.sh

diff --git a/scripts/cml-autostart/README.md b/scripts/cml-autostart/README.md
new file mode 100644
index 0000000..a67c9b9
--- /dev/null
+++ b/scripts/cml-autostart/README.md
@@ -0,0 +1,87 @@
+# README
+
+This script adds lab autostart capability to CML. It's implemented in a very
+simple way without any additional dependencies to install.
+
+> [!WARNING]
+>
+> It's important to understand that this mechanism is very simple and also very
+> insecure. You need to provide a password for a user of the system in clear
+> text as part of the configuration. If you are not comfortable to provide a
+> password that is stored in clear text on the server, then this solution is not
+> for you. Also, if the system uses external authentication via LDAP, then this
+> solution is likely not for you.
+
+## Installation
+
+Simply copy the `autostart.sh` script to the CML server. Either via scp or
+simply copying/pasting it into a file on the CML server (for example, via the
+Cockpit terminal). From there, run the script which then installs it:
+
+```plain
+$ sudo bash ./autostart.sh
+installing defaults     ✅
+installing script       ✅
+installing service unit ✅
+*****************************************************
+* ⚠️ IMPORTANT! ⚠️                                  *
+* you need to ensure that you change the username   *
+* and password for a user of the system that can    *
+* start the labs in /etc/default/cml-autostart      *
+*                                                   *
+* Add the string "(autostart)" to the description   *
+* of each lab that you wish to start automatically. *
+*****************************************************
+$
+```
+
+Then configure the defaults (e.g. change the password) as outlined in the next
+section.
+
+## Configuration
+
+The autostart script basically looks at all labs that the user has access to
+(users with admin rights will see all labs, the script passes the "show_all"
+flag so if a non-admin user runs this, they will see all labs they have access
+to).
+
+A lab that has `(autostart)` in the lab description will be started when the
+system comes up and is ready.
+
+The string that triggers the autostart is configured in the `TITLE_REGEX`
+variable. It is treated as a regular expression.
+
+Configuration (with defaults) is done in `/etc/default/cml-autostart`:
+
+```bash
+USERNAME="admin"
+PASSWORD="password-that-needs-to-be-changed"
+TITLE_REGEX="\(autostart\)"
+```
+
+After installation, at least the password needs to be changed.
+
+> [!NOTE]
+>
+> The user configured should be a general admin user that has visibility to all
+> potential labs that might need to be auto-started.
+
+## Troubleshooting
+
+If labs do not start as expected, check the service unit output:
+
+```bash
+sudo systemctl status cml-autostart.service
+```
+
+More details are available in the journal:
+
+```bash
+sudo journalctl -u cml-autostart.service
+```
+
+If that's not sufficient to pin-point the issue, enable debugging in the script
+by removing the comment in `/usr/local/bin/cml-autostart.sh` from the line that
+says `# set -x`.  If the script has been changed and debugging is enabled then
+the service can be triggered again by `systemctl start cml-autostart.service`.
+Then show the status and / or look at the journal output again.
diff --git a/scripts/cml-autostart/autostart.sh b/scripts/cml-autostart/autostart.sh
new file mode 100644
index 0000000..f1a77c9
--- /dev/null
+++ b/scripts/cml-autostart/autostart.sh
@@ -0,0 +1,124 @@
+#!/bin/bash
+
+set -e
+
+ensure_dir() {
+    local install_dir="$1"
+    if ! test -d "$install_dir"; then
+        echo "Error: $install_dir isn't there"
+        exit 1
+    fi
+}
+
+install_default() {
+    local install_dir="/etc/default"
+    ensure_dir $install_dir
+    cat >"$install_dir/cml-autostart" <<EOF
+USERNAME="admin"
+PASSWORD="password-that-needs-to-be-changed"
+TITLE_REGEX="\(autostart\)"
+EOF
+    chown root:root "$install_dir/cml-autostart"
+    chmod 0600 "$install_dir/cml-autostart"
+}
+
+install_script() {
+    local install_dir="/usr/local/bin"
+    ensure_dir $install_dir
+    cat >"$install_dir/cml-autostart.sh" <<EOF
+#!/bin/bash
+
+# set variables
+HOST="ip6-localhost"
+# the /etc/default/cml-autostart needs to define and these need to be present
+# in the environment!
+# - USERNAME
+# - PASSWORD
+# - TITLE_REGEX
+
+# set -x
+
+API="https://\${HOST}/api/v0"
+
+# wait until the system is ready
+until [ "true" = "\$(curl -skX GET \$API/system_information | jq -r .ready)" ]; do
+  echo "Waiting for controller to be ready..."
+  sleep 5
+done
+
+# get authentication token
+TOKEN=\$(curl -skX POST "\${API}/authenticate" \\
+        -H "Content-Type: application/json" \\
+        -d '{"username":"'\${USERNAME}'","password":"'\${PASSWORD}'"}' |
+        jq -r .)
+  
+# get all labs
+LABS=\$(curl -skX GET "\${API}/labs?show_all=true" \\
+            -H "Authorization: Bearer \${TOKEN}")
+  
+while read -r lab; do
+  labinfo=\$(curl -skX GET "\${API}/labs/\${lab}" \\
+            -H "Authorization: Bearer \${TOKEN}")
+  description=\$(echo \$labinfo | jq -r '.lab_description')
+  title=\$(echo \$labinfo | jq -r '.lab_title')
+  if [[ "\${description}" =~ \${TITLE_REGEX} ]]; then
+    curl -skX PUT "\${API}/labs/\${lab}/start" \\
+    -H "Authorization: Bearer \${TOKEN}"
+    echo "Lab '\${title}' (ID: \${lab}) start initiated"
+  fi
+done <<<\$(echo \$LABS | jq -r '. | join("\n")')
+exit
+EOF
+    chown root:root "$install_dir/cml-autostart.sh"
+    chmod a+x "$install_dir/cml-autostart.sh"
+}
+
+install_service_unit() {
+    local install_dir="/etc/systemd/system"
+    ensure_dir $install_dir
+    cat >"$install_dir/cml-autostart.service" <<EOF
+[Unit]
+Description=Autostart CML Labs based on description text
+After=network.target
+After=virl2.target
+  
+[Service]
+Type=oneshot
+EnvironmentFile=/etc/default/cml-autostart
+ExecStart=/usr/local/bin/cml-autostart.sh
+User=virl2
+  
+[Install]
+WantedBy=multi-user.target
+EOF
+    chown root:root "$install_dir/cml-autostart.service"
+    systemctl daemon-reload
+    systemctl &>/dev/null enable cml-autostart.service
+}
+
+if [[ $EUID -ne 0 ]]; then
+    echo "This script must be run as root." >&2
+    exit 1
+fi
+
+echo -n "installing defaults"
+install_default
+echo -e "\t✅"
+echo -n "installing script"
+install_script
+echo -e "\t✅"
+echo -n "installing service unit"
+install_service_unit
+echo -e "\t✅"
+
+cat <<EOF
+*****************************************************
+* ⚠️ IMPORTANT! ⚠️                                  *
+* you need to ensure that you change the username   *
+* and password for a user of the system that can    *
+* start the labs in /etc/default/cml-autostart      *
+*                                                   *
+* Add the string "(autostart)" to the description   *
+* of each lab that you wish to start automatically. *
+*****************************************************
+EOF