Changes between Version 2 and Version 3 of ContributorGuide


Ignore:
Timestamp:
10/29/14 13:05:28 (5 years ago)
Author:
dmasterson
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • ContributorGuide

    v2 v3  
    33
    44== Getting Started ==
    5 Before trying to create a scenario one should be familiar with the general structure of a ScenarioPackage and a ScenarioFile. Next one should understand what a [wiki:"Base VM"] is and how the [wiki:"Administrative VM"] and OccpAdmin program can use ContentPacks and other specifications in the scenario file to produce the VSN with ConfigurationPhases. Finally one should be familiar with the GameServer's capabilities.
     5Before trying to create a scenario one should be familiar with the general structure of a ScenarioPackage and a ScenarioFile. Next, one should understand what a [wiki:"Base VM"] is and how the [wiki:"Administrative VM"] and OccpAdmin program can use ContentPacks and other specifications in the scenario file to produce the VSN with ConfigurationPhases. A [wiki:"ReferenceVSN"] has been created as a starting point to get familiar with this process.
    66
    7 '''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. 
     7'''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.
    88
    99Though ''highly discouraged'', creating your VSN by hand is still an option. We discourage it because it makes reuse by yourself and others much more difficult. For those we haven't discouraged see [#byhand this section].
     
    1111
    1212== Roadmap ==
     131. Checkout the ReferenceVSN to see if it is a suitable starting point or reference for your goals.
    13141. Map out what machines you want in the VSN. Decide what exploits, services, content, configurations, etc. that you require on each machine. Also determine what players will need to accomplish and what tools should be available to them. Then for each machine:
    1415 1. Download and install a suitable [wiki:"Base VM"] in to your hypervisor(s) that you will be using to develop your scenario. Create the host tag and set the basevm attribute in the ScenarioFile. If a suitable Base VM does not exist you have three options, but we'd prefer you choose the first
    15   * Visit the [wiki:"Base VM"] page and create a generic one for your needs leaving additional configurations to be handled by content packs, then contributing it back.
    16   * Following the steps to create a Base VM but perform additional configurations leaving only phase 2 configuration to ContentPacks. This is creating a phase 1 VM by hand. See [#byhand building by hand info]
    17   * (Discouraged) Create the VM entirely by hand and specify it as a phase 2 VM. See [#byhand building by hand info]
     16  * Visit the [wiki:"Base VM"] page and create a generic one for your needs leaving additional configurations to be handled by content packs, then contribute it back.
     17  * Following the steps to create a Base VM but perform additional configurations leaving only Phase 2 configuration to ContentPacks. This is creating a Phase 1 VM by hand. See [#byhand building by hand info]
     18  * (Discouraged) Create the VM entirely by hand and specify it as a Phase 2 VM. See [#byhand building by hand info]
    1819 1. Find ContentPacks that can install the software, exploits, or other content you require and add them to your host tag's content. If no suitable ContentPacks exist, you have several options.
    1920  * Create a content pack and contribute it back.
     
    2122  * (Discouraged) Do the work of the content pack by hand. See [#byhand building by hand info]
    2223 1. Write a content pack to configure the remaining details specific to your scenario, such as users, passwords, SSH keys, and so on. Please see [wiki:Generators] to see how these things can be generated for use with your content pack.
    23 1. If Player VMs were not created in the previous step you should follow similar steps to produce them now. The PlayerVMSetup page has some examples for player VMs.
     241. If Player VMs were not created in the previous step you should follow similar steps to produce them now. The PlayerVM page has some examples for player VMs.
    24251. With your VSN machines configured you will now need to configure the GameServer. A generic GameServer content pack is probably sufficient for most but if your scenario needs to extend the GameServer you should extend the content pack to accomplish that.
    25261. Now add the GameServer's actions to your scenario file.
     
    27281. You can add report tags to your ScenarioFile which will generate the documentation with the [wiki:Variables] or generated content from [wiki:Generators]. Ideally there would be documentation for the administrator and participants with the former containing a solution or more detailed description of the scenario itself.
    28291. When you are convinced everything is order run the OccpAdmin program in export mode and it will package your scenario.
    29 1. Hopefully you contribute your scenario back to the community
     301. Please contribute your scenario to the community
    3031
    3132== Contributing a Scenario ==
    32 Todo: document the contribution procedure.
     33Contributing logistics are still in development, please contact us for details.
    3334
    3435== Creating VMs by hand == #byhand
    3536Again we hope to discourage this in favor of expanding the number of ContentPacks available to the community but here is what you'd need to know if you wanted to create VMs by hand.
    3637
    37 The OccpAdmin program generally only performs actions on VMs that have a phase snapshot. Aside from the existence of these snapshots ''grouping'' also helps the program find the exact machines it is to act on. This not only helps ensure that the program does not accidentally harm machines that have accidental naming conflicts but it also drives its deployment logic. So:
    38 * If you fully build the VM by hand and do not ever intend to use ContentPacks then you must take a snapshot called phase2, add your VM to the scenario's group, and declare the host to be phase2 in the ScenarioFile.
     38The OccpAdmin program was designed such that it would not harm VMs that were not part of your OCCP deployment. The program identifies OCCP VMs by the existence of phase snapshots, grouping, or other hypervisor specific attributes. The group will be "occp-!YourScenarioName". For example, if my scenario name was "!NetworkDefense", my group would be "occp-!NetworkDefence". For VMware you must also add a configuration parameter called "occp.group" whose value is the group name.
     39* If you fully build the VM by hand and do not ever intend to use ContentPacks then you must take a snapshot called "phase2", add your VM to the scenario's group, and declare the host to be phase2 in the ScenarioFile.
    3940* If you create or extend a [wiki:"Base VM"] but do not intend to use ContentPacks to configure phase 1 then you must take a snapshot named "phase1", add your VM to the scenario's group, and declare the host to be phase1 in the ScenarioFile.