Configuration
SocketXP agent uses a configuration file stored at /etc/socketxp/config.json
to connect the device with the SocketXP IoT Gateway.
Here is a summary of all the fields in the configuration file with an example value for each field:
{
"region": "eu",
"iot_slave": false,
"authtoken": "eyJhbGciOiJIUzI1Ni...",
"work_dir": "/var/lib/socketxp",
"ping_interval": 90,
"tunnels": [
{
"destination": "tcp://127.0.0.1:3000",
"custom_domain": "dev.example.com",
"subdomain": "my-subdomain",
"peer_device_id": "1234-abcd-12345-efgh-123545",
"peer_device_name": "abcdef12345",
"peer_device_port": "22",
"enable_sshd": true,
"ssh_username": "test123",
"ssh_password": "password123"
}]
}
We will discuss the usage of these flags in various usecases in the examples below.
Applying Config File Changes:
If you make changes to any field in the config file, you need to restart the SocketXP agent systemd service in the device for the new configuration to take effect. Use the following command to restart the SocketXP agent systemd service:
Also, ensure the status of the service is "active" and "running" after the restart using the following command:Region
Use the region
flag to specify the SocketXP cloud gateway region with which you want to establish connection.
Use the following config file to instruct the SocketXP agent to connect to the EU region cloud gateway.
The default gateway region
is US. The region
flag can be set to an empty string for the US region gateway, or better yet, avoid using the region
field in the config file for the US region as shown in the example below.
Configuration file for SSH remote access usecase:
Configuration file for Remote Desktop VNC remote access usecase:
Configuration file for web app remote access usercase:
{
"region": "",
"tunnels": [
{
"destination": "http://127.0.0.1:8080",
"custom_domain": "dev.example.com",
"subdomain": "my-subdomain"
}]
}
Configuration file for both SSH and Web app remote access usecase
{
"region": "",
"tunnels": [
{
"destination": "tcp://127.0.0.1:22"
},
{
"destination": "http://127.0.0.1:8080",
"custom_domain": "dev.example.com",
"subdomain": "my-subdomain"
}]
}
Configuration file for IoT Slave mode access
{
"region": "eu",
"authtoken": "eyJhbGciOiJIUzI1Ni...",
"iot_slave": true,
"tunnels" : [
{
"destination": "tcp://127.0.0.1:3000",
"peer_device_id": "1234-abcd-12345-efgh-123545",
"peer_device_name": "abcdef12345",
"peer_device_port": "22"
},
{
"destination": "tcp://127.0.0.1:3001",
"peer_device_id": "5678-abcd-12345-efgh-567890",
"peer_device_name": "pqrst56789",
"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.
Configuration file for IoT Slave mode access (Version 1.4.5 and earlier)
{
"region": "eu",
"authtoken": "eyJhbGciOiJIUzI1Ni...",
"tunnels" : [
{
"destination": "tcp://127.0.0.1:3000",
"iot_slave": true,
"peer_device_id": "1234-abcd-12345-efgh-123545",
"peer_device_name": "abcdef12345",
"peer_device_port": "22"
}]
}
Configuration file for enabling the SocketXP agent's built-in SSH server:
{
"region": "",
"tunnels" : [
{
"destination": "tcp://127.0.0.1:22",
"enable_sshd": true,
"ssh_username": "test123",
"ssh_password": "password123"
}]
}
Configuration file for changing the default working directory:
By default, SocketXP agent will write the device key and log files to /var/lib/socketxp
directory which requires root previleges. If you want to change the default working directory of the SocketXP agent, use the work_dir
flag to specify a new working directory, as shown in the example config below:
{
"region": "",
"work_dir": "/home/dave/socketxp",
"tunnels" : [
{
"destination": "tcp://127.0.0.1:22"
}]
}
Configuration file for changing the default ping interval:
By default, SocketXP agent will send keepalive(ping) messages every 90 seconds on an idle control channel connection (reverse proxy tunnel) to keep the connection alive. This will also prevent the NAT entries in your NAT router from timing out and avoid tearing down the reverse proxy connection from the IoT device to our cloud gateway.
SocketXP agent keepalive/ping messages will consume your cellular/mobile data bandwidth. In some situations, it may be prudent to change the ping_interval
to a large value that suits your needs.
If you want to change the default frequency of the ping messages(ping interval) sent by the SocketXP agent, use the ping_interval
flag to specify a new value (in seconds), as shown in the example config below:
Implications:
SocketXP agent will tear down an idle reverse proxy connection if no keepalive(ping) message is received in 3 times the ping_interval
value (3 x 90secs = 270 seconds).
If you set the ping_interval
to a very large value, the time taken to detect and recover a broken connection will also increase(3x the new ping_interval
value).
If you set the ping_interval
to a very small value, the time taken to detect and recover a broken connection will also decrease(3x the new ping_interval
value) but may consume more cellular bandwidth.
Configuration file for Device Resource Monitoring:
By default, device resource monitoring feature is disabled. Use the below configuration to enable Device Resource Monitoring feature on the device:
{
"device_monitoring": true,
"device_monitoring_threshold": 40.0,
"tunnels": [
{
"destination": "tcp://127.0.0.1:22"
}
]
}
device_monitoring_threshold
field is 80.0%. To set it to a non-default value, use the device_monitoring_threshold
configuration field to set a custom value.