Skip to content
Documentation: VM settings

Documentation · Using OSX-REIMS

VM settings

Memory, processors, screen, display server, OpenCore, GPU, refresh rate, network, sound and autostart: what each VM remembers and how to change it.

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.

Every VM keeps its own settings, in its own folder. You answer once and, from then on, starting the VM is a single key: osx-reims start shows a summary of what it will use and asks only whether to start it.

The start menu

With every setting saved for the VM, start shows the summary and offers:

Key Option
S Start: starts the VM with the settings in the summary
C Change: changes a setting before starting
Q Cancel: does not start the VM

C opens the list of settings, each with its current value. Picking one leads to the same question the first start asked; on the way back, the summary is printed again — so what the summary shows is always what the VM will use.

A VM's first start asks for everything it can: memory, processors, screen and display server. The answers are saved and become that VM's defaults.

Note

A setting answered in the C menu is saved as soon as it is answered. Changing a setting and then cancelling the start leaves the new value for next time; Q only means "do not start now".

What each VM keeps

Setting Key in C Values Command-line option
Memory M 8G, 16384M… (default: 8G) -r, --ram
Processors P 1 to 32 (default: 4) -c, --cpus
OpenCore O the VM boot disk or the macOS disk --opencore image|esp
Screen S window (default) or full screen --windowed, --fullscreen
Display server D wayland or x11 --wayland, --x11
Nested VMs V off (default) or on --nested, --no-nested
GPU U automatic (default) or a GPU on this computer --gpu auto|<vendor:device>
Refresh rate R automatic (default) or a rate in Hz --refresh auto|<Hz>
Network N NAT (default) or bridge --net nat|bridge
Sound H on (default) or off --audio, --no-audio
Autostart A off (default) or on, for one VM osx-reims autostart

On an installed VM that still has the installer it was created with, the C menu also offers I (Installer), to attach it again for a single start (see The installer, again).

  • OpenCore is listed only for a VM that is already installed, because a VM only becomes installed through its own first start. Without an answer it starts from its own boot disk, and the summary says so.
  • Nested VMs, GPU, refresh rate, network and sound are not asked for on the first start: they stay on their default value until you change them in the C menu or with a command-line option.
  • Autostart does not live in the VM folder: it is a service on this computer (see Autostart).
  • A command-line option applies to that start and becomes the VM's saved value.
  • A saved value that no longer passes the checks — more processors than the limit, after a VM folder was copied to another computer — counts as missing, and that start asks for it again.

The files live in the VM's folder, /opt/reims-vgpu/vm/disks/rails/macos-<number>/: RAM, CPUS, SCREEN, BACKEND, NESTED, GPU, REFRESH, NET, AUDIO and, inside live/, OPENCORE. A GUEST_IMPORT file left by version 0.4 (the former GPU memory setting) is ignored.

Screen: window or full screen

In full screen, the VM takes the whole monitor, with no window decorations and no Ubuntu desktop behind it. The question is asked for every VM, installed or not, because full screen is as useful during the macOS installation as afterwards.

  • Nothing changes inside macOS: it keeps its own resolution, 1920 × 1080, and the picture is scaled to the monitor and centred, so a monitor with a different aspect ratio shows black bars.
  • To get back to the terminal, give the keyboard back to Ubuntu with Ctrl+Alt+Super and use Alt+Tab.
  • The VM opens on the monitor its window appears on; choosing the monitor is not up to OSX-REIMS.

Display server: Wayland or X11

The VM window can open on the session's own Wayland or on X11, through XWayland. The default is the server your session runs: a desktop without Wayland (Linux Mint's Cinnamon, MATE and Xfce, and every other X11 session) gets x11 as its default. Both are always listed, and the one your session does not have is marked.

The window is Reims vGPU's own. Click into it to give macOS the keyboard: the shortcuts the desktop keeps for itself (Cmd, Alt+Tab, the Super combinations) then go to macOS. Ctrl+Alt+Super, pressed together, give the keyboard back to Ubuntu, and so does the window losing focus; the window's title says which state it is in.

Where the desktop has both servers, the difference is how the keyboard capture is granted:

  • on Wayland, GNOME confirms the request with a dialog every time the VM takes the keyboard, because the window cannot be matched to an installed application and the answer is never stored;
  • on X11, the same request is granted without asking.

Warning

Closing the VM window powers the VM off at once, like pulling its plug. Shut macOS down from its Apple menu, or with osx-reims stop.

Note

Asking for a server your session does not run is refused when the VM starts: a window on a server that is not there would open on nothing.

Nested VMs

With Nested VMs on, the processor macOS sees carries Intel VT-x, so Hypervisor.framework works inside the VM and Docker, VirtualBox and the Android emulator have something to run on. Inside macOS, sysctl kern.hv_support answers 1 once it is there.

  • Nothing else changes in macOS: the identity it shows is the same, so turning it on and off does not affect Apple services.
  • The VM has to be restarted for the change to reach it.
  • It needs an Intel computer with nested virtualization on in KVM (kvm_intel nested=Y, Ubuntu's default). This is not a matter of speed on AMD: macOS virtualizes through VT-x and nothing else, and KVM cannot present it on an AMD processor.
  • Where the computer cannot offer it, the VM's answer is still saved, the VM starts without it, and the menu, the summary and osx-reims doctor all say so.

GPU

On a computer with more than one GPU — an integrated one and a graphics card — the VM runs on the GPU Reims vGPU picks: the dedicated one. That is the automatic answer. Each VM can name another one:

osx-reims start 10 --gpu 8086:a780   # this VM on the Intel integrated GPU
osx-reims start 10 --gpu auto        # back to Reims vGPU's own pick

The C › U menu lists the GPUs Vulkan shows on this computer that Reims vGPU can use (Vulkan 1.2 or later, with the VK_EXT_external_memory_host extension), each by its vendor and device ID (1002:73ff), as vulkaninfo --summary prints them. A GPU that is not on the computer when the VM starts — a VM folder brought from another computer, or an integrated GPU the motherboard switches off — does not stop it: the VM starts on the automatic GPU, the summary says so, and the choice stays saved for when that GPU is back.

A GPU whose driver lacks VK_EXT_external_memory_host, such as NVIDIA on the open nouveau driver (NVK), cannot run VMs: it is not offered in the menu, and when the automatic choice would land on it, start uses the best GPU that has the extension and says which one it passed over and why. With no such GPU at all, start refuses and says what to install. See Requirements.

The start summary has a GPU line, with the GPU the VM runs on; osx-reims doctor shows this computer's automatic answer and the VMs with a choice of their own.

Note

Up to version 0.4.1, each VM had a GPU memory setting (--guest-import). The rewritten Reims vGPU no longer has that choice: it always hands the VM's memory to the GPU, through /dev/udmabuf where the driver needs it. The setting is gone.

Refresh rate

macOS draws its desktop at the refresh rate Reims vGPU offers it. On automatic, the default, it is the rate of the monitor the VM window opens on: on a monitor at 120 Hz, macOS runs at 120 Hz (System Settings › Displays says so). Each VM can have a rate of its own, in the C › R menu (60, 75, 100, 120, 144, 165 or 240 Hz) or with --refresh:

osx-reims start 10 --refresh 120    # macOS at 120 Hz, whatever the monitor runs at
osx-reims start 10 --refresh auto   # back to the monitor's own rate

A rate above the monitor's only costs GPU: macOS draws more frames than the window can show. A rate below it saves some. The VM reads the rate when it starts, so a change applies on the next start. The summary has a Refresh line.

Network: NAT or bridge

Each VM is on NAT, the default, or on the bridge, in the C › N menu or with --net:

osx-reims start 10 --net bridge    # an address of its own on this computer's network
osx-reims start 10 --net nat       # back behind this computer's address
  • NAT: the VM reaches the network and the internet through this computer's address and is reached from this computer alone; its SSH is at localhost:22<number>. Nothing to set up.
  • Bridge: the VM joins the network this computer is wired to, with an address of its own from the same router, and is reached from any computer on that network. This computer keeps its own address.

The bridge is set up once, in the console (Maintenance › VM network) or from the terminal:

osx-reims network                       # the bridge, the VMs on it and the wired ports
osx-reims network bridge on             # on the port the default route uses
osx-reims network bridge on --port enp6s0
osx-reims network bridge off            # refused while a VM on the bridge runs
  • It needs a wired network port: Wi-Fi cannot be bridged.
  • The port has to be managed by NetworkManager, as on Ubuntu Desktop. Otherwise nothing is changed and the bridge has to be set up by hand.
  • Turning the bridge on and off asks for the administrator password. The network stops for a few seconds while the bridge is set up; if the computer does not get its address back within a minute, the change is undone by itself.
  • From then on, the bridge comes up with the computer, with 8 ports for VMs: up to 8 VMs can be on the bridge at once. Starting or stopping a VM never touches this computer's network.
  • A VM set to the bridge does not start while the bridge is not there: it is not moved to NAT by itself. The summary says so, and C › N sets it to NAT.

osx-reims doctor has a VM network line. Removing the OSX-REIMS package does not undo the bridge: run osx-reims network bridge off first.

Sound

Each VM has sound unless you turn it off, in the C › H menu or with --audio and --no-audio:

osx-reims start 10 --no-audio    # no audio device in the VM
osx-reims start 10 --audio       # sound again

With sound on, the VM gets two devices, both playing through the session's sound server (Ubuntu's PipeWire, or PulseAudio):

  • a USB audio device, which macOS uses from Ventura to Tahoe with no driver to install: it is macOS's sound, listed in System Settings › Sound;
  • an HD Audio controller, for OpenCore's boot chime. It is in the EFI of VMs created from 0.6.0 on; VMs that already existed keep their own OpenCore, so they get macOS's sound but not OpenCore's chime.

The speakers used are the ones Ubuntu picks in its sound settings. With no sound server, the VM starts silent, and the summary says so. A change applies on the next start. The summary has an Audio line, and doctor a Sound line.

The installer, again

A new VM gets its installer on its first start only; from then on, it starts from its own disk. If the macOS installation was interrupted half way, or you want to reinstall or repair macOS, the installer can be attached again for one start, without deleting or recreating anything:

osx-reims start 10 --attach-installer

In the C menu it is the I option (Installer), offered for an installed VM that still has its installer. The VM's disk is kept as it is — Disk Utility in the installer can erase it, if that is what you want — and nothing is saved: the next start is without the installer. An imported VM has no installer.

OpenCore

The OpenCore that starts the VM can be the VM boot disk, the one that came with it, or the macOS disk, meaning the OpenCore in the EFI partition of the disk macOS is installed on. The details, including how to install the VM's OpenCore into that EFI, are in Advanced configuration.

Autostart

Autostart makes one VM open by itself, so that turning the computer on ends in macOS. It is in the C › A menu and has a command of its own:

osx-reims autostart status
osx-reims autostart on 13            # and offers Ubuntu's automatic login
osx-reims autostart on 13 --login    # without asking
osx-reims autostart off

Because the VM window opens on the graphical session, nothing can start the VM before somebody logs in: it is a systemd user service (osx-reims-vm@<number>.service), not a system service. So getting from power-on to macOS is two settings:

  1. the VM's autostart;
  2. Ubuntu's automatic login, which is a setting of Ubuntu itself (/etc/gdm3/custom.conf). OSX-REIMS offers to turn it on when autostart is enabled, and never turns it on as a side effect.

Warning

With automatic login, whoever turns the computer on is in your session, and the login password no longer unlocks the keyring. On the first change, a copy of the file is kept in /etc/gdm3/custom.conf.osx-reims.bak.

  • Only one VM can have autostart; enabling it for one takes it off the other.
  • Only a VM with macOS already installed can have it: the first start is the macOS installation, which is not something to leave running unwatched.
  • The VM starts with its own saved settings. For the whole monitor, set its Screen to full screen.
  • Shutting macOS down ends the service, and that is how you come back to Ubuntu. Logging out or turning the computer off asks macOS to shut down and waits up to 120 seconds instead of cutting the power.
  • If the VM does not start, a notification and a terminal window say why and open the console — the error is not left hidden in the system log.
  • The answer is kept by systemd, not in the VM folder: copying that folder to another computer does not take autostart with it.

Settings fixed for the computer

On a computer that always shows the VM the same way, such as a kiosk, the /etc/osx-reims.conf file accepts FORCE_SCREEN and FORCE_BACKEND. They come before each VM's saved choice and after that start's own answer, so the command-line options and the C menu still win. See Advanced configuration.

Everything from the command line

osx-reims start 13 -r 16G -c 6 --fullscreen --x11 --nested
osx-reims start 13 --refresh 120 --net bridge --no-audio
osx-reims start 13 -y            # no questions, with whatever is saved
osx-reims start 13 --dry-run     # shows the boot command and exits

Every option is in Commands.