Server Network Interfaces

Private and Public Network Interfaces

There are three configurations for any one NIC that determines how that NIC behaves. Not all combinations of configuration are valid:

  • vlan: Private Network
  • ip_v4_conf: Public IP v4 Network, either static, DHCP, or manually assigned.
  • ip_v6_conf: Public IP v6 Network, either static, DHCP, or manually assigned.
Configurations Result
vlan ip_v4_conf ip_v6_conf  
True True True Error: Cannot assign all configs on a NIC
True True False Error: Cannot assign both Private and Public on a NIC
True False True Error: Cannot assign both Private and Public on a NIC
True False False Private network assigned
False True True Both IP v4 and v6 assigned
False True False Only IP v4 assigned
False False True Only IP v6 assigned
False False False No config assigned

IP Assignment for Public Interfaces

Assignment of IPs on private network interface is up to the user.

For public network interfaces it is possible to configure the way the address is assigned by setting the “conf” attribute on the ip_v4_conf or ip_v6_conf object:

“dhcp”:

The address is chosen by the system at boot time and assigned through DHCP. On each reboot the VM may get a different address. It is an error to specify the IP address for “conf”: “dhcp”. It is possible get the currently assigned dynamic IP of a NIC from the server runtime of a running server.

{
    "ip_v4_conf": {
        "conf": "dhcp"
    }
}
“static”:

The address is chosen and specified by the user. It is assigned to the NIC through DHCP and does not change between reboots. The “ip” attribute is mandatory and an IP address can be assigned from the addresses owned by the user.

{
    "ip_v4_conf": {
        "conf": "static",
        "ip": "185.12.6.183"
    }
}
“manual”:

There is no address specified for the NIC, and the user has to specify the IP address from within the VM. When this setting is used, the NIC is allowed to use all IPs for which the user has subscription. This “conf” can be used to assign multiple IPs to the same NIC.

{
    "ip_v4_conf": {
        "conf": "manual"
    }
}

Note

The cloud firewall does not allow traffic to/from IPs which are not owned or not assigned to the VM. The only exception is for “manual” conf where the VM is allowed to use any of the IPs which are owned by the user (the user has a subscriptions for them).

MAC Addresses

Newly created NICs have their mac address randomly generated.

Note

All traffic from a MAC address different from the assigned by the system is stopped by the cloud firewall, so users should no attempt to change their MACs from within their VM.

In order to update a NIC definition, the definition should have its “mac” attribute filled in. If on “nics” list update a MAC address disappears from the list, the corresponding NIC is deleted. If a MAC appears in the new list, the corresponding nic is updated, and if no MAC is specified on a NIC, a new NIC is created. It is an error to attempt to specify a MAC address which was not previously in the “nics” list.

The order of NICs in the “nics” attribute is important, because it is also the order in which nics are presented to the VM. It is possible to rearrange NICs by rearranging their orded in the “nics” list.

NIC Models

The “model” attribute specifies the model of the emulated network card. It is recommended to use virtio, whenever possible (when drivers for virtio are available for the VM operating system).

Model Bus Speed Description
e1000 PCI 1Gb/s Intel Gigabit Ethernet
i82551 ? ? ?
i82557b ? ? ?
i82559er ? ? ?
ne2k_pci PCI 10Mb/s NE2000
pcnet ? ? ?
rtl8139 ? 10/100Mb/s Realtek Fast Ethernet
virtio PCI 1Gb/s Virtual High Performance Ethernet card (see Virtio)

Reference: Wikibooks QEMU/Devices/Network.

NIC Runtime

When a server is running, the server definition provides information on the currently assigned dynamic IP and the data traffic made through the NIC. See server runtime for more details.

Examples

Example 1 - Private Network assigned to server:

Definition with all other values default:

PUT /api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "vlan": "96537817-f4b6-496b-a861-e74192d3ccb0"
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Result:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:ef:1d:27:70:0b",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Example 2 - Dynamic IP v4 (DHCP) assigned to NIC with e1000 model:

Definition with model set to ‘e1000’:

PUT /api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "ip_v4_conf": {
                "conf": "dhcp"
            },
            "model": "e1000"
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Result:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "dhcp",
                "ip": null
            },
            "ip_v6_conf": null,
            "mac": "22:5f:87:fd:00:b1",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Example 3 - Update nics:

Here is an example of a server with two nics:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "dhcp",
                "ip": null
            },
            "ip_v6_conf": null,
            "mac": "22:dc:29:30:ac:81",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:a5:f0:db:fe:da",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

In order to change the IP configuration of the NIC the definitions should have a MAC specified. Notice that in order to not delete the other NIC both NICs should be put in the request:

PUT /api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "static",
                "ip": "185.12.6.183"
            },
            "ip_v6_conf": null,
            "mac": "22:dc:29:30:ac:81",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:a5:f0:db:fe:da",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

The result is:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "static",
                "ip": {
                    "resource_uri": "/api/2.0/ips/185.12.6.183/",
                    "uuid": "185.12.6.183"
                }
            },
            "ip_v6_conf": null,
            "mac": "22:dc:29:30:ac:81",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:a5:f0:db:fe:da",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Example 4 - Rearrange nics:

In order to rearrange the NICs of the server definition from Example 3, the definition should just be updated with different order of NICs (NICs are recognized by their MAC):

PUT /api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:a5:f0:db:fe:da",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "static",
                "ip": {
                    "resource_uri": "/api/2.0/ips/185.12.6.183/",
                    "uuid": "185.12.6.183"
                }
            },
            "ip_v6_conf": null,
            "mac": "22:dc:29:30:ac:81",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

The resulting “nics” are:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:a5:f0:db:fe:da",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
            }
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "static",
                "ip": {
                    "resource_uri": "/api/2.0/ips/185.12.6.183/",
                    "uuid": "185.12.6.183"
                }
            },
            "ip_v6_conf": null,
            "mac": "22:dc:29:30:ac:81",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Notice that the private and public NICs changed order compared to Example 3.

Example 5 - Delete a NIC and change type of the other:

In order to change a NIC from private to public just remove the “vlan” field and “ip_v4_conf” field. This can also be combined with deletion of the other interface. Using the NICs from Example 4 here is how to delete the public NIC and change the private NIC to public:

PUT /api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "ip_v4_conf": {
                "conf": "dhcp"
            },
            "mac": "22:a5:f0:db:fe:da"
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "dhcp",
                "ip": null
            },
            "ip_v6_conf": null,
            "mac": "22:a5:f0:db:fe:da",
            "model": "virtio",
            "runtime": null,
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/f2208a27-bcee-4842-accf-9ac473cbe6b4/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "f2208a27-bcee-4842-accf-9ac473cbe6b4",
    "vnc_password": "testserver"
}

Notice that the NIC has the same MAC as the private NIC from Example 4, but is configured with DHCP.