clab-api-server

Containerlab API Server

A standalone RESTful API server for managing Containerlab deployments, enabling programmatic control and remote management of network labs.

📚 Looking for detailed integration information? Check out the Integration Guide for in-depth documentation on architecture, deployment models, and configuration details.

✨ Features

• Lab Management: Deploy, destroy, redeploy, inspect, and list labs
• Node Operations: Execute commands and save configurations
• SSH Access: Connect to lab nodes via SSH through the API server
• Topology Tools: Generate and deploy CLOS topologies
• Network Tools: Manage network emulation, virtual Ethernet pairs, VxLAN tunnels
• Certification Tools: Certificate management
• User Management: Create, update, delete users and manage permissions using Linux system accounts
• Health Monitoring: Check server health status and system metrics
• Logs: Check logs of the nodes, static or streaming
• User Context: Track ownership and manage files within user home directories
• Multitenancy: Support for multiple users with separate access to labs
• Documentation: Embedded Swagger UI and ReDoc for API exploration

⚙️ Prerequisites

[!NOTE] Containerlab 0.68.0+ is not available yet, but the 0.1.0 release of the clab‑api‑server is compatible with Containerlab 0.67.0.

🚀 Deployment Options

The Containerlab API Server can be deployed in several ways:

1. Binary Installation (Recommended for Production)

The simplest approach for direct installation on a Linux host:

curl -sL https://raw.githubusercontent.com/srl-labs/clab-api-server/main/install.sh | sudo -E bash

This will:

• Download the appropriate binary for your architecture to /usr/local/bin/clab-api-server
• Create a default configuration at /etc/clab-api-server.env
• Create a systemd unit at /etc/systemd/system/clab-api-server.service

For post-installation steps, see the Post-Install Configuration section below.

2. Docker Deployment

Run the API server as a Docker container with access to the host resources:

docker run -d \
  --name clab-api-server \
  --privileged \
  --network host \
  --pid host \
  -e LOG_LEVEL=debug \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/run/netns:/var/run/netns \
  -v /var/lib/docker/containers:/var/lib/docker/containers \
  -v /usr/bin/containerlab:/usr/bin/containerlab:ro \
  -v /etc/passwd:/etc/passwd:ro \
  -v /etc/shadow:/etc/shadow:ro \
  -v /etc/group:/etc/group:ro \
  -v /etc/gshadow:/etc/gshadow:ro \
  -v /home:/home \
  ghcr.io/srl-labs/clab-api-server/clab-api-server:latest

[!NOTE] Volume mounts enable Docker management, networking features, Linux PAM authentication, and user file storage.

3. Other Docker Deployment Options

The repository also includes support for Docker-in-Docker (DinD) and Docker-out-of-Docker (DooD) deployment models:

• Docker-in-Docker (DinD): A fully isolated environment with its own Docker engine
• Docker-out-of-Docker (DooD): Uses the host's Docker daemon for better performance

For these options, clone the repository and use the provided clab-api-manager.sh script:

git clone https://github.com/srl-labs/clab-api-server.git
cd clab-api-server
cp docker/common/.env.example docker/common/.env  # Edit as needed
./clab-api-manager.sh [dind|dood] start

🔧 Post-Install Configuration

1. Edit the configuration

   • For binary install: /etc/clab-api-server.env
   • For Docker install: docker/common/.env

   At a minimum, change JWT_SECRET to a strong random string and set API_SERVER_HOST to your server's IP/hostname.

2. Enable & start the service (for binary installation):

   sudo systemctl enable --now clab-api-server
   

3. Verify

   # For binary install
   sudo systemctl status clab-api-server
   
   # For Docker install
   ./clab-api-manager.sh [dind|dood] status
   ./clab-api-manager.sh [dind|dood] logs
   

🗄️ Configuration Reference

🔐 Authentication

The Containerlab API Server uses Linux system users and passwords for authentication. Users must:

• Exist as valid Linux users on the system where the API server runs
• Belong to the configured API_USER_GROUP (clab_api by default) or SUPERUSER_GROUP (clab_admins by default)

When authenticating via the API, provide the Linux username and password to receive a JWT token for subsequent requests.

📡 Managing Docker Deployments

For the simple Docker deployment, use standard Docker commands:

# Basic commands
docker start clab-api-server    # Start the service
docker stop clab-api-server     # Stop the service
docker restart clab-api-server  # Restart the service
docker ps -f name=clab-api-server  # Check service status
docker logs clab-api-server     # View logs
docker logs -f clab-api-server  # Follow logs

For DinD/DooD deployments, use the provided management script:

# Basic commands
./clab-api-manager.sh [dind|dood] start    # Start the service
./clab-api-manager.sh [dind|dood] stop     # Stop the service
./clab-api-manager.sh [dind|dood] logs     # View logs

# Data persistence commands
./clab-api-manager.sh [dind|dood] backup   # Create a backup
./clab-api-manager.sh [dind|dood] restore <backup-file>  # Restore from backup

🛡️ Privilege Model & Security

• Server user – The process runs with permissions to execute clab and access the container runtime.
• Authenticated users – Must be members of API_USER_GROUP or SUPERUSER_GROUP.
• Command execution – All commands run as the server user, not the authenticated user.
• Ownership – Lab ownership is tracked via container labels.
• SSH sessions – Allocated ports forward to container port 22 with automatic expiration.
• Security controls – PAM for credential validation, JWT for session management, input validation, and optional TLS.

📝 API Documentation

Access interactive API documentation at:

http://<server_ip>:<API_PORT>/swagger/index.html  # Swagger UI
http://<server_ip>:<API_PORT>/redoc               # ReDoc UI

🚀 API Usage Example

# Authenticate with your Linux username and password
TOKEN=$(curl -s -X POST http://localhost:8080/login \
  -H "Content-Type: application/json" \
  -d '{"username":"your_linux_username","password":"your_linux_password"}' \
  | jq -r '.token')

# List labs
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/labs

# Deploy a lab
curl -X POST http://localhost:8080/api/v1/labs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topologyContent": "name: simple-lab\ntopology:\n  nodes:\n    router1:\n      kind: linux\n    router2:\n      kind: linux\n  links:\n    - endpoints: [\"router1:eth1\", \"router2:eth1\"]"
  }'

🔌 Flashpost Collection

Flashpost is a free alternative to Postman that runs entirely in VS Code as an extension.

The examples folder contains a Flashpost collection that demonstrates how to use the Containerlab API. The collection provides ready-to-use requests for all API endpoints.

The collection assumes that the server is running on localhost:8080, but you can change the server URL via a variable.

To use the collection:

1. Install the Flashpost VS Code extension
2. Import the collection from the json file in the examples folder

Variables

The collection makes use of the following variables:

• USER_NAME - Linux user name that client will use for authentication with the clab api server
• USER_PASSWORD - Linux user password that client will use for authentication with the clab api server
• baseUrl - for example: localhost:8080

👩‍💻 Development

For development setup:

git clone https://github.com/srl-labs/clab-api-server.git
cd clab-api-server
cp .env.example .env      # edit JWT_SECRET

# build & run
task                      # tidy → swag docs → build binary
./clab-api-server

📜 License

Distributed under the Apache 2.0 license. See LICENSE for details.