== Config Server API ==

The config server is a RESTful API. The server (by default) listens on port 5000. All messages are in JSON and have a top level {{{status}}} entry. If {{{status}}} is not zero, the only other entry in the message will be a {{{message}}} field, which contains an error message. Otherwise the message will contain the information requested. 

* URL: **/this_is_a_bad_URL**. Bad URLs return a non-zero {{{status}}} and {{{error}}} message.
  * Example: unknown URL:
{{{
> curl http://localhost:5000/borkborkbork
{
  "message": "404: Not Found",
  "status": 1
}
}}}
  * Example: Bad request. A valid URL, but with bad "arguments".
{{{
> curl http://localhost:5000/user/jjh
{
  "message": "user jjh not found",
  "status": 1
}
}}}
  * And another Invalid request.
{{{
> curl http://localhost:5000/computer/bork
{
  "message": "No computer 'bork' found.",
  "status": 1
}
}}}

* URL: **/pnodes**. Return names of all physical nodes in the experiment. Each entry contains a {{{type}}}, {{{control_name}}}, and {{{exp_name}}} fields. 
 * Example
{{{
> curl http://localhost:5000/pnodes
{
  "pnodes": [
    {
      "control_name": "cpc9",
      "exp_name": "pnode-0000",
      "type": "pnode"
    },
    {
      "control_name": "cpc93",
      "exp_name": "pnode-0001",
      "type": "pnode"
    },
    {
      "control_name": "cpc90",
      "exp_name": "config",
      "type": "pnode"
    }
  ],
  "status": 0
}
}}}

* URL: **/computer/<node_name>** - return information about computer given. What the information is is dependent on the type of computer. Currently supported: {{{pnode}}} and {{{qemu}}}. Examples of both are given below:
  * QEMU:
{{{
> curl http://localhost:5000/computer/glory
{
  "computer": {
    "arch": "x86_64",
    "image_url": "http://scratch/benito/pangolinbz.img.bz2",
    "interfaces": [
      {
        "address": "10.0.1.3",
        "bcast": null,
        "capacity": {
          "kind": "max",
          "rate": 100000.0,
          "units": "Kb/s"
        },
        "mac": "00:00:00:00:00:07",
        "mask": "255.255.255.0",
        "name": "inf000",
        "tap": false,
        "tun": false
      },
      {
        "address": "172.16.100.130",
        "bcast": null,
        "capacity": null,
        "mac": "00:66:00:00:64:82",
        "mask": "255.240.0.0",
        "name": "control0",
        "tap": false,
        "tun": false
      }
    ],
    "name": "glory",
    "os": "Ubuntu1204-64-STD",
    "type": "qemu"
  },
  "status": 0
}
}}}
  * Pnode:
{{{
> curl http://localhost:5000/computer/pnode-0000
{
  "computer": {
    "control_name": "cpc9",
    "exp_name": "pnode-0000",
    "type": "pnode"
  },
  "status": 0
}
}}}

* URL: **/embed/<pnode_name>**. Returns a list of containers ("embeds") that run on that pnode.
  * Example:
{{{
> curl http://localhost:5000/embed/pnode-0000
{
  "embeds": [
    "giles",
    "buffy",
    "xander",
    "angel"
  ],
  "status": 0
}
}}}

* URL: **/user/<login>**. Return the {{{/etc/passwd}}} type information for a user:{{{email}}}, {{{gid}}}, {{{password}}}, etc. 
  * Example
{{{
> curl http://localhost:5000/user/glawler
{
  "email": "\"glawler@tislabs.com\"",
  "gid": 1,
  "home": "/users/glawler",
  "login": "glawler",
  "name": "\"Geoff Lawler\"",
  "password": "$1$25502626$SJgRY/qEUFJWWIB1rkFqW1",
  "root": 1,
  "shell": "bash",
  "status": 0,
  "uid": 10467,
  "user": "glawler"
} 
}}}

== Config DB Tables (Schema) ==

*to be pasted*

== Config request path ==

Given the API/URls the request sequence should go as follows:

=== Pnodes ===

1. http://config:5000/computer/<name>. The pnode checks the "type" field and sees that it's a pnode. So it requests information about containers embedded in it next.
2. http://config:5000/embed/pnode-0000. The pnode gets a list of nodes embedded in it.
3. For each embedded node: http://config:5000/computer/<embedded node name> to get the container specific information (like path to qemu image) and embedded node interfaces so it can setup the virtual networking prior to launching the containers.


=== Nodes (containers) ===

1. http://config:5000/computer/<name>. To get at least the hostname and maybe the networking information if the system used to spawn the containers does not set that.
2. http://config:5000/moutns. Know what remote file systems to mount locally. Again, this may be taken care of by the vm spawn system (it can be when using Vagrant for instance.)
3. http://config:5000/users. Get the account information to create the users. 
4. TBD/other cool stuff.