Scenario File v1.2.1

The Scenario File is the heart of an OCCP scenario. It dictates what machines make up a VSN, how they should be configured, and what actions the GameServer should perform during the scenario. Every OCCP Scenario will have this file and it is written in XML. The OccpAdmin program will create an instance file from the scenario file which it will deliver to the GameServer.

Note If you name your ScenarioFile "instance.xml" it will be over written! The OccpAdmin program transforms your scenario file into an instance file which it names instance.xml.

Previous Versions

Common Edits

  • Hopefully most scenario contributors will make use of Variables and have them at the beginning of the scenario file. Though variables have a wide variety of things they could affect, you may be able to quickly change usernames or passwords by just editing the value of the variable. See the particular scenario's wiki page for more information about what could be configured for it.
  • You may also wish to change the number of clones for a particular host depending on your goals/needs. For instance changing the number of Player VMs.
  • In some cases it may be necessary for you to alter the amount of RAM a machine is using. Obviously caution will be needed when decreasing the RAM allocation to ensure the VM is still functional. Editing or adding the "ram" attribute to a host allows you to specify the RAM in MB.

XML Tag Reference

GameServer Specific Tags

<host>

A scenario XML will likely have several host tags. They describe the VM for the OCCPAdmin program so that it may configure the virtual hardware for you and in some cases also do software configurations of the machine.

Attribute Description ValuesDefaultRequired
basevmThe OCCP Base VM the host is made from if any.Stringn/aNo
isoThe ISO file the VM should boot from. Note this is mutually exclusive of basevm. Useful for using Live CDs as player VMs.Stringn/aNo
clonesThe number of clones to make of this host.Integer>=00No
configureInterfacesWhether or not the Configuration Manager should configure the network interfaces. If false, it is left to the content packs to configure interfaces. true or false trueNo
domainThe domain name to use.Stringn/aNo
labelName of the VM as it will appear in the hypervisor. Must be lowercase and uniqueStringn/aYes
ovanameThe ova file the OccpAdmin program will look to use if the machine does not exist in the hypervisor.StringThe value specified with the label attribute plus ".ova"No
hostnameThe hostname for the VM.Stringn/aYes
phaseThe minimum supported phase of this VM. Mainly used during export & installation1 or 2n/aYes
ramThe amount of RAM in MB to assign to the VM.Integer>0*No

* When the ram attribute is not set, the VM will inherit the RAM allocation from either the basevm or importvm specified. The appropriate value of this attribute will depend on your hypervisors capabilities.

In addition to the above attributes the host tag may have the following children tags:

<interface>

Attribute Description ValuesDefaultRequired
autoIf the interface should be brought up on boot (for applicable OSes).true or falsetrueNo
broadcastThe broadcast address to use.x.x.x.xn/aNo
configHow to configure the networking (in the OS), DHCP, Statically, or don't. Configuration depends on configureInterfaces in the host tag being true.dhcp, static, or nonedhcpNo
gatewayThe default gateway to use.x.x.x.xn/aNo
nameThe interface name, ex: eth0Stringn/aYes
networkIf a physical interface, the name of a network specified with a <network> tag.Stringn/aNo
ipv4The static IPv4 Address and netmask in CIDR format.x.x.x.x/yn/aYes if config=static

<content>

This is an array of pack tags associated with a host tag. This is where ContentPacks are specified.

<pack>

Attribute Description ValuesDefaultRequired
nameThe name of the content pack.Stringn/aYes
configThe configuration from the content pack to apply.Stringn/aNo

In addition to the above attributes this tag may have any number of sub tags that define parameters for the pack. These tags are named after the parameter. Parameters are optional.

For example, a pack with name “foo” that takes the parameters “bar” and “qaz” would be defined as follows:

<pack name=“foo”>
   <bar>Lorem Ipsum</bar>
   <qaz>1234</qaz>
</pack>

While a pack that takes no parameters could be defined as follows:

<pack name=“foo”/>

<network>

Attribute Description ValuesDefaultRequired
labelNetwork Name*n/aYes

Defines network segments. All host interfaces that should be connected to the router should be connected as fake-internet however this network does not need to be specified with this tag.

<var>

Please refer to Variables and Generators for information on this tag.

<report>

Attribute Description ValuesDefaultRequired
nameThe file name of the report to write to the reports directory.Stringn/aYes

This tag expects data which is the report itself. Variables can be used in reports and are a good way to get the values of generators. You can have as many reports as you’d like.

Example:

<report name="Directions.txt">Directions:
   Login to the webserver at ${occp:lampPubIP} using username "${occp:webusername}" and password "${occp:webuserPassword_plain}"
</report>

This will expand to a file Reports/Directions.txt:

Directions:
 Login to the webserver at 172.16.14 using username "fred" and password "merlin".

<rootdns>

This tag should have <entry> tags below it that contain the following attributes:

Attribute Description ValuesDefaultRequired
nameResource NameStringn/aYes
rrtypeResource TypeA/MX/PTR/CNAME/NS/TXT/SRVn/aYes
valueResource ValueStringn/aYes
ttlResource Entry TTL (currently unused)Number1440No
classResource Class (currently unused)ININNo

These entries are passed through to dnsmasq. Dnsmasq does not support changing the TTL on a per entry basis, and Class is always IN.

Example:

<rootdns>
   <entry name="example.com" rrtype="NS" value="192.0.2.4" />
</rootdns>

<scenario>

Describe the current scenario and its details.

Attribute Description ValuesDefaultRequired
gameididentify this scenarioIntegern/aNo
nameidentify this scenarioStringn/aYes
typescenario categoryStringn/aNo
descriptiondescription of the scenarioStringn/aNo
<scenario gameid="1" name="Red Team vs. Blue Team" type="Network Defense" description="Blue team defends">

<length />

Attribute Description ValuesDefaultRequired
timeThe length of the scenariointegern/aYes
formatThe units of the time parameter{seconds, minutes, hours}n/aYes

Example:

<length time="10" format="seconds" />

<users>

Each <user /> tag describes a login for the web services console. Attributes are only required if a <user /> is specified.

Attribute Description ValuesDefaultRequired
name Username of the user for loginStringn/aYes
passPassword for the user loginStringn/aYes
<users>
    <user name="moderator" pass="token"/>
    <user name="blueplayer" pass="token"/>
    <user name="spectator" pass="token"/>
</users>

<point-labels>

A <point-label /> allows specified events to be grouped together for score calculation. Label names must contain only alpha-numeric string characters. The default definition of a group is to sum all the point values in that group. A group may define a SQL expressions that returns a single value in a single row. If more than one row is returned only the first row value is used.

Attribute Description ValuesDefaultRequired
nameThe name of this group of scores::alphanum::n/aYes
sqlAn SQL expression that computes a single value.SQLite Expression Sum of all values in this groupNo
<point-labels>
    <!-- Example Default query if none provided -->
    <point-label name="group1" sql="SELECT SUM(value) FROM SCORE WHERE groupname='group1'"/>
    <!-- Example Additional WHERE clause parameters create a 5 minute sliding window -->
    <point-label name="webserverstatus" sql="SELECT SUM(value) FROM SCORE WHERE groupname='webserverstatus' AND time > (time('now') - 300)"/>
    <!-- Example Default sum query is used -->
    <point-label name="redteam" />
    <point-label name="blueteam" />
    <!-- Example Query may use any columns in the score table-->
    <point-label name="teamtotal" sql='SELECT SUM(value) FROM SCORE WHERE groupname!="webserverstatus"'/> 
</point-labels>

<score-names>

Scores are calculated by making calculations from the groups of the labels above. Each <score-name /> formula is treated as an ERb template; use point-label as variables in calculations.

Attribute Description ValuesDefaultRequired
nameThe unique name of this score. This value is referenced when creating scoreboards.Stringn/aYes
descrThe friendly name of this score.Stringn/aNo
formulaAn ERb string comprising the calculation for this score. The ERb string may only use <point-label /> names as variables.ERb templaten/aYes
<score-names>
    <score-name name="red-team" descr="Red Team" formula="group1 - webserverstatus + redteam" />
    <score-name name="blue-team" descr="Blue Team" formula="blueteam + webserverstatus - redteam" />
    <score-name name="service-level" descr="Service Level" formula="group1 + webserverstatus + teamtotal" />
</score-names>

<ip-pools>

IP pools describe pools of ip addresses that an event can use as source addresses. These are useful for allocating to zombie traffic where the particular source address does not matter. Each <pool> will only have unique addresses. If pool definition specifies overlapping addresses only one address is used in the pool.

Attribute Description ValuesDefaultRequired
nameThe name of the pool to be used in <event> definitions.::alphanum::n/aYes
networkThe named network interface that the addresses from this pool should talk on.::alphanum::n/aYes
cidrThis will be the netmask when the address is configured for sending.Integern/aYes
gatewayIf this is set the gameserver will attempt to send traffic for this pool through the provided gateway.IPv4 Addressn/aNo
<pool name="int_2" network="prvt" cidr="24" gateway="">
    <address type="list">10.3.3.2</address>
</pool> 

Each pool definition consists of one or more <address /> tags. Each address tag describes either a list or range of IP addresses to be added to the pool. If the type is a list, then the list should be comma separated values in the content section of the <address> tag.

Attribute Description ValuesDefaultRequired
typeEither a range or list of addresses{range,list}n/aYes
countThe number of address to be used from the specified range.Integern/aYes, if type=range
addrThe range specification using CIDR notationIPv4 Addressn/aYes, if type=range
<address type="range" count="12" addr="10.24.15.0/24" />
<address type="list">10.3.3.2, 10.3.3.3, 128.15.23.4, 143.34.21.9</address> 

Complete example block:

<ip-pools>
        <!-- Simplest definition is a list of one address. 
            Lists are comma separated IPv4 addresses of the format X.X.X.X with no CIDR. -->
  <pool name="int_2" network="prvt" cidr="24" gateway="">
    <address type="list">10.3.3.2</address>
  </pool>
        <!-- A range is defined by a  CIDR denoted address block
             count is the number of addresses to add to the pool-->
  <pool name="int_1" network="prvt" cidr="24" gateway="">
    <address type="range" count="12" addr="10.24.15.0/24" select="asc" />
    <address type="list">10.3.3.2, 10.3.3.3, 128.15.23.4, 143.34.21.9</address>
  </pool>
  <pool name="pub_1" network="prvt" cidr="24" gateway="" >
    <address type="range" count="9" addr="16.0.0.0/8" select="asc" />
    <address type="range" count="23" addr="78.3.0.0/24" select="asc" />
    <address type="range" count="15" addr="200.15.14.0/24" select="asc" />
  </pool>
</ip-pools>

<event-handlers>

Event handlers are responsible for decoding the xml description of an event. Each <handler /> must be identified by a local name and must specify the class file to be used.

Attribute Description ValuesDefaultRequired
nameThe file-local name to be used in identifying this handler.Stringn/aYes
class-handlerThe name of the Class that should be loaded.Stringn/aYes

Other attributes may be specified and will be provided to the class-handler Class on instantiation.

<event-handlers>
  <handler name="exec-handler-1" class-handler="ExecHandler" />
</event-handlers>

<team>

This section specifies a grouping of parameters and for events.

Attribute Description ValuesDefaultRequired
nameThe friendly name to be used in identifying this team.Stringn/aYes
<team name="Blue Team">

<team-host>

This tag will be used in future version to support federation of events. The value localhost should be supplied.

Attribute Description ValuesDefaultRequired
hostnameThe name to be used in identifying where this team should be run.localhostn/aYes

<team-event-list>

The <team-event-list> is the parent block for all of the event definitions that are part of this team.

<team-event>

Each <team-event> describes the event to be run. This is the smallest unit that defines an event. An event is a description of a single or recurring action taken by the gameserver. Events are required to be described by at least the following characteristics. Each EventHandler may define its own additional required parameters.

Attribute Description ValuesDefaultRequired
nameThe friendly name to be used in identifying this event.Stringn/aYes
handlerA name defined in <event-handlers> of the class that should parse this event.Stringn/aYes
ipaddressA name defined in <ip-pools> that this event should as its source address.Stringn/aYes
starttimeThe Game Clock time in seconds at which the event should begin to run.Integern/aYes
endtimeThe Game Clock time in seconds at which the event should stop running. Applies mostly to repeating events.Integern/aYes
frequencyThe rate in seconds between launches of the event. A value of 0 will cause an event to happen only once at starttime.Floatn/aYes
driftThe number of seconds plus or minus the frequency that the event should drift.Floatn/aYes

All other attributes are passed directly to the handler class for evaluation. Each <team-event> may have one or several <score-atomic> child tags. Each tag specifies a point value to assign to a group when the event completes. Each EventHandler specifies the acceptable values for the when parameter and the conditions under which it applies.

Attribute Description ValuesDefaultRequired
whenUse this rule on Success or Failure defined by handler.Stringn/aYes
score-groupA name defined in <score-groups> of the group label that this point should be added to.Stringn/aYes
pointsA value for this rule, numbers may be negative values.Floatn/aYes
<score-atomic when="success" score-group="group1" points="5" />
<score-atomic when="fail" score-group="group2" points="-3" />

A complete example shows a team with one event using the ExecHandler handler. It has two possible scores one if the event succeeds and one if the event fails.

<team name="Red Team"> 
  <!-- Identifies the name of the location to dispatch this team to -->
  <team-host hostname="localhost" />
  <team-event-list>
    <team-event name="Ping Test" id="" guid="" handler="exec-handler-1" ipaddress="pub_1"
                starttime="0" endtime="9999999" frequency=".01" drift="0">
      <command>ping -c 1 127.0.0.1</command>
      <score-atomic when="success" score-group="group1" points="5" />
      <score-atomic when="fail" score-group="group2" points="-3" />
    </team-event>
  </team-event-list>
</team>