Skip to main content

​
Overview

The network pool manages available ports for container bindings. Ports must be added to the pool before they can be used in containers.

​
Add Port to Pool

Add a port to the available pool. 
curl -X POST http://localhost:8070/network/ports \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "0.0.0.0",
    "port": 25565,
    "protocol": "tcp"
  }'
Request Body:
  • ip (required) - IP address (e.g., 0.0.0.0, 127.0.0.1)
  • port (required) - Port number (1-65535)
  • protocol (required) - Protocol type: tcp or udp
Response: 
{
  "message": "Port added to pool",
  "ip": "0.0.0.0",
  "port": 25565,
  "protocol": "tcp"
}
On Unix systems, Lightd automatically adds iptables rules for the port (requires root/sudo).

​
Get Specific Port

Retrieve information about a specific port. 
curl -X GET http://localhost:8070/network/ports/0.0.0.0/25565 \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Response: 
{
  "ip": "0.0.0.0",
  "port": 25565,
  "protocol": "tcp",
  "in_use": false
}

​
List All Ports

Get all ports in the pool. 
curl -X GET http://localhost:8070/network/ports \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Response: 
{
  "ports": [
    {
      "ip": "0.0.0.0",
      "port": 25565,
      "protocol": "tcp",
      "in_use": false
    },
    {
      "ip": "0.0.0.0",
      "port": 25566,
      "protocol": "tcp",
      "in_use": true
    },
    {
      "ip": "0.0.0.0",
      "port": 19132,
      "protocol": "udp",
      "in_use": false
    }
  ]
}

​
Get Random Available Port

Get a random available port from the pool. 
curl -X GET http://localhost:8070/network/ports/random \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Response: 
{
  "ip": "0.0.0.0",
  "port": 25567,
  "protocol": "tcp",
  "in_use": false
}
This endpoint does NOT mark the port as in use. It only returns an available port.

​
Mark Port as In Use

Update the usage status of a port. 
curl -X PUT http://localhost:8070/network/ports/0.0.0.0/25565/use \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{"in_use": true}'
Response: 
{
  "message": "Port usage updated",
  "ip": "0.0.0.0",
  "port": 25565,
  "in_use": true
}

​
Delete Port

Remove a port from the pool. 
curl -X DELETE http://localhost:8070/network/ports/0.0.0.0/25565 \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Response: 
{
  "message": "Port deleted from pool"
}

​
Bulk Delete Ports

Delete multiple ports at once. 
curl -X POST http://localhost:8070/network/ports/bulk-delete \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{
    "ports": [
      {"ip": "0.0.0.0", "port": 25565},
      {"ip": "0.0.0.0", "port": 25566}
    ]
  }'
Response: 
{
  "message": "Deleted 2 ports from pool",
  "deleted_count": 2
}

​
Port Binding Workflow

1

Add ports to pool

Add all ports you plan to use to the network pool.
2

Create container with ports

Reference the ports when creating a container. Ports are automatically marked as in_use: true.
3

Rebind if needed

Use the container rebind-network endpoint to change port bindings. Old ports are freed, new ports are marked as in use.

​
iptables Integration

On Unix systems, Lightd automatically manages iptables rules: TCP Port: 
iptables -A INPUT -p tcp --dport 25565 -j ACCEPT
UDP Port: 
iptables -A INPUT -p udp --dport 19132 -j ACCEPT
iptables commands require root/sudo privileges. Ensure Lightd has appropriate permissions.

​
Error Responses

Port Already Exists: 
{
  "error": "Port already exists in pool"
}
Port Not Found: 
{
  "error": "Port not found in pool"
}
No Available Ports: 
{
  "error": "No available ports in pool"
}