Closed User Groups (mp2mp_vc)

A closed user group is a participant-owned multi-user LAN service. You could either join an existing closed user group or create a new one.

Joining a Closed User Group

Query the network_services_list endpoint to retrieve the list of Network Services. You can filter by type in order to only list closed user groups: GET /network-services?type=mp2mp_vc

Within the result set, choose the appropriate network service. Normally, the closed user groups identify themselves via the property display_name.

The selected Network Service contains the property nsc_product_offerings which is a list of compatible Product Offerings of resource_type: network_service_config. You can use those ids to filter the product_offerings_list endpoint: GET /product-offerings?id=id1,id2,id3...

Once, you found a suitable product_offering (i.e. by choosing bandwidth or handover_metro_area_network) you can go ahead and create the Network Service Config. For this, use network_service_configs_create with the network_service and selected product_offering IDs.

Some exchanges require or allow mp2mp_vc circuits with MAC ACL Protection. In those cases, you would find a value describing the policy in the Network Service object in property mac_acl_protection.

For the selection and adding a MAC Address, please see configuring Exchange LAN Public Peering.

We list here the steps to obtain all the required properties.

  • The type for the NSC must match the type of the network service which in this case is mp2mp_vc.
  • The product_offering ID from the previously selected product offering response.
  • The network_service ID selected earlier.

You will also need Account IDs (managing_account, consuming_account, billing_account). If you are creating the service for yourself they will all match. Otherwise the consuming_account will be your sub-customer account ID and the billing_account could either be your or your sub-customer account ID depending on the billing policy of the exchange.

Next you will need to specify on which connection the service will reside. On how to obtain a connection ID please refer to Connection. The connection needs to be in the same handover_metro_area_network specified in the product offering.

When creating an NSC will also require a vlan config. Please see the Service VLAN section on how to specify it.

Specific services require specific contacts to be assigned to specific roles in that service context. Effectively being responsible for certain aspects of the service lifecycle (E.g: NOC contact supposedly reachable 24/7 for emergencies). You can find the required role assignments for a NSC using network_services_read on the selected Network Service in the nsc_required_contact_roles property.

Once you found out the required role assignment you need to either pick from existing or create the corresponding role assignments and specify their role assignments IDs during the creation of the NSC.

POST /network-service-configs network_service_configs_create
{
  "type": "mp2mp_vc",
  "managing_account": "<my_account_id>",
  "billing_account": "<my_account_id>",
  "consuming_account": "<customer_account_id>",
  "connection": "<connection_id>",
  "network_service": "<network_service_id>",
  "product_offering": "<product_offering_id>",
  "capacity": null,
  "role_assignments": [
    "<noc_role_assignment_id>",
    "<impl_role_assignment_id>"
  ],
  "vlan_config": {
    "vlan_type": "dot1q",
    "vlan": 23
  },
  "macs": ["<mac_address_id>"]
}

Creating a Closed User Group

First select a product offering of the type mp2mp_vc matching your criteria like handover and service metro area network.

Then create the network service using network_services_create with type mp2mp_vc and providing the ID of the selected product_offering.

You will also need Account IDs (managing_account, consuming_account, billing_account). If you are creating the service for yourself they will all match. Otherwise the consuming_account will be your sub-customer account ID and the billing_account could either be your or your sub-customer account ID depending on the billing policy of the exchange. Optionally you could specify a display name for the network service to make it easily identifiable by other users.

Closed user groups can have either a public or a private joining policy.

If private, the network service is only visible to users that have been invited by the owner by creation of a specific member joining rule for the joining member.

If public, the network service is visible to all users of the API and able to join unless there is a member joining rule in place, denying such access.

Create a member joining rule with the member_joining_rules_create operation.

You can choose to either allow or deny access to a customer identified by the consuming_account property. You need to specify the id of the network_service.

In case of allow, you can specify a minimal bandwidth requirement or limit.

Some exchanges might require you to join your own mp2mp_vc Network Service in order for it to become operational. In this case, follow the instructions in the above section.

POST /network-services network_services_create
{
  "type": "mp2mp_vc",
  "product_offering": "<product_offering_id>",
  "managing_account": "<my_account_id>",
  "consuming_account": "<customer_account_id>",
  "billing_account": "<my_account_id>",
  "display_name": "My Closed User Group",
  "public": false
}
Status: 201 Content-Type: application/json Response
{
  "id": "ffaaaaaa-1dd1-11b2-801b-000000000000",
  "type": "mp2mp_vc",
  "state": "requested",
  "status": [
    {
      "severity": 2,
      "tag": "member_joining_rule_required",
      "message": "A joining rule is required for non public Closed User Groups.",
      "attrs": {},
      "timestamp": "2019-08-24T14:15:22Z"
    },
    {
      "severity": 2,
      "tag": "nsc_required",
      "message": "Please join the closed user group by creating a Network Service Config.",
      "attrs": {},
      "timestamp": "2019-08-24T14:15:22Z"
    }
  ],
  "nsc_product_offerings": ["<nsc_product_offering_id>"],
  "nsc_required_contact_roles": [
    "<noc_role_id>",
    "<impl_role_id>"
  ],
  "mac_acl_protection": false,
  "product_offering": "<product_offering_id>",
  "managing_account": "<my_account_id>",
  "consuming_account": "<customer_account_id>",
  "billing_account": "<my_account_id>",
  "display_name": "My Closed User Group",
  "public": false,
  "member_joining_rules": [],
  "network_features": []
}
POST /member-joining-rules member_joining_rules_create
{
  "type": "allow",
  "managing_account": "<my_account_id>",
  "consuming_account": "<account_allowed_to_join_id>",
  "network_service": "<network_service_id>"
}