Pinggy uses the reverse tunneling feature provided by the secure-shell (
ssh) program. One can use any
ssh program as long as it provides the reverse tunneling feature. However, we recommend using
openssh whenever possible.
Pinggy utilizes different features of the
ssh protocol to provide different functionalities like web debugging, header manipulation, authentication, etc.
We directly use the options provided by the
ssh command to set the tunnel and enable the live debugging.
Tunnel tokens and a few keywords are sent as the username. Few command line options to configure different options for the tunnel.
Let’s start with basic ssh options:
Detailed usages are available on
ssh man page at https://man.openbsd.org/ssh
ssh -p 443 -R0:<localhost>:<localport> [<token/keyword/tunneltype>@]a.pinggy.io <remote options>
Expose a local service running on localaddress:localport to remoteport. There are multiple variations of reverse tunneling. However, Pinggy supports only this version.
Pinggy ignores the remote port and assigns a domain name and port as per the subscription and tunnel type.
Remote server port. By default
Force pseudo-terminal allocation. By default
Pinggy uses pseudo-terminal to provide a rich interface like this.
One can disable rich CLI using
|Disable pseudo-terminal. Pinggy works without a pseudo-terminal and provides basic information.|
Disable remote command execution.
Pinggy uses remote command execution to enable advanced functionalities including web debugging, header manipulations, and many more. It is not recommended to use this flag.
Enable local forwarding. It enables
Pinggy only allows forwarding to port 4300. Where it provides web debugging UI.
Pinggy does not require any username or authentication to start the tunnel as it does not provide any access to the server. However, this information goes to the server before
ssh could establish the connection. So, we use the username to send tunnel
token and other keywords to the server.
token can be found in <dashboard.pinggy.io>.
token and keywords are separated by
+. Pinggy has following keywords:
These keywords set the tunnel type. The default tunnel is the
http tunnel works only with the HTTP server. Pinggy provides links for both HTTP and HTTPS, however, it terminates traffic at the server and read it to provide live debugging and other functionalities. Any
http tunnel comes with the following functionalities.
http tunnel can be started using
ssh -p 443 -R0:localhost:<localport> a.pinggy.io
ssh -p 443 -R0:localhost:<localport> <token>@a.pinggy.io
tcp tunnel is the simplest form of tunnel. It simply forward incoming data without doing any kind of processing.
tcp tunnel also provides a server port. All the
tcp tunnel also comes with IP White Listing functionality.
tcp tunnel can be started using
ssh -p 443 -R0:localhost:<localport> firstname.lastname@example.org
ssh -p 443 -R0:localhost:<localport> <token>+email@example.com
tls tunnel is equivalent to
tcp tunnel with only one exception, the server does not allocate any TCP port, instead it forward incoming SSL/TLS traffic based on the
server name indication or
SNI. Instead of terminating a TLS/SSL traffic in
tls tunnel, a Pinggy server forwards the traffic as it is to the client.
tls tunnel can be started using
ssh -p 443 -R0:localhost:<localport> firstname.lastname@example.org
ssh -p 443 -R0:localhost:<localport> <token>+email@example.com
In perspective with privacy, a
tls tunnel is the most private tunnel where Pinggy can’t even look at the tunnel content. It also makes it hard for the client, as it has to handle everything about the TLS.
tlstcp tunnel is a
tcp tunnel with an option to
tls wrapper for the visitor. It provides a TCP port where the Pinggy server listens for incoming TCP connections and forwards the content as it is to the client. It also provides a
tls URL, where it listens at port 443 and terminates the incoming SSL connection and forward the plain text content to the client.
tlstcp tunnel can be started using
ssh -p 443 -R0:localhost:<localport> firstname.lastname@example.org
ssh -p 443 -R0:localhost:<localport> <token>+email@example.com
tlstcp is similar to
tcp tunnel with a convenience for visitors to connect to Pinggy server with an SSL connection.
It will allow a visitor behind a firewall to connect to a TCP-based service hosted on the Pinggy.
Passing multiple tunnel types is not recommended. The behavior is undefined.
Pinggy provides an option to display a QR Code with the URL in the terminal. The
qr key display a smaller unicode base QR Code on the terminal while
aqr draws a larger ASCII-only QR code. Start a
http tunnel with QR Code as follows:
ssh -p 443 -R0:localhost:<localport> firstname.lastname@example.org
ssh -p 443 -R0:localhost:<localport> <token>+email@example.com
Pinggy by default tries to start a tunnel without any authentication. However, it may not works always due to the limitation of some ssh client (e.g. dropbear) implementation. Use
auth keyword to stop this behavior. With this keyword, a client may ask for a password, kindly provide 0000 (or any string).
force keywords to forcefully disconnect existing tunnel with the same token before creating a new connection Use it as follows:
ssh -p 443 -R0:localhost:<localport> <token>@a.pinggy.io
It is useful only with token based connection.
Pinggy has options to configure live HTTP header manipulation, HTTP authentication, and IP whitelisting in the command line only. Syntax for a command line option is as follows
Here is the list of command line options.
It will add a header with
HeaderValue with every HTTP request. One can put as many add the header as one want.
It would remove every header with the header name
HeaderName from the HTTP request. Redunt remove header commands are silently ignored.
It is the combination of remove header and add header commands. It would remove every header with the header name
HeaderName and put a new header with the header name
HeaderName and value
Pinggy supports basic authentication for the visitor. It is username-password-based authentication that a browser asks for while visiting the website. The syntax to set basic authentication is as follows
It never sends basic auth to the client.
Key authentication is a mechanism where a visitor send an
Authorisation header with the value
Bearer <key>. The request will be passed to the client only if the Key matches the provided one. The syntax to set the key is as follows:
Basic authentication and key authentication can be used together.
IP White Listing is a feature where visitors from certain
IP addresses are allowed to connect. It ignores requests from other IP addresses without responding.
The syntax to set IP white list is as follows
Kindly note that a Pinggy server does not run any command in the remote server. It uses command line options to configure the tunnel.