OccpAdmin

The OccpAdmin program found on the Administrative VM is used to facilitate setting up the VMs as part of a given scenario. It supports a couple of modes of operation.

In verify mode, it is capable of doing the following tasks:

  • Verify the VMs are registered with the Hypervisor
  • Checks that the correct network segments exist in the Hypervisor
  • Checks that the VMs are connected to the correct network segments

In deploy mode, it does everything that verify mode does, plus:

  • Creates any network segments that are required
  • Imports, Clones, and/or Applies ConfigurationPhases as necessary
  • Assign the VMs to the correct network segments if they are not already there
  • Creates, uploads, and attaches the configuration floppy image for the Router VM

In launch mode, it does everything that deploy mode does, plus:

  • Creates or reverts the VMs to a snapshot called phase2
  • Powers on the VMs

In poweroff mode, it will power off any machine that would have been turned on by the launch mode.

In export mode, it will revert machines to phase 1 or phase 2 (if there is no phase 1), export them to OVA, and create a tar archive of those OVA files, the configuration file, and any support files in the scenario directory. If an OVA file already exists in the export directory, it will be used and the machine will not be re-exported. This allows the scenario creator to only export changed VMs.

Additional Flags

The regen flag will cause the following when used with deploy or launch before completing those modes

  • If the VM has a phase 1 snapshot it will revert to it and delete the phase 2 snapshot if it has one
  • If the VM only has a phase 2 snapshot it will revert to it

This has the affect of regenerating all machines that are capable of doing so.

Distributed deployments

If a scenario has many VMs and requires more RAM than you can support on a single machine then you can distribute the VMs across several machines. The OccpAdmin program can contact multiple hypervisors to make sure they are setup correctly. In order for the virtual networks to be linked, this will require a small VM to be run on each host to be a VPN terminator. The OccpAdmin program will generate the necessary configuration files for the VPN.

In order to use several hypervisors, you need to specify connection details for each of them to OccpAdmin. You can use the addhv mode to add these connection details to a file called "hypervisors.xml". While this file can store passwords, this is not recommended. If OccpAdmin does not have the password for a hypervisor when running, it will prompt for it. The delhv mode can be used to remove a hypervisor's configuration from the file.

addhv 
    --url
    --username
    --password
    --importdir

hvtype 'vcenter'
    #type parameters: 
    --datacenter
    --host
    --datastore
    --publicnet

hvtype 'vbox'
    #type parameters
    no special

The second requirement for using several hypervisors is to create a map file that describes how the VMs are distributed. This file is given to OccpAdmin via the --hvmap parameter. The structure of this file is one hypervisor per line, with the hypervisor name, optionally followed by a slash and the static Runtime VPN IP, optionally followed by a comma and a gateway address, followed by a colon, followed by a comma separated list of VMs.

Each LAN segment that is distributed between two or more hypervisors will utilize the automatically deployed Runtime VPN System. Each distributed LAN segment requires a server machine to be specified. The IP address specified after the host indicates which machine will be the VPN server for a distributed LAN segment. The addresses that you provide need to be routable on your physical network.

For example:

vbox1/10.99.99.10,10.99.99.1: vm1, vm2, Router
vbox2: vm3, vm4

Note that exactly one of the hypervisors must contain the Router VM, and it must be called Router. The name of each hypervisor must match one listed in hypervisors.xml, and the name of the VMs must match those in the Scenario File.

Also note that the VPN configuration will require the VPN VM's on each hypervisor to have one NIC (the first one) bridged with the host. In order for the OccpAdmin program to generate the configuration files without having these machines booted (see note below), some of them will require static addresses. This is the address that is specified in the map file (Note: This address must be different than the IP of the Hypervisor and must be available on the network). If the OccpAdmin program finds that it requires an address and one is not provided, then it will report this as an error.

VPN note

The reason the Runtime VPN system is setup with a static configuration is so that if it is restarted during the scenario, it can reconnect. Also, unlike the Setup VPN, the OccpAdmin program is not running while the scenario is, and therefore could not provide a dynamic configuration.

Configuration Files

In the home directory of the user running occpadmin you can add

~/.occp.conf:
concurrency=3

for additional concurrency.

File Permissions

The recommended permissions on files is 0644 and directories 0755.

Current Help Description

OccpAdmin - OCCP Administration utility
Visit https://www.opencyberchallenge.net for more detailed information

Global Parameters:
--config <path to file> - The path to the scenario file you wish to use
--instanceid <id> - Specifies the instance id of this scenario
--hvmap <path to map file> - The path to the hypervisor map file
--hvname <name> - Specifies the name of the hypervisor to be cached, used, or removed depending on the mode.
--hvtype <type> - Specifies the vendor/type of hypervisor
--mode <mode> - The operation mode for this program. Mode must be one of: 
	addhv - Adds a hypervisor to the hypervisor cache. Requires --hvname and --hvtype 
                  as well as any hypervisor specific options or the "remote" flag
	cleanup - (unimplemented) Will remove a scenario
	delhv - Removes a cached hypervisor by --hvname
	deploy - Prepares a scenario for launch but does not turn on the VMs
	export - Packages a scenario for distribution to OCCP users
	launch - Prepares a scenario for launch and powers on the VMs
	listhv - List a cached hypervisor by --hvname, or all
	poweroff - Power off all the VMs in a scenario
	testhv - Test a cached hypervisor by --hvname, specified details, or all
	verify - Check what would need to be done for a deploy or launch but do not act
--regen - Causes a regeneration of the VSN for deploy and launch modes
--remote - Specfies that hypervisor is not the same one that the AdminVM is running on
--overwriteova - Replace OVA files on remote VBox instances when deploying
--force - Remove VMs if they are in the way and discard saved (paused) state
--version - Displays the version for this program and the Admin VM

Hypervisor Specific Options:
vbox:
	--importdir <path> [required] The full path on the host to the folder being shared with the AdminVM
	--password <password> [optional] The password used to authenticate with VirtualBox web services, blank passwords are specified as ""
	--url <URL> [requried] The URL to connect to VirtualBox web services
	--username <username> [required] The username used to authenticate with VirtualBox web services
esxi | vcenter:
	--datacenter <datacenter> - The name of the datacenter. Only required for vcenter
	--datastore <datacenter> - The name of the datastore
	--folder <path> - The path of a folder used for OCCP VMs
	--host <host> [required] - The name of the host to use
	--password <password> [optional] The password used to authenticate with the VMware API, blank passwords are specified as ""
	--publicnet <name of network> [requried] The name of a network that can access the internet
	--url <URL> [requried] The URL to connect to VMware API
	--username <username> [required] The username used to authenticate with the VMware API

Examples:
Adding a VirtualBox hypervisor then using it to deploy
$ OccpAdmin --mode addhv --hvname myOCCPHV --hvtype vbox \ 
            --url http://my-ip-address:18083 --username vboxuser --password vboxpass \
            --importdir /path/on/host/to/shared/folder
$ OccpAdmin --mode deploy --hvname myOCCPHV --config /path/on/adminvm/to/share/scenario/scenarioFile.xml
Note: You do not have to add the hypervisor, you could specify the options each time

Regenerating a scenario
$ OccpAdmin --mode deploy --hvname myOCCPHV \
            --config /path/on/adminvm/to/share/scenario/scenarioFile.xml --regen

Launching and Powering off a scenario
$ OccpAdmin --mode launch --hvname myOCCPHV --config /path/on/adminvm/to/share/scenario/scenarioFile.xml
$ OccpAdmin --mode poweroff --hvname myOCCPHV --config /path/on/adminvm/to/share/scenario/scenarioFile.xml