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:
{
"gateway_domain": "gateway.socketxp.com",
"region": "eu",
"iot_slave": true,
"authtoken": "eyJhbGciOiJIUzI1Ni...",
"work_dir": "/var/lib/socketxp",
"ping_interval": 90,
"device_monitoring": true,
"device_monitoring_threshold": 80.0,
"asset_tracking": true,
"asset_tracking_interval": 86400,
"google_api_key": "abcdedfgh123456xyz",
"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"
}]
}
Note:
You need not set all the fields in the config.json file always. Setting specific fields for specific usecases is recommended. For any questions, write to us: [email protected].
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:Gateway Domain
Use the gateway_domain flag, if you are running a self-hosted or onprem version of the SocketXP IoT Gateway server and want the agent to connect to your onprem server.
By default, the "gateway_domain" flag is set togateway.socketxp.com. SocketXP agent, by default, will connect to our cloud gateway server. So, skip setting this flag in the config file, if you want the agent to connect to our SocketXP Cloud Gateway.
Set the flag to your self-hosted gateway server's domain name (Eg: gateway.socketxp.example.com), if you want the agent to connect to your self-hosted onprem server.
{
"gateway_domain": "gateway.socketxp.example.com",
"tunnels": [
{
"destination": "tcp://127.0.0.1:22"
}]
}
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.
SSH Remote Access
Remote Desktop VNC Remote Access
Web App Remote Access
{
"region": "",
"tunnels": [
{
"destination": "http://127.0.0.1:8080",
"custom_domain": "dev.example.com",
"subdomain": "my-subdomain"
}]
}
Both SSH and Web App Remote Access
{
"region": "",
"tunnels": [
{
"destination": "tcp://127.0.0.1:22"
},
{
"destination": "http://127.0.0.1:8080",
"custom_domain": "dev.example.com",
"subdomain": "my-subdomain"
}]
}
IoT Slave Mode
{
"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.
Provide the peer_device_id or peer_device_name of the remote (peer) IoT device you would like to connect to using the slave mode agent. You can find this information from the SocketXP Web Portal's Devices section. Also, provide the peer_device_port, so that the slave mode agent can connect to the appropriate service running in your remote (peer) device. The default value of the peer_device_port flag is 22. These flags take effect only if the iot_slave flag is enabled.
Hint:
The slave mode agent running in your laptop or PC sees the agent running in your remote IoT device as its peer. Therefore, all the peer_device_* flag settings in the above configs are those of the remote IoT device.
These flags cannot be used to set the device ID or the device name of the IoT device. You can set these values for the IoT device only from the SocketXP Web Portal's Devices section by editing the device settings.
IoT Slave Mode (Agent 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"
}]
}
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"
}]
}
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"
}]
}
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.
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.
Asset Tracking
By default, the asset tracking feature is disabled. Use the below configuration to enable the asset tracking feature on the device.
{
"asset_tracking": true,
"asset_tracking_interval": 86400,
"google_api_key": "abcdedfgh123456xyz",
"tunnels": [
{
"destination": "tcp://127.0.0.1:22"
}
]
}
asset_tracking_interval is 86400 seconds (or 24 hours). You can set it to a custom value for your requirements.
Also, if your device doesn't have a built-in GPS unit and you want to track the geolocation of your asset using the Google GeoLocation API, you can input the Google GeoLocation API key to the SocketXP agent using the google_api_key field shown above.