Running a Connector agent

Step 1: Creating the local configuration files

There are several ways to pass agent configuration environment variable information to the container. The following example uses configuration files. However, you can also use the docker run --env command to specify the values.

Be aware that if you use --env with your API key, the API key is exposed to the container environment and is visible on the output of docker inspect command. You can secure your API key in a file and then use the file name in the environment variable. If you choose to use the file name, you must make sure that the file path that you specify in the environment variable is mounted to a file path in the container, as shown in the following example.

The file names shown in the following steps are examples and can be tailored for your environment.

1. Create a directory for the configuration files, in this example ~/agent/env-files.

2. Create a file in the ~/agent/env-files directory called apikey with a single line value of your IBM Cloud API Key that can access the Satellite Connector.

3. Create a file in the ~/agent/env-files directory called env.txt with the following values. Modify the SATELLITE_CONNECTOR_ID variable with your Satellite Connector ID.

   SATELLITE_CONNECTOR_ID=<Your Satellite Connector ID>
   SATELLITE_CONNECTOR_IAM_APIKEY=/agent-env-files/apikey
   SATELLITE_CONNECTOR_TAGS=sample tag
   

4. At this point, your directory contains 2 files and looks similar to the following example.

   env-files$ ls
   apikey  env.txt
   

5. Complete the steps in the following section to pull the agent image.

Step 2: Pulling the agent image

1. Log in to IBM Cloud® Container Registry. Or log in to the repository directly from Docker with your API key.

   ibmcloud cr region-set icr.io
   

   docker login -u iamapikey -p <your apikey> icr.io
   

2. Pull the latest version of the published image. You can find the list of published versions from IBM Satellite Connector Agent Release History.

   docker pull icr.io/ibm/satellite-connector/satellite-connector-agent:latest
   

3. Complete the following steps to run the agent image.

Step 3: Running the agent image

1. To view available versions of agent image, run the following command.

   ibmcloud cr images --include-ibm|grep connector
   

   Example output:

   icr.io/ibm/satellite-connector/satellite-connector-agent    latest    5f4e42c8d53e   ibm         1 day ago       124 MB   -
   icr.io/ibm/satellite-connector/satellite-connector-agent    v1.0.5    6eadd91be5c0   ibm         1 week ago      124 MB   -
   icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.0    5f4e42c8d53e   ibm         1 day ago       124 MB   -
   

2. Mount your env-files directory to the container's /agent-env-files directory by using the -v option. You can use the latest version or a specific version of the published image.

   If an environment variable is using a path to a file, that path must be a file path inside the container. To retrieve the file path, use the -v option on the docker run command. The -v option is specified by the local environment variable directory path, followed by the mounted path in the container and separated by :. For example, -v ~/agent/env-files:/agent-env-files, where ~/agent/env-files is your local path and /agent-env-files is a path in your container.

   docker run -d --env-file ~/agent/env-files/env.txt -v ~/agent/env-files:/agent-env-files icr.io/ibm/satellite-connector/satellite-connector-agent:latest
   

   Example command using version 1.1.0 of the image, run the following command.

   docker run -d --env-file ~/agent/env-files/env.txt -v ~/agent/env-files:/agent-env-files icr.io/ibm/satellite-connector/satellite-connector-agent:v1.1.0
   

3. You can verify the tunnel gets established to your Connector by looking at the logs of the container.

   docker logs CONTAINER-ID
   

   Near the beginning of the log, you can find entries similar to the following examples.

   {"level":30,"time":"2023-06-20T16:12:20.133Z","pid":8,"hostname":"6b793f671c79","name":"agentOps","msgid":"A02","msg":"Load SATELLITE_CONNECTOR_ID value from SATELLITE_CONNECTOR_ID environment variable."}
   {"level":30,"time":"2023-06-20T16:12:20.138Z","pid":8,"hostname":"6b793f671c79","name":"agentOps","msgid":"A01","msg":"Load SATELLITE_CONNECTOR_IAM_APIKEY value from file /agent-env-files/apikey."}
   {"level":30,"time":"2023-06-20T16:12:20.140Z","pid":8,"hostname":"6b793f671c79","name":"agentOps","msgid":"A02","msg":"Load SATELLITE_CONNECTOR_TAGS value from SATELLITE_CONNECTOR_TAGS environment variable."}
   {"level":30,"time":"2023-06-20T16:12:20.142Z","pid":8,"hostname":"6b793f671c79","name":"connector-agent","msgid":"LA2","msg":"Connector id: U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI, region: us-south, release info: 20230610-dd48822928d35a84b31029a996fa9abc9d29fc93_A."}
   {"level":30,"time":"2023-06-20T16:12:20.392Z","pid":8,"hostname":"6b793f671c79","name":"tunneldns","msgid":"D04","msg":"DoTunnelDNSLookup DNS resolve c-01-ws.us-south.link.satellite.cloud.ibm.com to 169.61.31.178"}
   {"level":30,"time":"2023-06-20T16:12:21.560Z","pid":8,"hostname":"6b793f671c79","name":"utilities","msg":"MakeLinkAPICall GET /v1/connectors/U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI status code 200"}
   {"level":30,"time":"2023-06-20T16:12:21.563Z","pid":8,"hostname":"6b793f671c79","name":"agent_tunnel","msgid":"LAT03","msg":"Got configuration"}
   {"level":30,"time":"2023-06-20T16:12:21.565Z","pid":8,"hostname":"6b793f671c79","name":"agent_tunnel","msgid":"LAT04-wss://c-01-ws.us-south.link.satellite.cloud.ibm.com/ws","msg":"Connecting to wss://c-01-ws.us-south.link.satellite.cloud.ibm.com/ws"}
   {"level":30,"time":"2023-06-20T16:12:21.922Z","pid":8,"hostname":"6b793f671c79","name":"tunneldns","msgid":"D04","msg":"DoTunnelDNSLookup DNS resolve c-01-ws.us-south.link.satellite.cloud.ibm.com to 169.61.31.178"}
   {"level":30,"time":"2023-06-20T16:12:22.294Z","pid":8,"hostname":"6b793f671c79","name":"TunnelCore","msgid":"TC24","msg":"Tunnel open","connector_id":"U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI"}
   {"level":30,"time":"2023-06-20T16:12:22.299Z","pid":8,"hostname":"6b793f671c79","name":"connector_tunnel_base","msgid":"CTB26-U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI","msg":"Send connector information to tunnel server"}
   {"level":30,"time":"2023-06-20T16:12:22.307Z","pid":8,"hostname":"6b793f671c79","name":"connector_tunnel_base","msgid":"CTB27","msg":"Tunnel connected","connector_id":"U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI","cipher":{"name":"TLS_AES_256_GCM_SHA384","standardName":"TLS_AES_256_GCM_SHA384","version":"TLSv1.3"}}
   

After setting up an agent, you can create Endpoints and ACLs to manage access to those endpoints. For more information, see Creating and managing Connector endpoints.

Step 1: Downloading the Connector agent files from the CLI

1. From the CLI, run the following command to download the agent .zip file.

   ibmcloud sat agent attach --platform windows
   

   Example output.

   Downloading agent setup tools for windows...
   OK
   Satellite connector agent for windows was successfully returned /var/folders/17/y8wr4y_x1tb4yf__g3wr6g8m0000gp/T/windows_satellite_connector_4097559421.zip
   

2. Verify the sha512sum of the .zip by running the following command in PowerShell.

   Get-FileHash -Algorithm SHA512 -Path c:\windows_satellite_connector_1420916628.zip
   

3. Run the following command in PowerShell to extract the .zip file contents.

   Expand-Archive -Path 'C:\path\to\windows_satellite_connector_4097559421.zip' -DestinationPath ‘C:\path\to\extract'
   

4. Complete the steps in the following section to update the configuration files that you extracted.

Step 2: Updating the config.json file

Configuration information is provided to the agent through the following environment variables in the config.json file that you extracted in the previous step. Review the following parameters for the agent image.

1. Update the config.json that you extracted earlier with the appropriate values for each parameter.

   You must escape the slash in the file path.

   Example config.json.

   {
     "SATELLITE_CONNECTOR_ID":"<Your Satellite Connector ID>",
     "SATELLITE_CONNECTOR_IAM_APIKEY":"<Your API Key>",
     "SATELLITE_CONNECTOR_TAGS":"sample tag",
     "LOG_LEVEL": "info",
     "PRETTY_LOG": true
   }
   

   Example config.json with populated values.

   {
     "SATELLITE_CONNECTOR_ID":"U2F0ZWxsaXRlQ29ubmVjdG9yOiJjanM4cnRzZjFsN2c0M3U4cmp1MBA",
     "SATELLITE_CONNECTOR_IAM_APIKEY":"C:\\path\\to\\apikey",
     "SATELLITE_CONNECTOR_TAGS":"sample tag",
     "LOG_LEVEL": "info",
     "PRETTY_LOG": true
   }
   

2. Save the file.

3. Complete the steps in the following section to start the agent.

Step 3: Starting the agent

1. Start the agent by running the install command in PowerShell.

   .\install
   

   If you start the agent and receive a Windows Microsoft Defender SmartScreen error, this is expected. The plain text install scripts are not signed. We suggest relying on the step to verify the sha512sum after you downloaded the agent.

2. Verify the agent is installed by running the Get-Service command in PowerShell.

   Get-Service 'Satellite Connector Service'
   

3. View the agent logs by running the Get-Content command in PowerShell.

   Get-Content 'C:\path\to\extract\logs\{satelliteconnectorservice_{{yyyymmdd}}.out.log}'
   

4. Optional: Stop the agent by running the uninstall command in PowerShell.

   .\uninstall
   

After setting up an agent, you can create Endpoints and ACLs to manage access to those endpoints. For more information, see Creating and managing Connector endpoints.

Updating the agent on Windows

You can use the update-service command in the agent package to apply configuration changes to your agent. When you run the command, the agent is stopped, uninstalled, and reinstalled. Complete the following steps to update your agent.

1. Before updating, review the changes in the Connector Windows agent change log and check if the latest version is newer than your currently running agent.

   You can find your current version number in the version.txt file inside the agent package for your currently running agent. If no version.txt file is found or your current version number is less than the latest version number, there is a newer version available for update.

2. If there is a newer agent version available and you would like to use it, download the latest version by following the instructions in Step 1: Downloading the Connector agent files from the CLI before proceeding to the following steps.

3. Modify the configuration parameters in the config.json file.

   Example config.json.

   {
     "SATELLITE_CONNECTOR_ID":"<Your Satellite Connector ID>",
     "SATELLITE_CONNECTOR_IAM_APIKEY":"<Your API Key>",
     "SATELLITE_CONNECTOR_TAGS":"<tags>",
     "LOG_LEVEL": "info",
     "PRETTY_LOG": true
   }
   

   Example config.json with populated values.

   {
     "SATELLITE_CONNECTOR_ID":"U2F0ZWxsaXRlQ29ubmVjdG9yOiJjanM4cnRzZjFsN2c0M3U4cmp1MBA",
     "SATELLITE_CONNECTOR_IAM_APIKEY":"C:\\path\\to\\apikey",
     "SATELLITE_CONNECTOR_TAGS":"sample tag",
     "LOG_LEVEL": "info",
     "PRETTY_LOG": true
   }
   

4. Run the update-service command in PowerShell.

   .\update-service
   

5. Verify the agent is installed by running the Get-Service command in PowerShell.

   Get-Service 'Satellite Connector Service'
   

6. View the agent logs by running the Get-Content command in PowerShell.

   Get-Content 'C:\path\to\extract\logs\{satelliteconnectorservice_{{yyyymmdd}}.out.log}'