Documentation & User Guide

Introduction How It Works Use Cases Quickstart

Introduction

What is packetriot? Packetriot is an edge computing network that provides globally accessible, secure Layer 7 (L7) endpoints. L7 is the term used to identify the application layer in network systems. An example of an application is a web server (HTTP/S), however, it can be any networked application. You only need to update the DNS records for domains you own to point to packetriot's edge servers' IP address (A record) or domain name (CNAME record). Then users on the Internet can connect to your locally running network applications via our edge servers.

When you're behind a Firewall, NAT or on a private network, you are not accessible to the rest of the Internet. Packet riot overcomes this with its client software by establishing encrypted reverse tunnels to edge servers and request traffic flows to be directed to it. The client can then forward the traffic to local or remote resources (e.g. virtual machines, containers, ...). It functions identically to a reverse proxy.

Packetriot enables you to expose HTTP/S and TCP-based network applications to the rest of Internet, enabling developers and enthusiasts to use their own equipment to deploy code or self-host software. It will work with any ISP or connection to the Internet.

Easily substitute lower-tier resources on public clouds like AWS, Google Cloud, or Azure at a much lower cost with packetriot.

How It Works

Packetriot is a network of servers on the Internet. We refer to them as edge servers. The term edge implies that the server is close to the end-user. In the case of packetriot, the connection to these servers form an "edge" between your compute resources and the rest of the Internet.

So how is this L7 endpoint established?

First let's explain what we mean by the term endpoint. It's the HTTP/S or TCP traffic that is requested by the pktriot client program. This is based on rules your configure in your client. Let's say that we own the domain example.com. http://example.com or http://www.example.com are both L7 endpoints. These are what users on the Internet use to connect to the service.

The edge, or connection, between the client program and our servers is referred to as a tunnel. Each tunnel is assigned a hostname from the pktriot.net domain. So even if you don't own any domains, we can provide an endpoint that can be used so you can start using the network quickly. In most cases you want to buy your own domains and use them since it'll be easier to remember and more descriptive of the server you're hosting.

Along with the hostname we assign your tunnel, the edge server's hostname and IP address can be used to setup the DNS records for your custom domains. An A record requires the use of an IP address, so you would use the the IP address of the edge server your tunnel connects to. (This server is static until you switch servers.)

You can also use CNAME record to setup your domain. In that case you can use the hostname of the edge server or the hostname we assign your tunnel.

Edge servers route connections for many packetriot users, so its important that we verify who owns domains. Before the network routes any traffic for a custom domain, the domains ownership must be verified. We do this by generating a random token that you set as the value for a DNS TXT record for the domain.

This is checked every few minutes and when its found then it's verified that you own the domain and request traffic for it will routed to your tunnels and only your tunnels.

Once your domains are setup using A or CNAME records, and you've verified ownership, you can start the pktriot client program and configure rules that will direct traffic for the domain to your client, where it will then forward to a server or host running on your local private network.

This is how packetriot works in a nutshell.

Use Cases

Packetriot can support many different use-cases for developers, IT enthusiasts, self-hosters, small/independent businesses, college students and more!

Developers writing a new website or web service can expose it to the rest of the Internet. Whether it's running on bare-metal servers, virtual machine or docker container, packetriot can relay all HTTP/S traffic to that resource. Packetriot can prevent escalating costs and paying for underutilized resources on the cloud. Test your idea at much lower cost!

Pushing out a test build of software and want access to it across for geographically diverse team? Packetriot can help you do that with much lower cost than standing up resources on a cloud.

Are you self-hoster? Or IT enthusiast? Do you like hosting your own dropbox, music streaming server, or blog? You can easily do that with packetriot. Use your computers and store personal or private data on your hard drives. Packetriot overcomes the obstacles to hosting services over your ISP connections using encrypted reverse tunnels.

There are many use-cases for using packetriot, we hope these are helpful examples. Check out our blog for tips and example projects.

Client Software

Downloads

Filename Version Kind OS/Arch Size Hash (sha256)
pktriot-0.9.2-1.arm32.rpm v0.9.2 RPM linux
arm32
2 MB 0e683516e848ab27bb2107d3a16ffa9d56f9ae77c7506bccd3d02ab71f861ed4
pktriot-0.9.2.arm32.tar.gz v0.9.2 Archive linux
arm32
3 MB 7b23f49be2cd2c34c6a4bd881a1e2b76631f4287eecdac8b1a2b515f4e8a7d61
pktriot-0.9.2-1.arm64.rpm v0.9.2 RPM linux
arm64
4 MB 97868bfd5943975142138f659fe8d3f13e166778abf4541feadc15677ab7f0c5
pktriot-0.9.2.arm64.tar.gz v0.9.2 Archive linux
arm64
3 MB a95e2f34f2b690219b8aee31ff51f7fae49b33399dceba29533b916c290582ab
pktriot-0.9.2.i386.tar.gz v0.9.2 Archive linux
x86-32
3 MB d0987ba17e365c737bb9d2d64a2abee202aecac10952df2fd9663ad01b96ad88
pktriot-0.9.2-1.i386.rpm v0.9.2 RPM linux
x86-32
2 MB fa7e0de9dda4ca85b6903afcff69562403bc1a702301d7d02741591ee414e6a8
pktriot-0.9.2-1.x86_64.rpm v0.9.2 RPM linux
x86-64
2 MB 6732b34b17188f1e05f673cbcab31ed9757173810590682e262a365a3cfe8111
pktriot-0.9.2.amd64.tar.gz v0.9.2 Archive linux
x86-64
3 MB c0f094544f9778566d0cbfb25a99b2e43afc52f664bf78df3992379caeca3eff
pktriot-0.9.2.macos.tar.gz v0.9.2 Archive macos
x86-64
5 MB 6418072f05dc2d1a82600068a962582cdd81a9fe2aafe7126fb8df13696800bc
pktriot-0.9.2.win64.zip v0.9.2 Archive windows
x86-64
5 MB 465477758ec316838f05a7e3ec1475aef4bb8873159d80895ce94472b5942738

Installation & Setup

Please see the different sections for the various operating systems supported.

Linux

We have RPM, Debian and Archives that can be used for setting up and installing pktriot. The client program and some auxiliary files such as systemd service files are included. The service files can be used enable pktriot to be started during system boot or restarted automatically if there is a crash.

The RPM file will setup a user and group called pktriot. The system-wide configuration path, /etc/pktriot, will receive those ownership permissions. It's recommended that any users on the system be added to the pktriot group so they can add or modify traffic rules.

Installing via RPM can be done with the command below. There are additional example commands for adding your user to the pktriot group.

sudo rpm -Uvh pktriot-0.0.0.arch.rpm

sudo usermod -aG pktriot username
Installing via Debian can be done with the command below.
sudo deb -i pktriot-0.0.0.arch.deb

sudo usermod -aG pktriot username

When you install using an RPM or Debian you can use systemd to enable and start pktriot as a service. It's helpful to first configure and initialize the client using the system-wide configuration, /etc/pktriot/config.json, before enabling the service.

See client sections below for more information on setting it up.

MacOS

The client for MacOS is packaged in a tarball archive. It includes the client program a example launchd plist that can be used for launching the pkrtiot client as a user service or system-wide service.

The pktriot program should be copied to a location that is part of yours MacOS systems path, /usr/bin. Once its copied there it will be simple to execute from any working directory. You can use the Terminal.app program to copy the file there once you unarchive the tarball.

These commands below illustrate how to install it:

sudo cp pktriot /usr/bin

# for user launchd
cp pktriot.plist ~/Library/LaunchAgents

# for system-wide launchd
sudo cp pktriot.plist /Library/LaunchAgents

To enable launchd to start pktriot you'll want to use the following command:

launchctl load pktriot.plist

Use "sudo" when you are using the system-wide launchd location.

Windows

The client program for Windows is packaged in a zip archive. Currently there are not auxiliary files available for running it as a service. Please check back or email us to let us know if this feature is important to you.

Once you unpack the zip archive you can copy the pktriot program anywhere on windows system. More than likely you will want to put it in a place that is include in your PATH. This will make running pktriot in Powershell or CMD much easier.

Installing to the main C:\Windows directory will make the pktriot client program available for use any in Powershell or CMD.

Quickstart

Check our quickstart to setup an tunnel with the packetriot client (pktriot) and create an endpoint that is accessible to the rest of the Internet. You'll be able to authenticate your client, connect to the network and serve content in just a few steps.

Using the Client

pktriot is client program used to connect to the packetriot network. It's the software application used to establish your L7 endpoint that enables anyone on the Internet can access it. With the client you can identify it with your account and authenticate it to the network and then request traffic to routed to it.

Please see the sections on Domain Verification and System Description to dive it how packetriot actually works.

You can install the pktriot program on most operating systems: Windows, MacOS and Linux. It's available for different architectures on the Linux platform as well such as arm32 and arm64, so you can run it on Rapsberry Pi's. The program is a command line and works the same way on all systems.

There are many options for choosing the installation location of your client. The most simple is just install it on a PC or virtual machine that is hosting some service. It's very flexible since the client can forward requests to remote hosts, even if those hosts are just virtual machines, container or local compute resources on your private work.

Examples are useful to explain where you can install it. Let's say you have some virtual machines you're hosting on a single PC, or containers, then installing pktriot on the host machine can make sense. Once it authenticates with an edge server and and you request traffic to be routed to it, it can be forwarded to those VMs or containers.

The quickstart guide has some examples you can run to quickly get up and running or if you're curious about the commands to use connect.

Describing initializing the client, setting up servers, changing servers and configuring traffic relays.

Client Configuration

The first thing we need to after installing the pktriot client is configure it. This operation will it identify and authenticate you and create a new tunnel and secure token for that it. It will also ask you to choose a geography for the edge server you'll connect to.

If you location is static, choose a geography that's physically closer to you, that will help reduce latency between your client the server.

By default the pktriot client will prompt you to choose between the system-wide installation path or a local path for your user. If you choose the system path you'll want to use user/group permissions to enable your using to write to the system-wide configuration path, /etc/pktriot/config.json. You can run the pktriot client program using the sudo command, but setting up user/group permissions will be a cleaner approach.

Note, choosing the path in your users' home directory is the easiet and fastest approach for getting started. You can always copy the configuration file in ~/.pktriot/config.json to the system-wide directory and run it from there later.

The following commands provides an example flow for client confguration:

[user@host ~] pktriot configure

Please visit the URL:
Authenticate this client by visiting this URL:
https://packetriot.com/client/identauth/559bd756cec4f3611cd0075b90d075161....0f9f600d80f9330e55bc59cce4f

Identified and authenticated!

Choose the region for the edge server to connect to:
+-----------------+
| #   | Region    |
+-----------------+
| 1   | us-east   |
+-----------------+
| 2   | us-west   |
+-----------------+

Input selection [#]: 2

Once you finished authenticating your client and choosing an edge server you can give it a name. Using the following command to set a custom name.

[user@host ~] pktriot edit --name "hello world tunnel"
tunnel updated!

Now you're ready to connect to the packetriot network. You haven't setup any traffic rules but your client will be able to connect to the network and authenticate itself.

Tunnel Traffic Configuration

Your client should be setup to connect to the packetriot network through an edge server that you were assigned when the client is initially configured. Now you'll want to setup some rules request traffic to be routed to your client and serve locally on your computing resources.

Let's use some example scenarios to construct a few rules.

We have a personal blog website that we maintain using a static site generator like Hugo, Jekyl or Hyde. Once we finish editing our site, the HTML, CSS and other assets are generated and output to a directory, the web document roots.

We also have a NAS in our home that has dropbox-like features that allows us backup data, share files and acess through a mobile phone app. The NAS software has built in support for Lets Encrypt as well.

Finally, we have a machine that we'd like to connect to through SSH. We can check up on our resources in case we want to reconfigure them or maintain them remotely.

To make these services available to us, and others, we'll need to use the pktriot client program to construct a few rules. First we'll setup a rule for our static website.

The pktriot client allows us to service HTTP/S requets by forwarding to network services likes nginx or Apache, but it also has a built in file-server that can serve files over HTTP (TLS is not supported at the moment). To serve these files from a local path where the pktriot client is running we can use the following command.

[user@host ~] pktriot route http add --domain blog.example.com --webroot /path/to/static/webroot

This command will request to the edge server to route requests for blog.example.com to your client. Note, you will need to verify ownership of your domain prior to doing this. If you don't, the edge server will let you know that you need to. See the section below on DNS verification for more details.

blog.example.com will be served using the rources in the path specified. One thing to keep in mind that is that you cannot setup a rule that uses both a webroot and forwards to host/service. You must choose one of the methods.

Now we'd like to setup our NAS's dropbox software, using the domain drive.example.com. Our NAS supports LetsEncrypt, so we want to route both HTTP and HTTPS traffic. These following command will allow us to support both.

[user@host ~] pktriot route http add --domain drive.example.com --destination 192.168.0.123 --secure

By default the ports used when forwarding to hosts for HTTP and HTTPS are the standard ports, 80 and 443, respectively. You can override these defaults by using the --http and --tls flags. The --secure flag indicates that you want HTTPS as well as HTTP to be serviced by the edge server.

Finally, we want to connect to an server in our network using SSH so we can monitor and maintain our compute resources. For protocols like SSH that do not have a feature that allows us multiplex a port, an independently assigned port is used. First we request the edge server to allocate a port to us that. Then we setup rules to forward the traffic to our server.

[user@host ~] pktriot route tcp allocate
Allocated port 22872

[user@host ~] pktriot route tcp forward --port 22872 --destination 192.168.0.15 --dstport 22

The IP address for our SSH server is 192.168.0.15, so all requests to get forward there. You can use the hostname (*.pktriot.net) we assign you as the address to SSH to when you're on the Internet. Or if you have a domain setup with a A or CNAME reccords, you can use that custom domain as well.

SSH is used in many applications like git, or application that use git in the background. A non-standard SSH port like 22872 can break those applications, but there is a workaround that will allow you use SSH to your server seamlessly.

Edit the ~/.ssh/config file on the computer you're working on. You can replace the default port for hosts with the one packetriot allocate for you. Below is an example.

# custom domain example
Host example.com
	Port 22872

# pktriot.net hostname example
Host morning-breeze-95646.pktriot.net
	Port 22872

You're ready to start your client and serve up access to these resources. You can begin by running the command below. It'll display all of the services you've setup. If there are any that cannot be served, it'll let you know which ones those are.

[user@host ~] pktriot start


Running HTTP services:
+-------------------------------------------------------+
| Domain                              | Destination     |
+--------------------------------------------------------
| blog.example.com                    |                 |
+--------------------------------------------------------
| drive.example.com                   | 192.168.0.123   |
+-------------------------------------------------------+
Running TCP services:
+----------------------------------------+
| Port    | Destination    | Dest Port   |
+----------------------------------------+
| 22253   | 192.168.0.15   | 22          |
+----------------------------------------+

Have fun!!

Dashboard

The dashboard is the homepage for packetriot. It will list the tunnels that are currently active or ones that have been shutdown. There will be high-level metrics and information about the tunnels that are currently running, like the amount of data that has been transfer for the day or month, whether its currently online and connected to its assigned edge server, and its uptime.

You'll find the main navigation bar at the top of the page. With the navbar you can visit your account settings and billing details. A links to documentation page is here. You'll also find a status page that gives you a auto-refreshed picture of all the tunnels that are active and running. Finally, the domains page is where you'll find all the custom domains you've verified ownership of, and a page to enable you to verify any additional ones.

Describing initializing the client, setting up servers, changing servers and configuring traffic relays.

Tunnels

The tunnel page lists all of the active tunnels and ones that have been shutdown. An active tunnel is one that is assigned to server. Tunnels can be shutdown and deleted. A tunnel that has been shutdown means that its ability to connect and authenticate to the servers its been assigned has been removed. You won't be able to reconnect the tunnel, but your data and metrics will be intact and viewable. When a tunnel is deleted, the metrics and other information associated to it will also be deleted.

Click a tunnel will being you a detailed page with three sections. You'll see all the HTTP/S and TCP traffic rules you've configured through the pktriot client. You'll also see the individual metrics on bandwidth consumed by those servies.

The access page will give you information about the hosts on the Internet is connecting to your tunnel and the services behind it. Primarily the IP address of the host is available, but a timestamp and the amount of data transferred over that session is also available.

The access page is only available to members who have the Pro or higher plans.

The tunnel status page is displays the health information about the services that the pktriot client is forwarding traffic to. It's similar to a ping test. Members with the Pro or higher plans enjoy a periodic connectivity on their services and an alert, email, when those tests fail consecutively in a short period of the time.

The active marker on services indicates that its still a servcie that is being served. As you add and remove traffic rules for your tunnels, we keep the data associated to traffic that are no longer requested by your client. The data is still there, but the traffic is marked as inactive.

Status

The main status page is a high-level overview of the tunnels that are actively running and connected to edge-servers. The statistics on the traffic rules configured and the uptime of your tunnel is displayed. This page is refresh periodically so that you can have visual dashboard to view all interesting metrics across all of your tunnels in one page.

Domain Verification

The domain page displays all of the custom domains that you have verified ownership of. An important question to ask is why do we verify custom domains?

The reason we do this is that a bad actor could potentially connecto the same tunnel as you and request your custom domains. That would enable them to impersonate you and serve malicious content. In an effort to prevent that we have this system to verify a custom domain is owned by a user and use that to actually serve traffic to the right tunnels.

The process works by first clicking the Verify Domain button. It will provide a form where you input the name of your domain, e.g. example.com. You can put in a subdomain like blog.example.com, but it will be reduced to the root. This is keep it simple and reduce the number of times you need to repeat this activity.

A secure token is generated with the format pktriot=1283...394374. A DNS TXT record needs to be created where the host is the root, typically identified using the "@" symbol and the value being the entire token.

Packetriot will check for the existence of this record every few minutes and once it can validate that a DNS TXT record with the token value exists, it will confirm ownership of the domain to you.

Account Settings

The account setting is standard and allows using to indicate their and mobile phone number. Your full name is not used for anything and but it gives us something to address you when we send emails. We currently do not support two-factor authentication for some operations, but in the future we may, and so you're mobile phone can be updated here as well.

If you need to change your password, this page can be used for as well.

The account billing page is access through the account settings page. On this page you'll find the details of your selected plan. You can change your plan up to twice a month.

You'll find your currently bandwidth consumption and also a list of past billing statements.

Managed Services

Managed services provide different tiers of functionality and support, and do not require users to manage their own servers. It's the quickest, easiest and least expensive method for instantiating globally accessible secure endpoints.

Billing

Users are billed at the beginning of each period, the first day of the month. The end of the period is the last day of the same month. The amounts billed are pro-rated if you joined somewhere in the middle of the month. Note, plan changes are pro-rated as well.

A statement is generated for the user and a charge is made to their card on file. All charges are processed through Stripe. We don't store any payment details, just the information necessary so we can accept payments through Stripe.

At the end of the period the statement is updated with total bandwidth consumption for the period. Any adjustments due to over-consumption will be included in the end as well.

Plans

Packetriot include 4 plans that can be used at the moment. Users can change plans twice a month, but no more. When you upgrade your plans, a pro-rated difference is charged to your account. When you downgrade your plan no changes are made. The new plan's price will be used on the next periods statement.

Cancellation

Cancellations are performed by just switching your plan to free. If you're unhappy with your service please let us know. We'd like to improve the experience and utility of the service.

Self-managed Licenses

This service is coming soon...

With a self-managed license, users can run their own servers and host the same edge-server software that is used with managed service plans. Some of the integrated functionality such as service-health checks, outage notifications, and access logs are not available. However, the metrics and other traffic data that is normally collected will be available.

More information on self-managed servers will be coming soon. Contact us if you have any questions.

Downloads Documentation Contact Us