Commit 86021efb authored by Jonathan Shahen's avatar Jonathan Shahen
Browse files

lots of additions to the README.md; small comment changes to the JAVADOC strings

parent d97c1a2e
......@@ -80,42 +80,82 @@ seed=12
The following are settings accepted by the program:
* **numberOfMachines**
* Type: INT
* Description: The number of servers/machines of the network. Machines are used to run multiple virtual machines at one time.
* **Type:** UNSIGNED INT
* **Description:** The number of servers/machines of the network. Machines are used to run multiple virtual machines at one time.
* **numberOfMachineSlots**
* Type: INT
* Description: The servers/machines are assumed homogenious, this gives each machine a number of slots, where each slot can run 1 single virtual machine (VM).
* **Type:** UNSIGNED INT
* **Description:** The servers/machines are assumed homogeneous, this gives each machine a number of slots, where each slot can run 1 single virtual machine (VM).
* **numberOfClients**
* Type: INT
* Description: The number of clients in a system. A client can own more than 1 virtual machine (VM). We need to know the clients, because we are not considering the cases where a vm is stealing information from another vm owned by the same client.
* **Type:** UNSIGNED INT
* **Description:** The number of clients in a system. A client can own more than 1 virtual machine (VM). We need to know the clients, because we are not considering the cases where a vm is stealing information from another vm owned by the same client.
* **numberOfVMsPerClient**
* Type: INT
* Description: If we assume homogenious clients, then this number represents how many virtual machines (VMs) each client owns and that is placed in the system.
* **Type:** UNSIGNED INT
* **Description:** If we assume homogeneous clients, then this number represents how many virtual machines (VMs) each client owns and that is placed in the system.
* **fillInEmpty**
* Type: BOOL
* Choices: true, false
* Description: If TRUE, then any empty spaces in on machiens will be filled by creating virtual machines (VMs) for clients. This means that the system will be 100% utilized (every slot on all machines are filled with a VM). It can mean that clients no longer have the same number of VMs (this only occurs if the free space in the system is not equal to a multiple of numberOfClients).
* **Type:** BOOLEAN
* **Choices:** true, false
* **Description:** If TRUE, then any empty spaces on machines will be randomly filled by creating virtual machines (VMs) for clients. This means that the system will be 100% utilized (every slot on all machines are filled with a VM). It can mean that clients no longer have the same number of VMs (this only occurs if the free space in the system is not equal to a multiple of numberOfClients).
* **numberOfEpochs**
* Type: INT
* Description: An epoch is a duration of time, where at the end of an epoch we try to migrate virtual machines (VMs) to lower the total information leakage. If the migrationBudget
* **Type:** UNSIGNED INT
* **Description:** An epoch is a duration of time, where at the end of an epoch we try to migrate virtual machines (VMs) to lower the total information leakage. If the migrationBudget
* **slidingWindow**
* Type: INT
* Description: How many epochs into the past should the calculation of total information leakage take place. Nomad has a hardcoded sliding window of 5 epochs.
* **Type:** UNSIGNED INT
* **Description:** How many epochs into the past should the calculation of total information leakage take place. Nomad has a hard-coded sliding window of 5 epochs.
* **placement**
* Type: STRING
* Choices:
* Description:
* **Type:** STRING
* **Description:** Defines the algorithm of how the placement of client VMs are in the system
* **Choices:**
* `randomPlacement` -- Randomly places VM's from each client into random machine slots. See `RandomPlacement#generateRandomPlacement()` for details.
* `randomHalfFull` -- Random placement, but with special values for machines/slots/clients/vms such that the system has a 50% usage. Uses `equalSpreadNum`. See `PlacementMapExamples#specialTest1()` for details.
* `readFile` -- Reads in the placement map from a CSV formatted file. An example placement map is located `tests/nomadSubOptimalRCPlacement.csv`. Also see `vagabond.placement.readPlacementMap()` for more details.
* `equalSpread` -- Creates a 100% utilized system, and equally spreads all client VMs over the servers, such that each machine has 1 VM for each client. This placement ignores the values in numberOfMachines/numberOfMachineSlots/numberOfClients/numberOfVMsPerClient and instead uses the value in `equalSpreadNum`. See `PlacementMapExamples#equalSpreadClients()` for details.
* `equalSpreadHalf` -- Same as `equalSpread` but instead of 100% utilized, the system is 50% utilized. There are half as many clients as there are machines/slots/vms. See `PlacementMapExamples#equalSpreadClientsHalfFull()` for details.
* `equalSpreadHalf2` -- Same as `equalSpreadHalf` but now it is half as many vms as there are machines/slots/clients. See `PlacementMapExamples#equalSpreadClientsHalfFull2()` for details.
* `percentFill` -- This placement ignores the values in numberOfMachines/numberOfMachineSlots/numberOfClients/numberOfVMsPerClient and instead uses the value in `equalSpreadNum`. See `PlacementMapExamples#percentFilled()` for details.
* `nahidTest` -- Nahid produced an initial placement map where Nomad cannot get to the optimal solution (even with infinite migration budget). In fact it does not migrate any VMs when presented with this placement map. This placement ignores the values in numberOfMachines/numberOfMachineSlots/numberOfClients/numberOfVMsPerClient. See `PlacementMapExamples#nomadSubOptimalRCPlacement()` for details.
* `nomadTest` -- In the work's of Moon et.al. (Nomad), they have a placement map that is 50% utilized, this simulates that placement for different values of `equalSpreadNum`. See `PlacementMapExamples#nomadTest()` for details.
* `specialTest1` -- Random placement, but with special values for machines/slots/clients/vms. Uses `equalSpreadNum`. See `PlacementMapExamples#specialTest1()` for details.
* **reduction**
* Type: STRING
* Choices:
* Description:
* **Type:** STRING
* **Description:** This indicates which of the 3 solvers to run.
* **Choices:**
* `ilp` -- Reduces the placement map and migration budget to an instance of Intger Linear Programming (ILP) and solves the problem using CPLEX.
* `cnf` -- Reduces the placement map and migration budget to an instance of Conjunctive Normal Form Boolean Satisfiability and solves the problem using lingeling.
* `nomad` -- We have altered nomad slightly to print out necessary debugging information in order to run nomad through our software. The changes are minor, the code is still considered to be identical in functionality to the code presented in the works of Moon et.al.
* **migrationBudget**
* Type: INT
* Description:
* **Type:** INT
* **Choices:** -1 or UNSIGNED INT
* **Description:** The migration budget is a limit on the number of migrations allowed per EPOCH. If the migration budget is -1, then no migration budget is enforced (-1 == infinite migration budget).
---
* **name**
* **OPTIONAL**
* **Type:** STRING
* **Description:** This string is saved with the results of a test in the file `logs/vagabond.stats.csv`. It is purely cosmetic and offered as a way to keep track of similar test cases. There is no limit on the string length.
* **comment**
* **OPTIONAL**
* **Type:** STRING
* **Description:** Similar to `name`, but here is a larger string where you can identify the exact test you are performing in words. There is no limit on the string length.
* **equalSpreadNum**
* **SEMI-OPTIONAL**; required for many of the placement algorithms
* **Type:** INT
* **Description:** This is a special number that has many uses within different placement algorithms. It is suggested that `vagabond.placement.PlacementMapExamples` be analyzed to understand how this number is used (in the code it is called many names, but is represented as an integer parameter).
* **seed**
* Type: LONG
* OPTIONAL
* Description: This allows for deterministic and repeatable results. On computing systems the it is customary to report an average elapsed time when reporting test results. This is because general purpose computers have other tasks they need to run along side the test and this can lead to fluctuation in the elapsed time being reported.
* **OPTIONAL**; default value is to set the random number generator's seed with the value `System.currentTimeMillis()` (`java.util.Random.setSeed(long)`)
* **Type:** LONG
* **Description:** This allows for deterministic and repeatable results. On computing systems the it is customary to report an average elapsed time when reporting test results. This is because general purpose computers have other tasks they need to run along side the test and this can lead to fluctuation in the elapsed time being reported.
* **maxCCIL**
* **OPTIONAL**; default value of false
* **Type:** BOOLEAN
* **Choices:** true or false
* **Description:** Changes how information leakage is calculated
* **true:** the solver will optimize for the Maximum Client to Client Information Leakage
* **false:** the solver will optimize for the Total/Summation Client to Client Information Leakage
* **placementFile**
* **SEMI-OPTIONAL**; this is required/used when the placement algorithm setting is `placement=readFile`
* **Type:** FILEPATH
* **Description:** The file path to a placement map (in CSV format), of what the initial placement should be. The values of numberOfMachines/numberOfMachineSlots/numberOfClients/numberOfVMsPerClient will be derived from the CSV file.
---
FAQ
......
......@@ -91,22 +91,22 @@ public enum VagabondOptionString {
*/
SETTINGSFILE("settings"),
/**
* [Settings File Property] The number of how many machines are there
* [Settings File Property] The number of how many machines there are
* @vagabond.category Settings File Property
*/
NUMMACHINES("numberOfMachines"),
/**
* [Settings File Property] The number of how many slots do machines have
* [Settings File Property] The number of slots each machine has
* @vagabond.category Settings File Property
*/
NUMSLOTS("numberOfMachineSlots"),
/**
* [Settings File Property] The number of how many clients are there
* [Settings File Property] The number of clients there are
* @vagabond.category Settings File Property
*/
NUMCLIENTS("numberOfClients"),
/**
* [Settings File Property] The number of how many vms per client
* [Settings File Property] The number of Virtual Machines (VMs) per client
* @vagabond.category Settings File Property
*/
NUMVMS("numberOfVMsPerClient"),
......@@ -150,7 +150,7 @@ public enum VagabondOptionString {
EQUALSPREADNUM("equalSpreadNum"),
/**
* [Settings File Property] This is an optional setting for setting the placement map file when
* {@link #PLACEMENT_FILE} is used.
* {@link #PLACEMENT_FILE} is used as the value for {@link #PLACEMENT}.
* @vagabond.category Settings File Property
*/
PLACEMENTFILEPATH("placementFile"),
......@@ -171,7 +171,7 @@ public enum VagabondOptionString {
*/
TESTCOMMENT("comment"),
/**
* [Settings File Property] The name of the test to be recorded in the STATS file
* [Settings File Property] The name of the test to be recorded in the STATS file. This is optional.
* @vagabond.category Settings File Property
* @see StatisticsManager#testName
*/
......@@ -225,14 +225,14 @@ public enum VagabondOptionString {
/**
* [Placement Algorithms] Generates a placement map using
* {@link PlacementMapExamples#nomadTest(vagabond.placement.RandomPlacement, int)}
* {@link PlacementMapExamples#nomadSubOptimalRCPlacement()}
* @vagabond.category Placement Algorithms
*/
PLACEMENT_NAHIDTEST("nahidTest"),
/**
* [Placement Algorithms] Generates a placement map using
* {@link PlacementMapExamples#specialTest1(vagabond.placement.RandomPlacement, int)}
* {@link PlacementMapExamples#nomadTest(vagabond.placement.RandomPlacement, int)}
* @vagabond.category Placement Algorithms
*/
PLACEMENT_NOMADTEST("nomadTest"),
......@@ -259,8 +259,7 @@ public enum VagabondOptionString {
* [Reduction Algorithms] Sends a PlacementMap to NOMAD and runs it
* @vagabond.category Reduction Algorithms
*/
REDUCTION_NOMAD("nomad"),
;
REDUCTION_NOMAD("nomad"),;
private String _str;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment