xiidcorporation/commander

•Updated 3 months ago

Xiid's Commander is used to define Terniion SealedTunnel connections and process restrictions

Image

1.7K

xiidcorporation/commander repository overview

⁠Xiid Commander Container

A production-ready containerized deployment of the Xiid Commander for Linux, supporting the AMD64 (x86_64) architecture. This image provides a seamless way to run the Commander in containerized environments including Docker, Podman, and Kubernetes.

NOTE: The Commander must have persistent, non-network storage. If ephemeral storage is used, and the container/pod running the Commander along with its associated storage is torn down and recreated, the entire Terniion environment will be lost and is likely unrecoverable. Read the Storage Requirements⁠ section for more information.

For information on running and linking multiple Commanders, see the full Xiid Documentation⁠.

⁠Quick Start

The instructions in this Quick Start are appropriate for quick testing or local deployment and evaluation of the Commander in a development or Proof of Concept (PoC) environment.

For production environments, see the Production Deployment⁠ section.

docker run -d -p 10466:10466 -e XIID_ACTIVATION_CODE=your_activation_code_here xiidcorporation/commander:latest

Replace your_activation_code_here with your valid Xiid Commander activation code.

To then configure your Commander, access the Commander Portal at exposed port 10466 (HTTPS).

To shell into the container for testing/debugging, use:

docker run -it -e XIID_ACTIVATION_CODE=your_activation_code_here xiidcorporation/commander:latest /bin/bash

⁠Prerequisites

Activation Code: A valid Xiid Commander activation code from an Xiid Connector is required to run this container. Contact Xiid for additional assistance.
Container Runtime: Docker, Podman, or any OCI-compatible container runtime
Architecture: AMD64 (x86_64)

⁠Usage

⁠Basic Deployment

Run the Commander as a standalone container, replacing 4.0.1 with latest or a specific, tagged version number:

docker run -d -p 10466:10466 -e XIID_ACTIVATION_CODE=your_activation_code_here xiidcorporation/commander:latest

The container will:

Install the Commander with your provided activation code
Start the Commander service
Error if there is an existing Commander installation under a different activation code to prevent accidental data loss
(>=v4.0.2) Upgrade the Commander if already activated with the same code

⁠Specifying Architecture

To explicitly specify the platform:

# For AMD64/x86_64
docker run -d -p 10466:10466 --platform linux/amd64 -e XIID_ACTIVATION_CODE=your_activation_code_here xiidcorporation/commander:latest

⁠Production Deployment

The Commander locally stores its configurations in an encrypted database, including all STLinks, mappings and bindings, user accounts, routes, and other key Terniion components.

Special care must be taken in production environments to ensure consistency. Specifically, the files at paths /opt/Xiid and /etc/xdg/Xiid must be persisted and regularly backed up.

Additionally, your Terniion deployment is only as safe as your Commander deployment. If you expose the Commander and its portal (at port 10466) to the public internet, you are at risk.

At a minimum, after initial configuration, close all inbound access to the Commander from the public internet and access it via the STLink⁠ (for which we have a container image⁠ ready to go)!

⁠Storage Requirements

Ensure that the storage backing the Commander is not ephemeral, as the Commander will not function and the entire Terniion environment will be lost and is likely unrecoverable if the storage is lost.

Further, the storage for the /etc/xdg/Xiid path must not be Network File System (NFS). This means, for example, that Amazon EFS is not a valid storage option. This is a requirement of the Commander's underlying database engine.

⁠AWS ECS Task Definition Example

Below is a working configuration of the Commander deployed with persistent storage, running on an EC2 ECS cluster and using EBS volumes for persistence. Ensure that frequent backups are taken of the EBS volume and that protection is enabled so that the volume and associated Commander configurations are not lost if the EC2 instance is terminated.

{
    "taskDefinitionArn": "<your_task_definition_arn>",
    "containerDefinitions": [
        {
            "name": "Xiid-Commander",
            "image": "xiidcorporation/commander",
            "cpu": 2048,
            "memory": 8192,
            "memoryReservation": 8192,
            "portMappings": [
                {
                    "name": "commanderportal",
                    "containerPort": 10466,
                    "hostPort": 10466,
                    "protocol": "tcp",
                    "appProtocol": "http"
                }
            ],
            "essential": true,
            "environment": [
                {
                    "name": "XIID_ACTIVATION_CODE",
                    "value": "<your activation code goes here>"
                }
            ],
            "environmentFiles": [],
            "mountPoints": [
                {
                    "sourceVolume": "OptComm",
                    "containerPath": "/opt/Xiid",
                    "readOnly": false
                },
                {
                    "sourceVolume": "XdgComm",
                    "containerPath": "/etc/xdg/Xiid",
                    "readOnly": false
                }
            ],
            "volumesFrom": [],
            "ulimits": [],
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-group": "/ecs/Xiid-Commander",
                    "awslogs-create-group": "true",
                    "awslogs-region": "us-west-2",
                    "awslogs-stream-prefix": "ecs"
                },
                "secretOptions": []
            },
            "systemControls": []
        }
    ],
    "family": "Xiid-Commander",
    "executionRoleArn": "arn:aws:iam::<your IAM account ID>:role/ecsTaskExecutionRole",
    "networkMode": "bridge",
    "revision": 28,
    "volumes": [
        {
            "name": "OptComm",
            "host": {
                "sourcePath": "/ecs-data/commander/opt-xiid"
            }
        },
        {
            "name": "XdgComm",
            "host": {
                "sourcePath": "/ecs-data/commander/xdg-xiid"
            }
        }
    ],
    "status": "ACTIVE",
    "requiresAttributes": [
        {
            "name": "com.amazonaws.ecs.capability.logging-driver.awslogs"
        },
        {
            "name": "ecs.capability.execution-role-awslogs"
        },
        {
            "name": "com.amazonaws.ecs.capability.docker-remote-api.1.19"
        },
        {
            "name": "com.amazonaws.ecs.capability.docker-remote-api.1.21"
        },
        {
            "name": "com.amazonaws.ecs.capability.docker-remote-api.1.18"
        },
        {
            "name": "com.amazonaws.ecs.capability.docker-remote-api.1.29"
        }
    ],
    "placementConstraints": [],
    "compatibilities": [
        "EC2"
    ],
    "requiresCompatibilities": [
        "EC2"
    ],
    "cpu": "2048",
    "memory": "8192",
    "runtimePlatform": {
        "cpuArchitecture": "X86_64",
        "operatingSystemFamily": "LINUX"
    },
    "registeredAt": "2026-03-27T05:23:22.166Z",
    "registeredBy": "arn:aws:iam::<your IAM account ID>:user/xiidalex",
    "enableFaultInjection": false,
    "tags": []
}

⁠Kubernetes Deployment (EKS Example)

⁠Step 1: Deploy the Commander

Deploy the Commander with persistent storage. The Commander must be running and configured before you can generate activation codes for STLink sidecars.

The slimmed-down example below uses a PersistentVolumeClaim backed by block storage (e.g., AWS EBS via the gp2 StorageClass, or any CSI driver that provides block-level storage). Do not use NFS-based storage (e.g., Amazon EFS) for the /etc/xdg/Xiid path — see Storage Requirements⁠.

Additionally, for this EKS-based sample, ensure that vpc-cni, coredns, kube-proxy, aws-ebs-csi-driver, and eks-pod-identity-agent add-ons are installed. Also, make sure that you are using an x86 Node Group that also has the AmazonEBSCSIDriverPolicy policy attached to the Node Group's IAM Role.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: commander-opt-xiid
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: gp2  # Change this to your cluster's block storage class
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: commander-xdg-xiid
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: gp2  # Change this to your cluster's block storage class
  resources:
    requests:
      storage: 5Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: xiid-commander
spec:
  replicas: 1
  strategy:
    type: Recreate  # Ensures the PVC is released before the new pod starts
  selector:
    matchLabels:
      app: xiid-commander
  template:
    metadata:
      labels:
        app: xiid-commander
    spec:
      containers:
        - name: xiid-commander
          image: xiidcorporation/commander:latest
          startupProbe:
            tcpSocket:
              port: 10466
            periodSeconds: 5
            failureThreshold: 24
          ports:
            - containerPort: 10466
              protocol: TCP
          env:
            - name: XIID_ACTIVATION_CODE
              value: #<- Insert your Commander Activation Code here
          volumeMounts:
            - name: opt-xiid
              mountPath: /opt/Xiid
            - name: xdg-xiid
              mountPath: /etc/xdg/Xiid
      volumes:
        - name: opt-xiid
          persistentVolumeClaim:
            claimName: commander-opt-xiid
        - name: xdg-xiid
          persistentVolumeClaim:
            claimName: commander-xdg-xiid
---
apiVersion: v1
kind: Service
metadata:
  name: xiid-commander
spec:
  selector:
    app: xiid-commander
  ports:
    - port: 10466
      targetPort: 10466
      protocol: TCP
  type: LoadBalancer  # This exposes the Commander Portal on 10466 via an AWS NLB. This is dangerous and is only for initial configuration!

Once the Commander is running, find the load balancer's DNS name:

kubectl get svc xiid-commander

Then access the Commander Portal at https://<EXTERNAL-IP-or-DNS>:10466 to complete initial configuration and generate STLink activation codes.

After initial configuration, delete the LoadBalancer Service as soon as possible by applying Step 2, which switches the Service to ClusterIP. From that point, access the Commander exclusively through an STLink to minimize exposure.

⁠Step 2: Add an STLink Sidecar to the Commander

Once the Commander is configured via the Portal, generate an STLink activation code for the Commander itself, adding a Mapping⁠ to the Commander Portal. Then update the Commander deployment from Step 1 to include an STLink sidecar. This allows secure access to the Commander Portal through the STLink. Once you've added the sidecar, you can then configure a Binding⁠ to access the Commander Portal from your client machine.

Once you've confirmed that the Binding is working, delete the LoadBalancer Service by switching to ClusterIP. At this point, you can access the Commander exclusively through an STLink, and you can even go as far as to remove all public internet access to your Kubernetes cluster entirely.

The STLink sidecar requires NET_ADMIN capability to enable binding to any address in the 127.0.0.0/8 range for its dynamic loopback bindings.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: commander-opt-xiid
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: gp2  # Change this to your cluster's block storage class
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: commander-xdg-xiid
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: gp2  # Change this to your cluster's block storage class
  resources:
    requests:
      storage: 5Gi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: stlink-opt-xiid
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: gp2  # Change this to your cluster's block storage class
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: stlink-xdg-xiid
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: gp2  # Change this to your cluster's block storage class
  resources:
    requests:
      storage: 5Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: xiid-commander
spec:
  replicas: 1
  strategy:
    type: Recreate  # Ensures the PVC is released before the new pod starts
  selector:
    matchLabels:
      app: xiid-commander
  template:
    metadata:
      labels:
        app: xiid-commander
    spec:
      containers:
        - name: xiid-commander
          image: xiidcorporation/commander:latest
          startupProbe:
            tcpSocket:
              port: 10466
            periodSeconds: 5
            failureThreshold: 24
          ports:
            - containerPort: 10466
              protocol: TCP
          env:
            - name: XIID_ACTIVATION_CODE
              value: #<- Insert your Commander Activation Code here
          volumeMounts:
            - name: opt-xiid
              mountPath: /opt/Xiid
            - name: xdg-xiid
              mountPath: /etc/xdg/Xiid
        - name: xiid-stlink
          image: xiidcorporation/stlink:latest
          securityContext:
            capabilities:
              add:
                - NET_ADMIN
          startupProbe:
            tcpSocket:
              port: 10479
            periodSeconds: 5
            failureThreshold: 12
          env:
            - name: XIID_ACTIVATION_CODE
              value: #<- Insert the Commander's STLink Activation Code here (generated from the Commander Portal for access to the Commander Portal itself)
          volumeMounts:
            - name: stlink-opt-xiid
              mountPath: /opt/Xiid
            - name: stlink-xdg-xiid
              mountPath: /etc/xdg/Xiid
      volumes:
        - name: opt-xiid
          persistentVolumeClaim:
            claimName: commander-opt-xiid
        - name: xdg-xiid
          persistentVolumeClaim:
            claimName: commander-xdg-xiid
        - name: stlink-opt-xiid
          persistentVolumeClaim:
            claimName: stlink-opt-xiid  
        - name: stlink-xdg-xiid
          persistentVolumeClaim:
            claimName: stlink-xdg-xiid  
---
apiVersion: v1
kind: Service
metadata:
  name: xiid-commander
spec:
  selector:
    app: xiid-commander
  ports:
    - port: 10466
      targetPort: 10466
      protocol: TCP
  type: ClusterIP  # Commander is now accessed exclusively through the STLink

⁠Environment Variables

Variable	Required	Description
`XIID_ACTIVATION_CODE`	Yes	Your Xiid Commander activation code

⁠Technical Details

Base Image: Red Hat Universal Base Image 9 (UBI9)
Service Port: 10466 (HTTPS)
Installation: Automatic on first run
Persistence: Activation and Terniion configurations can be maintained across container restarts as long as the key instructions are followed in Storage Requirements⁠
Root Privileges: Not required on the host system

⁠Troubleshooting

⁠Interactive Shell Access

To debug or inspect the container:

docker run -it -e XIID_ACTIVATION_CODE=your_activation_code_here xiidcorporation/commander:latest /bin/bash

⁠Support

For assistance with:

Activation codes: Contact Xiid support or your Xiid sales representative
Container issues: Check container logs and verify environment variables
Kubernetes deployment: Review the example YAML configuration

⁠License

This container image includes Xiid Commander software. Use of this software requires a valid activation code and is subject to Xiid's licensing terms.

⁠Security

The container can run without requiring root privileges on the host (e.g., using rootless Podman)
Activation codes should be managed securely
HTTPS is used for all Commander service communications

Tag summary

Recent tags

Content type

Image

Digest

sha256:37c42e24a…

Size

111.7 MB

Last updated

6 months ago

docker pull xiidcorporation/commander