tsiry-sandratraina.com
A convenient CLI tool to quickly spin up DragonflyBSD virtual machines using QEMU with sensible defaults.
update README
+138
-4
README.md
+138
-4
README.md
···
42
42
- **⚙️ Configuration Files**: Define VM settings in a `vmconfig.toml` file for
43
43
reproducible setups
44
44
- **🚀 Image-based VMs**: Run VMs directly from saved or pulled images
45
+
- **🌐 HTTP API**: RESTful API for programmatic VM, image, and volume management
46
+
with bearer token authentication
45
47
46
48
## 📋 Prerequisites
47
49
···
186
188
dflybsd-up logout ghcr.io
187
189
```
188
190
191
+
### HTTP API Server
192
+
193
+
```bash
194
+
# Start the HTTP API server (default port: 8893)
195
+
dflybsd-up serve
196
+
197
+
# Start on a custom port
198
+
dflybsd-up serve --port 9000
199
+
200
+
# Set a custom API token via environment variable
201
+
export DFLYBSD_UP_API_TOKEN="your-secure-token"
202
+
dflybsd-up serve
203
+
204
+
# If no token is set, a random UUID will be generated and displayed
205
+
```
206
+
207
+
The HTTP API provides RESTful endpoints for:
208
+
209
+
- **Machines**: List, create, start, stop, restart, inspect, and remove VMs
210
+
- **Images**: Create, list and remove VM images
211
+
- **Volumes**: List, create, inspect, and remove volumes
212
+
213
+
All endpoints require bearer token authentication. See the API documentation
214
+
section below for detailed endpoint information.
215
+
216
+
## 🌐 HTTP API
217
+
218
+
The HTTP API server provides programmatic access to all dflybsd-up functionality
219
+
through RESTful endpoints.
220
+
221
+
### Starting the API Server
222
+
223
+
```bash
224
+
# Start with default settings (port 8893)
225
+
dflybsd-up serve
226
+
227
+
# Custom port
228
+
dflybsd-up serve --port 9000
229
+
230
+
# Set custom token via environment variable
231
+
export DFLYBSD_UP_API_TOKEN="your-secure-token"
232
+
dflybsd-up serve
233
+
```
234
+
235
+
### Authentication
236
+
237
+
All API endpoints require bearer token authentication. Include the token in the
238
+
`Authorization` header:
239
+
240
+
```bash
241
+
curl -H "Authorization: Bearer your-token" http://localhost:8893/machines
242
+
```
243
+
244
+
### API Endpoints
245
+
246
+
#### Machines
247
+
248
+
- **GET `/machines`** - List all machines
249
+
- Query params: `?all=true` to include stopped machines
250
+
- **POST `/machines`** - Create a new machine
251
+
- Body:
252
+
`{ "image": "ghcr.io/tsirysndr/dragonflybsd:6.4.2", "cpus": 4, "memory": "4G", "bridge": "br0", "portForward": ["2222:22"], "volume": "volume-name" }`
253
+
- **GET `/machines/:id`** - Get machine details
254
+
- **POST `/machines/:id/start`** - Start a machine
255
+
- Body (optional):
256
+
`{ "cpus": 4, "memory": "4G", "cpu": "host", "portForward": ["2222:22"] }`
257
+
- **POST `/machines/:id/stop`** - Stop a machine
258
+
- **POST `/machines/:id/restart`** - Restart a machine
259
+
- Body (optional):
260
+
`{ "cpus": 4, "memory": "4G", "cpu": "host", "portForward": ["2222:22"] }`
261
+
- **DELETE `/machines/:id`** - Remove a machine (must be stopped)
262
+
263
+
#### Images
264
+
265
+
- **GET `/images`** - List all local images
266
+
- **POST `/images/pull`** - Pull an image from registry
267
+
- Body: `{ "image": "ghcr.io/user/image:tag" }`
268
+
- **POST `/images/push`** - Push an image to registry
269
+
- Body: `{ "image": "ghcr.io/user/image:tag" }`
270
+
- **POST `/images/tag`** - Tag a machine's image
271
+
- Body: `{ "vmName": "machine-name", "image": "ghcr.io/user/image:tag" }`
272
+
- **DELETE `/images/:ref`** - Remove an image
273
+
- Path param: URL-encoded image reference
274
+
275
+
#### Volumes
276
+
277
+
- **GET `/volumes`** - List all volumes
278
+
- **POST `/volumes`** - Create a new volume
279
+
- Body: `{ "name": "volume-name", "size": "20G", "format": "qcow2" }`
280
+
- **GET `/volumes/:name`** - Get volume details
281
+
- **DELETE `/volumes/:name`** - Remove a volume
282
+
283
+
### Example API Usage
284
+
285
+
```bash
286
+
# List all machines
287
+
curl -H "Authorization: Bearer your-token" \
288
+
http://localhost:8893/machines?all=true
289
+
290
+
# Create a new machine
291
+
curl -X POST \
292
+
-H "Authorization: Bearer your-token" \
293
+
-H "Content-Type: application/json" \
294
+
-d '{"image":"ghcr.io/tsirysndr/dragonflybsd:6.4.2","cpus":4,"memory":"8G"}' \
295
+
http://localhost:8893/machines
296
+
297
+
# Start a machine
298
+
curl -X POST \
299
+
-H "Authorization: Bearer your-token" \
300
+
-H "Content-Type: application/json" \
301
+
-d '{"cpus":8,"memory":"16G"}' \
302
+
http://localhost:8893/machines/clxy1234567890/start
303
+
304
+
# Pull an image
305
+
curl -X POST \
306
+
-H "Authorization: Bearer your-token" \
307
+
-H "Content-Type: application/json" \
308
+
-d '{"image":"ghcr.io/tsirysndr/dragonfly:latest"}' \
309
+
http://localhost:8893/images/pull
310
+
311
+
# Create a volume
312
+
curl -X POST \
313
+
-H "Authorization: Bearer your-token" \
314
+
-H "Content-Type: application/json" \
315
+
-d '{"name":"data-volume","size":"50G","format":"qcow2"}' \
316
+
http://localhost:8893/volumes
317
+
```
318
+
189
319
## ⚙️ Options
190
320
191
321
| Option | Short | Description | Default |
···
232
362
detach = false
233
363
```
234
364
235
-
When you run `dflybsd-up` without arguments, it will use the settings from this file. Command-line options override configuration file settings.
365
+
When you run `dflybsd-up` without arguments, it will use the settings from this
366
+
file. Command-line options override configuration file settings.
236
367
237
368
## 🔢 Version Format
238
369
···
292
423
293
424
## � OCI Registry Integration
294
425
295
-
The tool supports pushing and pulling VM images to/from OCI-compliant registries like Docker Hub, GitHub Container Registry (ghcr.io), and others.
426
+
The tool supports pushing and pulling VM images to/from OCI-compliant registries
427
+
like Docker Hub, GitHub Container Registry (ghcr.io), and others.
296
428
297
429
### Workflow
298
430
···
329
461
### Supported Registries
330
462
331
463
- **GitHub Container Registry**: `ghcr.io`
332
-
- **Docker Hub**: `docker.io` or just the image name (e.g., `username/image:tag`)
464
+
- **Docker Hub**: `docker.io` or just the image name (e.g.,
465
+
`username/image:tag`)
333
466
- Any OCI-compliant registry that supports the OCI Distribution Specification
334
467
335
468
## �🗃️ Virtual Machine Management
···
419
552
dflybsd-up 6.4.2 --image dragonfly.qcow2 --disk-format qcow2
420
553
```
421
554
422
-
The `--install` option ensures that changes made during the VM session are written to the disk image, making them persistent across reboots.
555
+
The `--install` option ensures that changes made during the VM session are
556
+
written to the disk image, making them persistent across reboots.
423
557
424
558
## 🔐 SSH Access
425
559