zboxapi 0.0.6__tar.gz → 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. zboxapi-0.1.0/PKG-INFO +181 -0
  2. zboxapi-0.1.0/README.md +160 -0
  3. zboxapi-0.1.0/pyproject.toml +72 -0
  4. zboxapi-0.1.0/pyproject.toml.orig +70 -0
  5. zboxapi-0.1.0/src/zboxapi/__init__.py +6 -0
  6. zboxapi-0.0.6/src/zboxapi/main.py → zboxapi-0.1.0/src/zboxapi/dns.py +59 -88
  7. zboxapi-0.1.0/src/zboxapi/main.py +88 -0
  8. zboxapi-0.1.0/src/zboxapi/vlan.py +679 -0
  9. zboxapi-0.0.6/PKG-INFO +0 -51
  10. zboxapi-0.0.6/README.md +0 -34
  11. zboxapi-0.0.6/pyproject.toml +0 -43
  12. zboxapi-0.0.6/src/zboxapi/__init__.py +0 -1
zboxapi-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,181 @@
1
+ Metadata-Version: 2.4
2
+ Name: zboxapi
3
+ Version: 0.1.0
4
+ Summary: zPodFactory zBox API: DNS and VLAN management for the zbox VM
5
+ Author: Kelby Valenti, Timo Sugliani
6
+ Author-email: Kelby Valenti <kelby.valenti@gmail.com>, Timo Sugliani <timo.sugliani@gmail.com>
7
+ License-Expression: MIT
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Programming Language :: Python :: 3.10
10
+ Classifier: Programming Language :: Python :: 3.11
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Classifier: Programming Language :: Python :: 3.14
14
+ Classifier: Framework :: FastAPI
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Requires-Dist: fastapi>=0.118
17
+ Requires-Dist: pydantic>=2.12
18
+ Requires-Dist: uvicorn>=0.37
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+
22
+ # zBoxApi
23
+
24
+ zPodFactory zBox Api
25
+
26
+ ## Features
27
+
28
+ - **DNS Management**: Manage DNS records in `/etc/hosts` with automatic dnsmasq integration
29
+ - **VLAN Management**: Manage VLAN interfaces with automatic network configuration
30
+
31
+ ## Installation
32
+
33
+ Complete the following steps to set up zBox Api:
34
+
35
+ 1. Install pipx
36
+
37
+ ```bash
38
+ # Install and configure pipx
39
+ apt update
40
+ apt install -y pipx
41
+ pipx ensurepath
42
+
43
+ # Reload your profile
44
+ source ~/.zshrc
45
+ ```
46
+
47
+ 1. Install zBoxApi:
48
+
49
+ ```bash
50
+ pipx install zboxapi
51
+ ```
52
+
53
+ Or with [uv](https://docs.astral.sh/uv/), which also fetches a suitable Python if needed:
54
+
55
+ ```bash
56
+ uv tool install zboxapi
57
+ ```
58
+
59
+ zBoxApi supports Python 3.10 through 3.14.
60
+
61
+ 1. Set up and start zboxapi.service
62
+
63
+ ```bash
64
+ cp zboxapi.service /etc/systemd/system
65
+ systemctl daemon-reload
66
+ systemctl enable zboxapi.service
67
+ systemctl start zboxapi.service
68
+ ```
69
+
70
+ **Note**: The service runs on `127.0.0.1:8000` and requires root privileges for network configuration operations.
71
+
72
+ ## Configuration
73
+
74
+ ### VLAN Management
75
+
76
+ For VLAN management functionality, create a configuration file at `/etc/zboxapi.conf`:
77
+
78
+ ```ini
79
+ [DEFAULT]
80
+ # Base interface name for VLAN management
81
+ interface = eth1
82
+
83
+ # MTU setting for VLAN interfaces
84
+ mtu = 1700
85
+
86
+ # System default VLANs that cannot be modified (comma-separated)
87
+ system_vlans_default = 10,20,30
88
+
89
+ # System zPod VLANs that cannot be modified (comma-separated)
90
+ system_vlans_zpod = 64,128,192
91
+ ```
92
+
93
+ See [DOC_VLAN.md](DOC_VLAN.md) for detailed documentation on VLAN management features.
94
+
95
+ ## API Usage
96
+
97
+ ### Authentication
98
+
99
+ 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:
100
+
101
+ ```bash
102
+ curl -H "access_token: your_zpod_password" http://127.0.0.1:8000/dns
103
+ ```
104
+
105
+ **Note**: The service runs on `127.0.0.1:8000` and requires root privileges for network configuration operations.
106
+
107
+ ### DNS Management
108
+
109
+ Manage DNS records in `/etc/hosts`:
110
+
111
+ ```bash
112
+ # Add DNS record
113
+ curl -X POST "http://127.0.0.1:8000/dns" \
114
+ -H "access_token: your_zpod_password" \
115
+ -H "Content-Type: application/json" \
116
+ -d '{"ip": "192.168.1.100", "hostname": "example.com"}'
117
+
118
+ # List all DNS records
119
+ curl -X GET "http://127.0.0.1:8000/dns" \
120
+ -H "access_token: your_zpod_password"
121
+ ```
122
+
123
+ For complete DNS management documentation, see [DOC_DNS.md](DOC_DNS.md).
124
+
125
+ ### VLAN Management
126
+
127
+ Manage VLAN interfaces:
128
+
129
+ ```bash
130
+ # Create VLAN interface
131
+ curl -X POST "http://127.0.0.1:8000/vlan" \
132
+ -H "access_token: your_zpod_password" \
133
+ -H "Content-Type: application/json" \
134
+ -d '{"vlan": 2000, "gateway": "192.168.42.129/25"}'
135
+
136
+ # List all VLAN interfaces
137
+ curl -X GET "http://127.0.0.1:8000/vlan" \
138
+ -H "access_token: your_zpod_password"
139
+ ```
140
+
141
+ For complete VLAN management documentation, see [DOC_VLAN.md](DOC_VLAN.md).
142
+
143
+
144
+ ## Development
145
+
146
+ The project is managed with [uv](https://docs.astral.sh/uv/). Clone the repository, then:
147
+
148
+ ```bash
149
+ uv sync # create .venv with the project and dev dependencies
150
+ uv run pytest # run the unit tests (no root, /etc or network access needed)
151
+ uv run pytest --cov # same, with a coverage report
152
+ uv run ruff check src tests && uv run ruff format --check src tests
153
+ ```
154
+
155
+ A `justfile` wraps the same commands (`just test`, `just lint`, `just format`).
156
+
157
+ ### Releasing
158
+
159
+ Every change gets a line under `[Unreleased]` in [CHANGELOG.md](CHANGELOG.md). A release is
160
+ one command:
161
+
162
+ ```bash
163
+ python3 tools/release.py 0.2.0 --push # or: just release 0.2.0
164
+ ```
165
+
166
+ It turns `[Unreleased]` into a dated `[0.2.0]` section, bumps `pyproject.toml` and `uv.lock`,
167
+ runs the tests, commits, tags `v0.2.0` and pushes. The tag then runs
168
+ `.github/workflows/release.yml`, which publishes the changelog section as the GitHub release
169
+ note, builds the package with `uv build`, publishes it to PyPI with `uv publish` and attaches
170
+ the wheel and sdist to the release. See [tools/README.md](tools/README.md) for the details,
171
+ including the one-time PyPI setup (an API token secret or trusted publishing).
172
+
173
+ The test suite exercises every endpoint through FastAPI's `TestClient`. The hosts file,
174
+ `/etc/zboxapi.conf`, `/etc/network/interfaces.d/` and the `vmtoolsd` password lookup are
175
+ redirected to temporary locations, and the `ip`, `ifup`, `ifdown` and `pkill` commands are
176
+ replaced by an in-memory fake, so the tests can run on any machine.
177
+
178
+ ## Documentation
179
+
180
+ - [DOC_DNS.md](DOC_DNS.md) - Complete guide to DNS management features
181
+ - [DOC_VLAN.md](DOC_VLAN.md) - Complete guide to VLAN management features
zboxapi-0.1.0/README.md ADDED
@@ -0,0 +1,160 @@
1
+ # zBoxApi
2
+
3
+ zPodFactory zBox Api
4
+
5
+ ## Features
6
+
7
+ - **DNS Management**: Manage DNS records in `/etc/hosts` with automatic dnsmasq integration
8
+ - **VLAN Management**: Manage VLAN interfaces with automatic network configuration
9
+
10
+ ## Installation
11
+
12
+ Complete the following steps to set up zBox Api:
13
+
14
+ 1. Install pipx
15
+
16
+ ```bash
17
+ # Install and configure pipx
18
+ apt update
19
+ apt install -y pipx
20
+ pipx ensurepath
21
+
22
+ # Reload your profile
23
+ source ~/.zshrc
24
+ ```
25
+
26
+ 1. Install zBoxApi:
27
+
28
+ ```bash
29
+ pipx install zboxapi
30
+ ```
31
+
32
+ Or with [uv](https://docs.astral.sh/uv/), which also fetches a suitable Python if needed:
33
+
34
+ ```bash
35
+ uv tool install zboxapi
36
+ ```
37
+
38
+ zBoxApi supports Python 3.10 through 3.14.
39
+
40
+ 1. Set up and start zboxapi.service
41
+
42
+ ```bash
43
+ cp zboxapi.service /etc/systemd/system
44
+ systemctl daemon-reload
45
+ systemctl enable zboxapi.service
46
+ systemctl start zboxapi.service
47
+ ```
48
+
49
+ **Note**: The service runs on `127.0.0.1:8000` and requires root privileges for network configuration operations.
50
+
51
+ ## Configuration
52
+
53
+ ### VLAN Management
54
+
55
+ For VLAN management functionality, create a configuration file at `/etc/zboxapi.conf`:
56
+
57
+ ```ini
58
+ [DEFAULT]
59
+ # Base interface name for VLAN management
60
+ interface = eth1
61
+
62
+ # MTU setting for VLAN interfaces
63
+ mtu = 1700
64
+
65
+ # System default VLANs that cannot be modified (comma-separated)
66
+ system_vlans_default = 10,20,30
67
+
68
+ # System zPod VLANs that cannot be modified (comma-separated)
69
+ system_vlans_zpod = 64,128,192
70
+ ```
71
+
72
+ See [DOC_VLAN.md](DOC_VLAN.md) for detailed documentation on VLAN management features.
73
+
74
+ ## API Usage
75
+
76
+ ### Authentication
77
+
78
+ 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:
79
+
80
+ ```bash
81
+ curl -H "access_token: your_zpod_password" http://127.0.0.1:8000/dns
82
+ ```
83
+
84
+ **Note**: The service runs on `127.0.0.1:8000` and requires root privileges for network configuration operations.
85
+
86
+ ### DNS Management
87
+
88
+ Manage DNS records in `/etc/hosts`:
89
+
90
+ ```bash
91
+ # Add DNS record
92
+ curl -X POST "http://127.0.0.1:8000/dns" \
93
+ -H "access_token: your_zpod_password" \
94
+ -H "Content-Type: application/json" \
95
+ -d '{"ip": "192.168.1.100", "hostname": "example.com"}'
96
+
97
+ # List all DNS records
98
+ curl -X GET "http://127.0.0.1:8000/dns" \
99
+ -H "access_token: your_zpod_password"
100
+ ```
101
+
102
+ For complete DNS management documentation, see [DOC_DNS.md](DOC_DNS.md).
103
+
104
+ ### VLAN Management
105
+
106
+ Manage VLAN interfaces:
107
+
108
+ ```bash
109
+ # Create VLAN interface
110
+ curl -X POST "http://127.0.0.1:8000/vlan" \
111
+ -H "access_token: your_zpod_password" \
112
+ -H "Content-Type: application/json" \
113
+ -d '{"vlan": 2000, "gateway": "192.168.42.129/25"}'
114
+
115
+ # List all VLAN interfaces
116
+ curl -X GET "http://127.0.0.1:8000/vlan" \
117
+ -H "access_token: your_zpod_password"
118
+ ```
119
+
120
+ For complete VLAN management documentation, see [DOC_VLAN.md](DOC_VLAN.md).
121
+
122
+
123
+ ## Development
124
+
125
+ The project is managed with [uv](https://docs.astral.sh/uv/). Clone the repository, then:
126
+
127
+ ```bash
128
+ uv sync # create .venv with the project and dev dependencies
129
+ uv run pytest # run the unit tests (no root, /etc or network access needed)
130
+ uv run pytest --cov # same, with a coverage report
131
+ uv run ruff check src tests && uv run ruff format --check src tests
132
+ ```
133
+
134
+ A `justfile` wraps the same commands (`just test`, `just lint`, `just format`).
135
+
136
+ ### Releasing
137
+
138
+ Every change gets a line under `[Unreleased]` in [CHANGELOG.md](CHANGELOG.md). A release is
139
+ one command:
140
+
141
+ ```bash
142
+ python3 tools/release.py 0.2.0 --push # or: just release 0.2.0
143
+ ```
144
+
145
+ It turns `[Unreleased]` into a dated `[0.2.0]` section, bumps `pyproject.toml` and `uv.lock`,
146
+ runs the tests, commits, tags `v0.2.0` and pushes. The tag then runs
147
+ `.github/workflows/release.yml`, which publishes the changelog section as the GitHub release
148
+ note, builds the package with `uv build`, publishes it to PyPI with `uv publish` and attaches
149
+ the wheel and sdist to the release. See [tools/README.md](tools/README.md) for the details,
150
+ including the one-time PyPI setup (an API token secret or trusted publishing).
151
+
152
+ The test suite exercises every endpoint through FastAPI's `TestClient`. The hosts file,
153
+ `/etc/zboxapi.conf`, `/etc/network/interfaces.d/` and the `vmtoolsd` password lookup are
154
+ redirected to temporary locations, and the `ip`, `ifup`, `ifdown` and `pkill` commands are
155
+ replaced by an in-memory fake, so the tests can run on any machine.
156
+
157
+ ## Documentation
158
+
159
+ - [DOC_DNS.md](DOC_DNS.md) - Complete guide to DNS management features
160
+ - [DOC_VLAN.md](DOC_VLAN.md) - Complete guide to VLAN management features
zboxapi-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,72 @@
1
+ [project]
2
+ name = "zboxapi"
3
+ version = "0.1.0"
4
+ description = "zPodFactory zBox API: DNS and VLAN management for the zbox VM"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ requires-python = ">=3.10"
8
+ classifiers = [
9
+ "Programming Language :: Python :: 3",
10
+ "Programming Language :: Python :: 3.10",
11
+ "Programming Language :: Python :: 3.11",
12
+ "Programming Language :: Python :: 3.12",
13
+ "Programming Language :: Python :: 3.13",
14
+ "Programming Language :: Python :: 3.14",
15
+ "Framework :: FastAPI",
16
+ "Operating System :: POSIX :: Linux",
17
+ ]
18
+ dependencies = [
19
+ "fastapi>=0.118",
20
+ "pydantic>=2.12",
21
+ "uvicorn>=0.37",
22
+ ]
23
+
24
+ [[project.authors]]
25
+ name = "Kelby Valenti"
26
+ email = "kelby.valenti@gmail.com"
27
+
28
+ [[project.authors]]
29
+ name = "Timo Sugliani"
30
+ email = "timo.sugliani@gmail.com"
31
+
32
+ [project.scripts]
33
+ zboxapi = "zboxapi.main:launch"
34
+
35
+ [dependency-groups]
36
+ dev = [
37
+ "httpx2>=0.1",
38
+ "ipython>=8.24",
39
+ "pytest>=8.3",
40
+ "pytest-cov>=6.0",
41
+ "ruff>=0.13",
42
+ ]
43
+
44
+ [build-system]
45
+ requires = ["uv_build>=0.9,<1"]
46
+ build-backend = "uv_build"
47
+
48
+ [tool.uv]
49
+ required-version = ">=0.9"
50
+
51
+ [tool.pytest.ini_options]
52
+ testpaths = ["tests"]
53
+ addopts = "-ra"
54
+
55
+ [tool.coverage.run]
56
+ source = ["zboxapi"]
57
+
58
+ [tool.ruff]
59
+ target-version = "py310"
60
+ line-length = 88
61
+
62
+ [tool.ruff.lint]
63
+ select = [
64
+ "E",
65
+ "W",
66
+ "F",
67
+ "I",
68
+ "C",
69
+ "B",
70
+ "UP",
71
+ ]
72
+ ignore = ["B008"]
zboxapi-0.1.0/pyproject.toml.orig ADDED
@@ -0,0 +1,70 @@
1
+ [project]
2
+ name = "zboxapi"
3
+ version = "0.1.0"
4
+ description = "zPodFactory zBox API: DNS and VLAN management for the zbox VM"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ requires-python = ">=3.10"
8
+ authors = [
9
+ { name = "Kelby Valenti", email = "kelby.valenti@gmail.com" },
10
+ { name = "Timo Sugliani", email = "timo.sugliani@gmail.com" },
11
+ ]
12
+ classifiers = [
13
+ "Programming Language :: Python :: 3",
14
+ "Programming Language :: Python :: 3.10",
15
+ "Programming Language :: Python :: 3.11",
16
+ "Programming Language :: Python :: 3.12",
17
+ "Programming Language :: Python :: 3.13",
18
+ "Programming Language :: Python :: 3.14",
19
+ "Framework :: FastAPI",
20
+ "Operating System :: POSIX :: Linux",
21
+ ]
22
+ dependencies = [
23
+ "fastapi>=0.118",
24
+ "pydantic>=2.12",
25
+ "uvicorn>=0.37",
26
+ ]
27
+
28
+ [project.scripts]
29
+ zboxapi = "zboxapi.main:launch"
30
+
31
+ [dependency-groups]
32
+ dev = [
33
+ "httpx2>=0.1",
34
+ "ipython>=8.24",
35
+ "pytest>=8.3",
36
+ "pytest-cov>=6.0",
37
+ "ruff>=0.13",
38
+ ]
39
+
40
+ [build-system]
41
+ requires = ["uv_build>=0.9,<1"]
42
+ build-backend = "uv_build"
43
+
44
+ [tool.uv]
45
+ required-version = ">=0.9"
46
+
47
+ [tool.pytest.ini_options]
48
+ testpaths = ["tests"]
49
+ addopts = "-ra"
50
+
51
+ [tool.coverage.run]
52
+ source = ["zboxapi"]
53
+
54
+ [tool.ruff]
55
+ target-version = "py310"
56
+ line-length = 88
57
+
58
+ [tool.ruff.lint]
59
+ select = [
60
+ "E", # pycodestyle errors
61
+ "W", # pycodestyle warnings
62
+ "F", # pyflakes
63
+ "I", # isort
64
+ "C", # flake8-comprehensions
65
+ "B", # flake8-bugbear
66
+ "UP", # pyupgrade
67
+ ]
68
+ ignore = [
69
+ "B008",
70
+ ]
zboxapi-0.1.0/src/zboxapi/__init__.py ADDED
@@ -0,0 +1,6 @@
1
+ from importlib.metadata import PackageNotFoundError, version
2
+
3
+ try:
4
+ __version__ = version("zboxapi")
5
+ except PackageNotFoundError: # pragma: no cover - running from a bare checkout
6
+ __version__ = "0.0.0"