mDIS User Documentation

Installation with VirtualBox

Installation with VirtualBox

Supported Host/Guest Relationships

Regarding the VM hosts and VM guests, the supported operating systems are shown in the figure below.

osmatrix

Green background means all versions should work in theory. Using VirtualBox is possible on these host/guest combinations. But we cannot test all of these combinations thoroughly. The best-studied combinations are shown with a checkmark.

Newer MacBooks, iPads, Chromebooks not supported

Some newer MacBooks are not supported: Computers with "Apple Silicon". Concretely, this includes MacBooks with "M1", "M2", "M3" processors, a new CPU architecture shipped by Apple since ~2020. VirtualBox does not run on Macs equipped with these processors.
Use VMWare Fusion instead, see Wikipedia (opens new window), Offcial Website (opens new window)(free personal licenses are available in 2023).
Apple iPads are also not supported.
Chromebooks not, either, because they run their own ChromeOS Operating System.

For details, see also the Virtualbox Virtual Machines (opens new window) section of the general "Technical Requirements" (opens new window) page.

Hardware Requirements / BIOS settings

The VirtualBox software will not run, or will be extremely slow, if hardware support for Virtualization is unavailable.

Therefore, the CPU of the host system that will run VirtualBox must be fairly recent. That means, the PC/laptop must be manufactured after, say, the year 2010. It must be an Intel-CPU or AMD CPU. Both CPU manufacturers are well-supported by VirtualBox.

It is currently not possible to install mDIS on MacBooks and tablets (e.g. Apple iPad), because VirtualBox is not available for these systems.

CPU Version and BIOS Settings

The PC/Laptop must be manufactured after 2010, and Virtualization Support must be enabled in the BIOS settings (opens new window). It probably is enabled by default, but you should check.

Still, even if you own such a modern CPU, the support for Virtualization may be disabled in the BIOS settings of the PC or Laptop. Make sure the Virtualization is set to "enabled" or "on". The exact name of the setting is different for each Laptop/PC manufacturer, and may vary even between BIOS versions.

It may be set to disabled to optimize the battery performance. Setting Virtualization Support to enabled will increase power demand only by a little bit. Enable it.

You can reach the screen showing the BIOS settings by hitting the F2 key during the first 5 seconds after switching on the PC. (The key can also be F10, or some other key - again, this depends on the laptop-/mainboard-manufacturer).

Other Hypervisors

Virtualbox 7 is recommended. Virtualbox 6.0. runs mDIS well, as does Virtualbox 6.1. However, some versions of Virtualbox 6.1 have some issues with clipboard support so working with VirtualBox versions 6.1.1 to 6.1.4 is a bit less convenient.

There are a lot of other hypervisors available (Parallels, Microsoft Hyper-V, VMWare Fusion, VMWare ESX, Xen, Qemu, KVM, Apple Virtalization Framework ...). We have not tested mDIS thoroughly with any of them at this time (2019-2024).

Do not use Microsoft's Hyper-V on Windows hosts

On Windows Hosts, the Microsoft Hypervisor (opens new window) built-in feature called Hyper-V must not be enabled. Hyper-V cannot co-exist with the Virtualbox management software. Virtualbox guests will not boot.
To disable Hyper-V (opens new window), go to "Control Panel"/"Programs and Features"/Left Sidebar/"Turn Windows Features On and Off". A long selection list of optional Windows Features will appear. Check off "Hyper-V". Check the list for more entries containing "Virtualization". Turn them off as well. Reboot the Windows Host.

If the VirtualBox Software did not install completely: restart VirtualBox installation, or perhaps even de-install and then re-install Virtualbox again (to start from a clean state).

Required VirtualBox Versions

As mentioned above and in 'guide/all', until 2023, Machine Images were created with Virtualbox (Major Version 6) on a Linux-, Windows- or MacOS Host. Recently, Version 7 has been released. VirtualBox 7 also works and is backward-compatible with version 6 (Using VirtualBox 6, you can open instances created with VirtualBox 7).

Therefore, any prospective hosts intended for running mDIS instances as Virtualbox Guests should also have Virtualbox version 6 or 7 installed on the Host machine. Virtualbox Versions with major version numbers (v5) might work, but the import process of the Virtualbox .ova file (see below) may be less smooth. Interactive, manual adaptation of guest-machine configuration parameters might be necessary by the system administrator during the import of the .ova file.

On VirtualBox 6 or 7, the import of a 5 GB .ova file takes about 3-5 Minutes .

How to generate a new mDIS by duplicating an existing preconfigured mDIS

Assumptions

You have a preconfigured mDIS available inside a runnable Virtual Machine
The mDIS is "empty", it contains no science data, except for some demo datasets, for example. (If mDIS does contain science data, you should keep the data as they are, clone the VM, and delete the data manually in the new copy of the mDIS. Do this deletion according to your needs.)
You want to access the cloned mDIS using NAT networking (NAT means Guest and Host share the same IP address).
It will be the only Virtualbox with that name and setting on that host computer. In other words, you do not want to "clone" an existing Virtualbox already present on your PC. You want to import an external one. ("Cloning" VMs on the same host machine has its own set of issues. In particular, some duplicated virtual network settings can create conflicts. For example, MAC Addresses, IP addresses and port forwarding rules should be tweaked slightly on the cloned/imported VM, because they should exist only once on the host. Avoid duplicated "virtual hardware").

The procedure entails generating a Virtualbox .ova image and importing this as a virtual guest OS into a host system. An .ova file (Open Virtualization Appliance) is a container file which contains all data and configuration needed to start up a new mDIS that is ready to run. However, it should only contain very few science datasets from previous unrelated drilling projects.

Exporting the virtual machine as .ova file

If you do not have an .ova file that you can import: Do this to create an .ova file that you can then import on a different host running VirtualBox.

Remove customizations first:

These may include, but are not limited to:
- Inside the VM, reset any changed network settings to DHCP. Don't use static IP addresses.
- Concerning the VirtualBox settings menu of the VM, reset VM network settings to "NAT" "Bridged" is also possible but this page describes the "Network Address Translation" configuration, "NAT". ("NAT" means Guest and Host share the same IP address).
- Check how mySQL (inside the guest) listens for network traffic. Check the settings in the /etc/mysql/mysql.cnf file. Make sure that mySQL is not bound to a specific, static IP Address. Do so by commenting out the bind_adress=... line to allow access to Mysql from hosts anywhere (change it later after ova was imported).

Export:

From VirtualBox "File" menu select "Export appliance".
Select the VM from the list.
Enter descriptive information like product, producer, version, ...
Set an appropriate output path and descriptive filename.
Keep all other settings at the default values.
Click "Export".

For advanced use-cases, see also:

section Shrinking a virtual partition (optional)
section Installing the VirtualBox Guest Additions (optional)
section How to create an mDIS VirtualBox instance from a native instance

How to install a new mDIS inside a VirtualBox on a Host System

Key terms

Host: Computer on which Virtualbox is installed (Host system)
VM = Virtual Machine = Guest: Virtual computer emulated by the Virtualbox Service/Process running on the host computer. VM appears to run "inside" the host.
.ova-image: A single file containing exported VM configuration, Guest Operating System, mDIS components, and data such as predefined mDIS users (initially, no Science Data)

1. Download and install current version of the free VirtualBox software (as of 2019: v6, 2023: v7)

We mentioned before, under "Assumptions", that installing VirtualBox was really not needed, but was already taken care of, by you system administrator for example. For completeness this is mentioned here briefly anyway.

You need superuser/Administrator access on the host machine, because installing VirtualBox alters the hosts' operating system on a deep level.
On a Linux host, for instance, VirtualBox installs 4 kernel modules (vboxdrv, vboxpci,vboxnetadp,vboxnetflt). On Windows, there will appear several Dialog boxes, containing both Warnings and Confirmation Dialogs. Aside from that, running the Graphical Installer for the VirtualBox Program is pretty straightforward.

Install prerequisites

Install a fresh Linux kernel, and some development tools.

Chance is high that most of these packages are already installed.

sudo apt install dkms build-essential linux-headers-generic linux-headers-$(uname -r)

2. Import Guest VM as .ova appliance

The VM requires around 10GB of hard disk space on the host. If you work with the mDIS application and upload files, the required hard disk space will increase.
The hard disk of the VM is configured to increase to a maximum of 32GB.
In the settings, assign at least about 2 Gb of RAM for the virtual machine guest. 512 MB might also work for testing purposes.
In the Virtualbox Menu select File -> Import appliance
Choose "*.ova" file (Ignore "Oracle Cloud" stuff if it appeared)
On Mac, the option "Import hard disk as VDI" should be enabled (otherwise the guest VM immediately requires the 32GB hard disk space).
Finish the installer
Wait for 10 Minutes. Done.

Troubleshooting

If you get errors "Invalid Args", you can try to import the file via the command line tool "VBoxManage". See Virtualbox documentation.
If that still does not work, you can create a new virtual machine and use an existing vdi disk file from a working VirtualBox installation, but this is a more advanced task.
Sometimes the .ova-Image can be imported fully, but the machine does not boot up properly ("/dev/null not found", or similar error). In this case, try to disable the Serial Interface in the VirtualBox settings of the VM, by unchecking a single checkbox.

3. Adjust VM settings

System:
- Adjust RAM, number of CPUs, etc. Usually no change is necessary here.
Network:
- decide and setup network as described below (see Chapter 4)
- The network settings in the VM have to be adjusted, since the specifics (IPv4 Address, MAC Address...), of the virtual network device will probably change on a different host.
Shared folder:
- Set the path for the shared folder to a convenient location on the host system. Recommended: Use the point-and-click GUI interface to the file selection dialog in order to avoid cutting-and-pasting invalid pathnames, prepended with witespace characters for instance.
- In the Virtualbox dialog box, keep the device name "Upload": in file '/etc/fstab' this is mapped to /var/www/dis/backend/data/upload (important for backups!)
- If shared folder "Upload" does not exist, the guest VM will boot, but the shared folder mechanism will not work properly. Many kinds of error messages are possible. See Section "Troubleshooting" below.
- On Linux guest systems: there is a cronjob (in the crontab of unixuser root) that will mount the shared folder after restart. Thus: (1) You do not need to set a mountpoint in the configuration form of the shared folder. (2) After the cronjob ran once, then the mount point and mount options for the shared folder are stored inside '/etc/fstab'.

4. Decide on network settings

There are three alternatives offered by VirtualBox: "Host-Only Newtorking", "NAT Networking" and "Bridged networking"

Host-Only networking - (too limited)
- Only the host can access the guest VM. The guest VM can or cannot access the internet.
About NAT Networking - (mDIS should use this)
- NAT means: Guest and Host share the same IP address.
- NAT = "Network Address Translation" - from a Private IP Address Range to a Public IP Address.
- Thus, other hosts in the same subnet as the host can access the guest VM.
- NAT works standalone and enables small client-server setups. It is optional have the host connect to the public internet.
- Inside-Out: Guest VM can connect to the public internet, if the host is connected to the public internet. The guest can access printers (and other computers) in the subnets accessible to the host.
- Outside-In: from within the host and other computers in the host subnet, the guest VM is only accessible via port forwarding configured on the host (see below); i.e. the port 80 (normal Webserver port) on the host will be forwarded to some port of the guest VM
- Other computers in the network of the host have to access the host via the forwarded port to connect to the Guest VM.
- On the host, settings must be adjusted to allow the access to the forwarded ports
  - On Mac you may not forward ports less than port number 1024 (e.g. 80); you can use a different port (> 1024, e.g. 8080), so in the browser you would have to enter http://ip-address-of-mac:8080/ to access the guest VM. Alternatively, use bridged networking (see below)
  - On Linux, it should be possible to allow VirtualBox to use privileged ports below 1024: See post (opens new window)
  - On Windows Hosts, Port 80 can be forwarded to the guest VM, but the Windows Firewall may complain on first access and proposes to immediately create a new firewall rule for port 80. Allow this. - Otherwise, use a nonprovileged port such as 8080, just like for Mac computers.
About Bridged Network - (mDIS guest can offer more services to the network)
- Slightly more complicated than NAT Networking setup, because you need to make more decisions and do more research up front.
- Host has to be connected to some network (by cable or WIFI)
- Guest VM: gets assigned a separate, own IP address on that network. (You must research up front which IP addresses are available, e.g. by asking your sysadmin, and you are in charge of that assignment). Guest and host are then separated "more strongly" than with NAT Networking.
- Host and other computers on the network access the guest VM via its IP address
- If the network provides DHCP, no network configuration has to be done on the guest VM, but the IP address could change between reboots. Even on a DHCP network, you could set the guest VM to a static IP address. (On Ubuntu Linux in file /etc/dhcpd/dhcp.conf).
- TBC

4.a Setup network mode "NAT"

Create a custom NAT network configuration

Configure a preset of port-forwarding rules, that later gets assigned to your virtual machine.

In Virtualbox Manager Window, open File/Preferences...
- Choose tab "Network"
- Add a new NAT network
- Edit its configuration:
  - Name: mDIS NatNetwork - this name is arbitrary, choose a convenient name
  - Network CIDR: 10.0.2.0/24 - first three bytes (here 10.0.2) is network portion)
  - Network Options: Support for DHCP: Enabled
  - Network Options: Support for IPv6: Disabled
  - Port forwarding:
    - Add two Forwarding Ports and enter the following values.
      - HTTP to mDisBox: Protocol: TCP; Host IP: ; Host port: <e.g. 80 if Windows host, try 8080 if MacOS host)>; Guest IP:10.0.2.15; Guest port: 80
      - SSH auf mDisBox: Protocol: TCP; Host IP: ; Host port: <e.g. 22/win, 2222/MacOS>; Guest IP:10.0.2.15; Guest port: 22
      - add other well-known ports as you might see fit (e.g. 3306 for mysql direct access), but then make sure that the Windows Firewall is not blocking this

Use/assign the custom NAT network configuration

Edit the Virtualbox configuration (click on Settings button) of the VM
- Choose "Network" and choose "NAT Network" selection box. This activates the next selection box below (which was greyed out before). Click and select the previously assigned configuration name (here "mDIS NATNetwork") for the network adapter 1.
Start the guest VM
After starting the guest VM, to check the IP address the guest VM has received from the DHCP server, do this:
- Login as User: Administrator; Password: 19DisBox
- Open a terminal window, and type "hostname -I" (big i) to get the IP address(es) displayed or, alternatively:
- Click on the network symbol on the top right of the guest VM's screen (next to the speaker icon)
  - Open "Wired Connected" and click on "Wired Settings"
  - Click on gear icon in section "Wired"
  - In tab "Details", check the IPv4 Address
- If that IP address is different from the one you entered as the Guest IP in the port-forwarding dialog-box, go back to the port forwarding settings (see above), change that IP to the IP adress visible in the Details tab, and reboot the guest VM.
Check if you can access the webserver running on the guest VM using the browser on the guest enter http://localhost:80/.
Check if you can access the guest VM from the host using the forwarded port; in the browser's address bar on a MacOS host, enter http://localhost:8080/ (or the port you've entered in "Host port" in the port-forwarding dialog-box mentioned above). On Windows hosts, http://localhost:80 might also work.
Troubleshooting:
- If Windows Hosts or Mac Hosts show an alert box during startup:
  Adjust the settings of the software firewall on the host to allow external access to the redirect ports; Check if you can access the guest VM from a different computer (but on the same subnet) by entering in browser: http://ip-address-of-host:forwarded-port/
- If Guest VM does not boot properly and the shared folder is not available:
  In file /etc/fstab, comment out line "Upload ..." by prepending it with a hashmark ("#Upload..."). Now the Shared Folders will not be available after booting up the guest, but the system is more likely to boot up properly. After booting up you can remove the hashmark from "#Upload" and type "mount -a" (without rebooting). Do this as 'root' user. This re-enables the shared folder. Optional: Before the next reboot, comment out the upload line again."
- Post-Bootup Startup Scripts and Cronjobs: On Linux guests, see ... TBC
- Linux guest should be rebooted after host network settings have been changed substantially, e.g. after logging into a different WLAN. Linux guest might show weird behaviour (e.g., ping still works, but DNS doesn't)

4.b Setup network mode "Bridged"

This is an alternative to the NAT Network setup described above. Use either Bridged or NAT but not both.

Edit the Virtualbox configuration of the VM
- Choose tab "Network" and select "Bridged Network" for the network adapter 1
- Choose the physical network device with which the host is connected to the network
  - On many hosts, it can be difficult to determine the correct network adapter to use. Things can become complicated in modern computer networks, e.g when you have Docker installed, or when you have VPN connections active. We cannot cover everything here. However:
  - On Microsoft Windows 10:
    - Open the settings and click on "Network and internet"
    - In tab "status" you see the current network connection
    - Click on the link below "Change network settings"
    - You can now see the details of the connection including IP address and then name of the network device
  - On Mac OS X:
    - Open the system settings and choose "Network"
    - Click on the connected device (hightlighted) and remember the IP address
    - Unfortunately here you do not see the device name listed in VirtualBox
    - Open a terminal window, enter ifconfig and look for the devices with that IP address
    - Is there a better way on Mac to determine the network device? ❓
  - On Linux:
    - In a terminal window enter "ifconfig" and see, which network device has an IP address in your network
Start the guest VM
- Login as User: Administrator; Password: 19DisBox
- Click on the network symbol on the top right of the guest VM's screen (next to the speaker icon)
  - Open "Wired Connection" and click on "Wired Settings"
  - Click on gear icon in section "Wired"
  - In "Details" tab, note the IP address
  - The IP address should be somehow similar to that of the host. Hosts are the same subnet, so that means that the guest vm's number behind rightmost dot (".") is different)
Enter the IP address in the browser of the host: http://ip-address/
If you prefer a "fixed" IP address for the guest VM:
- Open the "Wired connection" settings (see above)
  - Write down the current IP address, default route, and DNS ip
  - Choose tab "IPv4"
    - Set "IPv4 Method" to "manual"
  - Enter the same values as written down before
  - Netmask is 255.255.255.0 in most small networks
    - Which IP address you can use, depends on your network and DHCP server
  - Try with a high number smaller than 250 for the last number in the IP address, i.e. 192.168.3.245
  - Klick button "Apply" on top right of dialog
  - Switch off the connection an switch on again
  - Check the ip settings again
- Test if you can still access the guest VM from the host's browser
- supported host/guest combinations