The following curl commands can be used to configure teaming.
|
|
|
![[NOTE: ]](images/note.gif) |
NOTE: Examples of curl commands in this section use the |
|
|
Before creating a team ensure that your environment meets the requirements for teaming, see Requirements for teaming. And for each controller that will become a member of the team, configure NTP to use a centralized NTP daemon, see Configuring the controllers to use the same local NTP server.
The default configuration of the SDN Controller is the system’s eth0 interface. When a controller team is formed via REST with the team IP Address, an alias in the controller elected as leader will be configured automatically by the system and will attach to the eth0 interface by default. If the SDN Controller has multiple Ethernet interfaces, a different interface can be required for the team IP Address. In this case the configuration /etc/sdn/admin/options might be changed using vim or emacs to reflect the desired configuration.
sdncontroller:/opt/sdn/admin# cat options export ADMIN_OPTS="-Dcom.hp.sdn.admin.interface= eth0"
Once the change has been made, the SDNA service must be restarted as shown with the following command:
sdncontroller:/opt/sdn/admin#
sudo service sdna restart
sdna stop/waiting
This change must be made for every active controller within the team and does not require that the team be deleted via REST.
To view the team IP Address designation from the SDN Controller console or SSH session, use the ifconfig command:
sdncontroller:$
ifconfig
eth0 Link encap:Ethernet HWaddr ac:16:2d:9a:62:60
inet addr:172.17.3.17 Bcast:172.17.15.255 Mask:255.255.240.0
inet6 addr: fe80::ae16:2dff:fe9a:6260/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:1151070 errors:0 dropped:284 overruns:0 frame:0
TX packets:1134356 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:684988786 (684.9 MB) TX bytes:882495744 (882.4 MB)
Memory:f7f80000-f8000000
eth0:0 Link encap:Ethernet HWaddr ac:16:2d:9a:62:60
inet addr:172.17.3.41 Bcast:172.17.15.255 Mask:255.255.240.0
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
Memory:f7f80000-f8000000
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:65536 Metric:1
RX packets:116581 errors:0 dropped:0 overruns:0 frame:0
TX packets:116581 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:32894518 (32.8 MB) TX bytes:32894518 (32.8 MB)
This section describes configuring a controller team using curl commands.
Team authentication is managed with iptables. The team communication channel is not encrypted. If you deploy the team in a highly secure environment, you can always use standard Linux IPSec functionality to encrypt traffic between the team members.
You will need to setup bi-directional rules on each controller for communication with each of the other two controllers using the IP addresses specified during the team creation. For simplicity, you can configure host to host IPsec and secure all traffic between the controllers. However, all external communication channels other than teaming are already secured with SSL. If you only want to secure the team communication channel, the rules should be created to only encrypt port 5700.
|
|
|
|
|
NOTE: Do not use the team leader IP address in any of the IPsec rules. |
|
|
For more information on how to configure IPsec for Linux:
https://help.ubuntu.com/community/IPSecHowTo
http://manpages.ubuntu.com/manpages/precise/man5/ipsec.conf.5.html
http://manpages.ubuntu.com/manpages/precise/man5/ipsec.secrets.5.html
|
|
|
|
|
NOTE: The default domain and user settings are |
|
|
|
|
|
![[CAUTION: ]](images/caution.gif) |
CAUTION: Credential information (user name, password, domain, and authentication tokens) used in curl commands might be saved in the command history. For security reasons, Hewlett Packard Enterprise recommends that you disable command history prior to executing commands containing credential information. |
|
|
-
Install and start three standalone controllers in the network. (See the latest HPE VAN SDN Controller Installation Guide.)
-
Optional: To improve security, you can change the username and password from the default settings on each of the standalone controllers in step 1.
-
Select any one of the controllers to use for configuring the team.
-
On the selected controller, acquire an Authentication Token. Use the following curl command, with the controller IP address, to acquire the token:
curl --noproxy controller_ip> -X POST --fail -ksSfL --url "https://<controller_ip>:8443/sdn/v2.0/auth" -H "Content-Type: application/json" --data-binary '{"login": {"domain": "<domain>","user": "<user>","password": "<password>"}}'Command Example
In this example, the default domain, user name, and password are used.
curl --noproxy 192.15.135.187 -X POST --fail -ksSfL --url "https://192.15.135.187:8443/sdn/v2.0/auth" -H "Content-Type: application/json" --data-binary '{"login": {"domain": "sdn","user": "sdn","password": "skyline"}}'Command Response
The command generates the authentication token
1759f214479e4ffd9504acb42123ef40.{"record":{"token":"1759f214479e4ffd9504acb42123ef40", "expiration":1381982391381982399000,"expirationDate":"2014-10-16 20-59-59 -0700", "userId":"b00cb0e94c9441d58011f980cf9635ae","userName":"sdn","domainId": "a6701f6593d84fa5b8f23f9ab4ed69db","domainName":"sdn"}} -
Determine the team configuration parameters:
Parameter
Value
Team IP Address
The team IP address is different from the individual controller IP addresses. It is used as a virtual address for connecting to the team leader.
Controller IP Address
IP address of a team member.
NOTE: When the virtual address is programmed on the team leader, gratuitous ARP is sent out. The virtual address moves from one controller to another in the team as the leader changes. If any security features are configured to prevent such a move, they should be reconfigured to allow the movement of team IP Address such that it remains reachable for the rest of the network.
-
Select any active controller to initially configure the team.
-
Enter the following curl command:
curl -m 240 --noproxy member-1-ip --header X-Auth-Token:auth_token --fail -ksS --request POST --url https://member-1-ip:8443/sdn/v2.0/team --data-binary '{"team":{"ip":"team-ip","members":[{"ip":"member-1-ip"},{"ip":"member-2-ip"},{"ip":"member-3-ip"}]}}'
NOTE: The
member-1-ipshould be the IP address of the controller chosen to configure the team.
-
After executing the command in step 2, the team elects a team leader. The team leader then configures all team members and normal controller operation begins in the domain. The team creation command does not block until the team creation is complete. You will need to check the status of the system to verify on each controller that the team was successfully created.
The team
create POSTcommand may now take up to 4 minutes to complete. You will need to make sure the read timeout for the client request is increased accordingly.
Configuration example
This example shows a team of controllers configured with the following team member values:
-
Team IP Address: 192.0.2.100
-
Member IP Addresses :
-
192.0.2.119
-
192.0.2.125
-
192.0.2.127
-
-
Domain:
sdn(the default domain name) -
Username:
myname -
Password:
mypass
|
|
|
|
|
NOTE: It is not mandatory that the team IP address be in the same subnet as the member IP addresses. Other IP aliases can be used if the appropriate IP routes are present for the addresses to be reachable and usable. |
|
|
The following steps create and enable the team:
-
Acquire the authentication token:
Command example
curl --noproxy 192.0.2.119 -X POST --fail -ksSfL --url "https://192.0.2.119:8443/sdn/v2.0/auth" -H "Content-Type: application/json" --data-binary '{"login": {"domain": "sdn","user": "myname","password": "mypass"}}'Command response
{"record":{"token":"10f728e477cb4612b07069f339d0ca29","expiration": 1381119301000,"expirationDate":2013-12-06 21-15-01-0700", "userId":"51802e12d16345fe9a4389290c1a04e2","username":"sdn","domainId": "d45eca9bde1b4dc78bd7dff69ee9440d","domainName":"sdn"}} -
Configure the controller team by using the team values and token from step 1:
curl -m 240 --noproxy 192.0.2.119 --header X-Auth-Token: 10f728e477cb4612b07069f339d0ca29 --fail -ksS --request POST --url https://192.0.2.119:8443/sdn/v2.0/team --data-binary '{"team":{"ip":"192.0.2.100","members": [{"ip":"192.0.2.119"}, {"ip":"192.0.2.125"}, {"ip":"192.0.2.127"}]}}'
Since team creation is asynchronous, the response is always 202 unless the team configuration (JSON) is not valid or there is a problem configuring the local controller. Possible codes are:
| 202 Accepted |
| 400 Bad request |
| 401 Unauthorized |
| 503 Service unavailable |
In case the team is not created in a quorum or if the team is partially created, an alert is posted.
Example of an alert for a team partially created
Team partially created: [Successes: 192.168.1.1, 192.168.1.2], [Failures: 192.168.1.3]
The alert does not include the error description, however, the error description is added to the log files. Review the log files to get the cause of the partial team creation.
Example of an alert for a team creation that failed in a quorum
Team could not be created on a quorum
If a team cannot be created in a quorum, delete the team and create it again.
Error log for team configuration
| Log message | Description |
|---|---|
| Build version not consistent on all the systems. | Not all systems on the team have the same controller build version. Update the team as needed to have the same build version. |
| Invalid configuration. | The team configuration JSON is not valid. |
| Local member must be part of the team configuration. | If the members list from the JSON configuration does not include the system where the team is being created (The local system). |
| Team size must be greater than zero. |
HPE VAN SDN Controller 2.5 only supports a team of 3 controllers. |
| A team has already been created. | Teaming is already running on the system. |
| Team could not be created on a quorum. | Team configuration has failed on a majority of systems. For example, a team of three systems has experienced failures on two systems. |
| Team could not be deleted on a quorum. | A team delete has failed on a quorum number of systems. |
| Team not configured on this system. | An attempt has been made on a standalone controller to disband a team. |
Programming team alias ip-address failed. |
See Team alias node. |
Unprogramming team alias ip-address failed. |
See Team alias node. |
| Recovering from Partial Team Creation |
|
| Recovering from Partial Team Deletion | If the team was not successfully disbanded in all controllers, the failed controllers might go to suspended mode because they might not have quorum – they won’t be able to connect to those controllers where the operation was a success. To recover from this failure it is recommended to disband the team on each failed controller so configuration files are removed and so the controllers transition to standalone mode. Or you may need to reinstall the controller. |
Success log
| Message | Description |
|---|---|
| Team created. |
The controller has completed all required steps to configure itself as part of the team. |
| Team created with the following configuration: [Team IP: <team ip>, [Members<member list>]. |
The controller has completed all required steps to configure itself as part of the team. The log entry includes the team configuration provided by the user. |
| Team disbanded. |
The controller has completed all required steps to configure itself as a standalone controller. |
| Programmed Team alias: <team ip>. |
The controller has configured the team IP address as an alias. This results in the election of a leader. |
| Unprogrammed Team alias: <team ip>. |
The controller has removed the team IP address from the list of aliases. This results in the election of a leader. |
Team IP error log
| Message | Description |
|---|---|
| Exception while checking alias: <team ip>, <exception> |
The controller is unable to verify whether the team IP address has been configured as an alias. |
| Team alias: <team ip> already programmed |
Represents an invalid state. The controller is trying to configure the team IP address when it has been already configured. |
| Exception while programming alias: <team ip>, <exception> |
The controller was unable to configure the team IP address as an alias. |
| Exception while unprogramming alias: <team ip>, <exception> |
The controller was unable to remove the team IP address from the aliases. |
An IP Address (North-Bound IP) alias is created on the node that is elected as team leader to allow a controller team to be accessible with a single IP Address no matter which controller is the leader. This IP Address is provided as part of the team configuration when creating a team. If the elected node stops being the team leader, the team IP Address must be removed from the interface because this address must be reassigned to the actual team leader. This must be done as the sdn user. If assigning or removing an alias fails, one of the following messages appears in the Alert log:
In either of these instances, the condition is logged and the team continues to operate. In this case you can manually program the team alias.
You can configure the alias as follows:
sudo ifconfig <alias interface> <alias IP> netmask <net mask address> up
Example command
sudo ifconfig eth0:0 192.0.123.5 netmask 255.255.255.0 up
You can disable the alias as follows:
sudo ifconfig <alias interface> <alias IP> netmask <net mask address> down
Example command
sudo ifconfig eth0:0 192.0.123.5 netmask 255.255.255.0 down
Some applications may choose to use the Cassandra database to store persistent data. For these applications, there is an extra maintenance step that you must run once every ten days to help maintain the performance of the database and the consistency across the team, as follows:
-
You need to make sure all controllers are up and Cassandra is running:
/opt/sdn/cassandra/bin/nodetool ring |grep -c 'Up'
This command must return 3.
-
Login to each controller in sequence and run the following command. The command must be run as the
sdnuser./opt/sdn/cassandra/bin/nodetool repair
NOTE:
Do not attempt to run this command at the same time on different controllers. It must run to completion on one controller before you run it on another controller. This command may have a significant impact on disk and network I/O across all controllers in the team and it may take some time. You should run this command during a low usage window.
Disbanding a team returns the teamed controllers to standalone operation. This action initiates the team delete. The REST call might return before the delete has completed. You must check the system to see the running state of the system.
-
Before disbanding a team, delete the region configuration for that team.
-
Acquire an authentication token for the team leader. (See step 4 of Prerequisites.)
-
Using the token acquired in the step 2, disband the team:
curl --noproxy
team-ip--header "X-Auth-Token:auth_token" --fail -ksSfL --request DELETE --url https://member-ip:8443/sdn/v2.0/teamThe deletion of the team can take up to 4 minutes to complete. Increase the read timeout for the client request accordingly.
-
In order for the controller to be fully operational in standalone after a team is disbanded, you must completely re-install the controller on each node.
Since team deletion is asynchronous, the response is always 202 unless there is a problem configuring the local controller as standalone. Possible codes are:
| 202 Accepted |
| 400 Bad request |
| 401 Unauthorized |
| 503 Service unavailable |
If you get a returned error of 500, it might be that all regions have not been removed.
In case the team is not deleted in a quorum or if the team is partially deleted, an alert is posted.
Example of an alert for a team partially deleted
Team partially deleted: [Successes: 192.168.1.1, 192.168.1.2], [Failures: 192.168.1.3]
The alert does not include the error description, however, the error description is added to the log files. Review the log files to get the cause of the partial team deletion.
To recover from this failure, Hewlett Packard Enterprise recommends that you delete the team on each failed controller which will remove the configuration files and transition the controllers to standalone mode.
Example of an alert for a team deletion that failed in a quorum
Team could not be deleted on a quorum
If a team cannot be deleted in a quorum, delete the failed controllers individually.
To view your team configuration, do as follows:
-
Acquire an authentication token for the team leader. (See step 4 of Prerequisites.)
-
Using the token acquired in Step 1, view the team configuration as follows:
curl --noproxy team-ip --header "X-Auth-Token:auth_token" --fail -ksSfL --request GET --url https://team-ip:8443/sdn/v2.0/team
Example command
curl --noproxy 192.0.2.100 --header "X-Auth-Token:<auth_token>" --fail -ksSfL --request GET --url https://192.0.2.100:8443/sdn/v2.0/team
Example response
{ "team": { "ip": "192.0.2.100", "revision":0 "members": [ { "ip": "192.0.2.119" }, { "ip": "192.0.2.125" }, { "ip": "192.0.2.127" } ] } }
To support High Availability (HA) for controllers to OpenFlow switches, create region configurations in the controllers using the REST APIs provided by the Device Owner Service.
A region groups devices together with their controllers. Every region has a unique identifier (UID) assigned upon creation. Some REST commands will require that UID to manage the region. A region must have three controllers which must be specified in priority order for all devices within the region (master, primary slave, secondary slave). Devices in a region can be expressed as a list of individual IPv4 addresses, a list of IPv4 ranges, or a combination of both.
The Device Owner Service provides high availability between devices and controllers and ensures the availability of a controller to the devices. The Device Owner Service also provides a measure of security; only devices explicitly included in a region can connect to the region’s controllers; thus if no regions are defined for the teamed controllers, then no devices will be able to connect to the controllers.
Putting the region configurations in place for a controller team ensures seamless failover and failback among the configured controllers for the specified network devices in a region. That is, when a controller experiences a fault, the Device Owner Service ensures that a slave controller immediately assumes the master role over the group of network devices for which the failed controller was master. Once the failed controller recovers and rejoins the team, the Device Owner Service ensures restoration of this controller’s role; that is, the rejoining controller takes back the role for which it was configured with respect to the other network devices. If the controller was configured to operate as the master in a region, then it would be restored to the master role. If it was configured to operate in the slave role, it would resume operation in the slave role.
Once the region definition(s) are in place, the Device Owner Service ensures that a master controller is always available to the respective network element(s) even if the configured master fails or there is a disruption of the communication channel between the controller and the network device(s).
Regions in standalone environments
In a standalone environment, regions are not enforced, and devices are owned by the standalone controller.
Regions in teamed environments
In a teamed environment, assigning devices and controllers to regions can ensure controller availability to devices when one of the following situations occur:
Each region is configured with a prioritized list of controllers, which are used by the Device Owner Service to assign specific roles to each controller:
Device Owner Service triggers the failover operation in two cases:
-
Controller failure: The Device Owner Service detects a controller failure in a team through notifications from the teaming subsystem. If Device Owner Service determines that the failed controller instance was a master for any devices within a region, it immediately elects an appropriate backup (slave) controller to assume the master role over the affected devices.
-
Device disconnect: The Device Owner Service instance in a controller is notified of a communication failure with network device(s) through the Controller Service notifications. It instantly communicates with all Device Owner Service instances in the team to determine if the network device(s) in question are still connected to any of the backup (slave) controllers within the team. If that is the case, it elects one of the slaves to assume the master role over the affected network device(s).
The first slave will be chosen as master if it still has connectivity with the device(s), and the second slave will be chosen as master if neither the configured master or first slave have connectivity with the device(s).
In this example, the master controller 172.17.6.70 fails. Although it is still in the region, it is unavailable to the devices for which it is the configured master and is no longer the master controller. The primary slave controller 172.17.6.71 becomes the master controller. All 5 devices 192.168.1.101–105 now belong to the failover master controller 172.17.6.71.
Example command
curl --noproxyteamIp--header "X-Auth-Token:token" -ksS --request GET --url https://teamIp:8443/sdn/v2.0/owners/region-uid/state?dataPathDetails=yes
Example output
{
"regions":[
{
"uid":"713def9a-4f96-485f-990c-8924bc06c8d8",
"name":"Region-Red",
"prioritizedControllerIps":[
"172.17.6.70",
"172.17.6.71",
"172.17.6.72"
],
"devices":[
{
"deviceIp":"192.168.1.101",
"owningControllerIp":"172.17.6.71",
"dataPaths":[
{
"dpid":"00:01:44:31:92:5c:af:86",
"owningControllerIp":"172.17.6.71"
}
]
},
{
"deviceIp":"192.168.1.102",
"owningControllerIp":"172.17.6.71",
"dataPaths":[
{
"dpid":"00:1e:c8:cb:b8:dd:f0:c0",
"owningControllerIp":"172.17.6.71"
}
]
},
{
"deviceIp":"192.168.1.103",
"owningControllerIp":"172.17.6.71",
"dataPaths":[
{
"dpid":"00:1e:f0:92:1c:21:af:00",
"owningControllerIp":"172.17.6.71"
}
]
},
{
"deviceIp":"192.168.1.104",
"owningControllerIp":"172.17.6.71",
"dataPaths":[
{
"dpid":"00:01:cc:3e:5f:6b:19:00",
"owningControllerIp":"172.17.6.71"
}
]
},
{
"deviceIp":"192.168.1.105",
"owningControllerIp":"172.17.6.71",
"dataPaths":[
{
"dpid":"00:1e:00:9c:02:e0:e4:00",
"owningControllerIp":"172.17.6.71"
}
]
}
]
}
]
}
When the configured master recovers from a failure and rejoins the team, or when the connection from the disconnected device(s) with the original master is resumed, Device Owner Service initiates a failback operation in which the master role is restored to the configured master as defined in the region definition.
In this example, the configured master controller 172.17.6.70 recovers from failure and is active again. The controller 172.17.6.71 returns back to being a primary slave and all 5 devices 192.168.1.101–105 belong to the configured master controller 172.17.6.70.
Example command
curl --noproxyteamIp--header "X-Auth-Token:token" -ksS --request GET --url https:// teamIp>:8443/sdn/v2.0/owners/region-uid/state?dataPathDetails=yes
Example output
{
"regions":[
{
"uid":"713def9a-4f96-485f-990c-8924bc06c8d8",
"name":"Region-Red",
"prioritizedControllerIps":[
"172.17.6.70",
"172.17.6.71",
"172.17.6.72"
],
"devices":[
{
"deviceIp":"192.168.1.101",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:01:44:31:92:5c:af:86",
"owningControllerIp":"172.17.6.70"
}
]
},
{
"deviceIp":"192.168.1.102",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:1e:c8:cb:b8:dd:f0:c0",
"owningControllerIp":"172.17.6.70"
}
]
},
{
"deviceIp":"192.168.1.103",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:1e:f0:92:1c:21:af:00",
"owningControllerIp":"172.17.6.70"
}
]
},
{
"deviceIp":"192.168.1.104",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:01:cc:3e:5f:6b:19:00",
"owningControllerIp":"172.17.6.70"
}
]
},
{
"deviceIp":"192.168.1.105",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:1e:00:9c:02:e0:e4:00",
"owningControllerIp":"172.17.6.70"
}
]
}
]
}
]
}
This POST command adds a region to those configured on the controller and propagates the modifications to each controller in the team. All controllers configured for the team must be available for such a configuration change to be permitted.
In this example, we are adding a region with UID 713def9a-4f96-485f-990c-8924bc06c8d8 that has three controllers: 172.17.6.70 (master), 172.17.6.71 (primary slave), 172.17.6.72 (secondary slave). Two devices are part of the region: 192.168.1.101 and 192.168.1.10. The devices IP range includes 192.168.1.103, 192.168.1.104, 192.168.1.105
Example command
curl --noproxycontrollerIp--header "X-Auth-Token:token" --header "Content-Type:application/json" -ksS --request POST --url https://controllerIp:8443/sdn/v2.0/owners --data-binary '{"region": {"name": "Region-Red", "prioritizedControllerIps": ["172.17.6.70", "172.17.6.71", "172.17.6.72"], "deviceIps":["192.168.1.101", "192.168.1.102"],"deviceIpRanges": ["192.168.1.103-105"]}}'
Example output
{
"region":{
"uid":"713def9a-4f96-485f-990c-8924bc06c8d8",
"name":"Region-Red",
"prioritizedControllerIps":[
"172.17.6.70",
"172.17.6.71",
"172.17.6.72"
],
"deviceIps":[
"192.168.1.101",
"192.168.1.102"
],
"deviceIpRanges":[
"192.168.1.103-105"
]
}
}
If deviceIps or deviceIpRanges are not in numeric order, they are reordered in the response and in subsequent GET calls of the configuration.
This POST command adds a device with the specified IP address to the region with the specified UID and propagates the modifications to each controller in the team. A deviceIp query parameter must be specified. You can only add one IP address at a time in order to know which device IP address is involved when an error condition is encountered. The new device IP address will be added to the deviceIps list, unless it already appeared in the deviceIps list or was encompassed by one of the ranges listed among the deviceIpRanges, in which case no change will be made. All controllers configured for the team must be available for such a configuration change to be permitted.
In this example, for region UID 713def9a-4f96-485f-990c-8924bc06c8d8, device 192.168.1.103 is added to the region.
Example command
curl --noproxyteamIp--header "X-Auth-Token:token" -ksS --request POST --url https://teamIp:8443/sdn/v2.0/owners/region_uid/devices?deviceIp=192.168.1.103
Example output
{"result":"Device IP address 192.168.1.103 now exists in the region with UID '713def9a-4f96-485f-990c-8924bc06c8d8'"}
To check if your device was added to the region, check the Team screen in the controller UI or see Getting the configuration of a specific region using curl.
This GET command retrieves the configuration of all regions. The regions configuration may have been modified since controller startup to reflect the dynamic addition or removal of regions or devices within specific regions.
In this example, there were no changes since controller startup and the configuration is the same is in Adding a region using curl.
Example command
curl --noproxyteamIp--header "X-Auth-Token:token" -ksS --request GET --url https://teamIp:8443/sdn/v2.0/owners
Example output
{
"regions":[
{
"uid":"713def9a-4f96-485f-990c-8924bc06c8d8",
"name":"Region-Red",
"prioritizedControllerIps":[
"172.17.6.70",
"172.17.6.71",
"172.17.6.72"
],
"deviceIps":[
"192.168.1.101",
"192.168.1.102"
],
"deviceIpRanges":[
"192.168.1.103-105"
]
}
]
}
This GET command retrieves the configuration of the specified region. The regions configuration may have been modified since controller startup to reflect the dynamic addition or removal of regions or devices within specific regions.
In this example, there were no changes to the region of interest since controller startup and the configuration is the same is in Adding a region using curl.
Example command
curl --noproxyteamIp--header "X-Auth-Token:token" -ksS --request GET --url https://teamIp:8443/sdn/v2.0/owners/region_uid
Example output
{
"region":{
"uid":"713def9a-4f96-485f-990c-8924bc06c8d8",
"name":"Region-Red",
"prioritizedControllerIps":[
"172.17.6.70",
"172.17.6.71",
"172.17.6.72"
],
"deviceIps":[
"192.168.1.101",
"192.168.1.102"
],
"deviceIpRanges":[
"192.168.1.103-105"
]
}
}
This HEAD command returns a status (essentially a Boolean value) indicating whether the local controller owns the device corresponding to the specified IP address; this is decided based on the controller's locally cached data, which is guaranteed to be consistent with the receipt of DeviceOwnerEvents events. You must specify the deviceIp query parameter. The command returns one of the following status:
-
204: The local controller owns the device. -
404: The local controller does not own the device.
Example command
curl --noproxycontrollerIp-X HEAD --header "X-Auth-Token:token" -IL --insecure --url https://controllerIp:8443/sdn/v2.0/owners?deviceIp=192.168.1.102
Example output
HTTP/1.1 204 No Content Server: Apache-Coyote/1.1 X-FRAME-OPTIONS: deny Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, PUT, HEAD, PATCH Access-Control-Allow-Headers: Content-Type, Accept, X-Auth-Token Date: Wed, 11 Mar 2015 18:34:07 GMT
This GET command retrieves the devices in the region with the specified UID that the specified controller currently owns. You can use an optional controllerIp parameter to specify the controller IP address of interest; if no such address is specified, the local controller IP is used.
In this example, for region UID 713def9a-4f96-485f-990c-8924bc06c8d8 and controller 172.17.6.70 (master), the devices are 192.168.1.101, 192.168.1.102, 192.168.1.103, 192.168.1.104, and 192.168.1.105.
Regardless of how many IPs are configured for the devices in the region, this GET command indicates only those that are actually active and owned by the specified controller.
Example command
curl --noproxycontrollerIp--header "X-Auth-Token:token" -ksS --request GET --url https://controllerIp>:8443/sdn/v2.0/owners/region_uid/devices
Example output
{
"ownership":{
"uid":"713def9a-4f96-485f-990c-8924bc06c8d8",
"name":"Region-Red",
"owningControllerIp":"172.17.6.70",
"devices":[
{
"deviceIp":"192.168.1.101"
},
{
"deviceIp":"192.168.1.102"
},
{
"deviceIp":"192.168.1.103"
},
{
"deviceIp":"192.168.1.104"
},
{
"deviceIp":"192.168.1.105"
}
]
}
}
This GET command retrieves the current status of the region with the specified UID, including its configured devices and the controller that currently owns each device.
In this example, for region UID 713def9a-4f96-485f-990c-8924bc06c8d8, the command output shows the status of all the devices, including their datapaths. In this example all devices are owned by the master controller 172.17.6.70.
Example command
curl --noproxyteamIp--header "X-Auth-Token:token" -ksS --request GET --url https://teamIp:8443/sdn/v2.0/owners/region_uid/state?dataPathDetails=yes
Example output
{
"regions":[
{
"uid":"713def9a-4f96-485f-990c-8924bc06c8d8",
"name":"Region-Red",
"prioritizedControllerIps":[
"172.17.6.70",
"172.17.6.71",
"172.17.6.72"
],
"devices":[
{
"deviceIp":"192.168.1.101",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:01:44:31:92:5c:af:86",
"owningControllerIp":"172.17.6.70"
}
]
},
{
"deviceIp":"192.168.1.102",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:1e:c8:cb:b8:dd:f0:c0",
"owningControllerIp":"172.17.6.70"
}
]
},
{
"deviceIp":"192.168.1.103",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:1e:f0:92:1c:21:af:00",
"owningControllerIp":"172.17.6.70"
}
]
},
{
"deviceIp":"192.168.1.104",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:01:cc:3e:5f:6b:19:00",
"owningControllerIp":"172.17.6.70"
}
]
},
{
"deviceIp":"192.168.1.105",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:1e:00:9c:02:e0:e4:00",
"owningControllerIp":"172.17.6.70"
}
]
}
]
}
]
}
This GET command retrieves the current status of all regions, including their configured devices and the controller that currently owns each device. You can filter the returned content of this command in order to get the current status for a specified device, allowing you to determine which region the device is configured in addition to which controller owns the device.
You can also specify the optional dataPathDetails parameter to enhance the output for devices to include DPID information consisting of each DPID associated with the device and the controller that currently owns each DPID. You can specify this parameter independently of the deviceIp parameter, and the resulting output is similar to that when the optional dataPathDetails parameter is specified for the GET /owners/{region_uid}/state command.
In this example, there is only one region therefore, the command output is the same as the Getting the status of a specific region using curl.
Example command
curl --noproxyteamIp--header "X -Auth-Token:token" -ksS --request GET --url https://teamIp:8443/sdn/v2.0/owners/state?dataPathDetails=yes
Example output
{
"regions":[
{
"uid":"713def9a-4f96-485f-990c-8924bc06c8d8",
"name":"Region-Red",
"prioritizedControllerIps":[
"172.17.6.70",
"172.17.6.71",
"172.17.6.72"
],
"devices":[
{
"deviceIp":"192.168.1.101",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:01:44:31:92:5c:af:86",
"owningControllerIp":"172.17.6.70"
}
]
},
{
"deviceIp":"192.168.1.102",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:1e:c8:cb:b8:dd:f0:c0",
"owningControllerIp":"172.17.6.70"
}
]
},
{
"deviceIp":"192.168.1.103",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:1e:f0:92:1c:21:af:00",
"owningControllerIp":"172.17.6.70"
}
]
},
{
"deviceIp":"192.168.1.104",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:01:cc:3e:5f:6b:19:00",
"owningControllerIp":"172.17.6.70"
}
]
},
{
"deviceIp":"192.168.1.105",
"owningControllerIp":"172.17.6.70",
"dataPaths":[
{
"dpid":"00:1e:00:9c:02:e0:e4:00",
"owningControllerIp":"172.17.6.70"
}
]
}
]
}
]
}
This DELETE command removes a device with the specified IP address from the region with the specified UID and propagates the modifications to each controller in the team. A deviceIp query parameter must be specified. You can only remove one IP address at a time in order to know which device IP address is involved when an error condition is encountered. If the deleted IP address appears among the deviceIps addresses, it will be removed from the list of IPs, and if the deleted IP address was encompassed by one of the ranges listed among the deviceIpRanges, the range will be transformed into one or more ranges and/or individual IP addresses to reflect the removal of the deleted device IP address and the original range will be removed. All controllers configured for the team must be available for such a configuration change to be permitted.
In this example, for region UID 713def9a-4f96-485f-990c-8924bc06c8d8, device 192.168.1.103 is removed.
Example command
curl --noproxyteamIp--header "X-Auth-Token:token" -ksS --request DELETE --url https://teamIp:8443/sdn/v2.0/owners/region_uid/devices?deviceIp=192.168.1.103
Example output
{"result":"Device IP address 192.168.1.103 no longer exists in the region with UID '713def9a-4f96-485f-990c-8924bc06c8d8'"}
To check if your device was removed from the region, check the Team screen in the controller UI or see Getting the configuration of a specific region using curl.
This DELETE command removes the region with the specified UID and propagates the modifications to each controller in the team. All controllers configured for the team must be available for such a configuration change to be permitted.
In this example, region UID 713def9a-4f96-485f-990c-8924bc06c8d8 is deleted. Since only one region was configured, there are no regions configured for the team at this point. Therefore, no devices will be allowed to connect to the team until a new region is defined that encompasses the desired devices.
Example command
curl --noproxyteamIp--header "X-Auth-Token:token" -ksS --request DELETE --url https://teamIp:8443/sdn/v2.0/owners/region_uid
Example output
{"result":"Region with UID 713def9a-4f96-485f-990c-8924bc06c8d8 no longer exists"}