tsiry-sandratraina.com
A simple CLI tool to spin up OpenBSD virtual machines using QEMU with minimal fuss.
Update README to enhance VM management commands and add port forwarding examples
+73
-15
+72
-14
README.md
+72
-14
README.md
···
22
22
- ⚙️ **Configurable**: Customize CPU, memory, cores, and more
23
23
- 🌐 **Network Ready**: Support for both NAT (SSH port forwarding) and bridge
24
24
networking
25
-
- 📝 **Serial Console**: Direct terminal access via `-nographic` mode
25
+
- � **Port Forwarding**: Custom port mapping with `--port-forward` option
26
+
- �📝 **Serial Console**: Direct terminal access via `-nographic` mode
26
27
- 🗃️ **VM Management**: Persistent state tracking with SQLite database
27
-
- 📋 **VM Lifecycle**: Start, stop, list, and inspect VMs with unique names
28
+
- 📋 **VM Lifecycle**: Start, stop, restart, list, and inspect VMs with unique names
29
+
- 🗑️ **VM Cleanup**: Remove VMs from tracking with `rm` command
30
+
- 📊 **Logs Management**: View and follow VM logs in real-time
31
+
- 🔄 **Background Mode**: Run VMs detached with `--detach` option
28
32
- 🎯 **Smart Detection**: Automatically detects existing disk images to avoid
29
33
data loss
30
34
- 🔗 **Bridge Support**: Automatic bridge network creation and QEMU
···
73
77
# Start a specific VM by name or ID
74
78
openbsd-up start my-vm-name
75
79
80
+
# Start a VM in the background (detached mode)
81
+
openbsd-up start my-vm-name --detach
82
+
76
83
# Stop a running VM
77
84
openbsd-up stop my-vm-name
78
85
86
+
# Restart a VM
87
+
openbsd-up restart my-vm-name
88
+
89
+
# Remove a VM from state tracking
90
+
openbsd-up rm my-vm-name
91
+
79
92
# Inspect VM details and configuration
80
93
openbsd-up inspect my-vm-name
94
+
95
+
# View VM logs
96
+
openbsd-up logs my-vm-name
97
+
98
+
# Follow VM logs in real-time
99
+
openbsd-up logs my-vm-name --follow
81
100
```
82
101
83
102
### Advanced Configuration
···
92
111
--disk-format qcow2 \
93
112
--size 40G
94
113
114
+
# Run VM in background (detached mode)
115
+
openbsd-up 7.8 --detach
116
+
95
117
# Bridge networking (requires sudo)
96
118
openbsd-up 7.8 --bridge br0
97
119
120
+
# Custom port forwarding (host:guest port mappings)
121
+
openbsd-up 7.8 --port-forward 8080:80,3000:3000
122
+
98
123
# Save downloaded ISO to specific location
99
124
openbsd-up 7.8 --output ~/isos/openbsd-78.iso
100
125
```
···
103
128
104
129
### Global Options
105
130
106
-
| Option | Short | Description | Default |
107
-
| --------------- | ----- | ------------------------------------------------------------ | -------------- |
108
-
| `--output` | `-o` | Output path for downloaded ISO | Auto-generated |
109
-
| `--cpu` | `-c` | CPU type to emulate | `host` |
110
-
| `--cpus` | `-C` | Number of CPU cores | `2` |
111
-
| `--memory` | `-m` | RAM allocation | `2G` |
112
-
| `--image` | `-i` | Path to persistent disk image | None |
113
-
| `--disk-format` | | Disk format (qcow2, raw, etc.) | `raw` |
114
-
| `--size` | | Size of disk image to create if it doesn't exist | `20G` |
115
-
| `--bridge` | `-b` | Name of the network bridge to use for networking (e.g., br0) | None |
131
+
| Option | Short | Description | Default |
132
+
| ---------------- | ----- | ------------------------------------------------------------ | -------------- |
133
+
| `--output` | `-o` | Output path for downloaded ISO | Auto-generated |
134
+
| `--cpu` | `-c` | CPU type to emulate | `host` |
135
+
| `--cpus` | `-C` | Number of CPU cores | `2` |
136
+
| `--memory` | `-m` | RAM allocation | `2G` |
137
+
| `--image` | `-i` | Path to persistent disk image | None |
138
+
| `--disk-format` | | Disk format (qcow2, raw, etc.) | `raw` |
139
+
| `--size` | | Size of disk image to create if it doesn't exist | `20G` |
140
+
| `--bridge` | `-b` | Name of the network bridge to use for networking (e.g., br0) | None |
141
+
| `--detach` | `-d` | Run VM in the background and print VM name | `false` |
142
+
| `--port-forward` | `-p` | Port forwarding rules (hostPort:guestPort, comma-separated) | None |
116
143
117
144
### Subcommands
118
145
···
121
148
| `ps` | List virtual machines | `openbsd-up ps --all` |
122
149
| `start <name>` | Start a stopped VM by name or ID | `openbsd-up start my-vm` |
123
150
| `stop <name>` | Stop a running VM by name or ID | `openbsd-up stop my-vm` |
151
+
| `restart <name>` | Restart a VM by name or ID | `openbsd-up restart my-vm` |
152
+
| `rm <name>` | Remove a VM from state tracking | `openbsd-up rm my-vm` |
124
153
| `inspect <name>` | Show detailed VM information and configuration | `openbsd-up inspect my-vm` |
154
+
| `logs <name>` | View VM logs | `openbsd-up logs my-vm` |
125
155
126
156
## 🖥️ Console Setup
127
157
···
139
169
140
170
### NAT Mode (Default)
141
171
142
-
- **SSH Port Forward**: `localhost:2222` → VM port `22`
172
+
- **SSH Port Forward**: `localhost:2222` → VM port `22` (default)
173
+
- **Custom Port Forwarding**: Configure with `--port-forward` option
143
174
- **Network Device**: Intel E1000 emulated NIC
144
175
- No special privileges required
145
176
177
+
#### Custom Port Forwarding Examples
178
+
179
+
```bash
180
+
# Forward host port 8080 to VM port 80
181
+
openbsd-up 7.8 --port-forward 8080:80
182
+
183
+
# Multiple port forwards
184
+
openbsd-up 7.8 --port-forward 8080:80,3000:3000,2222:22
185
+
186
+
# Access services after VM is running
187
+
curl http://localhost:8080 # Access VM's port 80
188
+
ssh -p 2222 user@localhost # SSH to VM
189
+
```
190
+
146
191
### Bridge Mode
147
192
148
193
- **Direct Bridge Access**: VM gets IP from bridge network
···
180
225
- Start/stop VMs by name or ID
181
226
- Inspect detailed VM configurations
182
227
183
-
## �💡 Tips
228
+
## 💡 Tips
184
229
185
230
- 🐏 Allocate at least 2GB RAM for smooth installation
186
231
- 💿 ISOs are cached - re-running with same version skips download
···
190
235
- 🏷️ Use VM names for easy management: `openbsd-up start my-web-server`
191
236
- 🌉 Bridge networking requires sudo but provides direct network access
192
237
- 📊 Use `openbsd-up ps --all` to see both running and stopped VMs
238
+
- 🔄 Use `--detach` mode to run VMs in the background
239
+
- 🔗 Configure custom port forwarding with `--port-forward host:guest`
240
+
- 📝 Monitor VM activity with `openbsd-up logs <name> --follow`
241
+
- 🗑️ Clean up unused VMs with `openbsd-up rm <name>`
193
242
194
243
### Creating Persistent VMs
195
244
···
197
246
# Create a VM with persistent storage
198
247
openbsd-up 7.8 --image my-server.qcow2 --disk-format qcow2 --size 40G
199
248
249
+
# Run a VM in the background
250
+
openbsd-up 7.8 --detach --image background-vm.img
251
+
252
+
# Set up a web server VM with port forwarding
253
+
openbsd-up 7.8 --image webserver.qcow2 --port-forward 8080:80,8443:443
254
+
200
255
# Later, restart the same VM (no ISO needed for installed systems)
201
256
openbsd-up start <vm-name>
257
+
258
+
# Monitor the VM logs
259
+
openbsd-up logs <vm-name> --follow
202
260
```
203
261
204
262
## 🔧 Architecture