mDIS User Documentation

Installation with VirtualBox - advanced topics

see also Installation with VirtualBox and Converting an online mDIS instance to VirtualBox instance

VirtualBox Guest Additions: Manual installation

If running as a guest in VirtualBox, you should install the VirtualBox Guest Additions.

How to do this manually:

  • In host: Use the VirtualBox menu "Device" to add a (virtual) CD with Guest Additions
  • This action may trigger a download of the newest version of the VirtualBox Additions from the VirtualBox website.
  • Inside VM guest: open a shell/terminal window
  • Mount CD ROM drive:
sudo mkdir /media/cdrom
sudo mount /dev/cdrom /media/cdrom
  • Run the Guest Additions Installer
sudo /media/cdrom/VBoxLinuxAdditions.run

VirtualBox Guest Additions: Checking status

Installing the VirtualBox Guest Additions is not required for basic use. However, for using the "Shared Folders" feature, it is required. On Shared Folders, you can typically save backups and dump files, or access and import data files from the host.

On the preconfigured mDIS VirtualBox images, the VirtualBox Guest Additions are already installed. (You should check the version)

Inside a Linux guest, check if they are really installed with the shell command: lsmod | grep vboxguest. There should appear the output vboxguest.

Alternatively, from the host, use the key combination Host-N, which works for any guest OS, i.e., type Right CTRL-N (if you use the default Host key configured by VirtualBox). A dialog box will appear with two tabs with metadata about the session. Check the tab "Runtime Information", look for the item "Guest additions".

Swap File for VirtualBox Linux hosts

Optional

If you are using VirtualBox-based mDIS on a Linux host with limited amounts of memory, VirtualBox can slow down at times. This might also happen if you do memory-intensive tasks at the same time, e.g., when you edit a large document with lots of embedded graphics.

To make VirtualBox faster, it is recommended to create a swap file or a swap partition.

To see if you have a swap file enabled, type free -m, which shows types of memory available and the amount of free memory in Megabytes (-m).

To add a swap file to your host machine, you can use these shell commands:

#!/bin/sh
sudo swapon --show
free -h
sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
sudo swapon --show # sudo cmd optional

This creates a one-gigabyte swap file on the root partition / of the VM host.

If you have large amounts of RAM, you can configure the kernel parameter swappiness from default 60 (percent) to 15:

cat /proc/sys/vm/swappiness
sudo bash -c "echo 'vm.swappiness = 15' >> /etc/sysctl.conf"
sudo sysctl -p
cat /proc/sys/vm/swappiness

This will likely improve responsiveness by keeping more application data in RAM rather than swapping. As long as there is sufficient RAM for the workload, it should have minimal downsides.

More technical info on swappiness

The guest VM is not configured to have any swap file.

Automating VirtualBox installations with Vagrant

Optional, advanced.

You can use the free "Vagrant" tool to automate VirtualBox installations. For VirtualBox 6, at least version 2.2 of Vagrant is needed. Then you need to create a Vagrantfile which describes the VirtualBox instance you want to create. This file is a Ruby script, which is executed by Vagrant.

For details, see the GitHub repository of the Vagrant-based mDIS installer. Details are displayed in the README file and the source code there.

It also helps to create an .env file, which contains environment variables that are used by the Vagrantfile.

Check that Vagrant is installed properly with vagrant help. There is only one vagrant command to know: vagrant up:

# create the Virtual machine, according to 'Vagrantfile'
vagrant up

# optional: login into the new VirtualBox (if it is Linux-based and has no graphical desktop)
# username: vagrant, password: vagrant
vagrant ssh

If the complex setup script fails, you can try to run it again from the point where it failed with:

vagrant provision

or even more specifically:

vagrant provision --provision-with <name of step>

VirtualBox Guest extensions can be more conveniently installed with Vagrant. However, this needs the (free) vbguest Vagrant plugin to be installed.

The vagrant-env and vagrant-disksize plugins are also recommended.

Install with

vagrant plugin list
vagrant plugin install vagrant-vbguest
vagrant plugin install vagrant-env
# optional
vagrant plugin install vagrant-disksize
vagrant plugin list
Added value provided by Vagrant

This is really an advanced topic that requires some experience with Vagrant. However, it's the automation capabilities that make learning Vagrant worthwhile.

(For example, it is a single command to install the VirtualBox Guest Additions inside the newly created VirtualBox Guest. Try that with shell scripting!)

TBC

Shrinking a virtual hard-drive partition

Optional, advanced
When your VirtualBox host runs out of disk space too quickly

If the size of the virtual disk file (*.vdi) is much bigger than the disk space actually used by the virtual machine, this can become wasteful. Inside the box, check remaining disk space with the shell command df -h. Check for low values, e.g., "10%" in the Use% column of the df -h output.

If this value of percent-used is too small (that's your personal, subjective decision), you can reduce the size of the partition. This is a two-step process:

  1. Prepare the machine for shrinking. This happens inside of the VM guest.
  2. Shrink the partition of the Guest. Perform this on the host machine, outside of the guest.

Details:

  1. Prepare for shrinking inside the VM
  • (optional?) Boot from a virtual live CD, with the root file system of the Linux guest instance unmounted (TODO: verify this requirement)
  • Run application BleachBit, select "Wipe free space" and run it on the root file system
  1. Shrink the partition of the guest
  • Remove CD from VM, change boot order of the guest VM back to Hard Drive (hd)
  • On the host, search the paths for the program VBoxManage and your vdi disk file and shrink the partition of the hard drive by entering:
    /path/to/program/VBoxManage modifymedium /path/to/mDisBox2-001.vdi --compact

Afterwards, the .vdi file should be smaller.

Oracle Extension Pack

There is also another VirtualBox Extension available called "Oracle VirtualBox Extension Pack". It is not required for mDIS. Actually, it is recommended to not install the "Oracle VirtualBox Extension Pack" because it is distributed with a commercial End-User License Agreement (EULA) issued by Oracle. Agreeing to this EULA has some undesirable implications that we cannot explain here.
If you install this extension, you might have to pay Oracle for using VirtualBox.

How to create an mDIS VirtualBox instance from a native instance

A native instance is an mDIS instance running on a physical machine, not inside a VirtualBox Guest. This is a common scenario for development and testing. The native instance can be migrated to a VirtualBox Guest and then distributed as an .ova file.

Optional, advanced

Why? - Scenario:

Suppose you have an mDIS running natively (without VirtualBox) on a laptop, and you want to distribute the mDIS instance, but you do not want to give the laptop away. So you decide to create a copy of the mDIS instance inside a VirtualBox Guest. The VirtualBox Guest can be distributed easily as an .ova image, as mentioned above.

This migration can be achieved in many ways. It depends on your goals (what you need to distribute) and on the software you have available. This means importing from Linux host to Linux Guest is different than from Windows Host to Windows Guest.

This is one way how to do this for Linux host to Linux guest:

Work In Progress

  • You need to have substantial Linux experience to do the following.
  • This will probably not work unmodified. Use common sense and your sysadmin experience.
  • Design the native instance on a small disk partition (shrink the partition if possible, e.g., with gparted)
  • Create a disk image of that partition with dd, or an appropriate disk partitioning tool.
  • Create a fresh operating system instance as a VirtualBox Instance. Use an installation DVD or DVD image from inside VirtualBox, run the installer. Or use a preconfigured image you grabbed from elsewhere.
  • Add the disk image of the partition as an additional partition to the new VirtualBox instance. Use the VirtualBox Manager GUI to do this.
  • Mount the disk image under an appropriate mount point, e.g., /mnt/mDIS, /data/mDIS, or /data
  • Mount a live CD/DVD, or a third partition, such that the new Linux Guest will boot from that partition next time
  • Shut down the new guest system
  • Boot up the VirtualBox instance from a Linux live CD such that the (root) partition created previously is not mounted
  • Use dd again to overwrite the root partition inside the Linux guest
  • Remove the partition that you've imported previously, remove the live CD
  • Boot up the Linux guest

Tips

  • If you only want to add/import some directories, you achieve the same thing much more easily with the "shared folder" mechanism.
  • You can also create the directory that contains mDIS on its own disk partition. Unmount the partition in the host, mount it inside the guest.

Now continue with setting up the Operating System of the VirtualBox Guest.

See also