Docker agent (SaaS)

This topic describes how RAC/M Identity as a Service (SaaS) customers deploy the ICF connector server (ConnId) on their own infrastructure using the racm-icf-server-agent Docker image. The agent synchronizes connector artifacts from RAC/M, registers with RAC/M, and then either opens a secure outbound tunnel or listens so RAC/M can reach ConnId directly—depending on the connection mode configured for the ICF server.

SaaS only

The ICF server agent feature applies only to RAC/M Identity as a Service (SaaS). It is not supported for on-premises or private-cloud RAC/M Identity deployments.

This page covers the two SaaS agent-based connection types (Agent and Direct). For Legacy and Internal servers and an overview of the configuration wizard, see ICF servers.

Connection modes

Available in3.21.0 +

Registration returns a connectionMode value of TUNNEL or DIRECT. The agent image (0.6.5 or later) must be paired with a RAC/M release that emits this field. In the console, these correspond to Connection type Agent and Direct.

Mode	How RAC/M reaches ConnId	Network on the agent host
Tunnel (TUNNEL) — Agent	Agent opens an outbound WebSocket tunnel to RAC/M; RAC/M connects through that tunnel.	No inbound publish of ConnId is required. Allow outbound HTTPS (and the tunnel WebSocket) to RAC/M.
Direct (DIRECT) — Direct	RAC/M connects inbound to ConnId on the host and port you configure for the ICF server. The agent does not start the tunnel client.	Publish ConnId (container port 8759, TLS) with Docker -p hostPort:8759 (or the equivalent in Compose/Kubernetes). Open firewall / security-group rules so RAC/M can reach that host port.

Use Agent when the agent host cannot accept inbound connections from RAC/M. Use Direct when RAC/M can reach the agent host on the configured port (for example, on a shared network or with controlled port forwarding).

Firewall and network rules

An ICF server agent needs only outbound network access to RAC/M. On the agent host, open an outbound rule to your RAC/M endpoint on its HTTPS port (443 by default, or the port RAC/M is published on). The agent always initiates the connection to RAC/M, so no inbound rule to the agent host is required.

The exception is Direct: RAC/M connects to the connector server on the host and port you configured (default 8759), so you must also allow that inbound connection from RAC/M to the agent host. Agent needs the outbound rule only.

Create the agent server in RAC/M

The ICF server screen is a short guided wizard. The progress bar shows Configuration (sub-steps General and, when applicable, Connection), then Deployment, then Verification. Use Next and Previous to move between steps, or click a completed node.

1. Sign in to the RAC/M Identity management console with an account that can manage ICF servers.
2. Open Configuration → Target system servers (ICF servers).

3. Click + to create a new ICF server.
4. On the General sub-step of Configuration, enter a Name for this server (for example, the environment or application it will serve) and choose a Connection type: Legacy, Direct, or Agent.

5. Continue according to the connection type you chose:
   • Agent: the Connection sub-step is skipped (RAC/M manages the host and port) — after General, save directly.
   • Direct: on the Connection sub-step, enter the Host and Port (default 8759) where RAC/M reaches ConnId on the agent host. The Why this is needed note explains that these values are reused when generating racm-icf-agent.env and the deployment commands (including the port publish). Open that port in the host firewall (and any load balancer or security group) so RAC/M can connect inbound.

6. Click Save.

After you save, the wizard opens the Deployment step. In Direct mode, the generated docker run includes -p hostPort:8759 so ConnId is published on the port you configured.

Obtain deployment steps and the bearer secret

1. After a successful save, the wizard opens the Deployment step with Deploy the Docker agent.
2. Choose your container engine with the Container runtime toggle (Docker or Podman); the Step 2 and Step 3 commands are regenerated for the engine you select.
3. On a Linux host, complete the three steps shown in order.

Step 1 — Create the .env file on the host

1. Copy the file content shown under Content of racm-icf-agent.env and save it on the Linux host as racm-icf-agent.env in the directory where you will run the Docker commands.
2. Run the Restrict file access command (chmod 600 racm-icf-agent.env) on the host immediately after creating the file.

The file contains RACM_HOST, optional RACM_PORT and RACM_SCHEME, and RACM_AGENT_ICF_SERVER_BEARER_TOKEN. Treat it as highly confidential: the bearer secret authenticates your agent to RAC/M (artifact sync, registration, tunnel when used, and the embedded image registry). Store it in a secrets manager or secure runbook, not in email or chat.

Step 2 — Connect to the registry

Run the Step 2 — Connect to the registry command on the host. It authenticates Docker to the RAC/M embedded container registry using the bearer token from racm-icf-agent.env. The command reads the token from that file and pipes it to Docker so it is not exposed in the shell history or command line. Use username bearer; the password is the bearer secret.

RAC/M serves the racm-icf-server-agent image from this registry. The image reference in step 3 uses your RAC/M hostname (and port, when not the default HTTPS or HTTP port).

Step 3 — Start the agent container

Run the Step 3 — Start the agent container command. It starts the agent with --env-file ./racm-icf-agent.env and pulls the image from the RAC/M registry (--pull always). For Direct, the command also publishes ConnId with -p hostPort:8759 (container port 8759, TLS); for Agent, that publish mapping is omitted.

After you leave the page

The console warns that the full bearer secret in racm-icf-agent.env may not remain visible after you refresh or navigate away. Copy and secure the file content before leaving. If the secret is masked but you already have racm-icf-agent.env on the host, continue with steps 2 and 3. If you did not copy the secret, use Rotate bearer token to display a new file.

When you rotate the token, restart your agent containers on the host with the new .env file and commands; the previous secret stops working immediately.

After the agent has connected at least once, the page also shows Last connection to the system (or Never until the first successful contact). Use that timestamp together with Test on the Verification step to confirm the agent is reachable.

Run the agent in your environment

1. On the Linux host or cluster where ConnId should run, install Docker (or a compatible container runtime).

2. Complete the three console steps in order (create racm-icf-agent.env, registry login, docker run), or translate them into Docker Compose, Kubernetes, or your standard deployment template while preserving the same environment variables, registry authentication, and (for direct mode) published ConnId port.

3. Allow the container to reach RAC/M over HTTPS for sync and registration. On startup, the image waits for the agent-files HTTP endpoint (unless you disable the wait), runs artifact sync, then registration. In tunnel mode it then starts the tunnel client; in direct mode it skips the tunnel and runs ConnId so RAC/M can connect inbound.

4. For direct mode, confirm the host firewall (and any load balancer or Kubernetes Service) allows RAC/M to reach the published ConnId port. For tunnel mode, confirm outbound connectivity to RAC/M only.

5. Optionally monitor container logs for successful sync, registration, and (tunnel mode) tunnel startup. Registration logs include the active connection mode.

Agent image environment variables

The racm-icf-agent.env file from RAC/M supplies the required settings. The tables below list every environment variable the racm-icf-server-agent image recognizes if you need to add or override values (for example, in Compose or Kubernetes).

RAC/M connection

The container will not start unless these are set:

Variable	Description
RACM_HOST	RAC/M hostname, or bracketed IPv6. Do not include scheme or port here.
RACM_AGENT_ICF_SERVER_BEARER_TOKEN	Bearer secret for agent file access, registry authentication, and registration; treat as confidential.

Optional:

Variable	Default	Description
RACM_SCHEME	https	HTTP scheme for RAC/M (http or https). Used to build RAC/M HTTP(S) agent URLs.
RACM_PORT	(scheme default)	HTTP(S) port for RAC/M. If unset or blank, defaults to 443 when RACM_SCHEME is https (the default) and 80 when http. If set, use decimal digits only (1–65535).

HTTP readiness before agent-files sync (optional)

Before artifact sync runs, the image probes the RAC/M agent-files HTTP endpoint (bounded wait). Tune that behavior with:

Variable	Default	Description
RACM_SERVER_WAIT_SECS	120	Maximum seconds to wait for HTTP readiness; 0 skips the wait.
RACM_SERVER_PROGRESS_SECS	15	Emit a progress line every N seconds while waiting; 0 disables.
RACM_SERVER_READY_COUNT	3	After the first successful probe, require this many successive passes (1 s apart) before sync. Use 1 for “first success wins”.
RACM_SERVER_SETTLE_SECS	0	Extra sleep (seconds) after readiness and before sync.
RACM_SERVER_PROBE_DEBUG	(unset)	If 1, true, or yes (case-insensitive), failed probes use curl -S so stderr includes curl error detail.

Periodic sync and ConnId restart (optional)

Variable	Default	Description
RACM_ICF_SYNC_INTERVAL_SECS	300	Seconds between incremental sync attempts.
RACM_ICF_ICF_SIGTERM_WAIT_SECS	60	After SIGTERM to ConnId, seconds to wait before SIGKILL.

Tunnel client (optional, tunnel mode only)

These variables apply only when registration returns connectionMode: TUNNEL. In direct mode the agent does not start the tunnel client, so they have no effect.

Variable	Default	Description
TUNNEL_CONTROL_URL	(from registration)	Override only. Full WebSocket control URL (path must be /agent/icf-server/tunnel). Replaces the registration URL when set. Omit from normal deployments; RAC/M does not emit this variable in the deployment steps.
TUNNEL_EXTRA_ARGS	(unset)	Extra arguments appended to the tunnel client command.
TUNNEL_SERVER_CONNECT_WAIT_SECS	120	Wait for the tunnel server TCP port (parsed from the control URL) before starting the client; 0 skips.
TUNNEL_WAIT_PROGRESS_SECS	15	Progress line interval while waiting; 0 disables.
TUNNEL_LOG_LEVEL	INFO	Tunnel client log level; detail is written to tunnel.log under ${ICF_AGENT_ROOT}/logs/ (default /opt/icf-agent/logs/).

Install paths (optional)

Variable	Default (image)	Description
ICF_AGENT_ROOT	/opt/icf-agent	Agent install root.
ICF_ROOT	/opt/icf-agent/icf-server	ConnId bundle directory.

Using connectors with this server

Configure your ICF connectors to use this ICF server instance like any other server: Configuration → ICF Connectors, choose the connector, and select this server under ICF Server. See Connectors for the general workflow.