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 and the SATELLITE_CONNECTOR_REGION with the region of the Satellite Connector you created previously.

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

   Example env.txt with populated parameters.

   SATELLITE_CONNECTOR_ID=U2F0ZWxsaXRlQ29ubmVjdG9yOiJjanM4cnRzZjFsN2c0M3U4cmp1MBA
   SATELLITE_CONNECTOR_IAM_APIKEY=/agent-env-files/apikey
   SATELLITE_CONNECTOR_TAGS=test
   

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.141Z","pid":8,"hostname":"6b793f671c79","name":"agentOps","msgid":"A02","msg":"Load SATELLITE_CONNECTOR_REGION value from SATELLITE_CONNECTOR_REGION 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.

Prerequisites and notes

• Connector agent for Windows supports Windows 10 and later or Windows Server 2016 and later.
• The Windows server where you run your Connector agent must have at least 4 cores and 4GB memory.
• For high availability, plan to deploy 1 agent per host and at least 6 agents.

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 experimental connector agent --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. Optional: 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
   

2. Verify the agent is running by run 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\{connector-agent-{{yyyy-mm-dd.n}}.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.