#UKCloud IPSec VPN Configuration Tool

This command line tool allows UKCloud customers using vShield Edge firewalls to configure IPSec tunnels using a configuration file written in "YAML" For more information on YAML and it's syntax see: https://en.wikipedia.org/wiki/YAML

First ensure Ruby is installed on your machine.

To check you can run:

>ruby -v
ruby 2.0.0p247 (2013-06-27) [i386-mingw32]

The tool was built using Ruby 2.0.0p247 but other versions may work.

And then install the gem using:

>gem install ukcloud-vpn

Once installed the tool can be run by executing the following:

>ukcloud-vpn apply <path to yaml file>

For example:

>ukcloud-vpn apply c:\tmp\firewalls.yml

Or for Linux:

$ ukcloud-vpn apply /tmp/firewalls.yml

The configuration file uses YAML as a format and defines one or more vShield Edge Firewalls to be configured. The file has the following syntax:

Firewalls:
  - Name: Firewall_1
    Service:
      IsEnabled: true
    Creds:
      User: xxx.xxxx.xxx
      Password: xxxxxxxxxxxx
      Org: x-x-xx-xxxx
      Url: api.vcd.portal.skyscapecloud.com
      Edge: nftxxxxxx-x
    GatewayIpsecVpnService:
      IsEnabled: true
      Tunnel:
      - Name: west-to-east
        IpsecVpnLocalPeerId:
        IpsecVpnLocalPeerName:
        PeerIpAddress: 111.111.111.111
        PeerId: 111.111.111.111
        LocalIpAddress: 222.222.222.222
        LocalId: 222.222.222.222
        LocalSubnet:
        - Name: DMZ
          Gateway: 10.0.1.1
          Netmask: 255.255.255.0
        PeerSubnet:
        - Name: DMZ
          Gateway: 10.0.10.1
          Netmask: 255.255.255.0
        SharedSecret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        EncryptionProtocol: AES256
        Mtu: 1400
        IsEnabled: true
  - Name: Firewall_2
    Creds:
      User: xxx.xxxx.xxx
      Password: xxxxxxxxxxxx
      Org: x-x-xx-xxxx
      Url: api.vcd.portal.skyscapecloud.com
      Edge: nftxxxxxx-x    
    GatewayIpsecVpnService:
      IsEnabled: true
      Tunnel:
      - Name: east-to-west
        IpsecVpnLocalPeerId:
        IpsecVpnLocalPeerName:
        PeerIpAddress: 222.222.222.222
        PeerId: 222.222.222.222
        LocalIpAddress: 111.111.111.111
        LocalId: 111.111.111.111
        PeerSubnet:
        - Name: DMZ
          Gateway: 10.0.1.1
          Netmask: 255.255.255.0
        LocalSubnet:
        - Name: DMZ
          Gateway: 10.0.10.1
          Netmask: 255.255.255.0
        SharedSecret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        EncryptionProtocol: AES256
        Mtu: 1400
        IsEnabled: true

Note that a hyphen ( - ) in YAML represents an array item (an item which can appear one or more times). Hopefully it is clear from the example file above the the file supports:

• One or more vShield firewalls per file
• One or more tunnels per vShield firewall
• One or more local subnet per tunnel
• One or more peer subnet per tunnel

PeerIpAddress & PeerId should be set to the public IP address of the remote vShield Firewall
LocalIpAddress & LocalId should be set to the public IP address of the local vShield Firewall

The file can be created in any text editor (notepad etc) and is usually saved with a ".yml" file extension although this is not required by the tool.

Bug reports and pull requests are welcome on GitHub at https://github.com/ukcloud-cloud-services/ukcloud-vpn. Please ensure that the tests run successfully before creating a PR and consider increasing the coverage if adding new features.

The project has unit tests using Rspec which can be run using:

>bundle exec rspec

One of the tests configures a VPN using the firewalls.yml file and a mocked HTTP connection to vCloud Director API. The UKCloud VPN tool will print out what it is doing as it does it, so you can also verify that the tool still works by checking the output in the console against this list:

UKCloud::Vcloud::Ipsec::Configuration
  loading current configuration using the vCloud API
Connecting to vCloud Director API
Connected to vCloud Director API
Getting vShield Edge HREF From Query
Finished Getting vShield Edge HREF From Query
Configuring VPN Service For Firewall: nftxxxxxx-x
  Task:  Completed With Status: completed
Finished Configuring VPN Service For Firewall: nftxxxxxx-x
Connecting to vCloud Director API
Connected to vCloud Director API
Getting vShield Edge HREF From Query
Finished Getting vShield Edge HREF From Query
Configuring VPN Service For Firewall: nftxxxxxx-x
  Task:  Completed With Status: completed
Finished Configuring VPN Service For Firewall: nftxxxxxx-x

The CLI tests are written using Cucumber & Aruba and can be run using:

>bundle exec cucumber

Note: Cucumber tests do not appear to work on Windows