Skip to content

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"
    }]
}
You need not set all the fields in the config.json file always. Setting specific fields for specific usecases is recommended.

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: 

$ systemctl restart socketxp
Also, ensure the status of the service is "active" and "running" after the restart using the following command: 
$ systemctl status socketxp

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.

{
    "region": "eu",        
    "tunnels": [           
    {
        "destination": "tcp://127.0.0.1:22"
    }]
}

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.

{
    "tunnels": [           
    {
        "destination": "tcp://127.0.0.1:22"
    }]
}

Configuration file for SSH remote access usecase:

{
    "region": "",        
    "tunnels": [           
    {
        "destination": "tcp://127.0.0.1:22"
    }]
}

Configuration file for Remote Desktop VNC remote access usecase:

{
    "region": "",        
    "tunnels": [           
    {
        "destination": "tcp://127.0.0.1:5901"
    }]
}

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: 

{
    "region": "",  
    "ping_interval": 135,      
    "tunnels" : [           
    {
        "destination": "tcp://127.0.0.1:22"
    }]
}

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.