Set up and register a Connector Agent

Deploy on Linux

1. Make the installer executable:

   chmod +x connector_agent_7.3.12_linux_x64_installer
   

2. Install Connector Agent as root:

   sudo ./connector_agent_7.3.12_linux_x64_installer -- --install
   
   Verifying archive integrity... All good.
   Uncompressing Connector Agent  100%
   Installer log: /tmp/connector_agent_installer_L1JZZ5.log
   ------------------------------------------------------------------------------
   ==> Starting Connector Agent installation...
   ------------------------------------------------------------------------------
   ==> This is x86_64 system
   kernel_version is: 4.18.0
   ==> Service user: connector_agent
   ==> Service group: connector_agent
   ==> Creating system group connector_agent...
   + groupadd --system connector_agent
   ==> Creating system user connector_agent...
   + useradd --system --no-create-home --shell /usr/sbin/nologin --gid connector_agent connector_agent
   
   Do you want to install Connector Agent? [y/N] y
   ==> Installation directory: /opt/connector_agent
   ==> Config directory: /etc/connector_agent
   ==> Log directory: /var/log/connector_agent
   ==> Creating directories...
   + mkdir -p /opt/connector_agent/bin
   + mkdir -p /opt/connector_agent/lib
   + mkdir -p /var/log/connector_agent
   + mkdir -p /etc/connector_agent
   + install -o root -g root -m 0600 /dev/null /opt/connector_agent/.connector_agent
   + install -o root -g root -m 0600 /dev/null /etc/connector_agent/.connector_agent
   + install -o root -g root -m 0600 /dev/null /var/log/connector_agent/.connector_agent
   ==> Copying connector_agent_exec to /opt/connector_agent/bin...
   + cp /tmp/selfgz3528422832/connector_agent_exec /opt/connector_agent/bin/
   + chmod 755 /opt/connector_agent/bin/connector_agent_exec
   ==> Copying bundled libraries to /opt/connector_agent/lib...
   + cp -r /tmp/selfgz3528422832/dlls_for_linking/. /opt/connector_agent/lib/
   + chmod -R 755 /opt/connector_agent/lib
   ==> Running patchelf on connector_agent_exec...
   Setting r-path for connector_agent_exec to /opt/connector_agent/lib
   + /opt/connector_agent/lib/patchelf --remove-rpath /opt/connector_agent/bin/connector_agent_exec
   + /opt/connector_agent/lib/patchelf --force-rpath --set-rpath /opt/connector_agent/lib /opt/connector_agent/bin/connector_agent_exec
   Setting r-path for all libs in /opt/connector_agent/lib
   + /opt/connector_agent/lib/patchelf --set-rpath /opt/connector_agent/lib /opt/connector_agent/lib/libc.so.6
   + /opt/connector_agent/lib/patchelf --set-rpath /opt/connector_agent/lib /opt/connector_agent/lib/libcrypto.so.3
   + /opt/connector_agent/lib/patchelf --set-rpath /opt/connector_agent/lib /opt/connector_agent/lib/libnss_compat.so.2
   + /opt/connector_agent/lib/patchelf --set-rpath /opt/connector_agent/lib /opt/connector_agent/lib/libnss_db.so.2
   + /opt/connector_agent/lib/patchelf --set-rpath /opt/connector_agent/lib /opt/connector_agent/lib/libnss_dns.so.2
   + /opt/connector_agent/lib/patchelf --set-rpath /opt/connector_agent/lib /opt/connector_agent/lib/libnss_files.so.2
   + /opt/connector_agent/lib/patchelf --set-rpath /opt/connector_agent/lib /opt/connector_agent/lib/libnss_hesiod.so.2
   + /opt/connector_agent/lib/patchelf --set-rpath /opt/connector_agent/lib /opt/connector_agent/lib/libresolv.so.2
   + /opt/connector_agent/lib/patchelf --set-rpath /opt/connector_agent/lib /opt/connector_agent/lib/libssl.so.3
   Setting interpreter-path for connector_agent_exec to /opt/connector_agent/lib/ld-linux-x86-64.so.2
   + /opt/connector_agent/lib/patchelf --set-interpreter /opt/connector_agent/lib/ld-linux-x86-64.so.2 /opt/connector_agent/bin/connector_agent_exec
   ==> Generating set_env.sh...
   + cp /tmp/selfgz3528422832/set_env_template.sh /etc/connector_agent/set_env.sh
   + chmod 640 /etc/connector_agent/set_env.sh
   ==> Installing management script...
   + cp /tmp/selfgz3528422832/connector_agent.sh /opt/connector_agent/bin/
   + chmod 755 /opt/connector_agent/bin/connector_agent.sh
   ==> Applying ownership and permissions for service user connector_agent...
   + chown -R root:root /opt/connector_agent
   + chmod 755 /opt/connector_agent /opt/connector_agent/bin
   + chgrp -R connector_agent /opt/connector_agent/lib
   + chmod 750 /opt/connector_agent/lib
   + chown -R root:connector_agent /etc/connector_agent
   + chmod 770 /etc/connector_agent
   + chown -R connector_agent:connector_agent /var/log/connector_agent
   + chmod 750 /var/log/connector_agent
   ==> Starting connector agent...
   Starting connector_agent_exec...
   connector_agent_exec started (PID: 35831).
   ------------------------------------------------------------------------------
   
   Connector Agent installed at /opt/connector_agent
   
   Management:
   sudo /opt/connector_agent/bin/connector_agent.sh {start|stop|status|restart|version}
   

Deploy on Windows

1. Open a powerShell terminal.

   C:\>powershell
   Windows PowerShell
   Copyright (C) Microsoft Corporation. All rights reserved.
   

2. Run the connector agent installer with the "-install" option.

   PS C:\> .\connector_agent_7.3.12_win_x64_installer.exe -install
   Installer log: C:\Users\ADMINI~1.ARE\AppData\Local\Temp\2\connector_agent_installer_1163485291.log
   
   Do you want to install Connector Agent? [y/N] y
   Extracting to C:\Program Files\ConnectorAgent ...
   Service 'ConnectorAgent' started.
   Install complete. Service 'ConnectorAgent' is registered and started.
   Install dir: C:\Program Files\ConnectorAgent
   Config dir:  C:\ProgramData\ConnectorAgent
   Log dir:     C:\ProgramData\ConnectorAgent\logs
   

Key parameters

connectionName

Must be unique within the tenant. This name identifies the connection in the IBM Cloud Backup and Recovery UI.

joinExistingConnection

Set to true if this agent is joining an already-claimed connection, such as in Oracle RAC clustered agent scenarios. For stand-alone agents, use false.

Option 1: Verify agent registration that uses API

1. List all Connector Agents on the cluster:

   Use the following curl command to retrieve a list of connector agents for your tenant:

   curl -k -X GET "https://<your-instance-url>/v2/connector-agents?tenantId=<tenant-id>" \
   -H "Authorization: Bearer <iam-token>" \
   -H "X-IBM-Tenant-ID: <tenant-id>" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json"
   

   Where:

   <your-instance-url>: The URL of your Backup Recovery Service instance. You can find this value on your BRS instance's page in the IBM Cloud console.

   <tenant-id>: Your tenant ID. You can find this value on your BRS instance's page in the IBM Cloud console. This value is used in both the query parameter and the X-IBM-Tenant-ID header.

   <iam-token>: Your IBM Cloud IAM access token.

   Before you can call the Backup Recovery Service API, you need to generate an IAM access token. Use the following curl command to generate a token:

   curl -X POST 'https://iam.cloud.ibm.com/identity/token' \
   -H 'Content-Type: application/x-www-form-urlencoded' \
   -d 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=<apikey>'
   

   Where:

   <apikey>: Your IBM Cloud API key with access to your Backup Recovery Service instance.

   The response includes an access_token field that contains your IAM token. Use this token value as the <iam-token> in the connector agents request.

2. Review the JSON array response to confirm your agent and connection name appear in the list.

3. Optionally, filter the results:

   • By connection ID: append &connectionIds=<id> to the URL
   • By connection name: append &connectionNames=<name> to the URL

Option 2: Verify agent registration by using the Backup and Recovery service instance dashboard

1. In the dashboard, navigate to Sources in the left navigation menu.
2. If you just completed the registration, you might need to refresh the page to see the newly registered source.
3. Use the search bar at the top of the Sources page to locate your data source by:
   • Hostname (for example, WIN-SERVER-01)
   • IP address (for example, 10.241.0.4)
   • Partial name match
4. Alternatively, use the filter dropdown to narrow the list by source type.

Option 1: Register a data source that uses API

1. Register the Physical box (Linux or Windows) using the provided curl command:

   curl -X POST \
      --url 'https://<your-instance-url>/v2/data-protect/sources/registrations' \
      -H 'Authorization: Bearer <iam-token>'\
      -H 'X-IBM-Tenant-ID: <tenant_id>'\
      -H 'Accept: application/json'\
      -H 'Content-type: application/json' \
      --data-raw '{
      "environment": "kPhysical",
      "dataSourceConnectionId": "<connector_agent_id>",
      "physicalParams": {
         "endpoint": "<IP address of host>",
         "hostType": "<kLinux, or kWindows>",
         "physicalType": "kHost",
         "name": "<name_for_this_source>"
      }
      }'
   

2. Register the SQL or Oracle application by using the provided curl command:

   curl -X POST \
      --url 'https://<cluster_endpoint>/v2/data-protect/sources/registrations' \
      -H 'Authorization: Bearer <access_token>'\
      -H 'X-IBM-Tenant-ID: <tenant_id>'\
      -H 'Accept: application/json'\
      -H 'Content-type: application/json' \
      --data-raw '{
      "environment": "kPhysical",
      "dataSourceConnectionId": "<connector_agent_id>",
      "physicalParams": {
         "endpoint": "<IP address of host>",
         "hostType": "<kWindows or kLinux>",
         "physicalType": "kHost",
         "applications": ["<kSQL or kOracle>"],
         "name": "<name_for_this_source>"
      }
      }'
   

Option 2: Register a data source by using Backup and Recovery service instance dashboard

1. Log in to the IBM Cloud Backup and Recovery UI.

2. Navigate to the Data Protection tab.

3. Select the Sources tab.

4. Click Register Source.

5. Select the type of source that you want to protect (for example, Oracle, MS SQL, or file system).

6. On the source registration page, select the Direct radio button to use a Connector Agent.

7. From the dropdown menu, select the connection name of the Connector Agent you registered.

8. Complete the remaining source registration fields according to your source type.

9. Click Register to complete the source registration.

The data source is now registered and ready for backup operations by using the Connector Agent.

10. Verify the following information:
    • Source name: Confirms that the correct host is registered
    • IP address: Matches your target host's IP address
    • Status: Should show as "Active" or "Connected"
    • Source type: Displays the correct type (Physical, SQL, and more.)
11. For Microsoft SQL Server sources, verify that the source appears in two locations:
    • Under SQL category (when filtered by Microsoft SQL)
    • Under Physical category (when filtered by Physical)

This dual listing occurs because SQL Server is both a database application and runs on a physical server. You can manage backups for the SQL databases separately from the physical server backups.

Config file errors on startup

If you see config file errors when starting the agent, this is expected behavior for an unclaimed agent. The config file is created automatically after a successful claim operation.

Permission denied errors

If you encounter permission denied errors when running the binary or creating the config file:

• On Linux: Make certain the binary has run permissions by using chmod +x
• On Windows: Run the command prompt or PowerShell as administrator

Cannot reach the cluster

If the agent cannot connect to the cluster, verify network connectivity:

1. Test HTTPS connectivity:

   nping <ip-or-fqdn> -p 443
   

2. Test broker connectivity:

   nping <ip-or-fqdn> -p 29991
   

3. Try an unauthenticated API call:

   curl -sk "https://<ip-or-fqdn>/v2/data-protect/policies"
   

4. Check broker (gRPC) connectivity:

   openssl s_client -connect <ip-or-fqdn>:29991
   

   You should receive a valid TLS response.

Agent not appearing after claim

If the agent does not appear in the cluster after claiming:

• Contact IBM Support
• Confirm that you are using the correct registration token for the agent you are registering
• Check that the tenant ID in the API calls matches the tenant where the agent should be registered
• Review the agent logs for any error messages