Attempt at documenting run-virt. Note that lecture and VM are often used interchangeably here and in the actual run-virt scripts. -------------------- ### Global constants -------------------- These constants are globally defined in the run-virt environment and are read-only. # $CONFDIR This is where the downloaded metadata for the VM to be run is located. Contains the VM hw description (virtualizer specific), network shares to mount, startup scripts, ... # $DEBUG Set to either "true" or "false" so it can simply be used like this: if $DEBUG; then .... # $HW_CORES Number of physical CPU cores of host machine. # $HW_THREADS Number of logical CPUs (SMT) of host machine. # $IMGUUID The UUID of this VM/lecture, extracted from the passed $XMLFILE. Used to fetch meta data for the VM, like vmx, netrules, netshares, etc. # $LOGFILE Log file for run-virt. You shouldn't need to access this file directly but rather use the "writelog" function. # $PLUGIN_ID Name of the virtualizer plugin required to run the current VM, e.g. vmware or virtualbox. This is used to source the according scripts from $VMCHOOSER_DIR/plugins/$PLUGIN_ID/* # $SELF Absolute path to the main run-virt script. Should usually be /opt/openslx/vmchooser/vmchooser-run_virt # $SHARE_REMAP_MODE How to map network shares into guest 0 = disabled 1 = mount normally in guest (openslx.exe) 2 = mount normally in gues, but fall back to shared folders if it fails 3 = use shared folders feature of virtualizer # $SRC_IMG_ABSOLUTE Absolute path to the VMs HDD image. When using DNBD3, which requires $SRC_IMG_RELATIVE to be set, this file might not actually exist. This can be empty if $SRC_IMAGE_RELATIVE is given. # $SRC_IMG_RELATIVE Relative path to the VMs HDD image. Used for DNBD3, or for constructing the absolute path in case it's not supplied via the $XMLFILE, but $VMSTORE_PATH is known. This can be empty if $SRC_IMG_ABSOLUTE is given. # $TMPCONFIG Main config file for the virtualizer. This should be supplied by the meta data downloader, which can be overridden by a hook. For VMware, this is the basic vmx, for VirtualBox, the xml file. # $TMPDIR Temporary directory to work in. Create single files, or if you feel like you need a bunch of them, group within a subdirectory. This will be wiped on exit. # $USER Name of the currently logged in user. This doesn't necessarily match the name on the auth server (LDAP/AD) but rather what the running Linux system sees. # $VMCHOOSER_CONF_DIR Config dir of run-virt, where several (sourcable) files are located. # $VMCHOOSER_DIR Base directory of run-virt/vmchooser, usually /opt/openslx/vmchooser # $VMSTORE_PATH Currently hard-coded to /mnt/vmstore via run-virt-includes/get_xml_file_variables.inc. In case VMs are read via CIFS/NFS, this is where it should be mounted. # $VM_CLEANNAME "Clean" version of $VM_DISPLAYNAME, no spaces or special chars except '_', '-' and '.', 32 chars max. # $VM_DISPLAYNAME Name of the VM as shown to the user, and displayed in vmchooser. # $VM_OS_TYPE Name of the VMs operating system as known to the virtualizer in use. This should not exist but does for complicated reasons. # $XMLFILE XML description file of VM session to be run. Passed via command line. ------------------------ ### Configuring run-virt ------------------------ ## /opt/openslx/vmchooser/config/resource_urls.conf url_lecture_netrules: URL to download firewall rules from url_lecture_metadata: URL to download lecture metadata.tgz from ## /opt/openslx/vmchooser/hooks/* Several sub directories for different hooks. These can contain files named *.sh, which will be executed, or *.inc, which will be sourced. The following hooks exist: # download.d/ Executed in order to obtain the VMX/metadata. In *.sh form, the first parameter ($1) will be the target directory, where the script is supposed to put the downloaded files. In the *.inc form, the destination directory is $CONFDIR, and also in $1. The files to place there have to be named as follows: "vmx": The machine description, a vmx file for vmware, and xml file for virtualbox, etc... "runscript": Optional script that will be executed by the openslx.exe The first line is abused to pass further information along and has the format key=value;key2=value2;key3=value3 ... Currently in use are ext=bat (to signify the type of script being executed, batch in this case) visibility=0 (whether the script is hidden while running (0 = hidden, 1 = normal, 2 = minimized) soundMuted=1 (whether sound is muted by default in the VM (0 = no, 1 = yes, -1 = let SLX_VM_SOUND decide) "netshares": Optional file defining the network shares to be mounted by openslx.exe Also there can be a sub-directory for additional runscripts called "adminrun" containing files in the format [index]-[visibility]-[passcreds].[ext] e.g. 001-1-1.bat index is just used for sorting, visibility is explained above, and passcreds decides whether the script gets passed the username and password via parameters. If your .sh is responsible for downloading the meta data, it should exit 0. Any other exit code tells run-virt that your script was only meant for some preparation work and run-virt should download the meta data on its own. Likewise for an .inc, it should return 0 to signify that downloading was done (or at least attempted) by your include, and run-virt should not try to download anything. For cleanliness you should prefer writing .sh hooks, .inc should only be used if you really need to modify the environment of run-virt. For *.sh hooks, the environment will provide $TMPDIR, $IMGUUID and $USER. # floppy.d/ Hook to add more files to the virtual floppy. $1 is the directory you should copy your files to. Symlinks work too, mcopy will follow them and copy the linked file. Note that this is a floppy, not the cloud, so you're limited to 1.44MB of storage. # image-access.d/ Hook to set up read or write access to image. Here, only *.inc type hooks make sense, since they're expected to set either VM_DISKFILE_RO or VM_DISKFILE_RW, depending on desired access. You should only ever set one of the two variables, as it is undefined what the individual virtualizer plugins will do if both variables are set. # pre-exec.d/ Hook that is run right before the virtualizer is executed. $1 is the virtualizer ID, $2 is the imageuuid. # post-exec.d/ Hook that is run right after the virtualizer finished executing. $1 is the virtualizer ID, $2 is the imageuuid.