Skip to content
Documentation: Console

Documentation · Using OSX-REIMS

Console

The OSX-REIMS menu: create and manage VMs, view logs and maintain the computer.

Alpha

This documentation covers OSX-REIMS 0.6.0, alpha software. Commands and options may change between versions; when in doubt, check osx-reims --help on the installed version.

The console is the OSX-REIMS menu in the terminal. It gathers what you need for day-to-day operation: creating and managing VMs, viewing logs and maintaining the computer.

Opening the console

  • From the applications menu, open OSX-REIMS. The console opens in a terminal window, 160 × 35 characters in Ptyxis, Ubuntu's default terminal, and in GNOME Terminal. The window closes when you quit; if the console exits with an error, it stays open until you press Enter.
  • Or run this in a terminal:
osx-reims

The console needs an interactive terminal. For automation, use the commands.

Main screen

The main screen lists the VMs, with the number, macOS version and state of each, and shows the menu:

Key Option
1 Create new VM: creates a VM (see Your first VM)
2 Import VM disk: creates a VM from the QCOW2 disk of a macOS already installed in another VM (see Importing a VM)
3 Manage VMs: starts, shuts down and restarts VMs
4 View logs: lists the recent logs
5 Maintenance: deletes VMs, cleans the cache, checks the computer, updates OSX-REIMS and Reims vGPU and turns on the bridged network
6 Backup & Restore: backs up a VM, restores or deletes a backup (see Backup and restore)
Q Quit: leaves the console

Just press the option's key.

Note

While the environment is not ready (on first use or after an update), the screen shows why and offers S (Prepare environment), which runs osx-reims setup. Creating, importing and managing VMs are unavailable until then.

The main screen also shows one line when a newer OSX-REIMS version has been published, with the name of the file to download on Discord and the way to Maintenance › Update OSX-REIMS. It reads the last check saved on the computer and runs the next one in the background — at most once a day — so the screen never waits for the network and never fails because of it. See Updating and removing.

Managing VMs

Manage VMs lists the VMs and asks for a number. If the VM is shut down, the console shows a summary of its settings and offers S to start it, C to change a setting or Q to cancel. On a VM's first start the settings are asked one by one and saved for the next times. See VM settings.

If the chosen VM is already running, the console offers:

Key Option
S Shut down: macOS closes everything safely (recommended)
R Restart: forced restart, without saving
F Force power off: cuts the VM's power
T Terminate process: when the VM does not respond
C Cancel: does nothing

When shutting down, OSX-REIMS waits up to 60 seconds for macOS. If macOS does not shut down, there may be a confirmation in the VM window or an app preventing the shutdown. You then choose Wait longer, Force power off or Cancel (the VM keeps running).

While the VM is open

The VM opens in its own window. Click it to give macOS the keyboard; Ctrl+Alt+Super, pressed together, give the keyboard back to Ubuntu. To shut the VM down, use the Apple menu › Shut Down, inside macOS: closing the VM window powers it off at once, like pulling its plug. Keep the terminal open while you use the VM.

In the terminal, these keys act on the VM. Press the same key twice within 5 seconds to confirm:

Key What it does
S Asks macOS to shut down
R Forces the VM to restart
F Forces the VM to power off; anything unsaved is lost
T Terminates the VM process; anything unsaved is lost

The first Ctrl+C only warns that the VM is still running; a second one within 5 seconds asks macOS to shut down. Closing the terminal does not shut the VM down.

Viewing logs

View logs lists the 15 most recent runs, with date, action, VM and result. Type a log's number and press Enter to open it; the arrow keys and PgUp/PgDn scroll, and Q goes back. Enter without a number returns to the menu.

Result Meaning
Done The action finished
Nothing was done Nothing was done
Cancelled The action was cancelled
Failed The action failed
Terminal closed with the VM running The terminal was closed while the VM was on
unfinished The action is in progress or was interrupted

Logs are kept in /opt/osx-reims/logs/, up to the 100 most recent. To ask for help, share the log of the run with the problem and a doctor log (see Troubleshooting).

Maintenance

Key Option
1 Delete a VM: deletes a VM that is shut down
2 Delete all VMs: deletes every VM; all must be shut down
3 Clean cache: deletes the downloaded macOS installers
4 Check this computer: runs doctor, whose log is the one to share when asking for help
5 Prepare environment: runs setup
6 Update Reims vGPU: tested or latest version, with the VMs shut down
7 Rebuild Reims vGPU: builds the same version again from scratch, with the VMs shut down
8 Update OSX-REIMS: installs the .deb package you downloaded, with the VMs shut down
9 VM network: turns on or off the bridge that gives VMs an address of their own on the network
B Back: returns to the main menu

Deleting VMs and cleaning the cache always ask for confirmation, and the default answer is no. Deleting a VM cannot be undone.

  • Rebuild Reims vGPU is for a build that stopped working, usually after a system update. It downloads nothing and changes no version: for that, use Update Reims vGPU. See Reims vGPU version.
  • Update OSX-REIMS installs a newer version from the .deb file you downloaded from the #osx-reims channel. After the update the console closes itself, so the next window opens on the version just installed. See Updating and removing.
  • VM network shows the bridge, the VMs on it and the wired network ports, and turns the bridge on or off. It asks for the administrator password. See Network.

Backup & Restore

Key Option
1 Back up a VM: keeps the whole VM in a single file; a running VM is shut down first, if you agree
2 Restore a backup: puts a backup back, over the VM it came from or as a new VM
3 Delete a backup: deletes a backup file
B Back: returns to the main menu

The details are in Backup and restore.