zBoxApi

zPodFactory zBox Api

Features

• DNS Management: Manage DNS records in /etc/hosts with automatic dnsmasq integration
• VLAN Management: Manage VLAN interfaces with automatic network configuration, with an optional masquerade (source NAT to the management interface) for VLANs that must reach out without being routed in
• NFS Exports (zcore): Export folders under /FILER/STORAGEnn to clients, with /etc/exports.d/zboxapi.exports and exportfs -ra
• Disks and Storages (zcore): Turn a new disk into a mounted /FILER/STORAGEnn, raw or LVM, grow it after a vSphere resize, manage its folders. NFS-01, STORAGE01 and the disk behind it are never modified.

Installation

Complete the following steps to set up zBox Api:

1. Install uv

   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Reload your profile so ~/.local/bin is on the PATH
   source ~/.zshrc
   

2. Install zBoxApi:

   uv tool install zboxapi
   

   zBoxApi requires Python 3.14. Debian ships an older interpreter, so install with uv, which downloads a managed Python 3.14 on its own. pipx install zboxapi only works where a 3.14 interpreter is already on the PATH.

3. Set up and start zboxapi.service

   cp zboxapi.service /etc/systemd/system
   systemctl daemon-reload
   systemctl enable zboxapi.service
   systemctl start zboxapi.service
   

   Note: The service runs on 127.0.0.1:8000 and requires root privileges for network configuration operations.

Configuration

VLAN Management

For VLAN management functionality, create a configuration file at /etc/zboxapi.conf:

[DEFAULT]
# Base interface name for VLAN management
interface = eth1

# MTU setting for VLAN interfaces
mtu = 1700

# System default VLANs that cannot be modified (comma-separated)
system_vlans_default = 10,20,30

# System zPod VLANs that cannot be modified (comma-separated)
system_vlans_zpod = 64,128,192

See DOC_VLAN.md for detailed documentation on VLAN management features.

NFS and Storage (zcore)

Both work without configuration. The optional [storage] and [nfs] sections of /etc/zboxapi.conf are documented in DOC_STORAGE.md and DOC_NFS.md.

API Usage

Authentication

All API endpoints require authentication using the access_token header. The API key is the zPod password which is also the root password of the zbox VM. The password is automatically retrieved from VMware tools:

curl -H "access_token: your_zpod_password" http://127.0.0.1:8000/dns

Note: The service runs on 127.0.0.1:8000 and requires root privileges for network configuration operations.

DNS Management

Manage DNS records in /etc/hosts:

# Add DNS record
curl -X POST "http://127.0.0.1:8000/dns" \
     -H "access_token: your_zpod_password" \
     -H "Content-Type: application/json" \
     -d '{"ip": "192.168.1.100", "hostname": "example.com"}'

# List all DNS records
curl -X GET "http://127.0.0.1:8000/dns" \
     -H "access_token: your_zpod_password"

For complete DNS management documentation, see DOC_DNS.md.

VLAN Management

Manage VLAN interfaces:

# Create VLAN interface
curl -X POST "http://127.0.0.1:8000/vlan" \
     -H "access_token: your_zpod_password" \
     -H "Content-Type: application/json" \
     -d '{"vlan": 2000, "gateway": "192.168.42.129/25"}'

# List all VLAN interfaces
curl -X GET "http://127.0.0.1:8000/vlan" \
     -H "access_token: your_zpod_password"

For complete VLAN management documentation, see DOC_VLAN.md.

NFS Exports and Storage (zcore)

# What disks are attached, and what state each is in
curl -H "access_token: your_zpod_password" http://127.0.0.1:8000/disk

# Turn blank disk sdc into /FILER/STORAGE02 (LVM), preview first with ?dry_run=true
curl -X POST "http://127.0.0.1:8000/storage" \
     -H "access_token: your_zpod_password" -H "Content-Type: application/json" \
     -d '{"disk": "sdc", "lvm": true}'

# Export a folder on it (the folder is created if missing)
curl -X POST "http://127.0.0.1:8000/nfs" \
     -H "access_token: your_zpod_password" -H "Content-Type: application/json" \
     -d '{"storage": "STORAGE02", "folder": "NFS-15", "clients": ["10.60.60.0/26"]}'

# After enlarging the virtual disk in vSphere
curl -X POST "http://127.0.0.1:8000/storage/STORAGE02/grow" -H "access_token: your_zpod_password"

See DOC_STORAGE.md and DOC_NFS.md.

Development

The project is managed with uv. Clone the repository, then:

uv sync                 # create .venv with the project and dev dependencies
uv run pytest           # run the unit tests (no root, /etc or network access needed)
uv run pytest --cov     # same, with a coverage report
uv run ruff check src tests && uv run ruff format --check src tests

A justfile wraps the same commands (just test, just lint, just format).

Releasing

Every change gets a line under [Unreleased] in CHANGELOG.md. A release is one command:

python3 tools/release.py 0.2.0 --push      # or: just release 0.2.0

It turns [Unreleased] into a dated [0.2.0] section, bumps pyproject.toml and uv.lock, runs the tests, commits, tags v0.2.0 and pushes. The tag then runs .github/workflows/release.yml, which publishes the changelog section as the GitHub release note, builds the package with uv build, publishes it to PyPI with uv publish and attaches the wheel and sdist to the release. See tools/README.md for the details, including the one-time PyPI setup (an API token secret or trusted publishing).

The test suite exercises every endpoint through FastAPI's TestClient. The hosts file, /etc/zboxapi.conf, /etc/network/interfaces.d/ and the vmtoolsd password lookup are redirected to temporary locations, and the ip, ifup, ifdown and pkill commands are replaced by an in-memory fake, so the tests can run on any machine.

Documentation

• DOC_DNS.md - Complete guide to DNS management features
• DOC_VLAN.md - Complete guide to VLAN management features
• DOC_STORAGE.md - Disks, storages, folders, and the guard rail (zcore)
• DOC_NFS.md - NFS exports and clients (zcore)