Getting Started

SocketXP is a cloud based SaaS service that empowers web applications running in your local network, behind the firewall and NAT, to securely communicate with web applications running in the cloud or the internet.

SocketXP creates a secure and unique public endpoint (URL) for your localhost web applications, through which online services could talk to your localhost web applications.

For the SocketXP service to work, you need to download and install a lightweight SocketXP agent to run on your local host machine.

Installation:

Download and install a simple SocketXP agent to run on the localhost server where your web application also runs.  SocketXP agent is a CLI utility with which you could configure and create tunnels to your localhost web application or service.  A single SocketXP agent process could create any number of tunnels on the same host machine, limited only by your subscription plan.

Linux:

$ curl -O https://portal.socketxp.com/download/linux/socketxp && chmod +wx socketxp && sudo mv socketxp /usr/local/bin

MacOSX

$ curl -O https://portal.socketxp.com/download/darwin/socketxp && chmod +wx socketxp && sudo mv socketxp /usr/local/bin

Windows

https://portal.socketxp.com/download/windows/socketxp.exe

Windows (32 bit)

https://portal.socketxp.com/download/windows32/socketxp.exe

ARM

$ curl -O https://portal.socketxp.com/download/arm/socketxp && chmod +wx socketxp && sudo mv socketxp /usr/local/bin

ARM(aarch64, arm64, v8)

$ curl -O https://portal.socketxp.com/download/arm64/socketxp && chmod +wx socketxp && sudo mv socketxp /usr/local/bin

Docker Container

$ docker pull expresssocket/socketxp

Create a config.json file in your local directory and map it as a volume inside the container at /data direcotry as shown in the example below.

$ docker run -d  -v /tmp/my_data:/data expresssocket/socketxp

25ad610483f7a324858b79f94de5356c37b3997abc8d105d0eb8ca004c27ec54
$ docker logs 25ad
Using config file: /data/config.json
Login Succeeded.
User [] Email [test-user@gmail.com].

Connected.
Public URL -> https://test-user-gmail-com-33323.socketxp.com

Here is the content of a sample config.json file.

$ cat /tmp/my_data/config.json

{
    "authtoken": "",
    "tunnel_enabled": true,
    "tunnels" : [{
        "destination": "https://172.10.0.1:8123",
        "protocol": "http",
        "custom_domain": ""
    }],
    "relay_enabled": false,
    "relays": [{
    "destination": "https://172.10.0.1:8123"
    }]
}

If you want to configure TLS tunnels then use the below config.json file.

$ cat /tmp/my_data/config.json

{
    "authtoken": "",
    "tunnel_enabled": true,
    "tunnels" : [{
        "destination": "https://172.10.0.1:8123",
        "protocol": "tls",
        "custom_domain": "dev.example.com"
    }],
    "relay_enabled": false,
    "relays": [{
    "destination": "https://172.10.0.1:8123"
    }]
}

Where “172.10.0.1” is the IP address of the other docker container running your web application (Eg; Jenkins server or Home Automation server or nodejs app)

Verify Installation:

After installing the SocketXP agent, check if it works.

$socketxp

Usage: socketxp [OPTIONS] COMMAND

Socketxp - secure tunnels to your localhost servers.

SocketXP is a cloud based SaaS service that empowers web applications running in your local network, behind the firewall and NAT, to securely communicate with web applications running in the cloud or the internet.

By using this product, you are agreeing to the terms of SocketXP Ltd. Terms of service can be found at: https://www.socketxp.com/tos/

Don't have an account? Create a free account here: https://portal.socketxp.com/#/login

If you have any questions or security related issues, please contact us via email: support@socketxp.com.

Options:

--help             Print usage

--no-auto-update   Disable SocketXP agent software auto-update feature

--use-system-dns   Use the system's DNS to resolve domain names;

default is Google's DNS

Commands:

connect     Connect the supplied local destination to the public endpoint

login       Login to the SocketXP service.  Obtain an auth token from https://portal.socketxp.com

relay       Relay webhook notifications from the public endpoint to the localhost webhook supplied

Run 'socketxp COMMAND --help' for more information on a command.

SocketXP Linux Daemon

For production, it is better to run SocketXP agent as a daemon service. SocketXP can be installed as a linux systemd daemon service. Here are the steps.

Follow the instruction above to first download and install the linux SocketXP agent in your /usr/local/bin directory.

Install the daemon

Create a config.json file (Refer to the sample config.json file shown in the Docker example above) in your home directory and execute the below daemon service install command.

$ sudo socketxp service install --config /home/test-user/config.json

Reload

$ sudo systemctl daemon-reload

SocketXP will come up as a daemon service.

Status Check

Check the status of the SocketXP daemon service using the below cli.

$ sudo systemctl status socketxp

If you want to check the logs from the SocketXP daemon to find the public URL, execute the following command using the “journalctl” command.

$ journalctl -u socketxp.service -f

Note: systemctl , journalctl are linux commands/utilities.

Start/Stop the service:

$ sudo systemctl start socketxp
$ sudo systemctl stop socketxp

Uninstall

To uninstall, first stop the service. Then uninstall using the socketxp CLI.

$ sudo systemctl stop socketxp

$ sudo socketxp service uninstall

Authentication Token:

Sign up at https://portal.socketxp.com and get your authentication token.

SocketXP Portal - Authtoken

Use the authentication token to authenticate the SocketXP agent with the SocketXP Cloud Service, as shown below.

$ socketxp login "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NDk1MTg0MDAsImlkIjoiZ2FuZXNodmVscmFqYW5AZ21ha6K208n0.cB2uYevpH4lWIQGQUJdQ0eiEDqS8OiP_YOiqernnui3rjjadfadsfsfas34"

HTTP Tunnels:

Make your localhost web application or web server go online, by creating a HTTP tunnel using the SocketXP agent.  Here is the SocketXP command to create a HTTP tunnel endpoint.

$ socketxp connect http://localhost:8000

Public URL -> https// john-gmail-com-234234.socketxp.com

Where 8000 is the tcp port on which your localhost web application is listening for HTTP requests.  Use the public URL provided in the output above to access your localhost web application from anywhere in the internet.

Note the “https” in the SocketXP public URL created above.  Even though the localhost web application doesn’t have the capabilities to encrypt the data it transfers,   (meaning, it is just a plain HTTP server and not a HTTPS server ), we provide the SSL encryption on behalf of the localhost web application.

SocketXP always encrypts the data while transmitting over the internet.  We never send anything unencrypted over the internet. Customer data security is the heart and soul of our business.

Only the data exchanged between SocketXP agent and your local web application will be a clear-text data transfer(because your web application doesn’t support HTTPS), and the data transfer happens within the realm of your local server or local network.

HTTP Tunnels with Custom Subdomain

SocketXP public URLs with random subdomain name (your email-id plus some random number) is good for quick testing. But for production or for sharing your URL publicly with others, it is nice to have a subdomain that makes sense and easy to remember.

Use the “–subdomain” option in the above command to get a SocketXP public URL with your preferred subdomain name.

$ socketxp connect http://localhost:3000 --subdomain database

Public URL -> https://database.socketxp.com

Note: Subdomains are assigned to users from a free pool of available subdomains. Subdomains are not reserved resources. It will be recycled automatically, if it is found not being used by a user.

HTTP Tunnels with Custom Domain (White-Label URLs)

Instead of your tunnels appearing as a subdomain of socketxp.com domain, you could run your HTTP tunnels on your own domain.  It’s a two step process.

First, execute the following SocketXP command to create a HTTP tunnel, for example, over “devops.example.com”,

$ socketxp connect --white-label-domain devops.example.com http://localhost:5000

Public URL -> https// john-gmail-com-235637.socketxp.com

Next, use the above SocketXP public URL to create a DNS CNAME record for “devops.example.com” and point it to “john-gmail-com-235637.socketxp.com”.  Please check with your DNS provider on how to configure a DNS CNAME record for your custom domain.

Thereafter, you could use the public URL “https://devops.example.com” to access your web service.

HTTPS Tunnels

If your web application has the capabilities to encrypt and decrypt HTTP traffic using its own SSL certificate and key, then you could create a HTTPS tunnel, as  shown below.

$ socketxp connect https://localhost:8000

Public URL -> https// john-gmail-com-234234.socketxp.com

Now the data exchanged between SocketXP agent and your localhost web application will also be encrypted, in addition to the data transferred over the internet.  This capability is extremely important if your local network is unsafe for clear text data transfer.

Please note that the data transferred through HTTPS tunnel is encrypted hop-by-hop and not end-to-end. HTTPS tunnels are good for development and testing purposes but for production you should create SSL/TLS tunnels with end-to-end encryption capabilities.  Read the next section about TLS tunnels to know more about configuring end-to-end SSL/TLS tunnels using SocketXP.

SSL/TLS Tunnels

HTTPS tunnels terminate all SSL/TLS traffic at the SocketXP Cloud Servers using socketxp.com SSL certificate and key.  For production-grade services or anything that involves sharing sensitive information, such as authentication token or financial data, you’ll want your traffic to be tunneled through SSL/TLS tunnel, which encrypts data traffic end-to-end with your own SSL Certificate and Key.  SocketXP supports TLS tunnels and it is extremely easy to set it up.

$ socketxp connect --tls-e2e https://127.0.0.1:443
Public URL -> https://john-gmail-com-78372.socketxp.com

Make sure, your web application running at https://127.0.0.1:443 has the proper SSL certificate and key setup.

Now, try accessing the public URL above with curl utility.

$ curl --insecure https://john-gmail-com-78372.socketxp.com

TLS end-to-end tunnels without certificate warnings

In the previous curl command example, “–insecure” option is required so that we can ignore certificate warnings. You need to specify that because your local HTTPS server doesn’t have the TLS key and certificate necessary to terminate traffic for any socketxp.com subdomains. If you try to load up that page in a web browser, it will ask you to add an exception.

If you want your certificates to match and be protected from man-in-the-middle attacks, you need two things. First, you’ll need to buy an SSL certificate for a domain name that you own and configure your local web server to use that certificate and its private key to terminate TLS connections. How to do this is specific to your web server and SSL certificate provider and beyond the scope of this documentation. For the sake of example, we’ll assume that you were issued an SSL certificate and key for the domain “devops.example.com”.

Once you have your key and certificate, it’s time to run an end-to-end TLS tunnel on your own custom domain name. The instructions to set this up are identical to those described in the previous section on “HTTP Tunnel with Custom Domain(White Label URL)”.  We will be specifying the “–white-label-domain” option to specify the custom white-label domain to be used over your TLS tunnel.

The custom domain you register should be the same as the one in your SSL certificate (For eg: devops.example.com).

Now run the TLS tunnel over your custom domain name, as shown below in the example below.

$ socketxp connect --tls-e2e --white-label-domain “devops.example.com” https://127.0.0.1:8233

Public URL -> https://devops-example-com.socketxp.com

Where 8233 is the TCP port on which your HTTPS server is listening for new connections.  Next configure the DNS CNAME record for your custom domain “devops.example.com” to point towards the above SocketXP public URL.

Accessing your custom white-label domain (https://devops.example.com) using curl should work just fine now. It shouldn’t throw any certificate mismatch errors.

$ curl https://devops.example.com

Running non-HTTP services over SSL/TLS tunnels:

SocketXP SSL/TLS tunnels make no assumptions about the underlying protocol being transported. All examples in this documentation use HTTPS because it is the most common use case, but you can run run any TLS-wrapped protocol over a TLS tunnel (e.g. imaps, smtps, sips, etc) without any changes.

TCP Tunnels:

TCP tunnels, unlike HTTP(S) tunnels, can be used to take any localhost applications online not just web applications that talk HTTP. Use TCP tunnels to take your local SMTP server, SFTP server, game server, databases or SSH server online.
For example, to take your localhost network service such as SSH (which listens on TCP port 22 and talks no HTTP) online, use the below command to create a TCP public endpoint for your localhost SSH server.

$ socketxp connect tcp://localhost:22
Public URL -> tunnel.socketxp.com:45332

Use the above public endpoint (tunnel.socketxp.com and TCP port 45332)  to SSH from anywhere in the internet to your localhost SSH server. For eg:

$ ssh -i john-public-key.pub  john@tunnel.socketxp.com -p 45332

Where “john” is a valid user in your localhost SSH server and has his SSH public/private keys setup in the server.

Webhook Relay Tunnels:

SocketXP webhook relay tunnel provides a public endpoint which can accept webhooks from an online service and relay it to a localhost destination.  Webhook relay tunnels can be created using the following command.

$ socketxp relay https://localhost:8080/github-webhook/
Public URL -> https://webhook.socketxp.com/john-gmail.com-34324

Use the above public webhook URL to configure the online service from which you are expecting to receive webhook notifications.