Pure commitment. how to change IPsec VPN settings via the vcloud Director API version 3.0
Contents Overview... 3 Obtaining your vcloud API credentials... 3 Installing a REST client... 4 Obtaining an authorisation token... 7 Retrieving organisation details via the API... 12 Retrieving virtual data centre details via the API... 14 Retrieving edge gateway configuration via the API... 15 Reviewing the edge gateway configuration... 17 Locating the IPsec VPN settings in the returned XML... 19 Modifying the IPsec VPN configuration... 20 Modifying the local endpoint IP and local ID... 20 Modifying the peer endpoint IP and peer ID... 20 Adding or removing local subnets... 21 Adding or removing peer subnets... 21 Amending the shared secret... 22 Applying the new configuration... 22 What s next?... 24 Feedback... 24 UKCloud Ltd, 2017 Open Page 2 of 25
Overview This guide covers the installation and basic usage of a Firefox plugin called REST Client. Using this plugin, you can to retrieve, modify, and submit blocks of XML that represent the configuration of the IPsec VPN tunnels. The guide covers modifications to the local and peer IP addresses, local and peer IDs as well the addition or removal of local and peer subnets. In addition to this, the guide also outlines the steps required to modify the shared secret key used on a given IPsec VPN tunnel. Use cases: Enabling customers to quickly amend IPsec configurations Modifications of this nature are not possible in the vcloud Director graphical user interface without first deleting the existing IPsec VPN configuration entirely and reentering the settings. Depending on the number of tunnels, this can be a lengthy task. Making changes to the IPsec VPN configuration via the vcloud Director API can greatly speed up this process. Edge gateway configuration data You can also use the steps in this guide to obtain a backup of the current configuration applied to an edge gateway. You can then use this to restore the configuration of the edge gateway at a later point in time. By following the instructions in this guide you can make amendments to the IPsec VPN configuration without first needing to engage with UKCloud Support. Obtaining your vcloud API credentials Before using the vcloud API, you first need to find your API credentials. 1. Log in to the UKCloud Portal. If you need more detailed instructions, see the Getting Started Guide for UKCloud Portal (Assured Elevated). 2. Select your account. 3. In the top right corner of the page, click your username and then select API. UKCloud Ltd, 2017 Open Page 3 of 25
4. The API page provides a view of your personal credentials for accessing the vcloud API. In particular, the page provides the following: Compute service ID (in parentheses after the compute service name) to uniquely identify the compute service (or vorg) when using the vcloud API. API URL use this URL at the beginning of your calls to the vcloud API. Note! This URL will be different depending on the region in which your compute service is locate. Username your user ID to authenticate yourself with the vcloud API. Note! The compute service ID is appended to the end of the username. This is because you may have access to multiple compute services. Password for authentication with the vcloud API. This password is the same as the one you use to log in to the UKCloud Portal. 5. Make a note of the compute service ID, the API URL and your Username. Installing a REST client Having reviewed the information of the API page in the Portal, you now need to install a REST client within your internet browser. Note! This guide covers the installation of the REST Client plugin under Mozilla Firefox. The installation and configuration of REST clients for other browsers is outside the scope of this guide. To install the REST Client plugin: 1. Browse to the following URL: https://addons.mozilla.org/en-us/firefox/ 2. In the search box in the upper right-hand corner of the ADD-ONS page enter the words Rest Client and click on the white arrow. UKCloud Ltd, 2017 Open Page 4 of 25
3. When presented with the search the results, hover over the entry called RESTClient, a debugger for RESTful web services. A green button will appear that reads Add to Firefox, click this button. 4. This will start the downloading the REST Client in the background, after a short amount of time a window will be displayed (see below). When the download has completed click the Install Now button. UKCloud Ltd, 2017 Open Page 5 of 25
5. To complete the installation you ll need to restart Firefox (see below): 6. Once restarted, you should see the icon for the REST Client towards the upper right-hand corner of the Firefox window. Click the REST Client icon. 7. After clicking on the REST Client icon you should be presented with a screen similar to the one shown below: UKCloud Ltd, 2017 Open Page 6 of 25
Obtaining an authorisation token Having installed the REST Client plugin for Firefox, you can start interacting with the vcloud API. You first need to obtain an x-vcloud-authorization token; to do this you need to adjust some settings on the REST Client. 1. Click the Method drop down menu and select POST. 2. In the API field, enter the API URL you recorded earlier and append the following to the end of the URL: /api/sessions. UKCloud Ltd, 2017 Open Page 7 of 25
3. Next add a Basic Authentication header, to do this click the Authentication menu at the top of the REST Client and select Basic Authentication. 4. After selecting Basic Authentication a new window is displayed prompting for a username and password. In the Username field, enter your API username recorded earlier from the API page. In this example the username will be as follows: 999.9.FFFFFF@9-9-9-FFFFFF. In the Password field enter your UKCloud Portal password and then click Okay. UKCloud Ltd, 2017 Open Page 8 of 25
5. The Headers section should now be displayed in the REST Client containing an Authorization header. 6. Next add an Accept header to the REST Client. To do this click the Headers menu and select Custom Header. 7. In the Request Header window enter the word Accept in the Name field. In the Value field enter application/*+xml;version=5.5 and then click Okay. UKCloud Ltd, 2017 Open Page 9 of 25
8. A second header should now be visible in the REST Client. 9. The REST Client has now got all the required settings in place to make a request to the vcloud API to obtain a x-vcloud-authorization token, so click the SEND button. You ll see the following screen until a response is received from the vcloud API: UKCloud Ltd, 2017 Open Page 10 of 25
10. When a response is received the Response Headers section will be populated, the response should contain an x-vcloud-authorization token. 11. The x-vcloud-authorization token will replace the Basic Authentication header added earlier. To do this highlight and copy the string of characters displayed after the word x-vcloud-authorization. (as highlighted in the image above). Note! If at any point while following the instructions in this guide, the output displayed in the REST Client does not look similar to that shown in the images, you can use the value of the Status Code field to determine what went wrong and needs investigation. In this case above, Status Code received was HTTP 200 OK, which means that the request succeeded. For a list of HTTP response codes, see HTTP Response Codes. 12. To add an x-vcloud-authorization header to the REST Client, click the Headers menu and select Custom Header. The Request Header window displays. In the Name field enter x-vcloud-authorization. In the Value field, paste the string of characters copied in the previous step, then click Okay. UKCloud Ltd, 2017 Open Page 11 of 25
Retrieving organisation details via the API Now that you ve obtained an x-vcloud-authorization token, you can remove the Basic Authentication Header. 1. Click the x in the upper right-hand corner of the header. 2. Set the Method to GET using the drop down menu. UKCloud Ltd, 2017 Open Page 12 of 25
3. Next select the Response Body (Preview) tab towards the bottom of the REST Client. This view lists the links that you can use to drill down into the various objects exposed via the vcloud API. Of interest in the output below is a link that will, when queried, return details about the organisation and the objects contained within it. Clicking the URL will automatically update the contents of the URL box towards the top of the REST Client. 4. Verify that the URL has been updated and no longer reads https://api_url/api/sessions. Instead the contents of the URL field should contain https://api_url/api/org/ followed by the unique identifier of your organisation as displayed in the output from the previous step. 5. Ensure that the Method drop down is set to GET and click SEND. After a short amount of time the contents of the Response Body (Preview) window will be updated to reflect the response from the vcloud API to your latest request. UKCloud Ltd, 2017 Open Page 13 of 25
Retrieving virtual data centre details via the API In our example, the organisation object contains two virtual data centres (VDCs). In the response from the vcloud API shown below there are two links, one for each of the VDCs. These have been highlighted in a green rectangle. To retrieve details about the VDCs in an organisation: 1. Click the link for the VDC containing the target edge gateway. This will update the URL field towards the top of the REST Client. In our example, the target edge gateway is located in the UKCloud IPSEC VPN Demo (IL0-PROD-BASIC) VDC, so select the first link. UKCloud Ltd, 2017 Open Page 14 of 25
2. Verify that the URL displayed at the top of the REST Client has been updated; the URL should now read as follows https://api_url/api/vdc/. Appended to the end of the URL will be the unique identifier for the selected VDC. If this is the case click SEND. Retrieving edge gateway configuration via the API The contents of the Response Body (Preview) tab will be updated once more. 1. The response this time will probably be quite long. To easily locate a specific section in the response, use your browser s search utility. You can invoke this in Firefox by pressing CTRL+F. In the search dialog window at the bottom of the screen enter edgegateways, and then click the down arrow button to locate a section that looks similar to the one shown in the screenshot below: UKCloud Ltd, 2017 Open Page 15 of 25
2. Click the link ending in /edgegateways and verify that the URL displayed at the top of the REST Client has been updated to match. Ensure that the Method drop down is set to GET and click SEND. If this request is successful, the response will contain a link to the edge gateway which, when queried, will return the configuration of the edge gateway. Once you have received a response, use your browser s search utility to locate the EdgeGatewayRecord section within the response. UKCloud Ltd, 2017 Open Page 16 of 25
3. Within the EdgeGatewayRecord section of the above from the response, locate the link to the edge gateway that starts with the following: https://api_url/api/admin/edgegateway/ 4. Appended to the end of the URL will be a unique identifier for the edge gateway within the VDC. Click this link and verify that the URL displayed in the URL field has been updated accordingly and then click SEND. Reviewing the edge gateway configuration After a short amount of time the current configuration of the edge gateway will be displayed in a block of XML. This configuration information is contained between an opening <Configuration> and closing </Configuration> tag. This block of XML is split into sections which detail the configuration settings applied to a specific item, function or service available on the edge gateway. There are twelve sections in total; however only the configuration settings contained under the <GatewayIpsecVpnService> tags will be discussed in this guide. The example below shows a high-level overview of the structure of the XML block returned, with the opening and closing <GatewayIpsecVpnService> tags highlighted. UKCloud Ltd, 2017 Open Page 17 of 25
<EdgeGateway> <Configuration> <GatewayBackingConfig> </GatewayBackingConfig> <GatewayInterfaces> </GatewayInterfaces> <EdgeGatewayServiceConfiguration> <FirewallService> </FirewallService> <NatService> </NatService> <GatewayIpsecVpnService> </GatewayIpsecVpnService> <StaticRoutingService> </StaticRoutingService> <LoadBalancerService> </LoadBalancerService> </EdgeGatewayServiceConfiguration> <HaEnabled> </HaEnabled> <UseDefaultRouteForDnsRelay> </UseDefaultRouteForDnsRelay> </Configuration> </EdgeGateway> Before making any changes to the edge gateway via the API it is highly recommended to keep a copy of the XML returned. You can then use this backup to restore the configuration of the edge gateway to a known working configuration if the need arises. To copy the XML: 1. Select the Response Body (Highlight) tab of the REST Client. 2. Scroll down to the opening <Configuration> tag and highlight everything up to and including the closing <\Configuration> tag. The length of the XML to copy is dependent on the number of NAT, firewall rules and another configuration applied to the edge gateway. 3. With the contents of the <Configuration> tags highlighted, right click and select Copy. 4. Paste the configuration into a text editor, saving the file to a known location on your computer. Using a text editor that offers syntax highlighting such as Notepad++ will simplify the editing process. UKCloud Ltd, 2017 Open Page 18 of 25
Locating the IPsec VPN settings in the returned XML To locate the IPsec VPN settings, open a new text editor window and copy and paste the contents between the opening <GatewayIpsecVpnService> and closing </GatewayIpsecVpnService> tags. The contents should look similar to the XML block shown below: <GatewayIpsecVpnService> <IsEnabled>true</IsEnabled> <Endpoint> <Network type="application/vnd.vmware.admin.network+xml" href="https://api.vcd.portal.ukcloud.com/api/admin/network/ 3c284ec8-2850- ba77-098c-7f697a3d8769"/> <PublicIp>37.26.88.73</PublicIp> </Endpoint> <Tunnel> <Name>UKCloud IPSEC VPN Demo</Name> <Description/> <IpsecVpnThirdPartyPeer> <PeerId>134.170.188.221</PeerId> </IpsecVpnThirdPartyPeer> <PeerIpAddress>134.170.188.221</PeerIpAddress> <PeerId>134.170.188.221</PeerId> <LocalIpAddress>172.26.45.97</LocalIpAddress> <LocalId>172.26.45.97</LocalId> <LocalSubnet> <Name>VPN Test Network 1</Name> <Gateway>192.168.1.254</Gateway> <Netmask>255.255.255.0</Netmask> </LocalSubnet> <PeerSubnet> <Name>192.168.2.0/24</Name> <Gateway>192.168.2.254</Gateway> <Netmask>255.255.255.0</Netmask> </PeerSubnet> <SharedSecret>UKCloudIPSECVPNDemoSharedSecretKey</SharedSecret> <SharedSecretEncrypted>false</SharedSecretEncrypted> <EncryptionProtocol>AES256</EncryptionProtocol> <Mtu>1500</Mtu> <IsEnabled>true</IsEnabled> <IsOperational>true</IsOperational> </Tunnel> </GatewayIpsecVpnService> UKCloud Ltd, 2017 Open Page 19 of 25
Modifying the IPsec VPN configuration This section outlines common tasks performed via the API to manipulate the IPsec VPN configuration applied to a given edge gateway. Modifying the local endpoint IP and local ID You can change the local IP and local ID by editing the contents between the opening <localipaddress> and closing </localipaddress> and <localid> and </localid> tags as shown below: Original: <LocalIpAddress>172.26.45.97</LocalIpAddress> <LocalId>172.26.45.97</LocalId> Modified: <LocalIpAddress>37.26.88.73</LocalIpAddress> <LocalId>37.26.88.73</LocalId> This is by far the most commonly performed modification to the IPsec VPN configuration via the vcloud API. You can use this to change the local IP address from the IP address assigned to the edge gateway on the transit network to the IP address assigned to the edge gateways on the public network. For the tunnel to come up successfully the local IP address must be set to the edge gateway s public IP address. The local ID must also match the public IP address specified. Modifying the peer endpoint IP and peer ID If you need to move the remote endpoint of the tunnel to a new device or IP address, then you can adjust the following as required: Original: <PeerIpAddress>134.170.188.221</PeerIpAddress> <PeerId>134.170.188.221</PeerId> Modified: <PeerIpAddress>212.58.244.18</PeerIpAddress> <PeerId>212.58.244.18</PeerId> When changing the peer IP address of the tunnel you must ensure that the peer ID is also updated to match the new peer IP address. UKCloud Ltd, 2017 Open Page 20 of 25
Adding or removing local subnets You can add additional local subnets to the IPsec VPN tunnel. This involves adding a new local subnet definition to the IPsec VPN config: Original: <LocalSubnet> <Name>VPN Test Network</Name> <Gateway>192.168.1.254</Gateway> <Netmask>255.255.255.0</Netmask> </LocalSubnet> Modified: <LocalSubnet> <Name>VPN Test Network 1</Name> <Gateway>192.168.1.254</Gateway> <Netmask>255.255.255.0</Netmask> </LocalSubnet> <LocalSubnet> <Name>VPN Test Network 2</Name> <Gateway>192.168.3.254</Gateway> <Netmask>255.255.255.0</Netmask> </LocalSubnet> Adding or removing peer subnets You can use the same process to add or remove peer subnets: Orginal: <PeerSubnet> <Name>192.168.2.0/24</Name> <Gateway>192.168.2.254</Gateway> <Netmask>255.255.255.0</Netmask> </PeerSubnet> Modified: <PeerSubnet> <Name>192.168.2.0/24</Name> <Gateway>192.168.2.254</Gateway> <Netmask>255.255.255.0</Netmask> </PeerSubnet> <PeerSubnet> <Name>192.168.4.0/24</Name> <Gateway>192.168.4.254</Gateway> <Netmask>255.255.255.0</Netmask> </PeerSubnet> UKCloud Ltd, 2017 Open Page 21 of 25
Amending the shared secret If you need to update or amend the shared secret on an IPsec VPN, edit the value between the opening <SharedSecret> and closing </SharedSecret> tags. Original: <SharedSecret>UKCloudIPSECVPNDemoSharedSecretKey</SharedSecret> Modified: <SharedSecret>4dae850771fbe3f06588b49772c0b8eb</SharedSecret> Note! The shared secret must be at least 32 characters in length. To enhance the security of the tunnel, we highly recommend that you avoid using dictionary words in the shared secret key. Applying the new configuration When you ve updated the relevant sections of the configuration, you can apply it to the edge gateway. 1. enclose the new configuration in a pair of <EdgeGatewayServiceConfiguration> tags, as shown in the following example. <?xml version="1.0" encoding="utf-8"?> <EdgeGatewayServiceConfiguration xmlns="http://www.vmware.com/vcloud/v1.5"> <GatewayIpsecVpnService> <IsEnabled>true</IsEnabled> <Endpoint> <Network type="application/vnd.vmware.admin.network+xml" href="https://api.vcd.portal.ukcloud.com/api/admin/network/ 3c284ec8-2850- ba77-098c-7f697a3d8769"/> <PublicIp>37.26.88.73</PublicIp> </Endpoint> <Tunnel> <Name>ukcloud IPSEC VPN Demo</Name> <Description/> <IpsecVpnThirdPartyPeer> <PeerId>212.58.244.18</PeerId> </IpsecVpnThirdPartyPeer> <PeerIpAddress>212.58.244.18</PeerIpAddress> <PeerId>212.58.244.18</PeerId> <LocalIpAddress>37.26.88.73</LocalIpAddress> <LocalId>37.26.88.73</LocalId> <LocalSubnet> <Name>VPN Test Network 1</Name> <Gateway>192.168.1.254</Gateway> <Netmask>255.255.255.0</Netmask> </LocalSubnet> <LocalSubnet> <Name>VPN Test Network 2</Name> <Gateway>192.168.3.254</Gateway> <Netmask>255.255.255.0</Netmask> </LocalSubnet> <PeerSubnet> UKCloud Ltd, 2017 Open Page 22 of 25
<Name>192.168.2.0/24</Name> <Gateway>192.168.2.254</Gateway> <Netmask>255.255.255.0</Netmask> </PeerSubnet> <PeerSubnet> <Name>192.168.4.0/24</Name> <Gateway>192.168.4.254</Gateway> <Netmask>255.255.255.0</Netmask> </PeerSubnet> <SharedSecret>4dae850771fbe3f06588b49772c0b8eb</SharedSecret> <SharedSecretEncrypted>false</SharedSecretEncrypted> <EncryptionProtocol>AES256</EncryptionProtocol> <Mtu>1500</Mtu> <IsEnabled>true</IsEnabled> <IsOperational>true</IsOperational> </Tunnel> </GatewayIpsecVpnService> </EdgeGatewayServiceConfiguration> 2. Copy and paste this configuration into the Body section of the REST Client. 3. Click the Method drop down menu and select POST. 4. Append the following to the URL displayed in the URL box: /action/configureservices In our example, the contents of the URL were: https://api_url/api/admin/edgegateway/48fbb9e-2e90-c055-aa46-86f18766f5b1 So, the updated URL would be: https://api_url/api/admin/edgegateway/48fbb9e-2e90-c055-aa46-86f18766f5b1/action/configureservices 5. You must also add one more Header to the REST Client prior to submitting the new configuration. Click the Headers drop down menu at the top of the REST Client and select Custom Header. 6. In the Name box enter Content-Type. 7. In the Value box enter the following: application/vnd.vmware.admin.edgegatewayserviceconfiguration+xml 8. The REST Client should now look similar to the screenshot below: UKCloud Ltd, 2017 Open Page 23 of 25
9. To submit the new configuration, click SEND. 10. The status of the edge gateway as viewed from vcloud Director will briefly show as Updating Configuration. Once this process has completed, right click the edge gateway and select Configure Services. 11. In the Configure Services window select the VPN tab. 12. You should see the new configuration settings. Verify the status of the IPsec VPN tunnel on your remote device to ensure that the tunnel has been established successfully. What s next? If you need any further assistance, or if you want to discuss any aspect of this service or settings specific to your domain, log a support ticket via the UKCloud Portal. Feedback If you have any comments on this document or any other aspect of your UKCloud experience, please send them to feedback@ukcloud.com. UKCloud Ltd, 2017 Open Page 24 of 25
UKCloud Ltd A8 Cody Technology Park Ively Road, Farnborough Hampshire, GU14 0LX T 01252 303300 E info@ukcloud.com ukcloud.com @ukcloudltd ukcloudltd ukcloud-ltd Reasonable efforts have been made to ensure the accuracy of the information contained in this document. No advice given or statements or recommendations made shall in any circumstances constitute or be deemed to constitute a warranty by UKCloud Ltd as to the accuracy of such advice, statements or recommendations. UKCloud Ltd shall not be liable for any loss, expense, damage or claim howsoever arising out of the advice given or not given or statements made or omitted to be made in connection with this document. No part of this document may be copied, reproduced, adapted or redistributed in any form or by any means without the express prior written consent of UKCloud Ltd. UKCloud Ltd 2017 All Rights Reserved. UKC-GEN-129 06/2017