Self-Hosting Server
SocketXP IoT Management Platform server can be self-hosted in your data center or private/public cloud as a Virtual Machine(VM) instance.
The server is called SocketXP Gateway(socketxp-gtwy).
Download and Install
Download and install the SocketXP Gateway binary package for your Linux distribution as shown below:
Redhat/Centos/Fedora
curl -LO https://portal.socketxp.com/download/socketxp-gtwy/socketxp-gtwy-2.1.7-1.x86_64.rpm
sudo yum install ./socketxp-gtwy-2.1.7-1.x86_64.rpm
Debian/Ubuntu
curl -LO https://portal.socketxp.com/download/socketxp-gtwy/socketxp-gtwy_2.1.7-1_amd64.deb
sudo apt install ./socketxp-gtwy_2.1.7-1_amd64.deb
Note
After installation, socketxp-gtwy server will be running in the background as a Linux systemd service. The systemd service configuration file can be found at: /etc/systemd/system/socketxp-gtwy.service. The log file can be found under /var/lib/socketxp-gtwy/log/
Server Configuration
Create a configuration file named config.json under the folder /var/lib/socketxp-gtwy/ with the following configurations:
{
"gateway_domain":"gateway.socketxp.example.com",
"gateway_port":9443,
"email": "[email protected]",
"oidc_providers": [
{
"name": "microsoft",
"client_id": "1111-2222-3333-4444-5555",
"client_secret": "abcdefgh1234567"
}
],
"log_level": "debug"
}
microsoft or google. How to do this is specific to your OIDC SSO provider and outside the scope of this documentation.
Use https://your-socketxp-portal-domain-name/api/logincallback as the OIDC client app's login callback (redirect) API.
For this example, we'll register https://portal.socketxp.example.com/api/logincallback as the login callback API with the OIDC provider - Microsoft 365 or Google G-Suite.
You should replace the example.com domain in the above URL with your own domain name.
Note:
Please ensure that the login callback URL (or the login redirection URL) you register with your OIDC provider has the URL Path /api/logincallback in it. If you make any typo errors or add a trailing "/" to the URL, the login page redirection will not work and will throw an error.
Replace the client_id and client_secret in the above config file with the OIDC client app credentials provided by your OIDC SSO provider for the app.
{
...
...
"oidc_providers": [
{
"name": "google",
"client_id": "1111-2222-3333-4444-5555",
"client_secret": "abcdefgh1234567"
}
],
...
...
}
Server SSL Certificate and Key
Register your server's wildcard domain name (*.socketxp.example.com) with Let'sEncrypt or any SSL certificate authority(CA) and get an SSL certificate/key pair for your server's wildcard domain name (*.socketxp.example.com).
Store the server's certificate chain file and the private key file as server.crt and server.key under the /var/lib/socketxp-gtwy folder.
License File
We offer a 30-day free trial license for our Enterprise Version software.
To create an Enterprise Free Trial License, login to the SocketXP Cloud Gateway in the US region (only). If you don't have an account in the US region gateway, create one from here: SocketXP Web Portal Sign Up.
Go to the License tab, click the "Start Free Trial" button. Fill in your organization details and requirements in the form and click the "Create Free Trial License" button. An new Free Trial License will be created.
Click the "Download License File" button to download the license file. Copy the license.pem file to /var/lib/socketxp-gtwy folder in your self-hosted VM server.
Note:
COMMUNITY FREE VERSION:
If you don't provide any license.pem file under the /var/lib/socketxp-gtwy/ folder, the gateway server will start to run in the Community Free Version mode with only limited software features turned ON. It will not have any Enterprise features and functions turned ON. Moreover, NO SUPPORT is offered for the Community Free Version. We offer support only for the Enterprise Version.
We provide the Community Free Version of our software for hobbyists, professionals, and students for non-commercial use.
Database
By default, the server will create and use an SQLite DB file in the /var/lib/socketxp-gtwy directory to store information about the devices. This DB is good enough for trial and testing.
For production, you should use PostgreSQL DB. Here is a sample configuration for connecting the SocketXP Gateway server to a PostgreSQL DB. You should add the below DB configuration to the config.json file.
{
...
...
"database": {
"driver": "postgres",
"hostname":"psqldb.example.com",
"port":"5432",
"user":"your-user",
"password":"your-password",
"db_name":"socketxp_db",
"ssl_mode":"enable"
},
...
...
}
Please update the values in the the above config file according to your DB settings.
Restart the Server
After you save the configuration file, restart the socketxp-gtwy server to pickup the above configuration changes, using the command shown below:
Access the Web Portal
Access the server's web portal by pointing your browser to https://portal.socketxp.example.com. Login using your SSO credentials as a primary admin user (Eg: [email protected]).
After you login to the web portal, you can provide your team members access to the server, by adding their email IDs in the MyTeam page under the Settings.
Your server is now ready to accept any device registration requests.
Accessing the APIs
Your SocketXP Gateway server's APIs can be accessed using the following subdomain URL:
https://api.socketxp.example.com
The API endpoints are same as the ones documented in the API Reference Guide.
For example, to list the devices in your account:
curl https://api.socketxp.example.com/v1/devices/:page_num/:rows_per_page \
-X GET \
-H "Authorization: Bearer <your-auth-token-goes-here>"
Accessing the Log file
Log files can be found at /var/lib/socketxp-gtwy/log/. Set the debug_level flag in the config.json file to one of: "error", "debug", "info". The flag when set to "error" will log less verbose output such as only errors. The "debug" option will print more verbose output such as debugs and errors. The "info" option will print the most verbose output such as info, debugs and errors.
Event Logging Database
The server will log all events (user activities, security events, and device events) into a separate MongoDB database. This DB is different from the postgresql DB configured above to store the server objects and their states. The MongoDB is used exclusively for storing the event logs.
The configuration to enable the server to log into a MongoDB is shown below:
{
...
...
"mongodb": {
"hostname": "mongodb",
"port": "27017",
"db_name": "event_db",
"user": "your-user",
"password": "your-password"
},
...
...
}
Event logging is useful for security audit purposes.
Any Questions?
Please write to [email protected], if you have any questions.