Sign in
By piernov in amt —

Open AMT Cloud Toolkit — Part 2: Installation

In this article we will be installing the Open AMT Cloud Toolkit stack on our server.

You can look at the Get Started guide in the official documentation for the installation and configuration steps, but we provide some additional details below.

Setup a Linux machine

This part is left to the reader. Our goal here is to obtain a working Docker environment, so you can use any machine with enough RAM (2 GiB) and free disk space (10 GiB). Note that the docker images are x86_64, you can try to rebuild them for a different architecture but this has not been tested.

We chose to create a Debian 12 virtual machine on a Proxmox server. Only the standard system utilities and the SSH server have been selected as part of the installation. Once this is done, install git and docker-compose, e.g.:

sudo apt install git docker-compose

Install Open AMT Cloud Toolkit

This is simply a matter of cloning the main repository recursively, the various services are referenced as git submodules and the main repository contains the docker-compose.yml file for deployment. here we choose version 2.13.0 (latest as the time of writing) but you can try a newer one if it is available:

cd /opt
sudo git clone https://github.com/open-amt-cloud-toolkit/open-amt-cloud-toolkit --branch v2.13.0 --recursive
cd /opt/open-amt-cloud-toolkit
sudo docker-compose pull

Configure Open AMT Cloud Toolkit

First, copy the .end.template file to .env in /opt/open-amt-cloud-toolkit/:

sudo cp .env.template .env

Then edit .env with nano for example, and set some required parameters:

MPS_COMMON_NAME=<server FQDN>
MPS_WEB_ADMIN_USER=admin
MPS_WEB_ADMIN_PASSWORD=<Web admin password>
MPS_JWT_SECRET=<JWT token>
POSTGRES_PASSWORD=<PostGreSQL databased password>

MPS_COMMON_NAME is the FQDN you want to use for the Open AMT Cloud Toolkit stack, e.g. amt.example.com.

Set the passwords and token to whatever you want, but we recommend generating and saving passwords in a password manager such as KeepassXC. MPS_WEB_ADMIN_PASSWORD will be used later on to log into the web interface. MPS_WEB_ADMIN_USER is the associated user.

Next, edit the kong.yaml file and replace the previously set JWT token:

jwt_secrets:
  - consumer: admin
    secret: "<JWT token>"

Relative URL configuration (optional)

If you have a single domain name shared for multiple services, you can setup Open AMT Cloud Toolkit to appear under a subdirectory such as /openamtcloudtoolkit/. The recommended setup is however to have a dedicated subdomain, so if you can have one, skip this part.

Edit the docker-compose.yml file and add /openamtcloudtoolkit to the 3 SERVER URLs:

services:
  webui:
    environment:
      RPS_SERVER: https://${MPS_COMMON_NAME}/openamtcloudtoolkit/rps
      MPS_SERVER: https://${MPS_COMMON_NAME}/openamtcloudtoolkit/mps
      VAULT_SERVER: https://${MPS_COMMON_NAME}/openamtcloudtoolkit/vault

Then, edit sample-web-ui/Dockerfile to add the --base-href parameter to the npm run build command:

RUN npm run build -- --configuration=production --base-href=/openamtcloudtoolkit/

Finally, edit sample-web-ui/src/app/core/navbar/navbar.component.html to fix the logo path:

<img alt="logo" style="margin:10px 0" height="35" src="assets/logo.png">

You can now rebuild the webui Docker image:

sudo docker-compose build webui

Reverse proxy configuration (optional)

While you can access the Open AMT Cloud Toolkit web UI directly, you may want to run it behind a reverse proxy for reasons such as:

  • Virtual host
  • Relative URL
  • HTTPS with correct certificates instead of changing the Open AMT Cloud Toolkit ones

Below is an Apache 2 configuration file so that an Open AMT Cloud Toolkit stack running on a different server (10.0.0.2) is accessible under the /openamtcloudtoolkit/ subdirectory:

SSLProxyEngine on
SSLProxyVerify none
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off

RewriteEngine On
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule ^/openamtcloudtoolkit/?(.*)           wss://10.0.0.2/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]
RewriteRule ^/openamtcloudtoolkit/?(.*)           https://10.0.0.2/$1 [P,L]

Note that ProxyPass cannot be used here since HTTPS and WSS requests need to be routed seperately.

Additionally, when connecting to the Open AMT Cloud Toolkit web server, certificate check is disabled since the certificate is self-signed and may have an invalid domain name. As it is internal only, there is no concern of man-in-the-middle attack here.

Finally, Open AMT Cloud Toolkit web server is exposed on port 443 by default which may conflict with other services running on the same machine, this can be corrected in docker-compose.yml as needed and adjusted in the above Apache 2 configuration.

Configure production vault

In order for the certificates and keys to be saved after restarting the server, the vault must be set to production mode. If you do not perform this step, after the server is restarted, you will need to create a new profile and re-enroll all clients which is not desirable.

Edit the vault service in docker-compose.yml to mount volumes for the persistent data:

services:
  vault:
    volumes:
      - private-volume:/vault/data:rw
      - ./vault:/vault/config:rw
    entrypoint: vault server -config=/vault/config/vault.json

Create a directory for the vault configuration:

sudo mkdir vault

And create a vault/vault.json file with the following content:

{
    "storage":{
        "file":{
            "path":"/vault/data"
        }
    },
    "listener":{
        "tcp":{
            "address":"0.0.0.0:8200",
            "tls_disable": "true"
        }
    },
    "default_lease_ttl":"168h",
    "max_lease_ttl":"0h",
    "ui":true,
    "log_level":"Debug"
}

Start the vault service:

sudo docker-compose up -d vault

Open the vault web interface in a web browser: http://localhost:8200/

Set key shares to 5, key threshold to 3 and click Initialize.

Download the key backup file and make sure to save it in a safe and secure place, you will need the keys every time the vault is restarted. You can save them in KeepassXC for example.

Now unseal the vault, for that you will need to enter 3 of the 5 keys you just saved successively.

To log into the web interface, you need to enter the root token also from the file you saved previously.

Once logged in, click the Enable New Engine + button, select KV type, keep the default settings and confirm by clicking Enable Engine.

Finally, edit the .env file and set the root token (the same you used to log in to the web interface):

SECRETS_PATH=kv/data/
VAULT_TOKEN=<Vault root token>

You can now stop the vault Docker service (it needs to be restarted to apply the new configuration):

sudo docker-compose down vault

Persistent database

In order for the database to be persistent across reboots or restart of the container, a Docker volume mount must be created.

Edit the db service in docker-compose.yml to mount volumes for the persistent data:

services:
  db:
    volumes:
      - ./data:/docker-entrypoint-initdb.d
      - ./data/db:/var/lib/postgresql/data

Start Open AMT Cloud Toolkit

Finally, you can start all the services:

sudo docker-compose up -d

You need to unseal the vault again after a restart of the service, so open the vaul web interface again and enter 3 of the vault keys: http://localhost:8200/

You can now log into the Open AMT Cloud Toolkit web UI at https://amt.example.com/ or https://example.com/openamtcloudtoolkit/ with the relative URL setup. The credentials are the MPS_WEB_ADMIN_* set in the .env file.

Configure firewall/NAT

If the Open AMT Cloud Toolkit machine is behind a firewall or a NAT as seen by the clients, TCP port 4433 must be opened and redirected so that clients can connect directly to the MPS (Management Presence Server) service.

Creating AMT profiles

In the next article, we will see how to create a CCM (Client Control Mode) profile in preparation of the enrollment of a device.

Subscribe to piernov

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.
jamie@example.com
Subscribe