Last updated December 07, 2009 20:30, by Glenn Brunette


According to Amazon Web Services (AWS), their Virtual Private Cloud (VPC) offering is a secure and seamless bridge between a company’s existing IT infrastructure and the AWS cloud. Amazon VPC enables enterprises to connect their existing infrastructure to a set of isolated AWS compute resources via a Virtual Private Network (VPN) connection, and to extend their existing management capabilities such as security services, firewalls, and intrusion detection systems to include their AWS resources.

Currently, AWS has offered documented support only for organizations wishing to use Cisco or Juniper devices as the customer gateway to the AWS Virtual Private Cloud. The goal of this project is to show how an out of the box OpenSolaris-based system (physical or virtual) could be configured to act as a VPC Customer Gateway. For more information on AWS VPC Customer Gateways, see the AWS VPC Network Administrator's Guide.

Project Team

  • Core Team
    • Glenn Brunette
    • Dileep Kumar
    • Dan McDonald
  • Extended Team
    • Sebastien Roy
    • Sowmini Varadhan


  • v0.1. Initial public release.


The OpenSolaris VPC Gateway is a software bundle that will allow an OpenSolaris-based system to be used as an Amazon Web Services Virtual Private Cloud (VPC) Customer Gateway. The software automates the steps needed to create and deploy a virtual machine into a new subnet on a created Amazon VPC. Further, this software will perform all of the necessary steps to configure the OpenSolaris system so that it can communicate with the VPC.

Functional Diagram


  • WARNING 1: This is pre-alpha (preview) software that is still undergoing substantial development and testing. The goal in making it available is to increase the number of potential reviewers so that further feedback can be collected. It is recommended that this software not be used on production systems at this time. Further, this software does not have an uninstall capability, so only use this software on a system that can be devoted to OpenSolaris VPC testing - such as a virtual system.
  • WARNING 2: Note that Amazon Web Services does not support the creation or use of VPCs communicating with Customer Gateways that connect to the Internet through a device performing Network Address Translation. This situation was tested using this software and was found to work (in some situations) although given the lack of support from AWS for this scenario, its use is considered unsupported and strongly discouraged.
  • WARNING 3: Note that Amazon Web Services does not support the creation or use of VPCs connecting to Customer Gateways that do not have an Internet-routable, static IP address. The use of DHCP was tested and found to work for as long as the Customer Gateway's IP address was maintained. Again, due to the lack of support from AWS for a non-static IP address, its use is considered unsupported and strongly discouraged.
  • WARNING 4: Version 0.1 of the OpenSolaris VPC Gateway configures an OpenSolaris node as an endpoint allowing it to communicate with an Amazon Virtual Private Cloud. This configuration is interesting as it allows someone to effectively build a virtual data center from their desktop or laptop. That said, the current software does not implement the steps required to enable the OpenSolaris node to act as a gateway for an internal network - allowing the internet network to also communicate with the VPC. It is possible to implement these steps by hand, but automation of these steps was out of scope for v0.1. The steps will be validated and documented in a future update.


  • DEPENDENCY 1: This software was developed and tested on development builds of OpenSolaris (build 126 and 127). Some of the functionality used by this toolkit requires build 125 or later. Earlier versions should not be used with this software as it may have unexpected results.


  • CONVENTION 1: Actions that are prefixed by the command pfexec must be executed with administrative privileges. Specifically, these commands require that the user have sufficient privileges to be able to write to files owned by the root user as well as the ability to start and stop several services via SMF. In the examples below, the user has been assigned the Primary Administrator rights profile allowing such operations to be completed. If required, more tightly controlled rights can be assigned using a customized rights profile. All other actions not prefixed by the command pfexec can be run as an unprivileged user.


In order to use the OpenSolaris VPC Gateway software, three software components must be downloaded and installed. They include two OpenSolaris packages, the Amazon EC2 API Tools, and the OpenSolaris VPC Gateway software itself.

OpenSolaris Packages

First, install the OpenSolaris packages required by the OpenSolaris VPC Gateway tool. These packages are not installed by default, but they are available from the OpenSolaris package repository. The packages include:

  • SUNWmercurial. Mercurial is needed in order to access the OpenSolaris VPC Gateway source code.
  • SUNWquagga. Quagga implements the BGP routing functionality required by the AWS VPC implementation.

To install these packages, use the command:

      $ pfexec pkg install SUNWmercurial SUNWquagga

Amazon EC2 API Tools

Next, the Amazon EC2 API Tools must be downloaded from Amazon Web Services. Typically, this software will be called Once downloaded, this software should be extracted on the OpenSolaris system. To extract the software, use the command:

      $ unzip

OpenSolaris VPC Gateway Software

Once this is completed, the OpenSolaris VPC Gateway software can then be downloaded. Currently, this software is accessible from a Mercurial source code repository. A "tarball" bundle may be made available after the results of the initial pre-alpha test have been collected and changes integrated. To download a copy of the source, you can use a command similar to:

      $ hg clone osolvpc 
      requesting all changes
      adding changesets
      adding manifests
      adding file changes
      added 2 changesets with 32 changes to 32 files
      updating working directory
      32 files updated, 0 files merged, 0 files removed, 0 files unresolved

The OpenSolaris VPC Gateway distribution will be installed into the directory osolvpc.


Once the required software packages have been downloaded and installed, a small amount of configuration is needed in order to begin using the OpenSolaris VPC Gateway software.

Amazon EC2 API Tools

First, the following EC2 API Tools environment variables must be set:

      $ export EC2_HOME=[location of extracted EC2 Tools]
      $ export JAVA_HOME=/usr/java
      $ export EC2_CERT=[location of EC2 certificate file]
      $ export EC2_PRIVATE_KEY=[location of EC2 private key file]

To ensure that these parameters have been properly set, a basic test can be performed:

      $ ${EC2_HOME}/bin/ec2-describe-vpcs

Since no VPCs have been created, there should be no expected output. That said, there should also be no error messages reported from this command. If there are any error messages, these should be corrected before continuing.

OpenSolaris VPC Gateway Software

Next, configure the OpenSolaris VPC Gateway environment variables:

      $ export VPC_TK_HOME=[location of extracted VPC Toolkit]

Update the PATH environment variable to account for the EC2 API Tools and the OpenSolaris VPC Gateway software:

      $ export PATH=${VPC_TK_HOME}/bin:${EC2_HOME}/bin:$PATH

Lastly, the site.conf configuration file (located in the directory ${VPC_TK_HOME}/etc) must be updated to account for site specific information. In particular, be sure to set the following parameters:

  • CGW_IPADDR. Address of the customer gateway. If the customer gateway system is behind a NAT device, the IP address of the Internet-accessible device must be used here. Note that using AWS VPC from behind a NAT is not supported by AWS per WARNING 2 above.
  • AMI_ID. The identifier associated with the first Instance to be created into the Subnet on the VPC. To use the Immutable Service Container AMI, this variable should be set to ami-48c32021 (US) or ami-78567d0c (Europe).
  • KEY_ID. The security key identifier to be used with the first instance (defined by AMI_ID above).

The rest of the parameters can be left as-is for initial testing. The following parameters should not be changed as they are used by this Toolkit:


Establishing the VPC Connection

Note that before attempting these steps, be certain that the environment variables listed above have been set in the shell that is being used to launch these commands.

Create the Remote VPC Configuration

      $ start-vpc-remote
      [NOTE] [20091117151253] VPC: Creating
      [NOTE] [20091117151301] VPC: Created (vpc-104cb679)
      [NOTE] [20091117151301] Subnet: Creating
      [NOTE] [20091117151310] Subnet: Created (subnet-134cb67a)
      [NOTE] [20091117151310] Instance: Creating
      [NOTE] [20091117151516] Instance: Created (i-6f7b1807)
      [NOTE] [20091117151516] Customer Gateway: Creating
      [NOTE] [20091117151525] Customer Gateway: Created (cgw-acaa4fc5)
      [NOTE] [20091117151525] VPN Gateway: Creating
      [NOTE] [20091117151607] VPN Gateway: Created (vgw-f4a94c9d)
      [NOTE] [20091117151607] VPN Connection: Creating
      [NOTE] [20091117151644] VPN Connection: Created (vpn-22ae4b4b)
      [NOTE] [20091117151644] VPN Gateway: Attaching
      [NOTE] [20091117151811] VPN Gateway: Attached (vgw-f4a94c9d)

Configure the Local VPC Configuration

      $ pfexec config-vpc-local
      Physical NIC    : e1000g0
      MY IP Address   :
      BGP ASN         : 65530
      Tunnel #1
      Outside CGW IP: [redacted]
      Outside VGW IP:
      Inside  CGW IP:
      Inside  VGW IP:
      Inside  CIDR  :
      Key           : [redacted]
      Formatted Key : [redacted]
      Tunnel #2
      Outside CGW IP: [redacted]
      Outside VGW IP:
      Inside  CGW IP:
      Inside  VGW IP:
      Inside  CIDR  :
      Key           : [redacted]
      Formatted Key : [redacted]

Enable the Local VPC Configuration

      $ pfexec start-vpc-local

Validating the VPC Connection

Once the installation steps have been successfully completed, it is important to verify that the OpenSolaris VPC Gateway is properly functioning. The following validation steps can be performed to that end:

Verify Tunnel #1 Endpoints (Local and Remote)

Note that the actual IP addresses used below should correspond to the Inside Customer Gateway (CGW) and Inside VPN Gateway (VGW) IP addresses (for Tunnels #1) as displayed by config-vpc-local command above.

  • Local:
      $ ping is alive
  • Remote:
      $ ping is alive

Verify Tunnel #2 Endpoints (Local and Remote)

Note that the actual IP addresses used below should correspond to the Inside Customer Gateway (CGW) and Inside VPN Gateway (VGW) IP addresses (for Tunnels #2) as displayed by config-vpc-local command above.

  • Local:
      $ ping is alive
  • Remote:
      $ ping is alive

Determine the IP address of the Provisioned Instance

Note that the actual instance identifier used below should correspond to the instance identifier reported by the start-vpc-remote command above.

      $ ec2-describe-instances i-6f7b1807
      RESERVATION	r-dd5e89b5	332678506123	
      INSTANCE	i-6f7b1807	ami-48c32021			running	[redacted]	0		m1.small	2009-11-17T20:15:11+0000
      us-east-1a	aki-1783627e	ari-9d6889f4		monitoring-disabled	vpc-104cb679	subnet-134cb67a

Connect to the Provisioned Instance

Note that the actual IP address used below should correspond to the IP address as reported by the ec2-describe-instances command above. Also, note that depending upon the AMI selected, you may not be able to ping the host due to implemented firewall restrictions (e.g., Immutable Service Container AMI).

      $ ssh -i [path_to_SSH_key_file] root@
      Last login: Tue Nov 17 20:24:55 2009 from
      Sun Microsystems Inc.   SunOS 5.11      snv_111b        November 2008

Terminating the VPC Connection

When the OpenSolaris VPC Gateway is no longer needed, the VPC connection can be terminated using the following steps:

Disable the Local VPC Configuration

      $ pfexec stop-vpc-local

Unconfigure the Local VPC Configuration

      $ pfexec unconfig-vpc-local

Destroy the Remote VPC Configuration

      $ stop-vpc-remote
      [NOTE] [20091117152744] VPN Gateway: Detaching (vgw-f4a94c9d)
      [NOTE] [20091117152753] VPN Gateway: Detached (vgw-f4a94c9d)
      [NOTE] [20091117152753] VPN Connection: Deleting (vpn-22ae4b4b)
      [NOTE] [20091117152849] VPN Connection: Deleted (vpn-22ae4b4b)
      [NOTE] [20091117152850] VPN Gateway: Deleting (vgw-f4a94c9d)
      [NOTE] [20091117152937] VPN Gateway: Deleted (vgw-f4a94c9d)
      [NOTE] [20091117152938] Customer Gateway: Deleting (cgw-acaa4fc5)
      [NOTE] [20091117152947] Customer Gateway: Deleted (cgw-acaa4fc5)
      [NOTE] [20091117152947] Instance: Deleting (i-6f7b1807)
      [NOTE] [20091117153021] Instance: Deleted (i-6f7b1807)
      [NOTE] [20091117153021] Subnet: Deleting (subnet-134cb67a)
      [NOTE] [20091117153026] Subnet: Deleted (subnet-134cb67a)
      [NOTE] [20091117153026] VPC: Deleting (vpc-104cb679)
      [NOTE] [20091117153030] VPC: Deleted (vpc-104cb679)


1. In some cases, it may not be possible to ping the IP addresses associated with the two Inside VPN Gateways. If this situation is encountered, use the following command to re-establish communications:

      $ pfexec stop-vpc-local
      $ pfexec start-vpc-local

2. In order to test BGP fail-over, it may be necessary to implement the following workaround for a possible bug in the Zebra routing code. Normally, a netmask is not required for a point-to-point network interface, but it appears as though Zebra may be using the interface's netmask for routing decisions. To set a netmask for the virtual point-to-point interfaces, use the following commands:

      $ pfexec ifconfig vpc0 netmask
      $ pfexec ifconfig vpc1 netmask

Note that the netmask value in the commands above should be adjusted as needed based upon the actual configuration being used.

Related Projects

Additional Reading

  • Mysql
  • Glassfish
  • Jruby
  • Rails
  • Nblogo
Terms of Use; Privacy Policy;
© 2014, Oracle Corporation and/or its affiliates
(revision 20160708.bf2ac18)
Please Confirm