Documentation & User Guide

Introduction Use Cases Quickstart

Introduction

Packetriot uses a secure tunneling protocol to expose servers on local or private networks to the Internet. It's quick and easy to host a website, side-project, or self-host applications; like file-sharing or messaging, on your existing Internet service.

These tunnels are establish in reverse so they work behind NATs and Firewalls. You can change networks and all your services will still work, no configuration changes required.

Tunnels connect to Packetriot servers using TLS. Any services you expose that also use TLS are transparently proxied over that connection to the server. Effectively, incoming client connections to your services enjoy two layers of encryption.

Let's Encrypt is supported out of the box with our client or you can bring your own certificates.

Each tunnnel is assigned a unique, persistent hostname. For example: bold-wave-1234.pktriot.net. The hostname, and its subdomains, can be used as aliases for customs domains. Each tunnel connects to the same server until you reconfigure it, so the IP address of the server can be used for setting up DNS A records.

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.

Do you want to self-host applications similar to Dropbox, a private music streaming server, or host a blog? You can easily do that with Packetriot and overcome the obstacles of hosting services using your consumer Internet service.

Packetriot supports so many different use-cases, check out our blog for tips and example projects.

Client Software

Downloads

Filename Version Kind OS/Arch Size Hash (sha256)
pktriot-0.9.5.arm32.tar.gz v0.9.5 Archive linux
arm32
4 MB ce6e7021ce7d5b78dfef3e93f2a70690fe60b601ebff97e11117ff17daba1a1b
pktriot-0.9.5-1.arm32.rpm v0.9.5 RPM linux
arm32
4 MB 795e324482c081eef8e482c7600d7c784b34555ee8c7e580cb2f02679dcb2c9c
pktriot-0.9.5-1.arm64.rpm v0.9.5 RPM linux
arm64
4 MB c0614737b39e05f6d064dbda9360c6c2a7107c190d28a3de05fd3ca72a364d8b
pktriot-0.9.5.arm64.tar.gz v0.9.5 Archive linux
arm64
4 MB 307f6c67b23c165a145d93a60e9623eb7bcced05ca9fa37cbda84f302d0ab1c7
pktriot-0.9.5.i386.tar.gz v0.9.5 Archive linux
x86-32
5 MB 2d205d7a7fe1102a190d42633a16d2c380ea1d83ba99d42d3e48ae4f8c63c014
pktriot-0.9.5-1.i386.rpm v0.9.5 RPM linux
x86-32
2 MB 1cdcadd044289d37903ef6b286af717afc21e18dd0a4334ab3d9c8652bc5ca87
pktriot-0.9.5-1.x86_64.rpm v0.9.5 RPM linux
x86-64
2 MB 5b38efca398c9a0b58ce9060d9bc7acfcefe479a9cfb1995a30891f993feab41
pktriot-0.9.5.amd64.tar.gz v0.9.5 Archive linux
x86-64
3 MB 3820d78be931b65b07135addcdf2d9b91675bea9489755d1a2ba0490e939f52b
pktriot-0.9.5.macos.tar.gz v0.9.5 Archive macos
x86-64
5 MB 8d2d7b0e4901658b728e2fff70ddd3261892563aa6effac695c4d1b37db31cee
pktriot-0.9.5.win64.zip v0.9.5 Archive windows
x86-64
5 MB d4394a6cab8bbf96aaef9bfbb854008d58c253f2d6c8911d278ce56f96cc190e

Container Images

Using Docker? Pull our container image packetriot/pktriot:latest. We currently only support x86-64 images.

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.

Docker

Pull the container image down first. Using the container is the same as the normal client but you'll need to prepend commands with docker exec -it container-name. It's important to use the flags -it since some commands require your input.

The sections will below will describe more use-cases for the client, but I'll provide some examples below to illustrate the differences here when using the container.

# fetch the image
[user@host ~] docker pull packetriot/pktriot:latest

# create an unconfigured container to run continously
[user@host ~] docker run -id --restart always --name hello-world packetriot/pktriot:latest

The main directory inside the container is /data. This is where the pktriot configuration and certificates from Lets Encrypt are stored. Custom certificates should be copied here. For example: docker cp example.com-ca.pem example.com-privkey.pem container-name:/data

Mounting /data can be advantageous when the tunnel was created for long-term use and you may want to be able to move tunnel configuration and data to some other location.

Mounting /data can be also useful for serving static sites in the container but generating the content on the host.

[user@host ~] docker run -id --restart always -v /path/to/hello-world-data:/data --name hello-world packetriot/pktriot:latest

These are examples for configuring and creating rules with the container. After any changes to rules, or (re)configuration, you'll need to restart the container.

[user@host ~] docker exec -it hello-world pktriot configure
...
[user@host ~] docker exec -it hello-world pktriot route http --add example.com --webroot /data/example.com
...
[user@host ~] docker restart hello-world

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 used in the following work-flow: 1) configuration, 2) setting up rules, 3) updating rules, 4) running the tunnel.

The sections below will describe in more detail these actions.

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