Inner Workings of the Connection Between a SystemLink Server and Client

Issue Details

• I want to know how the connection process between a SystemLink Server and Client looks like.
• What ports are used in the connection between SystemLink Server and Client?
• I want to know what is the ideal connection process between SystemLink Server and Client.

Solution

1. The SystemLink Client software is installed in the client system.
   • The installation process changes if the client is a Windows or Real-Time (RT) target. 
   • The user enters the SystemLink server address (preferred host name, host name or IP address) in the SystemLink Client application in Windows or via NI MAX for RT targets.
2. The salt-minion service on the client computer tries to connect to the entered server address.
   • This service is installed automatically by the SystemLink Client application.
   • Automatically creates a unique public_key for data encryption.
   • Automatically creates a unique minionID (GUID) for this client system.
   • Opens TCP connections to the server on port 4505 and port 4506.
   • These TCP connections persist and are used over and over for communication.
   • Regularly tries to send the public_key and minionID to the server on TCP port 4506.
3. The SystemLink Server gets the public_key and minionID from the client.
   • The SystemLink Client dialog in Windows or the SystemLink Settings field in NI MAX, for Real-Time targets, shows a status of “Connected”.
   • At this point the SystemLink client’s minionID appears in the Systems Management>>Systems>>Pending Systems tab of the SystemLink Server web UI.
   • In this stage the SystemLink Server cannot yet send salt jobs to the SystemLink client.
   • Running “salt-key” in DOS shows this SystemLink Client’s minionID in “Unaccepted Keys”.
   • Running a salt-master test.ping with this SystemLink client’s minionID will return False.
4. The SystemLink Server user approves the pending SystemLink client. For this you hit the Approve button in the Systems Management>>Systems>>Pending Systems tab for that client (identified by its minionID).
   • The SystemLink Server checks out a node license for that SystemLink client (if available).
   • That SystemLink client’s minionID and public_key are now stored in SystemLink Server.
   • Running “salt-key” in DOS shows this SystemLink client’s minionID in “Accepted Keys”.
   • Running a salt-master test.ping with this SystemLink client’s minionID will return True.
5. SystemLink Server schedules a Refresh job to run on this SystemLink client.
   • The salt-master publishes an event to announce the establishment of the connection.
   • The SystemsManagement Service reacts to that event.
     • Updates the system page header for this SystemLink client to “Connected”.
     • Sends the refresh job to this SystemLink client on TCP port 4505.
   • The refresh job runs on the SystemLink client computer, where it:
     • Registers the HTTPS web certificate sent from the server.
     • Stores the URL sent from the server.
     • Stores the ApiKey for this client system sent from the server.
     • Gathers all its client info (hostname, network config, serial number, installed software, configured feeds, etc), called the “grains dictionary”.
     • Sends the SystemLink client’s “grains dictionary” back to the SystemLink server.
6. The SystemLink server receives the client system’s “grains dictionary”.
   • Receives the “grains dictionary” from the client on TCP port 4506.
   • Stores all the SystemLink client info from the “grains dictionary”.
   • Displays the received SystemLink client info in all system tables and pages.
   • Shows the system table “Status” column as “Connected” for this SystemLink client.
7. The SystemLink client sends all (subsequent) data to the server over the HTTP(S) connection.
   • Uses stored host address, ApiKey, and web certificate to connect via HTTP(S).
   • Sends tags, files, test results, etc. exclusively over HTTP(S), not salt or TCP.
   • You can verify this is working by checking the SystemLink client’s health tag updates.
   • Health tags update every 5 minutes, so you have to wait initially.
   • It’s convenient to create a custom column in the system table to show this.

Additional Information

• SystemLink Client dialog shows “Connected” when the client has contacted the server through Salt.
• SystemLink Client dialog shows “Partially Connected” when the client’s stored HTTP(s) info fails.
• SystemLink Server system page header shows “Connected” when client is approved and activated.
  • SystemLink Server system pages show grains dictionary info if the server has ever received it.
• SystemLink Server system table “Status” column shows “Connected” if last Refresh job succeeded.