wiki:SharedNetworkCommands

Shared Network Manipulation Commands

The following page documents our plan for implementing initial set of commands used to manipulate shared networks. This set of commands is somewhat basic, but we expect to have it expanded in the future.

List networks (network4-list, network6-list)

There are two commands: network4-list and network6-list. Each returns specific type of shared networks.

{
    "command": "network4-list"
}

The response will generate a list of IPv4 shared networks. Only very basic information is returned about each network at this stage. To get more details, use network4-get. Example response:

{
     "result": 0,
     "text": "2 IPv4 shared networks found",
     "arguments": {
         "shared-networks": [
             {
                 "name": "frog"
             },
             {
                 "name": "parrot"
             }
         ]
     }
}

TODO: describe network6-list. It will work exactly the same as network4-list.

Retrieving shared network (network4-get, network6-get)

Once network4-list is called, the names of configured shared networks are known. To retrieve details about specific shared network, network4-get and network6-get can be called. Both of those commands have one mandatory parameter "name" that specifies a name of the network to be retrieved. Example command:

{
    "command": "network4-get",
    "arguments": {
        "name": "floor13"
    }
}

An example response would look as follows:

{
    "arguments": {
       "shared-networks": [
       {
          "name": "floor13",
            "option-data": [
                {
                    "name": "domain-name-servers",
                    "code": 6,
                    "space": "dhcp4",
                    "csv-format": true,
                    "data": "192.0.2.3"
                }
          ],
          "subnet4": [
          {
              "subnet": "192.0.2.0/24",
              "id": 1024,
              "pools": [
                 { "pool": "192.0.2.10-192.0.2.20" },
                 { "pool": "192.0.2.64/26" }
              ]
          },
          {
              "subnet": "192.0.3.0/24",
              "id": 1025,
              "pools": [
                 { "pool": "192.0.3.1-192.0.3.33" }
              ]
          }]
       }]
    },
    "result": 0,
    "text": "Info about IPv4 shared network (name 'floor13') returned."
}

Adding shared network (network4-add, network6-add)

Shared networks can be added using network4-add and network6-add commands. Typically, a whole shared network with several subnets would be added at once. In the near future it will be possible to add a new subnet to existing network or add existing subnet to existing network.

{
    "command": "network4-add",
    "arguments": {
        "shared-networks": [
            {
                "name": "foo",
                "option-data": [
                    // option data here
                ],
                // other parameters here.
                "interface": "eth0",
                "subnet4": [
                     // list of subnets here
                ]
            }
        ]
    }
}

Deleting shared network (network4-del, network6-del)

There are two commands that allow deleting shared networks: network4-add and network6-del. An example call looks as follows:

{
    "command": "network4-del",
    "arguments": {
        "name": "floor13"
    }
}

If there are any subnets in the shared network being deleted, those will be downgraded to regular subnets. If you want to delete them, please use subnet4-del command before or after deleting the network.

Adding subnet to existing shared network

TODO: need to extend existing subnet4-add, subnet6-add to accept additional parameter "shared-network" what would take the shared network name.

Removing a subnet from existing shared network

To remove a subnet from existing shared network, simply use subnet4-del, in the similar way as if removing plain subnet.

Old notes (obsolete)

TODO: need to remove this.

Proposed operations:

  1. Create shared network (without subnets in it)
  2. Remove shared network with an option for cascaded removal of subnets within this network.
  3. Add existing subnet(s) to the existing shared network
  4. Remove assignment of subnets from a shared network (This doesn't remove subnets).

The following subsections provide the proposed formats of the corresponding control commands.

Create Shared Network

Remove Shared Network

{
    "command": "shared-network-del",
    "arguments": {
        "name": "foo",
        "cascade-delete": false
    }
}

Add Subnets to Shared Network

We still have to design commands updating subnets. It is proposed here that assignment of the specific subnet to a shared network will be made using those commands.

{
    "command": "subnet4-update",
    "arguments": {
        "subnets": [ {
            "id": 123,
            "subnet": "10.20.30.0/24",
            "shared-network": "foo"
        } ]
    }
}

Remove Subnets from Shared Network

This is up for discussion whether it is acceptable to unassign a subnet from a shared network by specifying empty name of shared network. The pros are:

  • no need for adding extra commands to just unassign a subnet from a shared network
  • anything else?

The cons:

  • it is not immediately clear what is being changed with the command. You need to compare it with existing configuration.
  • The other (unrelated) parts of subnet configuration have to be specified within a command (e.g. option-data etc.)
{
    "command": "subnet4-update",
    "arguments": {
        "subnets": [ {
            "id": 123,
            "subnet": "10.20.30.0/24",
            "shared-network": ""
        } ]
    }
}

A possible way forward is to allow assignment of shared subnets using subnet4-update commands (that may be useful in some cases when there is a general subnet information update going on), but later implement additional (dedicated) commands that solely assign/unassign subnets to/from shared networks. How about that?

Last modified 5 weeks ago Last modified on Oct 16, 2017, 1:55:27 PM