Running under GNOME Boxes

GNOME Boxes is a new virtual machine manager and remote desktop manager powered by QEMU, KVM, and libvirt virtualisation technologies. Running Gobolinux under GNOME Boxes is quite easy, even more so than under Virtualbox.

Setup Instructions

1. Create a new Virtual Machine by clicking “New” in the top left corner.
2. Click “Select a file”.
3. Select the Gobolinux LiveCD ISO file.
4. Boxes will be ready to create a virtual machine with 2GB of RAM and 21.5GB of storage. If that is sufficient, click “Create”.
5. Otherwise you can click “Customize” and adjust the sliders for RAM and storage respectively, then click the back arrow.
6. The LiveCD session will then start. Continue normal installation procedures. Remember to eject the LiveCD prior to reboot by going to the top right menu and clicking “Properties” -> “Devices & Shares” and then clicking “Remove” beside the CD/DVD section.

Installing SPICE

Spice allows for integration with the host system including setting native resolutions, file transfers, clipboard support etc.

1. Compile SPICE-VDAgent
2. Run StartTask Spice-VDAgent after login
3. Run spice-vdagent
4. Run xrandr --output Virtual-0 --preferred to update the resolution

Running under VirtualBox

Setting up VirtualBox guest additions

VirtualBox requires its own graphics drivers in order to perform advanced features such as smart mouse sharing and running at a window-dependent full resolution.

These drivers can be built using the “Guest Additions” ISO image included with VirtualBox.

The catch is that we are already using the virtual CD drive from VirtualBox to run the ISO, so we need to add a second one. With the virtual machine shut down, right-click the image, then at the Storage pane, add a second optical drive, and insert the VBoxGuestAdditions.iso file that should be somewhere in your VirtualBox installation:

Then, boot GoboLinux normally in VirtalBox, and do the following:

mount /dev/sr1 /Mount/CD-ROM
cd /Mount/CD-ROM
./VBoxLinuxAdditions.run
udevadm trigger

When you run udevadm trigger the drivers should be loaded, and the console will change resolution immediately. (It will also lose the nice-looking GoboLinux font: to reload it, type setfont lode-2.0-lat1u-16.)

Now, you can start Xorg normally with:

startx

If you want to resize your VirtualBox window, make sure “Auto-resize guest display” is turned on in the VirtualBox “Machine” menu, then, after resizing the VirtualBox window, type in the GoboLinux terminal the following

xrandr --output VGA-0 --preferred

This will resize the desktop to match your window size.

Note that this installation of the VirtualBox guest additions will only last for the current Live-CD session. If you install GoboLinux into a VirtualBox virtual hard drive, you will have to do the same again.

Running under VMWare Workstation Player

When you install GoboLinux 016 on VMWare and boot it for the first time, you will get a black screen after the GRUB boot selection menu. The underlying problem is that the VMWare SCSI hard disk controller driver has been built as a module on the kernel. Because of that, the virtual disk image is not recognized and booting the installed system fails.

Workaround

VMWare saves the virtual machine settings on a file with the .vmx extension. If you have named your virtual machine “GoboLinux 016”, then you will have a file called GoboLinux 016.vmx. Shut down VMWare, open that file with a text editor and replace the lines:

scsi0:1.present = "TRUE"
scsi0:1.fileName = "GoboLinux 016.vmdk"
scsi0:1.redo = ""

with the following:

sata0:1.present = "TRUE"
sata0:1.fileName = "GoboLinux 016.vmdk"
sata0:1.deviceType = "disk"

The fileName may look different on your machine. You will want to keep whatever name your config file presents. Also, make sure that the following lines do exist in the vmx file (again, pciSlotNumber may look different on your vmx file):

sata0.present = "TRUE"
sata0.pciSlotNumber = "37"

Once you are done, save the file and launch VMWare. The system should boot up nicely this time.

Running under HyperV

When running the GoboLinux 016.01 live ISO through Hyper-V, you will notice that startx does not start correctly by default. You can fix this by adding a kernel boot parameter and creating an Xorg configuration file.

Edit /System/Kernel/Boot/grub/grub.cfg and find the kernel boot line. Change video=vesafb:off to video=hyperv_fb:1024x768 and save it. You may wish to try this part in advance first, without saving it; in that case, press e at the Grub menu, make this same edit, and press Ctrl-X to boot once only with the new command line.

Run X -configure. It will generate a file xorg.conf.new. Edit this file, and change vesa to fbdev. Move the file to /etc/X11/xorg.conf.

Reboot. startx will now work normally.

Running GoboLinux under QEMU

We’ll illustrate how to:

• create a disk image
• boot an ISO image of Gobo under QEMU
• install Gobo to a disk image on the host filesystem
• reboot the newly installed guest
• initialize networking
• launch QEMU from a helper script

Create a disk image

This is where we will install our Linux system.

qemu-img create gobo.img 10G

Boot the installer

Here is the full command you can edit and paste into the terminal:

sudo qemu-system-x86_64 \
-cdrom GoboLinux-016.01-alpha-x86_64.iso \
-hda gobo.img \
-boot d \
-m 768 -enable-kvm -show-cursor -cpu host -daemonize \
-vga std -soundhw ac97 -rtc base=utc \
-usb -usbdevice tablet -device usb-mouse -vga std -clock unix

To test boot only the ISO, omit the -hda option.

Boot the disk image

After you’ve finished the installation, shutdown the guest OS and terminate QEMU. Start QEMU again, this time booting from the disk image:

sudo qemu-system-x86_64 \
-hda gobo.img \
-boot c \
-m 768 -enable-kvm -show-cursor -cpu host -daemonize \
-vga std -soundhw ac97 -rtc base=utc \
-usb -usbdevice tablet -device usb-mouse -vga std -clock unix

Networking under QEMU

QEMU provides a networking stack so that the guest OS running on this virtual machine can access the internet, or ssh to the host.

The only extra setup needed is to run Gobo’s DHCP client inside the guest.

dhcpcd

By default QEMU acts as a firewall and does not permit any incoming traffic. It also doesn’t support protocols other than TCP and UDP. This means that ping and other ICMP utilities won’t work.

Details can be found here.

Helper script

Qemust is a perl5 script you can use to start your QEMU processes. With most options defined in the script, the command line becomes much simpler.

To boot from an ISO and install to a disk image:

qemust --iso=GoboLinux-016.01-alpha-x86_64.iso --image=gobo.img

To boot from the disk image

qemust  --image=gobo.img

To test an ISO:

qemust --iso=GoboLinux-016.01-alpha-x86_64.iso

The script has some library dependencies. The most convenient way to install them (and any CPAN modules) is to use cpanminus (cpanm). So install cpanminus, then the dependencies:

cpan App::cpanminus
cpanm Getopt::Long::Descriptive

The script follows below. Edit the QEMU options to your liking, put the script in somewhere in your $PATH, and make it executable with something like chmod a+x ~/bin/qemust.

#!/usr/bin/env perl
use strict;
use warnings;

#   qemust - start QEMU

use 5.012;
use Getopt::Long::Descriptive;
my ($opt, $usage) = describe_options(
   '%c %o',
   [ 'iso=s',  "ISO file to boot" ],
   [ 'image=s',"OS disk image file" ],
   [ 'help',   "print usage message and exit" ],
   [ 'n',      "print QEMU startup command and exit" ],
 );
print($usage->text), exit if $opt->{help} or ! keys %$opt;

my $boot_drive = $opt->{iso} ? 'd' : 'c';

my @cmd = grep{! /^\s*$/} map{s/\s*#.*$//; $_} split "\n",<<"CMD";

sudo                 # run as root
qemu-system-x86_64   # for 64-bit CPUs
-enable-kvm          # faster virtualization
-show-cursor         #
-boot $boot_drive    # boot from DVD/CDROM if present
-m 768               # use memory 768MB
-cpu host            # same CPU model as host
-daemonize           # avoid race conditions when QEMU started by external program
-vga std             # probably -vga vmware would work, too
-soundhw ac97        # typical soundcard, -soundhw hda should also work
-rtc base=utc        # timer related
-usb                 # enable USB driver
-usbdevice tablet    # so QEMU can report mouse position without grabbing mouse
-device usb-mouse    #
-clock unix          #

CMD

push @cmd, "-cdrom $opt->{iso}" if $opt->{iso};
push @cmd, "-hda $opt->{image}" if $opt->{image};
my $cmd = join " \\\n",@cmd;
say $cmd;
system($cmd) unless $opt->{n};
__END__

Installing to external storage devices

GoboLinux 016 comes with two installation modes: UEFI and BIOS-compatibility mode. Depending on how your computer firmware is configured you may need to follow one or another recipe below.

BIOS-compatibility mode

Ensure that your external disk has been configured with a MSDOS partition table. You need to have at least one Linux partition (e.g., ext4), with the BOOT flag set.

You can then proceed with the installation of GoboLinux by selecting that Linux partition as install target and by enabling the installation of the bootloader on the master boot record (MBR) of that disk.

UEFI mode

Ensure that your external disk has been configured with a GPT partition table. You need to have at least one Linux partition (e.g., ext4) and a FAT (32/16/12) partition which is where the UEFI application embedding the GRUB bootloader will be stored. The FAT partition needs to have both the ESP and BOOT flags set. If you are using GParted, that FAT partition will be automatically formatted by the tool. If you are not, then make sure to invoke mkfs.msdos to format it yourself.

Once the partitioning is arranged, you can proceed with the installation of Gobo by selecting the Linux partition as system install target and by selecting the FAT partition (also called EFI System Partition) as bootloader install target.

Troubleshooting

Unable to mount root fs

Both USB-Storage and UAS (USB-Attached-SCSI) drivers are built into the kernel. However, at times the kernel may not have time to discover the partitions on your external disk and may fail to mount the root filesystem. This particular problem can be fixed by adding the rootwait parameter to the kernel command line.

For BIOS-compatibility mode:

1. Mount your system partition using the LiveCD under /Mount/GoboLinux
2. Edit the file at /Mount/GoboLinux/System/Kernel/Boot/grub/grub.cfg. Look for the lines starting with linux /System/Kernel/Boot/kernel-4.8.2-Gobo and append the word rootwait to the very end of those lines
3. Unmount the partition under /Mount/GoboLinux and reboot.

For UEFI mode:

1. Mount your boot partition (the one with a FAT filesystem) using the LiveCD under /Mount/GoboLinux
2. Edit the file at /Mount/GoboLinux/EFI/BOOT/grub-efi.cfg. Look for the lines starting with linux /System/Kernel/Boot/kernel-4.8.2-Gobo and append the word rootwait to the very end of those lines
3. Regenerate the UEFI application. This is a large command, so it’s better to just copy+paste it.

cd /Mount/GoboLinux/EFI/BOOT
grub-mkstandalone-efi -d /lib/grub/x86_64-efi -O x86_64-efi --modules="part_gpt part_msdos iso9660 all_video efi_gop efi_uga video_cirrus gfxterm gettext font" --fonts="unicode" --themes="" -o BOOTx64.EFI --compress=gz "boot/grub/grub.cfg=grub-efi.cfg"

Afterwards, unmount the partition under /Mount/GoboLinux and reboot.