Singularity Builder VM

Singularity Builder VM is an easy-to-install virtual machine running a mininmal Debian Linux installation prepared with Sylabs Singularity, allowing to build Singularity images as root user in a sandbox environment. The Builder VM is preconfigured to exchange data between some host and guest file systems. The Builder VM in its current concept may only be used on (managed) Linux computers.

Installation

You can use any ISG.EE managed computer to perform the following steps:

1. Open a Linux terminal

2. Enter sgbuilder. This will show you an overview/ help on how to install and start the Singularity Builder VM.

3. Create a new VM copy of the Singularity Builder VM in any directory you like, e.g. /scratch/<Your_Username>/<VM1>:

   sgbuilder install default /scratch/Your_Username/VM1

   Please note you should install your VM somewhere in /scratch and not in your user home directory for performance reasons.

4. Once the VM has been installed, you can start it up as many times as you want using:

   sgbuilder start /scratch/Your_Username/VM1

5. To shut down the VM in a clean manner, enter "shutdown now" at the shell.

Usage

1. Startup the Builder VM as described in the Installation section above. The following window appears after some startup seconds.

   • 

2. /root will be the current working directory right after VM startup. This is a 30 GB virtual disk within the VM that can be used to save newly generated Singularity images or a Singularity image sandbox.

3. /root/home is your ITET user home. This can be used to import or export data (e.g. generated SIF images) from the VM to your regular user home directory and vice versa.

4. /root/scratch is the /scratch directory of the Linux (host system) computer where you started up the VM using sgbuilder start. This can be used to import or export data from the VM to your computer's /scratch directory and vice versa.

5. When using Singularity, always ensure the output path (e.g the sandbox directory or Singularity image output location) is somewhere below /root. DO NOT ATTEMPT to save Singularity sandbox data or images directly to /root/home or /root/scratch or any other directory above /root (like the root user's home). Saving Singularity output data directly to the scratch or home won't work, as you cannot store any files there using other user id's or group id's than your own id's. Storing data above /root won't work because that would be on the VM's operating file system disk which has - intentionally - almost no diskspace left.

6. That said, the idea is to use the VM as follows: first import all data needed from external filesystems into the VM's filesystem. Then do your Singularity image processing and at the end, export the generated Singularity image to an external filesystem.

Tips & tricks

Changing the VM's keyboard settings

The default keyboard setting is "us" (american english keyboard). If you want to change this setting permanently (across reboots), you can edit /etc/default/keyboard within the VM and set another country code, e.g. "ch" for Swiss German keyboards. To make the change immediately effective without rebooting the VM, you can enter

setupcon <keymapcode>
e.g.
setupcon ch

Accessing the VM through serial console

Sometimes you want to copy-paste text from your Linux desktop to the Singularity Builder VM console. You may have noticed however, that copy/ paste from/ to the VM console window does not work. As a workaround, you might access the VM's shell from outside the VM using the VM's serial console feature.

• To make this work, you will first have to set a password for the root user

  root@sgbuilder:~# passwd
  New password: .......
  Retype new password: .......
  passwd: password updated successfully

• Then you can access the VM's console from any Linux terminal as follows (example):

  socat - /scratch/Your_Username/VM1/sgbuilder.sock

• NOTE: /scratch/Your_Username/VM1 is the path to your VM installation as described above in the "Installation" section

• NOTE: Terminal emulation in serial console is not very good. You might enter  stty -echo  to disable echoing your inputs twice on each line entered.

The VM cannot access the network, because it has no IP address

Usually, the IP address is automatically assigned during the VM startup. You may check this entering ip addr within the VM. The network interface used for external connections is ususally named ensNN, e.g. ens33. If it doesn't have a valid IPv4 address, you may either reboot the VM or try to obtain a new IP without rebooting, using dhclient <interfacename>. In our example, the <interfacename> would be ens33.