VM settings

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:

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.

What each VM keeps#

• 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 and GPU memory are not asked for on the first start: they stay on their automatic 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, GUEST_IMPORT and, inside live/, OPENCORE.

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 and is centred in the monitor, so a monitor with a different aspect ratio shows black bars.
• The VM window cannot be resized while it is in full screen. Use Alt+Tab to get back to the terminal.
• 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.

Where the desktop has both, the difference is the keyboard. macOS needs shortcuts the desktop keeps for itself (Cmd, Alt+Tab, the Super combinations), and the Reims vGPU window asks for them as soon as it has focus:

• on Wayland, GNOME confirms the request with a dialog ("The app Unknown wants to inhibit shortcuts") at every start, 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.

While the shortcuts are captured, Ctrl+Alt+Esc gives them back to Ubuntu.

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 and GPU memory#

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, 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.

GPU memory decides how the VM's memory reaches the GPU. On automatic, OSX-REIMS has it copied on a computer whose GPU is an Intel or AMD integrated one, and leaves the decision to Reims vGPU everywhere else — see Troubleshooting. on and off fix the choice for that VM, for a computer where the automatic answer is not the right one.

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

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.

• 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 -y            # no questions, with whatever is saved
osx-reims start 13 --dry-run     # shows the boot command and exits

Every option is in Commands.