Getting Started
Follow these 3 simple steps to get started with SocketXP quickly.
Step #1: SocketXP agent installation
Download and Install a simple SocketXP agent to run on the localhost server(or IoT device) where your web application or SSH server also runs. SocketXP agent is a CLI utility with which you could configure and create secure reverse proxy tunnels to the any service (SSH server or web app) running in your Linux device.
You'll find the download and installation instructions for your OS and CPU platform here:
Step #2: Login to your SocketXP account
Execute the following command to authenticate the SocketXP agent installed in your device with the SocketXP Cloud Gateway, using the auth-token provided to you in the SocketXP Portal.
Visit the SocketXP Portal to get your auth token. Don’t have an account ? Sign up for free to receive your auth-token.EU Region Users Note:
Use the --region="eu" option, if you want to register your device with the EU region gateway. By default, the above command registers the device with the US gateway. Please note: You cannot use the authtoken/device key obtained from EU region gateway to connect with US region gateway or vice versa.
Note
If you prefer to name your device using a unique identifier, you could use additional arguments to the login command as shown below:
The login command uses the authtoken to generate a unique per-device private key file at /var/lib/socketxp/device.key.
Security Note
The authtoken is never stored in the device as part of the /etc/socketxp/config.json file or anywhere in the device. Your customer or vendor or your team will not be able to know your authtoken unless you explicitly share the token or your SocketXP account with them. Device key cannot be used to access the REST APIs.
Login Error:
If you see any error while using the SocketXP command, please refer to the following troubleshooting guide: SocketXP Troubleshooting Guide
Step #3: Create secure tunnels
Once you have authenticated the SocketXP client with the SocketXP Cloud Gateway, you could begin creating secure tunnels to your IoT device's SSH server, VNC server or any localhost web application.
Usecase #1: IoT Remote SSH Access Over the Internet:
For example, to enable remote SSH access to your Raspberry Pi or IoT devices in your office or home network, execute the below command.
$ sudo socketxp connect tcp://127.0.0.1:22
Connected to SocketXP Cloud Gateway.
Access the TCP service securely using the SocketXP agent in IoT Slave Mode.
EU Region
If you are a EU region user, use the --region="eu" flag in the above connect command, to connect your device with the EU gateway. Otherwise you may get, "Invalid Device Key" error.
Note
SocketXP automatically assigns a unique Device ID for your device.
Now you could remote SSH into your Pi or IoT device over the internet from the SocketXP Web Portal devices page. Click the terminal icon displayed next to your device to get into its SSH shell.
Usecase #2: Public URL for your IoT Web Service:
For example, to remotely access a web service running in your localhost network (say, port 8080) over the internet, execute the below command. The command creates a secure HTTP tunnel to your localhost web service.
$ sudo socketxp connect http://127.0.0.1:8080
Connected.
Public URL -> https://test-user-a29dfe42e3.socketxp.com
After you have successfully created the HTTP tunnel, use the public URL provided by SocketXP https://test-user-a29dfe42e3.socketxp.com to access your localhost web service from anywhere in the world.
EU Region
If you are a EU region user, use the --region="eu" flag in the above connect command, to connect your device with the EU gateway. Otherwise you may get, "Invalid Device Key" error.
Single-Touch Installation Command:
The 3 step instruction explained above to setup SocketXP agent on your IoT device is a tedious process, if you have thousands of devices to install, configure and manage.
With this mind, SocketXP IoT Solution also provides a single-touch installation command for installing and configuring SocketXP IoT Agent on large number IoT or RPi devices.
You can find the detailed instruction on how to use the single-touch-installation command here.