change IPsec VPN settings via the vCloud Director API€¦ · Pure commitment. how to change IPsec VPN settings via the vCloud Director API version 3.0

Pure commitment.

how to

change IPsec VPN settings via the vCloud

Director API

version 3.0

How to change IPsec VPN settings via the vCloud Director API UKC-GEN-129 • v3.0 © UKCloud Ltd, 2017 Open Page 2 of 25

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


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 re-entering 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.

https://portal.ukcloud.com/support/knowledge_centre/0435318d-a94b-41bb-a4ff-a52adbe863e5

https://portal.ukcloud.gsi.gov.uk/support/knowledge_centre/a561f02f-79bf-495c-94e8-f7c2d52513c0


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.

https://addons.mozilla.org/en-US/firefox/


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.


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:


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.


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.


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.


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:


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.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status


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.


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.


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.


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:


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.


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.


<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.


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:


<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>



</PeerSubnet>

<SharedSecret>UKCloudIPSECVPNDemoSharedSecretKey</SharedSecret>

<SharedSecretEncrypted>false</SharedSecretEncrypted>

<EncryptionProtocol>AES256</EncryptionProtocol>

<Mtu>1500</Mtu>


<IsOperational>true</IsOperational>

</Tunnel>



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:



Modified:



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:


<PeerId>134.170.188.221</PeerId>

Modified:


<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.


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>



</LocalSubnet>

Modified:

<LocalSubnet>




</LocalSubnet>

<LocalSubnet>




</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>



</PeerSubnet>

Modified:

<PeerSubnet>

<Name>192.168.2.0/24</Name>



</PeerSubnet>

<PeerSubnet>

<Name>192.168.4.0/24</Name>



</PeerSubnet>


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">



<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>


</IpsecVpnThirdPartyPeer>





<LocalSubnet>




</LocalSubnet>

<LocalSubnet>




</LocalSubnet>

<PeerSubnet>


<Name>192.168.2.0/24</Name>



</PeerSubnet>

<PeerSubnet>

<Name>192.168.4.0/24</Name>



</PeerSubnet>

<SharedSecret>4dae850771fbe3f06588b49772c0b8eb</SharedSecret>

<SharedSecretEncrypted>false</SharedSecretEncrypted>

<EncryptionProtocol>AES256</EncryptionProtocol>

<Mtu>1500</Mtu>


<IsOperational>true</IsOperational>

</Tunnel>


</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:


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 [email protected].

mailto:[email protected]

UKCloud Ltd

A8 Cody Technology Park Ively Road, Farnborough Hampshire, GU14 0LX

T 01252 303300 E [email protected]

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

mailto:[email protected]

http://www.ukcloud.com/

https://twitter.com/ukcloudltd

https://www.facebook.com/ukcloudltd

https://www.linkedin.com/company/ukcloud-ltd?trk=nav_account_sub_nav_company_admin

Documents

change IPsec VPN settings via the vCloud Director API€¦ · Pure commitment. how to change IPsec VPN settings via the vCloud Director API version 3.0