tsiry-sandratraina.com
A simple, powerful CLI tool to spin up OpenIndiana virtual machines with QEMU
1# 🌅 OpenIndiana Up
2
3A simple, powerful CLI tool to spin up OpenIndiana virtual machines with QEMU
4
5
6
7## ✨ Features
8
9- 🚀 **Quick Start** - Launch OpenIndiana VMs with a single command
10- 📦 **Auto-Download** - Automatically downloads ISO images from official
11 sources
12- 🎯 **Version Support** - Specify exact OpenIndiana versions or use the latest
13 default
14- 💾 **Persistent Storage** - Attach virtual disk drives for data persistence
15- ⚡ **KVM Acceleration** - Native hardware acceleration for better performance
16- 🌐 **SSH Ready** - Pre-configured port forwarding (host:2222 → guest:22)
17- 🎛️ **Customizable** - Configure CPU, memory, cores, and disk options
18- 📥 **Smart Caching** - Skips re-downloading existing ISO files
19- 🎮 **VM Management** - Start, stop, list, and inspect virtual machines
20- 📊 **State Persistence** - SQLite database tracks VM state and configuration
21- 🏷️ **Auto-naming** - Generates unique names for VMs automatically
22- 🌉 **Bridge Networking** - Support for bridge networking with custom network
23 interfaces
24- 🆔 **MAC Address Management** - Automatic MAC address generation for network
25 devices
26
27## 📋 Requirements
28
29- [Deno](https://deno.land/) runtime
30- QEMU with KVM support
31- Linux host with KVM enabled
32
33## 🛠️ Installation
34
35Run the following command to install the CLI:
36
37```bash
38deno install -A -g -r -f --config deno.json ./main.ts -n openindiana-up
39```
40
41## 🚀 Quick Start
42
43```bash
44# Use default OpenIndiana version (20251026)
45openindiana-up
46
47# Specify a version
48openindiana-up 20251026
49
50# Use a local ISO file
51openindiana-up /path/to/openindiana.iso
52
53# Download from a custom URL
54openindiana-up https://dlc.openindiana.org/isos/hipster/20251026/OI-hipster-text-20251026.iso
55```
56
57## 🎮 Usage
58
59```bash
60openindiana-up [path-or-url-to-iso-or-version] [options]
61```
62
63### Options
64
65| Option | Description | Default |
66| ------------------------ | ------------------------------------------------------------ | ------------ |
67| `-o, --output <path>` | Output path for downloaded ISO | ISO filename |
68| `-c, --cpu <type>` | CPU type to emulate | `host` |
69| `-C, --cpus <number>` | Number of CPU cores | `2` |
70| `-m, --memory <size>` | RAM allocation | `2G` |
71| `-i, --image <path>` | Path to virtual disk image | None |
72| `--disk-format <format>` | Disk format (qcow2, raw, etc.) | `raw` |
73| `--size <size>` | Size of the VM disk image to create if it does not exist | `20G` |
74| `-b, --bridge <name>` | Name of the network bridge to use for networking (e.g., br0) | None |
75
76### VM Management Commands
77
78| Command | Description |
79| ---------------------------------- | --------------------------------------------- |
80| `openindiana-up ps` | List all running virtual machines |
81| `openindiana-up ps --all` | List all virtual machines (including stopped) |
82| `openindiana-up start <vm-name>` | Start a stopped virtual machine |
83| `openindiana-up stop <vm-name>` | Stop a running virtual machine |
84| `openindiana-up inspect <vm-name>` | Inspect virtual machine configuration |
85
86## 💡 Examples
87
88### Basic VM with defaults
89
90```bash
91openindiana-up
92```
93
94### VM with custom resources
95
96```bash
97openindiana-up -C 4 -m 4G
98```
99
100### VM with persistent storage
101
102```bash
103# Create a disk image first
104qemu-img create -f qcow2 openindiana-disk.qcow2 20G
105
106# Launch with the disk attached
107openindiana-up -d openindiana-disk.qcow2 --disk-format qcow2
108```
109
110### Download to specific location
111
112```bash
113openindiana-up -o ~/isos/openindiana.iso
114```
115
116### VM Management Examples
117
118```bash
119# List all running VMs
120openindiana-up ps
121
122# List all VMs (including stopped ones)
123openindiana-up ps --all
124
125# Start a specific VM
126openindiana-up start my-vm-name
127
128# Stop a running VM
129openindiana-up stop my-vm-name
130
131# Inspect VM configuration
132openindiana-up inspect my-vm-name
133```
134
135### Bridge Networking
136
137```bash
138# Use bridge networking (requires bridge setup)
139openindiana-up --bridge br0
140```
141
142### Automatic Disk Creation
143
144```bash
145# Automatically create a 50GB disk if it doesn't exist
146openindiana-up --image my-disk.qcow2 --disk-format qcow2 --size 50G
147```
148
149## 🖥️ Console Setup
150
151When OpenIndiana boots, you'll see the boot menu. For the best experience with
152the serial console:
153
1541. **Select option `3. Escape to loader prompt`**
1552. **Configure console output:**
156 ```
157 set console=ttya
158 set osconsole=ttya
159 set ttya-mode=115200,8,n,1,-
160 boot
161 ```
162
163This enables proper console redirection to your terminal.
164
165## ⚙️ VM Configuration
166
167The script creates a VM with the following default specifications:
168
169- **CPU**: Host CPU with KVM acceleration (configurable with `--cpu`)
170- **Memory**: 2GB RAM (configurable with `--memory`)
171- **Cores**: 2 virtual CPUs (configurable with `--cpus`)
172- **Storage**: ISO-only by default; optional persistent disk (configurable with
173 `--image`)
174- **Network**: User mode networking with SSH forwarding
175- **Console**: Enhanced serial console via stdio with proper signal handling
176- **Default Version**: OpenIndiana 20251026 (when no arguments provided)
177
178### Available CPU Types
179
180Common CPU types you can specify with `--cpu`:
181
182- `host` (default) - Use host CPU features for best performance
183- `qemu64` - Generic 64-bit CPU for maximum compatibility
184- `Broadwell` - Intel Broadwell CPU
185- `Skylake-Client` - Intel Skylake CPU
186- `max` - Enable all supported CPU features
187
188### Available Disk Formats
189
190Common disk formats you can specify with `--disk-format`:
191
192- `raw` (default) - Raw disk image format for maximum compatibility
193- `qcow2` - QEMU Copy On Write format with compression and snapshots
194- `vmdk` - VMware disk format
195- `vdi` - VirtualBox disk format
196
197## 🔌 SSH Access
198
199The VM is configured with port forwarding for SSH access:
200
201```bash
202# After OpenIndiana is installed and SSH is configured
203ssh -p 2222 user@localhost
204```
205
206## 📝 Notes
207
208- The script uses text-based installer ISOs for better headless compatibility
209- Downloaded ISOs are cached and won't be re-downloaded if they exist
210- KVM acceleration requires `/dev/kvm` access on your host system
211- Serial console is connected to stdio for direct interaction
212- VM state is automatically persisted in a SQLite database at
213 `~/.openindiana-up/state.sqlite`
214- Each VM gets a unique randomly generated name using the Moniker library
215- MAC addresses are automatically generated for network devices
216- Bridge networking requires proper bridge configuration and may need sudo
217 privileges
218- VMs can be managed independently with start/stop/inspect commands
219
220## 📜 License
221
222See [LICENSE](LICENSE) file for details.
223
224## 🤝 Contributing
225
226Contributions, issues, and feature requests are welcome!
227
228---
229
230Made with ☀️ for OpenIndiana enthusiasts