cernvm command line utility to control VBox CernVMs
C++ Python CMake Shell Batchfile
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
ci
extern
include
src
.gitignore
.gitmodules
CMakeLists.txt
CONTRIBUTING.md
LICENSE
README.md
development.md
prepare-linux32.sh
prepare-linux64.sh
prepare-osx.sh
prepare-vs2013-vt120_xp.bat
technical_overview.md

README.md

CernVM-Launch

CernVM command line utility to control VirtualBox CernVMs. For user introduction, please visit the Official CernVM-Launch page.

Requirements

  • VirtualBox has to be installed in a default location.
  • You have to use a 64bit OS (we only provide 64bit executables)

Usage

CernVM-Launch provides following operations.

Create a virtual machine

create [--no-start] [--name MACHINE_NAME] [--cpus NUM] [--memory NUM_MB] [--disk NUM_MB]
       [--iso PATH] [--sharedFolder PATH] [USER_DATA_FILE] [CONFIGURATION_FILE]

Create a machine with default or specified user (contextualization) data. By default, the machine is started right away (use --no-start to suppress that).

If you do not provide a USER_DATA_FILE, you will be prompted if you want to use default user data.

Default user data:

[amiconfig]
plugins=cernvm

[cernvm]
auto_login=on
organisations=
repositories=
shell=/bin/bash
config_url=http://cernvm.cern.ch/config
users=user:user:password
edition=Desktop
screenRes=1280x800
keyboard=us-acentos
startXDM=on

When creating a machine, you may specify the parameters in several ways via:

  • command line arguments,
  • configuration file,
  • global CernVM-Launch config file.

Parameters are considered in the following precedence:

Command line parameters > configuration file > global config > hardcoded defaults.

When specifying sharedFolder, you must use a canonical path.

If you want to use your own CernVM ISO image, specify --iso parameter with a path to your ISO file. If you omit this parameter, a CernVM ISO image is downloaded automatically, with respect to the cernvmVersion parameter.

Configuration file

When creating a machine, you can specify the creation parameters in a configuration file.

Creation parameters file example with all recognized items:

name=launch_testing_machine
apiPort=22
cernvmVersion=2.6-9
cpus=1
memory=512
disk=10000
diskChecksum=
sharedFolder=
diskURL=
diskChecksum=
diskPath=
executionCap=100
#Flags: 64bit, guest additions, (headless mode)
flags=5

Hardcoded default parameters

If a user does not provide all of the parameters (neither through one of the three options), hardcoded defaults are used in that case:

apiPort=22
cernvmVersion=latest
cpus=1
memory=2048
disk=20000
executionCap=100
# Flags: 64bit host OS, headful mode, graphical extensions enabled
flags=49

Flags parameter

There is one special parameter called flags, which uses a bit mask format for configuring several VM options.

Active bit   Effect
     1       The system is 64-bit instead of 32-bit
     2       Use regular deployment (HDD) from an online source (instead of micro-iso)
     4       Include a guest additions CD-ROM
     8       Use floppyIO instead of contextualization CD-ROM
    16       Start the VM in headful mode
    32       Enable graphical extension (like drag-n-drop)
    64       Use secondary adapter instead of creating a NAT rule on the first one
   128       Use ttyS0 as external logfile.
   256       Use a bootable VDI file as the main deployment image.

If you want to use online source deployment, you need to specify the diskURL and diskChecksum parameters.

If you want to use a bootable VDI file, you need to provide the diskPath parameter.

Create a virtual machine through OVA image import

import [--no-start] [--name MACHINE_NAME] [--memory NUM_MB] [--disk NUM_MB]
       [--cpus NUM] [--sharedFolder PATH] OVA_IMAGE_FILE [CONFIGURATION_FILE]

When a machine is created via OVA import, no contextualization is done. The OVA image is also expected to be bootable.

Configuration file has the same format as in the create operation.

Destroy an existing VM

destroy [--force] MACHINE_NAME

Destroy an existing VM. If the machine is running, the user is prompted with confirmation. If want to avoid the prompting, use --force flag.

List existing virtual machines

list [--running] [MACHINE_NAME]

List all existing machines or a detailed info about given machine. If --running is specified, only running machines are listed. If MACHINE_NAME is specified, detailed information about a machine is displayed.

Machine details contain the following fields:

  • cpus: how many assigned CPUs the machine has
  • memory: how much memory (in MB)
  • disk: how big the disk is (in MB)
  • executionCap: hypervisor's execution capability
  • cernvmVersion: used CernVM version
  • apiPort: VM's port connected to the host OS
  • baseFolder: where all the VM files are stored
  • rdpPort: RDP port for accessing the machine

Pause a virtual machine

pause MACHINE_NAME

Pause a running machine.

SSH into a machine

ssh MACHINE_NAME

SSH into an existing machine. You must have ssh installed and available in your PATH. Not supported on Windows.

Start a virtual machine

start MACHINE_NAME

Start an existing machine.

Stop a virtual machine

stop MACHINE_NAME

Stops a running machine. It saves the state, does not power off the machine.

Config files

In CernVM-Launch, you have two types of configs. A global CernVM-Launch config, that also affects CernVM-Launch behaviour, and a machine creation config, that provides parameters for machine creation (see above).

Global config file

Global config file has to be named .cernvm-launch.conf and placed in the user home directory, i.e.:

On Linux and Mac:

~/.cernvm-launch.conf

On Windows:

${USERPROFILE}\.cernvm-launch.conf

When specifying launchHomeFolder and sharedFolder, you must use canonical paths.

Config file example with all recognized items:

########### CernVM-Launch configuration ###########
# Folder on the host OS which will be shared to VMs
sharedFolder=
# Base folder on the host OS where a CernVM subdirectory ('CernVM' on Win and Mac, '.cernvm' on Linux) is created.
# All VM configuration files and images are stored in this subdirectory (can get large).
# Changing this folder will disconnect already existing machines from CernVM-Launch
launchHomeFolder=
########### Default VM parameters ###########
# VM's port connected to the host OS. Use 22 to have SSH access to the machine
apiPort=22
cernvmVersion=latest
cpus=1
memory=2048
disk=20000
executionCap=100
# Flags: 64bit, headful mode, graphical extensions
flags=49

Known issues

If you encounter a problem with creating symlinks in the shared folder from the host OS, please restart VirtualBox.