Quickstart

Welcome to our quickstart guide. Links are below for commonly used client packages. We also have package repositories for apt, yum and dnf. Installation and updates for major Linux distributions will be a breeze if you set them up on your system.

Visit our downloads page to see all all the operating systems and architectures our client supports. Also, if you haven't already setup an account, please sign up, it's necessary for setting up our client.

If you're familiar with administering Linux/Unix operating systems, virtual machines, or containers this quickstart guide should be straight-forward.

If you want to use a container those specific instructions are in the Packetriot Client section of our documentation. It's not much different but there are small nuances.

Follow us on Twitter @packetriot for announcements of updates to the client and other services.

Download

Below are quick links to popular operating systems and packages.

Linux x86

Linux ARMv7 (Raspberry Pi 1/2/3/zero and similar SBC)

Linux ARMv8 (Raspberry Pi 4)

Install

The steps below are assuming you used the manual download links above. Use the following commands for the respective client packaging you downloaded.

RPM

sudo rpm -Uvh pktriot-<version>-1.<arch>.rpm

Debian

sudo dpkg -i pktriot-<version>.<arch>.dev

Tarball

tar zxvf pktriot-<version>.<arch>.tar.gz
cd pktriot-<version>

Zip

Put picture here of right-clicking and selecting "Extract to..." and then choosing a directly.

Configure

The Packetriot client can be configured to work in a few different use-cases. You can set it up for system-wide use or for user-only. If you're using your tunnel for intermittent hosting and testing, then you want user-only.

For more persistent hosting configure the tunnel for system-wide. Read our more complete documentation in the Packetriot Client section of our docs for information on persistent 24/7 hosting.

What's the difference? The only difference is that the system-wide configuration uses the pktriot user to run the client, so you need to configure rules as that user sudo su pktriot.

User-only is the basic user that you log into your system as, e.g. jack, jill, cubsfan70. In the quickstart guide we've logged in as our basic user account, so we are configuring our tunnel for our own use.

Run the command pktriot configure and choose option [3] which will save the configuration file in your home directory /home/user/.pktriot. Authenticate with your credentials and choose a region that's closest to you.

Did you use your Google account to create an account with Packetriot? Use pktriot configure --url to configure your tunnel with Google SSO.

[user@host] pktriot configure
Choose a path to the configuration file:
[1] /etc/pktriot/config.json
[2] /data/config.json
[3] /home/user/.pktriot/config.json

Input selection [#]: 3

Authenticate client with login credentials:

Email: new.user@domain.com
Password: 
Authenticated!

Choose the region for the edge server to connect to:
+------------------------+
| #   | Region           |
+------------------------+
| 1   | us-east          |
+------------------------+
| 2   | us-west          |
+------------------------+
| 3   | eu-central       |
+------------------------+
| 4   | asia-southeast   |
+------------------------+

Input selection [#]: 1

Tunnel configuration:
  Hostname: awesome-tunnel.pktriot.net
  Server: us-east-63815.packetriot.net
  IP: 138.197.66.62

Start the tunnel and visit URL to check its working:
  pktriot --config /home/user/.pktriot/config.json start
  https://awesome-tunnel.pktriot.net

Detailed help and step-by-step tutorials:
  https://packetriot.com/docs
  https://packetriot.com/tutorials.

Need more support?
  Email: packetriot@gmail
  Twitter: @packetriot (please follow us, we like new friends :)

You'll be provided some details about the tunnel printed in the output. This information is always available and can be printed out again at any time by running pktriot info.

Note, you don't need to specify --config /path/to/config.json if you use any of the default paths presented when you ran pktriot configure.

Give the tunnel a name, it'll be easier to discern which tunnel is which in the dashboard.

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

Verify Working Tunnel

Before adding rules verify that the tunnel is operating correctly. By default a tunnel with no persistent HTTP/TCP traffic rules will display a welcome page. This page will be available using the hostname that is assigned to your tunnel. This hostname does not change.

[user@host] pktriot start

In our example we would visit https://awesome-tunnel.pktriot.net in our browser.

HTTP

The Packetriot client supports HTTP and TCP traffic. In addition, if you have a basic plan or higher, you can setup firewall rules to filter traffic sources.

We'll be focusing on HTTP which is a primary use-case for most users. Check out our more complete documentation for details on the other cool features our client provides.

Instant Hosting

Many times you will want to host a website or application instantly to view changes, test a modification or share to a colleague. Your application may have static content and an API or be a dynamic web application. Instant hosting supports all these scenarios.

This command assumes we want to host static assets and a server listening on port 8080.

[user@host:~/project] pktriot http 8080 --webroot ./assets

If your server is started using something like npm, Python or is a compiled application. You can kick it off as a child process that the Packetriot client will manage. We can use the --exec flag to specify the command to run.

We'll use npm in our example below, it's default serving port is 3000 and we would normally execute the command npm run to serve it locally.

[user@host:~/project] pktriot http 3000 --webroot ./assets --exec "npm run"

Persistent Traffic Rules

The Packetriot client can save traffic rules so that you don't need to continually re-enter them. For hosting scenarios that are consistent this is useful. In addition, the rules you can setup have more options such as the ability to setup password protection on HTTP/S services, Let's Encrypt certificate management, firewall rules and more.

pktriot tunnel is the base command for setting up these traffic rules. We'll dive into some examples below. There's more detail in the Packetriot Client section in our documentation.

Packetriot does supports custom domains, however, there's a few steps to walk through so we can set them up. Visit our detailed documentation to learn those steps.

In the examples below, we'll use the hostname https://awesome-tunnel.pktriot.net that was assigned to our tunnel. pktriot start will authenticate, create a tunnel and then request traffic using the persistent traffic rules you saved earlier.

Changes to those rules will require the client to be restarted to take effect.

Reverse Proxy

In this scenario you're running a server, micro-service or web application that you're developing locally on your PC or laptop. You can just an easily be hosting any open-source web application or server.

Similar to our NodeJS server example earlier, let's create a traffic rule that sticks.

The domain we want to access our server is the hostname we were assigned, so we wil use that. Our NodeJS server is listening on port 3000 so we'll use the flag --http 3000 to indicate that. --destination indicates the IP address of the host 127.0.0.1 or can be a hostname localhost.

We are also serving static assets so will use --webroot $PWD/assets. Note we're assuming we are in our project directory. With $PWD an absolute path to the assets will be saved.

[user@host:~/project] pktriot info
Client:
    Hostname: awesome-tunnel.pktriot.net
    Server: us-east-63815.packetriot.net
    IP: 138.197.66.62

[user@host:~/project] pktriot tunnel http add --domain awesome-tunnel.pktriot.net \
    --destination 127.0.0.1 --http 3000 --webroot "$PWD/assets"

HTTP/S traffic rule added

[user@host:~/project] pktriot start
Connecting...

Running HTTP services:
+-----------------------------------------------------------------------------------------------------------------------+
| Domain                           | Destination   | HTTP   | TLS   | Secure   | Protect   | Site Root                  |
+-----------------------------------------------------------------------------------------------------------------------+
| awesome-tunnel.pktriot.net       | 127.0.0.1     | 3000   | 0     | true     |           | /home/user/project/assets  |
+-----------------------------------------------------------------------------------------------------------------------+

By default HTTPS is setup, along with secure-redirect, which means all HTTP traffic will be redirect to HTTPS.

The TLS column in the table printed out shows a value of 0. I just said HTTPS is set, why is it 0 then? I'll explain quickly.

We have two flags in the tunnel http add command to specify HTTP and TLS (HTTPS) ports: --http and --tls. It should be clear that --http is proxying to an upstream HTTP server listening on port 3000.

We use --tls for transparent TLS proxying. Most users will never use this flag since the Packetriot client supports Let's Encrypt and that's a convenient option. However, if you need to transparently proxy HTTPS traffic to a server already configured with TLS certificates then use this flag --destination a.b.c.d --tls 443.

Our detailed documentation for more information and use-cases.

Protected Websites

Let's say we want to password protect the server we're hosting. Note, this will add an extra layer if your application already has an authentication mechanism.

[user@host:~/project] pktriot tunnel http add --domain awesome-tunnel.pktriot.net \
    --destination 127.0.0.1 --http 3000 --webroot "$PWD/assets" \
    --password

Warning: existing rule entry for 'awesome-tunnel.pktriot.net' will be overwritten.
Input password for session-based authorized traffic
Password: 

HTTP/S traffic rule added

Notice that we warned about overwriting an existing rule. Now when you visit the URL https://awesome-tunnel.pktriot.net in your browser, you'll have to now enter the password to continue.

Subdomains

Need to host more then once website? You can create sub-domains with the hostname we assign the tunnel. You will receive HTTPS warnings in browsers or clients that enforce proper PKI and certificate management.

It's important to note that there are no limits to the number of HTTP services that can be served behind a single tunnel.

All hostname have a wildcard CNAME record to resolve to hostname assigned, e.g. *.awesome-tunnel.pktriot.net will also resolve to awesome-tunnel.pktriot.net.

Let's say we have two more servers running locally, listening on port 8080 and 8081 respectively. 

[user@host:~] pktriot tunnel http add \
    --domain app-01.awesome-tunnel.pktriot.net \
    --destination 127.0.0.1 --http 8080

[user@host:~] pktriot tunnel http add \
    --domain app-02.awesome-tunnel.pktriot.net \
    --destination 127.0.0.1 --http 8081

You can list all of your HTTP/S traffic rule with the command pktriot tunnel http ls.

[user@host:~] pktriot tunnel http ls

+-------------------------------------------------------------------------------------------------------------------------------------------+
| Domain                              | Destination   | HTTP   | TLS   | Secure   | Protect    | Site Root                                  |
+-------------------------------------------------------------------------------------------------------------------------------------------+
| awesome-tunnel.pktriot.net          | 127.0.0.1     | 3000   | 0     | true     | Password   | /home/user/project/assets                  |
+-------------------------------------------------------------------------------------------------------------------------------------------+
| app-01.awesome-tunnel.pktriot.net   | 127.0.0.1     | 8080   | 0     | true     |            | --                                         |
+-------------------------------------------------------------------------------------------------------------------------------------------+
| app-02.awesome-tunnel.pktriot.net   | 127.0.0.1     | 8081   | 0     | true     |            | --                                         |
+-------------------------------------------------------------------------------------------------------------------------------------------+

File Directories

Need to share some files quickly. You can do and setup some password protection to keep a random visitor from downloading your files.

[user@host:~] pktriot tunnel http add --domain awesome-tunnel.pktriot.net \
    --webroot /path/to/files \
    --password

Input password for session-based authorized traffic
Password: 

HTTP/S traffic rule added

You can share the URL https://awesome-tunnel.pktriot.net to anyone, along with the password you set, and they'll be able to authenticate and browse the files in the directory path you specified.

Conclusion

There are some quick examples to get you up and running. There are many hosting scenarios that Packetriot can support.

We didn't touch on custom domains, integrating Let's Encrypt, generic TCP relaying and Firewall rules.

We also have self-hosted version of our edge-server called Spokes. It works identically with the Packetriot client and runs on your server. It's great if you want to programmatically manage a fleet of Packetriot tunnels.

Visit our detailed documentation for the Packetriot Client and Dashboard to learn more about all the features available on Packetriot.