Upgrading to the latest version of VNS3
Introduction
Upgrade Requirements
- You have an existing VPN3 ver. 2.x or VNS3 ver. 3.x or 4.x controller launched and configured.
- You have access to a new VNS3 image provided by Cohesive Networks or Cloud Marketplace or public catalog.
- You have scheduled an operational window with any parties connected to or using the existing VNS3 instance (see the following section, downtime considerations).
Downtime Considerations
Upgrading between versions of VNS3 requires launching and configuring a new Controller server instance. While steps 1 and 2 of this document can be done with no impact to the existing VNS3 topology, cutting over to the new Controller will interrupt service to the networks connected to the VNS3 Controller (Cloud subnet, connected IPsec devices, VNS3 encrypted overlay, etc.)
Downtime can be reduced and the upgrade process simplified if your cloud environment allows and has been configured with a user-controlled and re-assignable static Public IP such as AWS’s Elastic IPs.
If you cannot control the Public IP address of your VNS3 controller, you may need to re-save your IPsec configurations following the snapshot import, as well as update any Overlay Network clients’ OpenVPN configuration files to use the new controller instance’s IP address.
Getting Help with VNS3
Cohesive Networks offer support and services for VNS3 version upgrades. Audits, snapshot reviews, and chaperoned upgrade windows can be scheduled with your account representative or by emailing us at support@cohesive.net.
Please review the VNS3 Support Plans and Contacts before sending support inquiries. If you need specific help with project planning, POCs, or audits, contact our professional services team via sales@cohesive.net for details.
Compatibility Consideration when upgrading from VNS3 version 2.x, 3.x, or 4.x to the latest version 5.x:
- If you are utilizing the Overlay Network, you may need to upgrade the client OpenVPN process to 2.5+ prior to the upgrade.
- IPSec connection utilizing DH2: If you have an IPsec connection that uses DH2 for the phase 1 or PFS group, you will need to explicitly define these parameters in the “extra configuration parameters box”, as shown below:
- Only certain VNS3 peered topologies with different major versions will operate as expected. It is recommended that all VNS3 controllers in a peered topology be upgraded to 5.x during the same operational window. Cohesive Networks Support can review existing deployments prior to upgrades and have resources standing-by during upgrades windows (advanced notice required) to ensure a smooth transition - support@cohesive.net.
VNS3 Upgrade Steps
1. Create a Configuration Snapshot from the Existing Controller
From the existing Controller’s Web UI, click the “Snapshots” menu item under the Maintenance section in the lefthand column.
On the Snapshots page, click Take New Snapshot Now.
The Controller will create a new Snapshot and present a download link. Click the download link and save locally. (Note: some browsers will attempt to unpack .gz files automatically; this will cause issues. You can re-gzip the file or use an alternate browser which does not do this.)
2. Launch the new Controller
Use the VNS3 virtual image available in your cloud’s public catalog or that provided by Cohesive Networks. Launch the Controller in the same Region/Datacenter/Availability Zone/Subnet as the old Controller. It is recommended that you use the same Security Group and other network settings as well in order to avoid unnecessary re-configuration of cloud assets.
Where applicable, the new controller should be launched into a cloud segment where the Public IP of the old Controller instance can be reassigned to the new instance.
In some clouds, you may need to take some action to allow the new instance to act as a router. In AWS, this is called “Source/destination checking.” In Azure it is called “Allow IP Forwarding.” Other cloud providers may use their own terminology or may not have this requirement.
3. Move the Public IP
If your old Controller and its Overlay Network topology is configured with a user-controlled and re-assignable static Public IP like AWS Elastic IPs, switching the Public IP from the old Controller to the new one will cause any IPsec, Peering, and Overlay Client connections to reconnect to the new Controller automatically.
If you do not have control over the Public IP address of the old Controller, you will need to re-save your IPsec connections and update any Overlay Network clients’ OpenVPN configuration files to point to the new instance’s IP following snapshot import.
For this example, the use of AWS’s Elastic IPs is demonstrated.
From the EC2 console, click the Elastic IPs left column menu item under the Network & Security section.
Select the Elastic IP associated with the old Controller and click Disassociate then Yes, Disassociate in the popup window.
With the same Elastic IP selected, click Associate and select the new Controller instance, then click Yes, Associate in the popup window.
4. Log into the New Controller
Log into the new Controller using the following log in credentials:
Username: vnscubed
Password:
- In AWS, the default password is the instance ID (i-xxxxxxxx).
- In Azure, the default password is your VM name, a dash, and the private IP of the VM. For example, if your VM is named “vns3-prod” and its private IP is 10.0.0.5, the default password would be “vns3-prod-10.0.0.5”
- In Google’s GCE, the default password is the instance ID (xxxxxxxxxxxxxxxxxx) for version 4.9.2 and later. For versions older than 4.9.2, use “vnscubed”
- In other clouds or in cases where cloud metadata is not available to VNS3, the default password will be “vnscubed”
You will be prompted to change both the Web UI and API passwords when logging into a VNS3 Controller for the first time. The passwords you enter in this step will be used by the Controller after the snapshot from the old Manager is uploaded.
If you do NOT change the default passwords before importing the snapshot, the passwords included in the snapshot from the old instance will be used. If you do not have a record of the password in the snapshot, you MUST change the new Controller’s passwords before snapshot import or you will not be able to log into the new controller later.
5. Upload the Snapshot to the new Controller
After the old controller IP address has been associated with the new instance, click the “Upload Snapshot” menu item under the “Initialization” section in the lefthand menu.
Browse for and select the VNS3 Snapshot file you saved earlier.
Click Submit and reboot.
Click OK on the popup window informing you that the Controller will reboot once the Snapshot is uploaded. Hitting the blue “Refresh” link in the body of the page will provide a summary of the import steps until the controller goes down for reboot.
6. Update cloud subnet routes
If your VNS3 controller is providing connectivity to/for your cloud subnet, you may need to update cloud routes to use the new instance as the gateway. Exactly how this is done varies by cloud provider. This step can be completed during the snapshot import reboot in order to save time.
7. Review the New Controller’s Imported Configuration
Extra Configuration Parameters
The 3.x release and some 4.x releases have introduced new arguments for the Extra Configuration Parameters field on the IPsec Endpoint page (see the Configuration Guide | Administration Guide for more information). All VNS3 versions are backward compatible with all previous Extra Configuration Parameters entries, but there may be additional options available to you in the new version.
CloudWAN Tunnels (2.x)
The 3.x release changed the way CloudWAN features are surfaced to the customer. 3.x release introduced the concept of “tunnels” where you define source and destination subnets, allowing complete control over IPsec connections. Previously-configured CloudWAN subnets in 2.x controllers will be converted to the tunnel format as part of the Snapshot import process.
Note: the default tunnels for each Endpoint, with the source subnet of the entire Overlay Subnet, will also be automatically created.
Firewall Rules
If you are using negation rules, the underlying VNS3 Firewall Rule syntax changed in version 3.5. Previously, the exclamation mark was placed after the -d or -s for an address space to be excluded. In VNS3 3.5 and newer, the exclamation mark is now placed before the -d or -s.
# Old Syntax
INPUT_CUST -s ! 192.168.1.0/24 -j ACCEPT
# New Syntax
INPUT_CUST ! -s 192.168.1.0/24 -j ACCEPT
Update Controller Peering
If your controller is part of a peered topology, you may need to update your other controllers’ Controller Peering to point at the correct IP address of the new instance following the upgrade.
Verify Functionality
Once the connections have migrated to the new Controller, validate traffic flow and final configuration of the new Controller. It is recommended that you do not delete the old controller for a 24 hour period in the case you wish to roll back. Ideally if supported in your cloud, stop or shut down the old controller instance.
In the event you need to roll back, follow the steps below.
- Disassociate the Elastic IP from the new Controller
- Associate the Elastic IP with the old Controller
- Reboot the old Controller, and if available, stop the new one.
8. Reboot or Stop the old Controller
If you are unable to stop or shut down the old instance, add the following Extra Parameters to each endpoint on the old Controller to prevent it from trying to connect:
In VPN3 ver. 2.x the parameters are:
auto=add
rekey=no
In ver. 3.x and newer, the parameters are:
connection=receive
connection-rekey=no
This allows you to keep the old Manager running in order to rollback if necessary without additional downtime.
Once the Elastic IP has been associated with the new Controller, there is some small risk that port floating will keep some connections briefly on the old controller. To help ensure all connections migrate to the new Controller in a timely fashion, reboot the old Controller from the VNS3 Web UI:
Click the Reboot left column menu item under the Admin section and confirm you want to reboot the old controller by clicking “OK” on the popup window.
The reboot will bounce the active tunnels and force them to reconnect. The total time to reconnect is usually ~1-2 minutes. Most VNS3 instances from 3.5 forward can be “stopped” in the Cloud Console where the instance is running. If available, this is the best manner to ensure the old controller does not interfere with any of the connections. Please ensure that your VNS3 instance can be stopped and restarted if needed.
Here is a link to a video that walks you through the upgrade process in AWS: https://www.youtube.com/watch?v=AU2PU7jjCB4
Here is a link to a video that walks you through the upgrade process in Azure: https://www.youtube.com/watch?v=KrK3c-3nIEM