Soracom Gate

Gate Peer Configuration

By configuring a Gate Peer within your private network environment, you can establish a connection from your private network back to your Soracom VPG in order to enable remote device access.

Gate Peer configuration involves the following steps:

Terminology

Gate Peer - A server used to establish a VXLAN connection between your private network and your Soracom VPG. When creating a VPG, two Gate Peers are automatically created inside the VPG (each residing in a different AWS Availability Zone). This document explains the process of setting up a corresponding Gate Peer within your environment. Gate Peers will handle the task of sending traffic between your network environment and the VPG, in order to allow device access.

Outer IP Address - Each Gate Peer will have a physical network interface within its respective network environment. The Outer IP Address refers to the address assigned to this interface. For Gate Peers in the VPG, addresses in the 100.64.0.0/16 range will automatically be assigned. For Gate Peers in your private network, this address should be the IP address within your private network, such as within a 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16 block.

Inner IP Address - Each Gate Peer will also have a VXLAN interface which is used to send network traffic between Gate Peers. The Inner IP Address refers to the address assigned to the VXLAN interface.

Requirements

In order to establish the VXLAN connection, you must have an underlying network connection between your Soracom VPG and your private network. Currently, Gate Peers can be configured for use with one of the following underlying connections:

When using a Public Internet connection as the underlying network connection, please be aware that the VXLAN interface will not encrypt network traffic. Therefore, ensure that all traffic on the established VXLAN interface is encrypted beforehand by using secured protocols, such as SSH and HTTPS.

Before continuing with Gate Peer configuration, ensure that you have completed the following:

With these requirements completed, continue to configure your Gate Peer.

This document will use an AWS EC2 instance as the Gate Peer and refer to AWS-specific configuration instructions. However, in general the same steps apply when configuring a Gate Peer within a non-AWS environment.

Create a Gate Peer Server

Create a Linux virtual machine instance in your private network, giving it a statically configured IP address within your private network's CIDR block range. You should follow best practices for securing the machine, such as utilizing SSH keys instead of passwords for accessing the machine. Make a note of its static IP address, as it is your Gate Peer's Outer IP Address and is needed later when registering this instance as a Gate Peer.

A Linux virtual machine is required in order to establish a VXLAN connection with the Soracom VPG. While VXLAN implementations are available for Windows servers, they are currently unstable and we do not recommend them for production environments.

Then configure the virtual machine's networking configuration to allow connections on the following ports/protocols:

Protocol Port Direction Source Description
TCP 22 Inbound 0.0.0.0/0 Allow connections over SSH to configure instance.
UDP 4789 Inbound 100.64.0.0/16 Allow connections from VPG over VXLAN.
ICMP — Inbound 0.0.0.0/0 Enable responses to ping requests.

Configuring your virtual machine instance to allow inbound TCP traffic on port 22 from 0.0.0.0/0 (any source) is intended only for remotely connecting to the instance in order to configure it. Leaving this configuration as-is will expose your instance to other external access.

Once you have verified that your instance has been configured, you should update this configuration to restrict external access, or remove this configuration altogether. You may also prefer to similarly restrict or remove ICMP traffic.

You can also add any application-specific ports/protocols, such as TCP 80 or 443 in order to allow HTTP access to devices. Where necessary, specify your private network's CIDR block as the Source address in order to confine remote access to requests originating from your private network.

When using an AWS EC2 instance as a Gate Peer, the instance will reject traffic where the destination does not match the EC2 network interface details by default, using a Source/Destination check policy. You must disable this policy so that the this instance can receive traffic to send to the VPG. Refer to the VPC NAT Instances: Disabling Source/Destination Checks documentation for instructions.

Register your Gate Peer

Registering your Gate Peer server tells your Soracom VPG about its existence, in order to establish the VXLAN connection between your private network and the VPG.

Gate Peer registration simply requires your server's static IP address within your private network.

During registration, an Inner IP Address will be automatically assigned to your Gate Peer, which will be used to establish the VXLAN connection between your server and the VPG. You can manually specify the this IP address in situations where you may have an existing IP address conflict, however in most cases auto-assignment is recommended.

You can register your Gate Peer from the User Console:

  1. Login to the User Console. From the Menu, open the VPG screen.

  2. From the list of VPGs, click the name of the VPG you want to configure to open its settings page.

  3. Click the Device LAN tab.

  4. Click the Add Gate Peer button in the Gate Peers in your network section.

  5. Enter the Tunnel Endpoint IP address (Outer IP Address) using your server's static IP address within your private network's CIDR block.

    If required, you can also specify the Device Subnet IP address (Inner IP Address). In most situations, leaving this blank is recommend.

    Then click the Create button.

  6. A dialog box with additional commands to help you configure your VXLAN settings on your Gate Peer will appear. We will address this script in further detail in our next section. Copying the script text with the automatically generated perematers will assist you in proceeding through this section more quickly.

Your server will now be registered as a Gate Peer, and will appear in the Gate Peers in your network section. Make a note of the Device Subnet IP Address, as it is your Gate Peer's Inner IP Address and is needed next.

Now that the VPG is aware of the Gate Peer in our private network, we can configure our server to create the VXLAN connection in order to complete configuration.

Configure your Gate Peer

  • This step is written assuming that you will be using Amazon Linux 2 AMI or Ubuntu as the Gate Peer. Settings may differ for other operating systems. If you are using an operating system other than Amazon Linux 2 AMI or Ubuntu please confirm that the operating system firewall is not blocking ICMP packets

  • The interface and routing settings configured here are not permanent and will be lost if the Gate Peer is restarted. After testing remote device access, configure your server to perform this configuration automatically in order ensure Gate Peer availability.

While still in the VPG settings Device LAN tab, we need to get the information of the Gate Peers that are inside the VPG. We will use these settings to tell our Gate Peer server where it should route traffic.

Make a note of the various IP addresses listed in the Gate Peers in VPG section.

Together with the IP addresses of your Gate Peer, we should have the following IP addresses noted:

These IP addresses are for example purposes only. The IP addresses associated with your VPG will be different.

Gate Peer Tunnel Endpoint IP addres
outerIpAddress		 Device Subnet IP addres
innerIpAddress
In your network 172.16.123.45 10.234.56.78
In VPG (1) 100.67.0.4 10.192.0.4
In VPG (2) 100.67.0.132 10.192.0.132

Now, let's use these IP addresses to configure our server. The following instructions are written for an AWS EC2 Amazon Linux AMI instance. If using other virtual machines, you may need to alter the commands according to your Linux environment.

  1. SSH to your Gate Peer server.

  2. Download the gate_init_vxlan.sh script for confiuring the VXLAN and give it execution privileges:
wget https://soracom-files.s3-ap-northeast-1.amazonaws.com/gate-peer-tools/gate_init_vxlan.sh
chmod +x gate_init_vxlan.sh
  1. Next, run gate_init_vxlan.sh with the following arguments as root. If any of these arguements are confusing to you, you can proceed throughg the steps above to register your Gate Peer in order to have the majority of the arguemens automatically generated for you on registration.
  sudo ./gate_init_vxlan.sh \
 {1. Gate Peer network interface name} \
 {2. The Gate Peer tunnel endpoint IP address} \
 {3. Name of the network interface to be assigned to the VXLAN} \
 {4. The Gate Peer device subnet IP address} \
 {5. Subnet mask for the device subnet IP address range} \
 {6. VXLAN ID} \
 {7. IP address for tunnel connection of VPG 1} \
 {8. IP address for tunnel connection of VPG 2}

The arguement values should be as follows:

Argument Explanation
1. Name of the Gate Peer network interface. Example: eth0
2. Gate Peer's IP address for tunnel connection. The tunnel connection IP address is displayed on the VPG settings screen under Device LAN → Gate Peers in your network
3. Network interface name to assign to VXLAN. Example: vxlan0
4. Gate Peer's device subnet IP address. The Gate Peer's device subnet IP address is displayed on the VPG settings screen under Device LAN → Gate Peers in your network
5. Subnet mask for the VPG's device subnet IP address range. Example: 9
6. VXLAN ID. You can specify anything in the range 1-16777215. Example: 10
7. IP address 1 for VPG tunnel connection. The tunnel connection IP address is displayed on the VPG settings screen under Device LAN → Gate Peers in VPG
8. IP address 2 for VPG tunnel connection. The tunnel connection IP address is displayed on the VPG settings screen under Device LAN → Gate Peers in VPG
  • Make sure that the "network interface name assigned to VXLAN", "VXLAN ID", and "device subnet IP address range" do not overlap for each VPG.

To connect to your device from an EC2 instance other than the Gate Peer, you must enable iptables packet forwarding for the Gate Peer to act as a NAT instance. This packet forwarding setting is not necessary if you use Gate Peer as a so-called "stepping stone server" where you log in to Gate Peer via ssh etc. and then log in to the device again via ssh when accessing the device.

To use Gate Peer as a NAT instance, execute the following on Gate Peer:

sudo sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward"
sudo iptables -t nat -A POSTROUTING  -o vxlan0 -j MASQUERADE

The iptables settings in the second line above will disappear when you restart the operating system. If necessary, make the iptables settings persistent according to the Linux distribution you are using.

Amazon Linux AMI example

sudo /etc/init.d/iptables save

Now our Gate Peer has been properly configured to accept packets that need to be sent to the VPG, and forward them to the corresponding Gate Peers using the VXLAN connection, which in turn will route them to the device for us. Each packet will also contain our Gate Peer's IP address as the packet source, ensuring any responses will be routed back to us correctly.

Confirm Remote Device Access

Now that the Gate Peer has been configured, you should be able to remotely access a cellular device attached to your Soracom VPG.

To test, first SSH to your Gate Peer server.

Then from within the SSH session, you can test a ping command, curl an HTTP resource on the device, or even open up another ssh session. 

ping 10.219.96.63
>PING 10.219.96.63 (10.219.96.63) 56(84) bytes of data.
>64 bytes from 10.219.96.63: icmp_seq=1 ttl=64 time=816 ms
>64 bytes from 10.219.96.63: icmp_seq=2 ttl=64 time=403 ms
>64 bytes from 10.219.96.63: icmp_seq=3 ttl=64 time=423 ms
>64 bytes from 10.219.96.63: icmp_seq=4 ttl=64 time=422 ms
>
curl http://10.219.96.63
>Hello World!

Although routing between network environments via the VXLAN connection is set up between your Gate Peer and the Soracom VPG, you will need to perform additional network configuration within your private network in order to route local traffic to your Gate Peer. As this process varies for each network environment, please test your routing configuration in order to confirm that only traffic intended for Soracom Air devices is routed accordingly.

Programmatic Usage

When configuring a Gate Peer, we can also use the Soracom API and Soracom CLI for registering our server as a Gate Peer, and listing the Gate Peers in our VPG:

Soracom API

Register a Gate Peer using the registerGatePeer API method:

curl -X POST \
>  -b '{
>        "outerIpAddress": "172.16.123.45"
>      }' \
>  https://g.api.soracom.io/v1/virtual_private_gateways/<VPG-ID>/gate/peers

Once registered, the API will return the following data about the Gate Peer:

{
  "outerIpAddress": "172.16.123.45",
  "ownedByCustomer": true,
  "innerIpAddress": "10.0.123.45"
}

Then get a list of all Gate Peers by using the listGatePeers API method:

curl -X GET \
>  https://g.api.soracom.io/v1/virtual_private_gateways/<VPG-ID>/gate/peers

The API will return something like this:

[
  {
    "outerIpAddress": "100.64.0.4",
    "ownedByCustomer": false,
    "innerIpAddress": "10.192.0.4"
  },
  {
    "outerIpAddress": "100.64.0.132",
    "ownedByCustomer": false,
    "innerIpAddress": "10.192.0.132"
  },
  {
    "outerIpAddress": "172.16.123.45",
    "ownedByCustomer": true,
    "innerIpAddress": "10.0.123.45"
  }
]

For each Gate Peer, the ownedByCustomer key corresponds to whether the Gate Peer is located in your private network or in the VPG.

Soracom CLI

You can also register a Gate Peer using the register-gate-peer command:

soracom vpg register-gate-peer --vpg-id "<VPG-ID>" --outer-ip-address "172.16.123.45" --coverage-type g

The CLI will return information about the registered Gate Peer as above.

Then list Gate Peers using the list-gate-peers command:

soracom vpg list-gate-peers --vpg-id "<VPG-ID>" --coverage-type g

The CLI will return information about the Gate Peers in the VPG as above.