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:


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


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 Allow connections over SSH to configure instance.
UDP 4789 Inbound Allow connections from VPG over VXLAN.
ICMP Inbound Enable responses to ping requests.

Configuring your virtual machine instance to allow inbound TCP traffic on port 22 from (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 Advanced settings tab.

  4. Click the Add Gate Peer button.

  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.

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

While still in the VPG settings Advanced settings 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:

Gate Peer Tunnel Endpoint IP addres
Device Subnet IP addres
In your network
In VPG (1)
In VPG (2)

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. Run the following commands:

    • Remove the VXLAN module, then reload it specifying the UDP port to use for the connection:

      rmmod vxlan
      modprobe vxlan udp_port=4789
    • Link the server's physical interface to the VXLAN interface:

      ip link add vxlan0 type vxlan local id 10 dstport 4789 dev eth0

      This command uses the following options:

      • add vxlan0 type vxlan - Create a new VXLAN interface named vxlan0
      • local - Set the source IP address in outgoing packets as your Gate Peer's Outer IP Address.
      • id 10 dstport 4789 - Set the VXLAN Network Identifier to 10 and specify the remote VXLAN tunnel endpoint port.
      • dev eth0 - Specifies the physical network interface to use for the VXLAN connection.
    • Enable the new vxlan0 interface, assigning its IP address to your Gate Peer's Inner IP Address:

      ifconfig vxlan0 up
    • Establish the VXLAN connection between your Gate Peer and each of the two Gate Peers in the VPG:

      bridge fdb append 00:00:00:00:00:00 dev vxlan0 dst
      bridge fdb append 00:00:00:00:00:00 dev vxlan0 dst
    • Enable packet forwarding:

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

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.

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.

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 ( 56(84) bytes of data.
>64 bytes from icmp_seq=1 ttl=64 time=816 ms
>64 bytes from icmp_seq=2 ttl=64 time=403 ms
>64 bytes from icmp_seq=3 ttl=64 time=423 ms
>64 bytes from icmp_seq=4 ttl=64 time=422 ms
>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": ""
>      }' \

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

  "outerIpAddress": "",
  "ownedByCustomer": true,
  "innerIpAddress": ""

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

curl -X GET \

The API will return something like this:

    "outerIpAddress": "",
    "ownedByCustomer": false,
    "innerIpAddress": ""
    "outerIpAddress": "",
    "ownedByCustomer": false,
    "innerIpAddress": ""
    "outerIpAddress": "",
    "ownedByCustomer": true,
    "innerIpAddress": ""

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