Skip to content

Slave Mode

SocketXP agent when run in slave mode will act like a local proxy server.

Tip

Imagine a VPN client software running on your laptop or PC.

If you want to connect to your remote device directly from your laptop or PC, without having to visit the SocketXP Portal page, then this is an alternate method provided by SocketXP for remotely connecting to your IoT gateway, Raspberry Pi or any Linux device over the internet.

Slave Mode Usecases

Use this method, if you want to use an SSH client of your choice such as OpenSSH client, PuTTY, FileZilla or SecureCRT to remotely access your IoT device from your laptop or PC.

Also, use this method if you want to use SSH public/private keys to login to your device more securely.

Note

The slave mode feature can be used to access any service (not just SSH server) running in your Raspberry Pi or Linux device. This method is equivalent to connecting to your device using a local IP address and TCP port, as if the device is connected to your local network. Again, imagine a VPN client software running on your laptop.

Here is a list of other services running in your Linux device or Raspberry Pi that can be accessed by running SocketXP agent in slave mode in your laptop or desktop:

  • SSH
  • SCP
  • Rsync
  • VNC/RDP
  • Database (MySQL or Postgresql DB)
  • SMTP
  • Python, NodeJS, Java, Golang web service
  • API Gateway
  • Any program or service listening on a TCP port.

How to enable Slave Mode

First download and install the regular SocketXP agent software on your accessing device (such as a laptop running Windows or Mac OS). Next, configure the agent to run in slave mode using the command option "--iot-slave" as shown in the example below. Also, specify the device ID of the IoT device you want to connect to, using the --peer-device-id option.

Note:

You must use the DEVICE-ACCESS token for accessing the device in slave mode. You cannot use any other auth token type.

$ socketxp connect tcp://localhost:3000 --iot-slave --peer-device-id "abc123456789" --peer-device-port 22 --authtoken <auth token>

Listening for TCP connections at:
Local URL -> tcp://localhost:3000
Accessing the IoT device from your laptop
Where port 3000 is the local proxy port at which the SocketXP agent is listening for SSH connections from any SSH client. You could specify any free port in your laptop as a local proxy port instead of 3000. You could find the device ID of your device from the SocketXP Portal page in the Devices section. Alternatively, you could provide the IoT device name to connect in slave mode as shown below:

$ socketxp connect tcp://localhost:3000 --iot-slave --peer-device-name "sensor12345" --peer-device-port 22 --authtoken <auth token>

Listening for TCP connections at:
Local URL -> tcp://localhost:3000
Accessing the IoT device from your laptop

Note

SocketXP automatically assigns a unique ID for your device. You could find this device ID information in the device.key file at /var/lib/socketxp/device.key. You could also find this information in the SocketXP Portal's device page

Why this is important?

SocketXP IoT Agent when run in IoT Slave Mode acts like a localproxy server. It proxies all connections to a user-specified local port (3000 in the example above) in your laptop/PC to the SocketXP IoT Cloud Gateway using a secure SSL/TLS tunnel. Also the SocketXP IoT Agent authenticates itself with the SocketXP IoT Cloud Gateway using your auth token. This ensures that only legitimate, authenticated users are permitted to access your remote IoT devices. SocketXP ensures Zero-Trust security on all connected devices.

Now you can SSH into your IoT device using the local proxy port (3000), as shown in the example below. 

$ ssh -i ~/.ssh/john-private.key john@localhost -p 3000
Where john is a user account that exists in your IoT device.

Tip

You can also use PuTTY SSH client to remote SSH into your device using the same parameters show above. You can also use PuTTY or FileZilla to perform SFTP actions such as file upload and file download on your remote IoT or Raspbery Pi device.

Configuration file for IoT Slave mode access

Here is a sample configuration file for running the agent in IoT Slave Mode to securely connect to your remote IoT devices:

{
    "authtoken": "eyJhbGciOiJIUzI1Ni...",       
    "iot_slave": true,
    "tunnels" : [           
        {
            "destination": "tcp://127.0.0.1:3000",
            "peer_device_id": "1234-abcd-12345-efgh-123545", 
            "peer_device_port": "22"
        },
        {
            "destination": "tcp://127.0.0.1:3001",
            "peer_device_id": "5678-abcd-12345-efgh-567890", 
            "peer_device_port": "8080"
        }
    ]
}

Authtoken:

You need to provide a DEVICE_ACCESS authtoken to connect to the IoT device in slave mode. For security reasons, it is highly recommended NOT to use the generic multi-purpose authtoken in production for this usecase.

The authtoken flag need not be specified in the config file for any other usecases. It should be specified for slave mode remote access usecase only.