You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Network manager
* Fix tests
* an instance test with network passes, but needs more work
* Test time
* Simplify to default network only
* Remove network logic from configdisk.go
* Random IP distribution
* Address concurrency and locking
* Fix json parsing
* Add a way to run just one test
* Get network allocation before deleting VMM
* Delete network working but delete looks messy
* Don't need to manage DNS yet
* Don't use CAP_SYS_ADMIN
* Inheritable CAP_NET_ADMIN
* Check for standby resume in network test
* Cleanup taps on standby
* Fix path to ch snap config
* WIP: proved that network not working after restore
* add stainless github action (#8)
* Enable network capabilities on make dev
* Address review comments
* fix make dev capabilities
* Fix network init
* fixing host setup initialization for partially-initialized state
* Improve error message with stale bridge config
* cleanup orphaned taps and naming convention hype-*
* Put our iptables rules at the top
* Discover host uplink
* 400 instead of 500 on name conflict
* Adjust test for new tap name
* Working on networking test
* Fix network test
* Delete redundant test
* Addressing PR review comments
* including ip and mac
* Change default subnet to 10.100.0.0/16
* Detect and informatively error on network conflict
* Derive gateway IP instead of config separately from subnet
* Add high level explainer to README
---------
Co-authored-by: Rafael <[email protected]>
**Note:** The `i` (inheritable) flag allows child processes spawned by hypeman (like `ip` and `iptables` commands) to inherit capabilities via the ambient capability set.
58
+
59
+
**Note:** These capabilities must be reapplied after each rebuild. For production deployments, set capabilities on the installed binary. For local testing, this is handled automatically in `make test`.
60
+
23
61
### Configuration
24
62
25
63
#### Environment variables
26
64
65
+
Hypeman can be configured using the following environment variables:
66
+
67
+
| Variable | Description | Default |
68
+
|----------|-------------|---------|
69
+
|`PORT`| HTTP server port |`8080`|
70
+
|`DATA_DIR`| Directory for storing VM images, volumes, and other data |`/var/lib/hypeman`|
71
+
|`BRIDGE_NAME`| Name of the network bridge for VM networking |`vmbr0`|
72
+
|`SUBNET_CIDR`| CIDR notation for the VM network subnet (gateway derived automatically) |`10.100.0.0/16`|
73
+
|`UPLINK_INTERFACE`| Host network interface to use for VM internet access |_(auto-detect)_|
74
+
|`JWT_SECRET`| Secret key for JWT authentication (required for production) |_(empty)_|
75
+
|`DNS_SERVER`| DNS server IP address for VMs |`1.1.1.1`|
76
+
|`MAX_CONCURRENT_BUILDS`| Maximum number of concurrent image builds |`1`|
77
+
|`MAX_OVERLAY_SIZE`| Maximum size for overlay filesystem |`100GB`|
78
+
79
+
**Important: Subnet Configuration**
80
+
81
+
The default subnet `10.100.0.0/16` is chosen to avoid common conflicts. Hypeman will detect conflicts with existing routes on startup and fail with guidance.
82
+
83
+
If you need a different subnet, set `SUBNET_CIDR` in your environment. The gateway is automatically derived as the first IP in the subnet (e.g., `10.100.0.0/16` → `10.100.0.1`).
84
+
85
+
**Alternative subnets if needed:**
86
+
-`172.30.0.0/16` - Private range between common Docker (172.17.x.x) and AWS (172.31.x.x) ranges
87
+
-`10.200.0.0/16` - Another private range option
88
+
89
+
**Example:**
90
+
```bash
91
+
# In your .env file
92
+
SUBNET_CIDR=172.30.0.0/16
93
+
```
94
+
95
+
**Finding the uplink interface (`UPLINK_INTERFACE`)**
96
+
97
+
`UPLINK_INTERFACE` tells Hypeman which host interface to use for routing VM traffic to the outside world (for iptables MASQUERADE rules). On many hosts this is `eth0`, but laptops and more complex setups often use Wi‑Fi or other names.
98
+
99
+
**Quick way to discover it:**
100
+
```bash
101
+
# Ask the kernel which interface is used to reach the internet
102
+
ip route get 1.1.1.1
103
+
```
104
+
Look for the `dev` field in the output, for example:
105
+
```text
106
+
1.1.1.1 via 192.168.12.1 dev wlp2s0 src 192.168.12.98
107
+
```
108
+
In this case, `wlp2s0` is the uplink interface, so you would set:
109
+
```bash
110
+
UPLINK_INTERFACE=wlp2s0
111
+
```
112
+
113
+
You can also inspect all routes:
114
+
```bash
115
+
ip route show
116
+
```
117
+
Pick the interface used by the default route (usually the line starting with `default`). Avoid using local bridges like `docker0`, `br-...`, `virbr0`, or `vmbr0` as the uplink; those are typically internal virtual networks, not your actual internet-facing interface.
118
+
119
+
**Setup:**
120
+
27
121
```bash
28
122
cp .env.example .env
29
-
# Edit .env and set JWT_SECRET
123
+
# Edit .env and set JWT_SECRET and other configuration values
30
124
```
31
125
32
126
#### Data directory
@@ -54,29 +148,27 @@ make build
54
148
```
55
149
### Running the Server
56
150
57
-
1. Copy the example environment file and modify the values:
58
-
```bash
59
-
cp .env.example .env
60
-
# Edit .env and set JWT_SECRET and other configuration values
61
-
```
62
-
63
-
2. Generate a JWT token for testing (optional):
151
+
1. Generate a JWT token for testing (optional):
64
152
```bash
65
153
make gen-jwt
66
154
```
67
155
68
-
3. Start the server with hot-reload for development:
156
+
2. Start the server with hot-reload for development:
69
157
```bash
70
158
make dev
71
159
```
72
160
The server will start on port 8080 (configurable via `PORT` environment variable).
73
161
74
162
### Testing
75
163
164
+
Network tests require elevated permissions to create bridges and TAP devices.
165
+
76
166
```bash
77
167
make test
78
168
```
79
169
170
+
The test command compiles test binaries, grants capabilities via `sudo setcap`, then runs tests as the current user (not root). You may be prompted for your sudo password during the capability grant step.
171
+
80
172
### Code Generation
81
173
82
174
After modifying `openapi.yaml`, regenerate the Go code:
0 commit comments