Network Interface Cards (NICs)

The NICs interface will allow you to configure the network interfaces on your virtual machine, but at present it is read only, apart from adding IP addresses.

The rules for what can be changed on a running virtual machine are currently complex. The simple advice is to power down a machine before making changes to NICs.

Endpoints

These are relative to https://uk0.bigv.io

At present, users are not able to make changes to their NIC configuration from the API; you will need to contact support.

GET /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}/nics
GET /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}/nics/{nic-id}

# Non-nested endpoints (currently only GET)
GET /nics
GET /nics?vm_id={vm-id}
GET /nics/{nic-id}

• Replace {account-id} with the account ID or name.
• Replace {group-id} with the group ID or name (or default if you don’t use groups!).
• Replace {vm-id} with the ID of the virtual machine.
• Replace {nic-id} with the NIC ID.

Attributes

• id – unique key (integer).
• label – unique device name.
• ips – list of IPs assigned to the interface (IPv4 and IPv6).
• vlan_num – maps to a bytemark VLAN (contact support for VLAN setup).
• mac – mac address for the interface.
• extra_ips – additional IPs (aliases).
• virtual_machine_id – ID of the virtual machine the NIC is linked to.

Additional IP Addresses

The ip_create endpoint (POST) can be used to add additional IP addresses to the virtual machine (up to a maximum of 4). This currently only supports routing extra non-contiguous IPv4 addresses via that NICs primary IPv4 address.

Additional IPs can be deleted using the IPs endpoint.

Endpoint

POST /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}/nics/{nic-id}/ip_create

Attributes

• addresses – how many addresses are being requested (integer).
• family –  ipv4 (ipv6 not currently supported for additional addresses).
• reason – A description of why the user requires this allocation (string).
• contiguous – Does the user want a block, or are they happy with a non-contiguous allocation? (currently not implemented).

Examples

All NICs on a virtual machine

Request

GET /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}/nics

# New style
GET /nics?vm_id={vm-id}

Curl

curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     https://uk0.bigv.io/accounts/myaccountname/groups/default/virtual_machines/1234/nics

Response

[
  {
    "id": 1,
    "label": null,
    "ips": [
      "213.123.123.123",
      "2001:1234:1:1:ffff:ff:ff:f12f"
    ],
    "vlan_num": 1,
    "mac": "fe:ff:00:ff:ff:ff",
    "extra_ips": {},
    "virtual_machine_id": 1234
  }
]

Single NICs on a virtual machine

Request

GET /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}/nics/{nic-id}

# New style
GET /nics/{nic-id}

Curl

curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     https://uk0.bigv.io/accounts/myaccountname/groups/default/virtual_machines/1234/nics/1

Response

{
  "id": 1,
  "label": null,
  "ips": [
    "213.123.123.123",
    "2001:1234:1:1:ffff:ff:ff:f12f"
  ],
  "vlan_num": 1,
  "mac": "fe:ff:00:ff:ff:ff",
  "extra_ips": {},
  "virtual_machine_id": 1234
}

Add Additional IP Address

Request

POST /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}/nics/{nic-id}/ip_create

Curl

curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     -X POST \
     -d '{"addresses":1,"family":"ipv4","reason":"I need an additional IP address for xyz"}' \
     https://uk0.bigv.io/accounts/myaccountname/groups/default/virtual_machines/1234/nics/1

Response

{
  "contiguous": false,
  "addresses": 1,
  "family": "ipv4",
  "ips": [],
  "reason": "I need an additional IP address for xyz",
  "id":1
}