# Installing the AIMS VM Agent

The AIMS agent is a small background service that reports this VM's health and
status to AIMS. It runs automatically at boot and restarts itself if it crashes.

Installation is one command. The installer checks and installs everything it
needs (Python, venv support, dependencies) — you do **not** need to prepare
anything on the VM first.

---

## Before you start

Your AIMS administrator gives you exactly **two values**:

| What | Looks like | Notes |
|---|---|---|
| **AIMS URL** | `https://aims.example.com` | Base URL only, no trailing path |
| **Asset key** | `umSQLAECjWV60Bd…` | Unique to this VM — do not reuse it on another VM |

Everything else (where to fetch the agent package from) is already baked into
the installer you download below.

**Requirements the installer handles for you:** Python 3.9+, `python3-venv`,
`pip`, the agent's Python dependencies. If Python is missing it installs it.

**What you need to have:** administrator/root on the VM, and network access from
the VM to (a) the package server `https://aims-assets.astratinvest.com`,
(b) your AIMS URL, and (c) PyPI (or an internal package index).

---

## Linux

Run these three commands as a user with `sudo`:

```bash
curl -fsSL -o install.sh https://aims-assets.astratinvest.com/install.sh
chmod +x install.sh
sudo ./install.sh --url <AIMS_URL> --asset-key <ASSET_KEY>
```

Substituting your two values, that middle line looks like:

```bash
sudo ./install.sh --url https://aims.example.com --asset-key umSQLAECjWV60Bd…
```

You should finish with:

```
✓ AIMS VM agent installed and started (runs on boot, restarts on crash).
```

**If `curl` is not installed:** `sudo apt install curl` (Debian/Ubuntu) or
`sudo dnf install curl` (RHEL/Fedora). If you have `wget` instead, use
`wget -O install.sh https://aims-assets.astratinvest.com/install.sh`.

### Checking it

```bash
systemctl status aims-vm-agent      # should say "active (running)"
journalctl -u aims-vm-agent -f      # live logs; Ctrl-C to exit
```

### Starting / stopping it

```bash
sudo systemctl stop aims-vm-agent            # stop now; still starts at boot
sudo systemctl start aims-vm-agent
sudo systemctl restart aims-vm-agent         # e.g. after editing config.ini

sudo systemctl disable --now aims-vm-agent   # stop now AND never at boot
sudo systemctl enable  --now aims-vm-agent   # start now AND at boot
```

### Uninstalling

Run these **one line at a time** — each is complete on its own:

```bash
sudo systemctl disable --now aims-vm-agent
sudo rm -f /etc/systemd/system/aims-vm-agent.service
sudo rm -rf /opt/aims-vm-agent
sudo rm -rf /etc/aims-vm-agent
sudo systemctl daemon-reload
```

> **Check before you press Enter.** If a `rm -rf` line ever arrives wrapped or
> truncated by your terminal, do not run it — retype it. A truncated
> `rm -rf … /etc/systemd/system/aims-vm-agent.service` that stops at
> `/etc/systemd/` deletes every service-enablement symlink on the machine.

---

## Windows

Open PowerShell **as Administrator** ("Run as administrator"), then:

```powershell
Invoke-WebRequest -UseBasicParsing https://aims-assets.astratinvest.com/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Url <AIMS_URL> -AssetKey <ASSET_KEY>
```

You should finish with:

```
OK - AIMS VM agent installed and started (Scheduled Task 'AIMSVMAgent', runs as SYSTEM on boot).
```

### Checking it

```powershell
Get-ScheduledTaskInfo AIMSVMAgent
Get-ScheduledTask AIMSVMAgent | Select-Object State    # should be "Running"
```

### Starting / stopping it

Elevated PowerShell:

```powershell
Stop-ScheduledTask  -TaskName AIMSVMAgent
Start-ScheduledTask -TaskName AIMSVMAgent

Disable-ScheduledTask -TaskName AIMSVMAgent   # won't run at boot
Enable-ScheduledTask  -TaskName AIMSVMAgent
```

### Uninstalling

```powershell
Unregister-ScheduledTask -TaskName AIMSVMAgent -Confirm:$false
Remove-Item -Recurse -Force C:\aims-vm-agent
```

---

## Options

Both installers accept the same optional settings. You normally need none of
them.

| Linux flag | Windows parameter | Default | What it does |
|---|---|---|---|
| `--interval <sec>` | `-Interval <sec>` | `60` | How often to report |
| `--verify-tls <true\|false>` | `-VerifyTls <true\|false>` | `true` | Set `false` only for a self-signed AIMS cert |
| `--lan-check-host <host>` | `-LanCheckHost <host>` | *(none)* | Gateway/host to probe for the LAN check |
| `--internet-check-host <host>` | `-InternetCheckHost <host>` | `1.1.1.1` | Host used for the internet check |
| `--aims-timeout <sec>` | `-AimsTimeout <sec>` | `10` | AIMS request timeout |

Example:

```bash
sudo ./install.sh --url https://aims.example.com --asset-key <KEY> --interval 30 --lan-check-host 192.168.1.1
```

---

## Stopping the agent shows the VM as down

This is expected, not a fault. AIMS decides a VM is down purely from missing
reports: once the agent has been silent for **3 report intervals** (3 minutes at
the default 60s interval), the VM turns red and raises a Critical alert. Starting
the agent again clears both on its next report.

So before any planned reboot or maintenance, ask your AIMS administrator to switch
the VM to **Maintenance mode** in the portal — reports and history keep flowing,
but no alert is raised.

---

## The agent blocks shutdown/reboot outside maintenance mode

To enforce the step above, the agent runs a **shutdown guard**: while the VM is
**not** in maintenance mode, it blocks OS shutdown and reboot — `shutdown`/`reboot`
and the Start-menu / desktop shutdown options are refused (on Linux the systemd
shutdown targets are masked; on Windows the "Shut down the system" right is removed
for everyone but SYSTEM). This applies to standard *and* administrator/root users.

The intended workflow is simply: **enable Maintenance mode in AIMS, wait a few
seconds for the agent's next report, then reboot.** Turning maintenance off again
re-arms the guard.

It is a guardrail, not a hard lock — an administrator/root can still force it
(Linux `systemctl unmask … && reboot` or `systemctl poweroff -f`; Windows re-grant
the right), and a hypervisor "Power off" always works. To disable it on a host, set
`enforce_shutdown_guard = false` in `config.ini` and restart the agent.

---

## Re-running and upgrading

Running the installer again is safe. It stops the agent, replaces the code with
the current version from the package server, reinstalls dependencies, and starts
it again. Use the same command to **upgrade** to a new agent release, or to
**repair** an install that failed partway through.

---

## Troubleshooting

**`sudo: ./install.sh: command not found`**
The file isn't in your current directory, or isn't executable. Check with `ls -l
install.sh`, then `chmod +x install.sh`. If it exists and you still get this,
the file has Windows line endings — run `sed -i 's/\r$//' install.sh`, or just
use `sudo bash install.sh --url … --asset-key …`.

**`curl: (23) client returned ERROR on write`**
You have the sandboxed snap build of curl, which cannot write everywhere.
Install the system one: `sudo snap remove curl && sudo apt install curl`. (The
installer itself already avoids snap curl; this only affects the first download
above.)

**Download fails / "the downloaded file is not a zip"**
The VM cannot reach the package server, or the server returned an error page.
Open `https://aims-assets.astratinvest.com/aims-vm-agent.zip` in a browser on
the VM to see what it actually serves, and check any firewall between the VM and
that host.

**"dependency install failed — check this VM can reach PyPI"**
The VM has no route to `pypi.org`. Ask your administrator for an internal
package index, or allow outbound HTTPS to PyPI.

**Installed, but the service is not running**
Almost always a wrong AIMS URL or a wrong/expired asset key. Check the logs
(`journalctl -u aims-vm-agent -n 50` on Linux) and confirm both values with your
administrator. Fix them by re-running the installer with the corrected values.

**Anything else**
Send your administrator the full output of the installer plus, on Linux,
`journalctl -u aims-vm-agent -n 50 --no-pager`.

---

## What gets installed

| | Linux | Windows |
|---|---|---|
| Agent code | `/opt/aims-vm-agent/` | `C:\aims-vm-agent\` |
| Config (contains your asset key) | `/etc/aims-vm-agent/config.ini` (mode 600) | `C:\aims-vm-agent\config.ini` (SYSTEM + Admins only) |
| Runs as | systemd service `aims-vm-agent`, as root | Scheduled Task `AIMSVMAgent`, as SYSTEM |
| Starts at boot | yes | yes |
| Restarts on crash | yes (after 5s) | yes (after 1 min) |