chi.network

The chi.network module exposes a functional interface for interacting with the various networking capabilities of the testbed.

chi.network.add_port_to_router(router_id, port_id)[source]

Add a port to a router.

Parameters:

  • router_id (str) – The router ID.

  • port_id (str) – The port ID.

chi.network.add_port_to_router_by_name(router_name, port_name)[source]

Add a port to a router, referencing the router and port by name.

Parameters:

  • router_name (str) – The router name.

  • port_name (str) – The port name.

chi.network.add_route_to_router(router_id, cidr, nexthop)[source]

Add a new route to a router.

Parameters:

  • router_id (str) – The router ID.

  • cidr (str) – The destination subnet CIDR for the route.

  • nexthop (str) – The nexthop address for the route.

chi.network.add_routes_to_router(router_id, routes)[source]

Add a set of routes to a router.

Parameters:

  • router_id (str) – The router ID.

  • routes (list[dict]) –

    A list of routes to add. The list is expected to consist of items with a ‘destination’ and ‘nexthop’ key, e.g.:

    [
   {'destination': '10.0.0.0/24', 'nexthop': '10.0.0.1'},
   {'destination': '10.0.1.0/24', 'nexthop': '10.0.1.1'}
]

chi.network.add_subnet_to_router(router_id, subnet_id)[source]

Add a subnet to a router.

Parameters:

  • router_id (str) – The router ID.

  • subnet_id (str) – The subnet ID.

chi.network.add_subnet_to_router_by_name(router_name, subnet_name)[source]

Add a subnet to a router, referencing the router and subnet by name.

Parameters:

  • router_name (str) – The router name.

  • subnet_name (str) – The subnet name.

chi.network.bind_floating_ip(ip_address, port_id=None, fixed_ip_address=None)[source]

Directly assign a Floating IP to an existing port/address.

Note

If you just want to attach a Floating IP to a server instance, the chi.server.associate_floating_ip() function is simpler.

Parameters:

  • ip_address (str) – The Floating IP address.

  • port_id (str) – The ID of the port to bind to.

  • fixed_ip_address (str) – The address in the port to bind to. This is only required if the port has multiple IP addresses assigned; by default the first IP in a port is bound.

chi.network.create_network(network_name, of_controller_ip=None, of_controller_port=None, vswitch_name=None, provider='physnet1', port_security_enabled=True) → dict[source]

Create a network.

For an OpenFlow network include the IP and port of an OpenFlow controller on Chameleon or accessible through the public Internet. Include a virtual switch name if you plan to add additional private VLANs to this switch. Additional VLANs can be connected using a dedicated port corresponding to the VLAN tag and can be conrolled using a valid OpenFlow controller.

Parameters:

  • network_name (str) – The new network name.

  • of_controller_ip (str) – the IP of the optional OpenFlow controller. The IP must be accessible on the public Internet.

  • of_controller_port (str) – the port of the optional OpenFlow controller.

  • vswitch_name (str) – The virtual switch to use name.

  • provider (str) – the provider network to use when specifying stitchable VLANs (i.e. ExoGENI). Default: ‘physnet1’

chi.network.create_port(port_name, network_id, fixed_ips=None, subnet_id=None, ip_address=None, port_security_enabled=True) → dict[source]

Create a new port on a network.

This function has a short-form and a long-form invocation. In the short form, you can specify subnet_id and ip_address to give the port a single assignment on a subnet. In the long form you can specify fixed_ips to define multiple assignments.

Parameters:

  • port_name (str) – The name to give the new port.

  • network_id (str) – The ID of the network that the port will be connected to.

  • fixed_ips (list[dict]) – A list of IP assignments to give to the port on various subnets. Each assignment must at minimum have a subnet_id defined. An optional ip_address can be included on an assignment to specify the exact IP address to assign. Otherwise, one is chosen automatically from the available IPs on the subnet. There can be multiple assignments (i.e., IPs) on a single subnet.

  • subnet_id (str) –

    The ID of the subnet that the port will be allocated on. The port will be automatically assigned an IP address on this subnet, unless the ip_address parameter is provided.

    Note

    This parameter is ignored if fixed_ips is set.

  • ip_address (str) –

    The IP address to assign the port, if a specific IP address is desired. By default an IP address is automatically picked from the target subnet.

    Note

    This parameter is ignored if fixed_ips is set.

  • port_security_enabled (bool) – Whether to enable port security. In general this should be kept on. (Default True).

Returns:

The created port representation.

chi.network.create_router(router_name, gw_network_name=None) → dict[source]

Create a router, with or without a public gateway.

Parameters:

  • router_name (str) – The new router name.

  • gw_network_name (str) – The name of the public gateway requested to provide subnets connected this router NAT to the Internet.

Returns:

The created router representation.

chi.network.create_subnet(subnet_name, network_id, cidr='192.168.1.0/24', allocation_pool_start=None, allocation_pool_end=None, gateway_ip=None) → dict[source]

Create a subnet on a network.

Parameters:

  • subnet_name (str) – The name to give the new subnet.

  • network_id (str) – The network to associate the subnet with ID.

  • cidr (str) – The subnet’s IPv4 CIDR range. (Default 192.168.1.0/24)

  • gateway_ip (str) – The subnet’s gateway address. If not defined, the first address in the subnet will be automatically chosen as the gateway.

Returns:

The new subnet representation.

chi.network.delete_network(network_id)[source]

Delete the network.

Note

This does not perform a full teardown of the network, including removing subnets and ports. It will only succeed if the network does not have any attached entities. See nuke_network() for a more complete teardown function.

Parameters:

network_id (str) – The network ID.

chi.network.delete_port(port_id)[source]

Delete the port.

Parameters:

port_id (str) – The port ID.

chi.network.delete_router(router_id)[source]

Delete the router.

Parameters:

router_id (str) – The router ID.

chi.network.delete_subnet(subnet_id)[source]

Delete the subnet.

Parameters:

subnet_id (str) – The subnet ID.

chi.network.get_floating_ip(ip_address) → dict[source]

Get the floating IP representation for an IP address.

Parameters:

ip_address (str) – The IP address of the floating IP.

Returns:

The floating IP representation.

chi.network.get_free_floating_ip(allocate=True) → dict[source]

Get the first unallocated floating IP available to your project.

Parameters:

allocate (bool) – Whether to allocate a new floating IP if there are no Floating IPs currently free in your project. Defaults to True.

Returns:

The free floating IP representation.

chi.network.get_network(ref) → dict[source]

Get a network by its name or ID.

Parameters:

ref (str) – The name or ID of the network.

Returns:

The network representation.

Raises:

RuntimeError – If the network could not be found, or multiple networks were returned for the search term.

chi.network.get_network_id(name) → str[source]

Look up a network’s ID from its name.

Parameters:

name (str) – The network name.

Returns:

The network’s ID, if found.

Raises:

RuntimeError – If the network could not be found, or multiple networks were returned for the search term.

chi.network.get_port(ref) → dict[source]

Get a port by its name or ID.

Parameters:

ref (str) – The name or ID of the port.

Returns:

The port representation.

Raises:

RuntimeError – If the port could not be found, or multiple ports were returned for the search term.

chi.network.get_port_id(name) → str[source]

Look up a port’s ID from its name.

Parameters:

name (str) – The port name.

Returns:

The port’s ID, if found.

Raises:

RuntimeError – If the port could not be found, or multiple ports were returned for the search term.

chi.network.get_router(ref) → dict[source]

Get a router by its name or ID.

Parameters:

ref (str) – The name or ID of the router.

Returns:

The router representation.

Raises:

RuntimeError – If the router could not be found, or multiple routers were returned for the search term.

chi.network.get_router_id(name) → str[source]

Look up a router’s ID from its name.

Parameters:

name (str) – The router name.

Returns:

The router’s ID, if found.

Raises:

RuntimeError – If the router could not be found, or multiple routers were returned for the search term.

chi.network.get_subnet(ref) → dict[source]

Get a subnet by its name or ID.

Parameters:

ref (str) – The name or ID of the subnet.

Returns:

The subnet representation.

Raises:

RuntimeError – If the subnet could not be found, or multiple subnets were returned for the search term.

chi.network.get_subnet_id(name) → str[source]

Look up a subnet’s ID from its name.

Parameters:

name (str) – The subnet name.

Returns:

The subnet’s ID, if found.

Raises:

RuntimeError – If the subnet could not be found, or multiple subnets were returned for the search term.

chi.network.list_floating_ips() → list[dict][source]

List all floating ips associated with the current project.

Returns:

A list of all the found floating ips.

chi.network.list_networks() → list[dict][source]

List all networks associated with the current project.

Returns:

A list of all the found networks.

chi.network.list_ports() → list[dict][source]

List all ports associated with the current project.

Returns:

A list of all the found ports.

chi.network.list_routers() → list[dict][source]

List all routers associated with the current project.

Returns:

A list of all the found routers.

chi.network.list_subnets() → list[dict][source]

List all subnets associated with the current project.

Returns:

A list of all the found subnets.

chi.network.nuke_network(network_ref: str)[source]

Completely tear down the network.

Cleanly tearing down an OpenStack network representation involves a few separate steps:

  1. Detach the network’s subnets from the router.

  2. Delete the router.

  3. Delete the subnet(s).

  4. Delete the network.

This function performs all of those steps for you.

Note

This function will not work well for very advance networks, perhaps those connected to multiple routers. You should perform your own cleanup if your network’s subnets are attached to multiple routers.

Parameters:

network_ref (str) – The network name or ID.

chi.network.remove_all_routes_from_router(router_id)[source]

Remove all routes from the router.

Parameters:

router_id (str) – The router ID.

chi.network.remove_port_from_router(router_id, port_id)[source]

Remove a port from the router.

Parameters:

  • router_id (str) – The router ID.

  • port_id (str) – The port ID.

chi.network.remove_route_from_router(router_id, cidr, nexthop)[source]

Remove a single route from the router.

Parameters:

  • router_id (str) – The router ID.

  • cidr (str) – The destination subnet CIDR for the route.

  • nexthop (str) – The nexthop address for the route.

chi.network.remove_routes_from_router(router_id, routes)[source]

Remove a set of routes from a router.

Parameters:

  • router_id (str) – The router ID.

  • routes (list[dict]) –

    A list of routes to remove. The list is expected to consist of items with a ‘destination’ and ‘nexthop’ key, e.g.:

    [
   {'destination': '10.0.0.0/24', 'nexthop': '10.0.0.1'},
   {'destination': '10.0.1.0/24', 'nexthop': '10.0.1.1'}
]

chi.network.remove_subnet_from_router(router_id, subnet_id)[source]

Remove a subnet from the router.

Parameters:

  • router_id (str) – The router ID.

  • subnet_id (str) – The subnet ID.

Wizards

There are additionally some functions that tie together several common tasks.

class chi.network.wizard[source]

A collection of “wizard” functions.

These utility functions are very opinionated but can reduce boilerplate.

static create_network(name_prefix, of_controller_ip=None, of_controller_port=None, gateway=False)[source]

Create a network and subnet, and connect the subnet to a new router.

Parameters:

  • name_prefix (str) – The common name prefix for all created entities.

  • of_controller_ip (str) – The OpenFlow controller IP, if using.

  • of_controller_port (int) – The OpenFlow controller port, if using.

  • gateway (bool) – Whether to add a WAN gateway to the router. Routers with a WAN gateway are able to NAT to the Internet.

Returns:

The created network representation.

static delete_network(name_prefix)[source]

Delete a network created via :func:wizard.create_network.

Parameters:

name_prefix (str) – The common name prefix for all created entities.