zboxapi 0.0.5__tar.gz → 0.0.7__tar.gz

zboxapi-0.0.7/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.1
+Name: zboxapi
+Version: 0.0.7
+Summary: 
+Author: Kelby Valenti
+Author-email: kelby.valenti@gmail.com
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: fastapi (==0.111.0)
+Requires-Dist: ipython (>=8.24.0,<9.0.0)
+Requires-Dist: uvicorn (==0.29.0)
+Description-Content-Type: text/markdown
+
+# 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
+
+## Installation
+
+Complete the following steps to set up zBox Api:
+
+1. Install pipx
+
+    ```bash
+    # Install and configure pipx
+    apt update
+    apt install -y pipx
+    pipx ensurepath
+
+    # Reload your profile
+    source ~/.zshrc
+    ```
+
+1. Install zBoxApi:
+
+    ```bash
+    pipx install zboxapi
+    ```
+
+1. Set up and start zboxapi.service
+
+    ```bash
+    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`:
+
+```ini
+[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](DOC_VLAN.md) for detailed documentation on VLAN management features.
+
+## 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:
+
+```bash
+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`:
+
+```bash
+# 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](DOC_DNS.md).
+
+### VLAN Management
+
+Manage VLAN interfaces:
+
+```bash
+# 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](DOC_VLAN.md).
+
+
+## Documentation
+
+- [DOC_DNS.md](DOC_DNS.md) - Complete guide to DNS management features
+- [DOC_VLAN.md](DOC_VLAN.md) - Complete guide to VLAN management features
+

zboxapi-0.0.7/README.md

@@ -0,0 +1,118 @@
+# 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
+
+## Installation
+
+Complete the following steps to set up zBox Api:
+
+1. Install pipx
+
+    ```bash
+    # Install and configure pipx
+    apt update
+    apt install -y pipx
+    pipx ensurepath
+
+    # Reload your profile
+    source ~/.zshrc
+    ```
+
+1. Install zBoxApi:
+
+    ```bash
+    pipx install zboxapi
+    ```
+
+1. Set up and start zboxapi.service
+
+    ```bash
+    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`:
+
+```ini
+[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](DOC_VLAN.md) for detailed documentation on VLAN management features.
+
+## 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:
+
+```bash
+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`:
+
+```bash
+# 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](DOC_DNS.md).
+
+### VLAN Management
+
+Manage VLAN interfaces:
+
+```bash
+# 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](DOC_VLAN.md).
+
+
+## Documentation
+
+- [DOC_DNS.md](DOC_DNS.md) - Complete guide to DNS management features
+- [DOC_VLAN.md](DOC_VLAN.md) - Complete guide to VLAN management features

{zboxapi-0.0.5 → zboxapi-0.0.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "zboxapi"
-version = "0.0.5"
+version = "0.0.7"
 description = ""
 authors = ["Kelby Valenti <kelby.valenti@gmail.com>", "Timo Sugliani <timo.sugliani@gmail.com>"]
 readme = "README.md"

zboxapi-0.0.7/src/zboxapi/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.7"

zboxapi-0.0.7/src/zboxapi/dns.py

@@ -0,0 +1,222 @@
+import contextlib
+import fcntl
+import re
+import socket
+import subprocess
+import time
+from ipaddress import IPv4Address
+from pathlib import Path
+from typing import IO, Annotated
+
+from fastapi import APIRouter, HTTPException, status
+from pydantic import AfterValidator, BaseModel
+from pydantic_core import PydanticCustomError
+
+
+@contextlib.contextmanager
+def get_hosts_file_object():
+    """Context manager for safely handling /etc/hosts file"""
+    pfile = Path("/etc/hosts")
+    if not pfile.is_file():
+        pfile.write_text("")
+
+    while True:
+        try:
+            file_handle = pfile.open("r+")
+            fcntl.flock(file_handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            break
+        except IOError:  # noqa: UP024
+            # File is locked, wait for a while and try again
+            time.sleep(0.1)
+
+    try:
+        yield file_handle
+    finally:
+        fcntl.flock(file_handle, fcntl.LOCK_UN)
+        file_handle.close()
+
+
+def get_hosts_lines(hosts_fo: IO) -> list[dict[str, str]]:
+    """Parse hosts file and return list of IP-hostname mappings"""
+    lines = []
+    for line in hosts_fo.read().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        line_ip, *line_hostnames = line.split()
+        lines.extend(
+            {"ip": IPv4Address(line_ip), "hostname": line_hostname}
+            for line_hostname in line_hostnames
+        )
+    return sorted(lines, key=sort_hosts_lines)
+
+
+def filter_hosts_file(
+    lines: list[dict[str, str]],
+    ip: IPv4Address | None = None,
+    hostname: str | None = None,
+):
+    """Filter hosts file lines by IP and/or hostname"""
+    return [
+        line
+        for line in lines
+        if (not ip or ip == line["ip"])
+        and (not hostname or hostname == line["hostname"])
+    ]
+
+
+def write_hosts_file(hosts_fo: IO, lines: list[dict[str, str]]):
+    """Write hosts file lines back to file"""
+    lines.sort(key=sort_hosts_lines)
+    hosts_fo.seek(0)
+    hosts_fo.truncate()
+    hosts_fo.writelines([f"{line['ip']}\t{line['hostname']}\n" for line in lines])
+
+
+def dnsmasq_sighup():
+    """Send SIGHUP to dnsmasq to reload configuration"""
+    print("Send SIGHUP to dnsmasq...")
+    subprocess.call(["pkill", "-SIGHUP", "dnsmasq"])
+
+
+def sort_hosts_lines(item: dict):
+    """Sort list by loopback first, ip second, hostname third"""
+    return (
+        not item["ip"].is_loopback,
+        socket.inet_aton(str(item["ip"])),
+        item["hostname"],
+    )
+
+
+def RecordNotFound(ip, hostname):
+    """Return HTTPException for DNS record not found"""
+    return HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail=f"DNS record not found: ip={ip}, hostname={hostname}",
+    )
+
+
+def RecordAlreadyPresent(ip, hostname):
+    """Return HTTPException for DNS record already present"""
+    return HTTPException(
+        status_code=status.HTTP_406_NOT_ACCEPTABLE,
+        detail=f"DNS record already present: ip={ip}, hostname={hostname}",
+    )
+
+
+def validate_hostname(value: str):
+    """Validate hostname format"""
+    if not 1 <= len(value) < 64:
+        raise PydanticCustomError("value_error", "Invalid hostname length")
+
+    #  Define pattern of DNS label
+    #  Can begin and end with a number or letter only
+    #  Can contain hyphens, a-z, A-Z, 0-9
+    #  1 - 63 chars allowed
+    hostname_re = re.compile(r"^[a-z0-9]([a-z-0-9-]{0,61}[a-z0-9])?$", re.IGNORECASE)
+
+    # Check that all labels match that pattern.
+    if not hostname_re.match(value):
+        raise PydanticCustomError("value_error", "Invalid hostname")
+    return value
+
+
+HOSTNAME = Annotated[str, AfterValidator(validate_hostname)]
+
+
+class DnsCreate(BaseModel):
+    """Model for creating DNS records"""
+
+    ip: IPv4Address
+    hostname: HOSTNAME
+
+
+class DnsUpdate(BaseModel):
+    """Model for updating DNS records"""
+
+    ip: IPv4Address
+    hostname: HOSTNAME
+
+
+class DnsView(BaseModel):
+    """Model for viewing DNS records"""
+
+    ip: IPv4Address
+    hostname: str
+
+
+# API Router
+dns_router = APIRouter(prefix="/dns", tags=["dns"])
+
+
+@dns_router.get("", response_model=list[DnsView])
+def dns_get_all() -> list[DnsView]:
+    """Get all DNS records"""
+    with get_hosts_file_object() as hosts_fo:
+        hosts_lines = get_hosts_lines(hosts_fo)
+    return hosts_lines
+
+
+@dns_router.get("/{ip}/{hostname}", response_model=DnsView)
+def dns_get(
+    ip: IPv4Address,
+    hostname: HOSTNAME,
+) -> DnsView:
+    """Get specific DNS record"""
+    with get_hosts_file_object() as hosts_fo:
+        hosts_lines = get_hosts_lines(hosts_fo)
+        hosts_lines = filter_hosts_file(hosts_lines, ip, hostname)
+    if not hosts_lines:
+        raise RecordNotFound(ip, hostname)
+    return hosts_lines[0]
+
+
+@dns_router.post("", response_model=list[DnsView])
+def dns_add(
+    dns_in: DnsCreate,
+) -> list[DnsView]:
+    """Add DNS record"""
+    with get_hosts_file_object() as hosts_fo:
+        hosts_lines = get_hosts_lines(hosts_fo)
+        if filter_hosts_file(hosts_lines, dns_in.ip, dns_in.hostname):
+            raise RecordAlreadyPresent(dns_in.ip, dns_in.hostname)
+        hosts_lines.append({"ip": dns_in.ip, "hostname": dns_in.hostname})
+        write_hosts_file(hosts_fo, hosts_lines)
+    dnsmasq_sighup()
+    return hosts_lines
+
+
+@dns_router.put("/{ip}/{hostname}", response_model=list[DnsView])
+def dns_update(
+    ip: IPv4Address,
+    hostname: HOSTNAME,
+    dns_in: DnsUpdate,
+) -> list[DnsView]:
+    """Update DNS record"""
+    with get_hosts_file_object() as hosts_fo:
+        hosts_lines = get_hosts_lines(hosts_fo)
+        key = {"ip": ip, "hostname": hostname}
+        if key not in hosts_lines:
+            raise RecordNotFound(ip, hostname)
+        ix = hosts_lines.index(key)
+        hosts_lines[ix] = {"ip": dns_in.ip, "hostname": dns_in.hostname}
+        write_hosts_file(hosts_fo, hosts_lines)
+    dnsmasq_sighup()
+    return hosts_lines
+
+
+@dns_router.delete("/{ip}/{hostname}", response_model=list[DnsView])
+def dns_delete(
+    ip: IPv4Address,
+    hostname: HOSTNAME,
+) -> list[DnsView]:
+    """Delete DNS record"""
+    with get_hosts_file_object() as hosts_fo:
+        hosts_lines = get_hosts_lines(hosts_fo)
+        key = {"ip": ip, "hostname": hostname}
+        if key not in hosts_lines:
+            raise RecordNotFound(ip, hostname)
+        hosts_lines.remove(key)
+        write_hosts_file(hosts_fo, hosts_lines)
+    dnsmasq_sighup()
+    return hosts_lines

zboxapi-0.0.7/src/zboxapi/main.py

@@ -0,0 +1,83 @@
+import os
+import re
+import subprocess
+from typing import Annotated
+
+import uvicorn
+from fastapi import Depends, FastAPI, HTTPException, Security, status
+from fastapi.routing import APIRoute
+from fastapi.security.api_key import APIKey, APIKeyHeader
+
+from zboxapi import __version__
+from zboxapi.dns import dns_router
+from zboxapi.vlan import vlan_router
+
+api_key_header = APIKeyHeader(name="access_token", auto_error=False)
+
+
+def validate_api_key(api_key: Annotated[APIKey, Security(api_key_header)]):
+    """Validate API key for authentication"""
+    if api_key != ZPOD_PASSWORD:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Invalid access_token",
+        )
+
+
+def get_zpod_password():
+    """Retrieve zpod password from VMware tools"""
+    ovfenv = subprocess.run(
+        ["vmtoolsd", "--cmd", "info-get guestinfo.ovfenv"],
+        capture_output=True,
+        text=True,
+    )
+    pw_re = re.compile(r'<Property oe:key="guestinfo.password" oe:value="([^"]*)"/>')
+    if item := re.search(pw_re, ovfenv.stdout):
+        return item[1]
+    raise Exception("Unable to retrieve zpod password")
+
+
+def simplify_operation_ids(api: FastAPI) -> None:
+    """
+    Update operation IDs so that generated API clients have simpler function
+    names.
+    """
+    for route in api.routes:
+        if isinstance(route, APIRoute) and not route.operation_id:
+            tag = route.tags[0] if route.tags else "default"
+            route.operation_id = f"{tag}_{route.name}"
+
+
+# Get zpod password for authentication
+ZPOD_PASSWORD = get_zpod_password()
+
+# Get root path from environment
+zboxapi_root_path = os.getenv("ZBOXAPI_ROOT_PATH", None)
+
+# Create FastAPI application
+app = FastAPI(
+    title="zBox API",
+    root_path=zboxapi_root_path,
+    dependencies=[Depends(validate_api_key)],
+    version=__version__,
+)
+
+# Include routers
+app.include_router(dns_router)
+app.include_router(vlan_router)
+
+# Simplify operation IDs
+simplify_operation_ids(app)
+
+
+def launch():
+    """Launch the FastAPI application with uvicorn"""
+    uvicorn.run(
+        app,
+        host="127.0.0.1",
+        port=8000,
+    )
+
+
+if __name__ == "__main__":
+    launch()