Back to documentation

Run HTTP Tunnels with Adal CLI

Configure a tunnel, connect Adal CLI, and diagnose connection and HTTP errors.

View as Markdown
On this page

How the connection works

A caller sends an HTTP request to the tunnel's public HTTPS address. Adal CLI calls the configured service from the computer where it runs and streams the service's HTTP response back to the caller. Request and response data can flow independently during the exchange, including when the local application responds before the caller finishes uploading.

For a runnable example, see the quickstart.

Tunnel settings

Setting Behavior
Name, Notes Identify the tunnel in the dashboard. Notes are optional and support up to 4,096 characters.
Region Determines the public address and where HTTP data is kept. Choose it when creating the tunnel. The region and address are fixed afterward.
Endpoint URL Base HTTP or HTTPS URL reachable from the CLI computer. Loopback and private addresses are allowed. Use a host and optional port and path. Leave out credentials, query and fragment. HTTPS certificates are verified.
Enabled Opens the tunnel once CLI is connected and the configuration is ready. Disabling or deleting the tunnel closes the session and cancels active requests.
Timeout (seconds) 1–120 seconds for the exchange, 30 by default.
Concurrent requests 1–64 simultaneous exchanges per tunnel, 16 by default. Requests above the available capacity are rejected immediately.
Save request, Save response Independent storage switches, both on by default. See HTTP data and downloads.

With the Endpoint URL http://127.0.0.1:3000/api, a request to the public path /orders?view=summary is sent to http://127.0.0.1:3000/api/orders?view=summary. The destination host and HTTPS server name come from the Endpoint URL.

If the local service accepts POST /api/orders, test the same call through the tunnel. Replace the example host with the public address from the card.

curl -i 'https://TUNNEL_ADDRESS.se.adal.cloud/orders?view=summary' \ -H 'Content-Type: application/json' --data '{"event":"demo"}'
$body = @{ event = 'demo' } | ConvertTo-Json -Compress Invoke-WebRequest -Uri 'https://TUNNEL_ADDRESS.se.adal.cloud/orders?view=summary' -Method Post -ContentType 'application/json' -Body $body

The caller receives the status, headers and body from the same request.

CLI commands and token

In Tunnels, open the tunnel card, select CLI token, and issue a token. Choose 30, 60 or 90 days, or a calendar expiration date in UTC. Save the secret when it is shown. Replacing or revoking the token ends its access. Restart CLI with the new token after replacement.

./adal-cli --token '<TUNNEL_TOKEN>' ./adal-cli --host wss://cli.adal.cloud --token '<TUNNEL_TOKEN>' ./adal-cli --help
.\adal-cli.exe --token '<TUNNEL_TOKEN>' .\adal-cli.exe --host wss://cli.adal.cloud --token '<TUNNEL_TOKEN>' .\adal-cli.exe --help

The connection defaults to wss://cli.adal.cloud. The optional --host takes precedence over ADAL_API_HOST. Use a WSS origin without a path, query or credentials. The tunnel token selects the mode. A Channel token connects Inbound delivery.

HTTP and traffic limits

  • Request and response bodies are each limited to 128 MiB. The regional HTTP handler limits request headers to 64 KiB and the request target to 16 KiB. An oversized body detected after streaming starts can interrupt the transfer.

  • HTTP requests and responses can stream in both directions. WebSocket upgrades and HTTP CONNECT are unsupported. CLI returns the local HTTP status, including redirects and 4xx or 5xx responses. It does not follow redirects.

  • Tunnel requests have no delivery queue, automatic HTTP retries or replay. On disconnect, active exchanges are cancelled. The client reconnects after temporary failures. After the tunnel is disabled and enabled again, start CLI manually.

  • Admission requires a known, positive traffic balance. Usage is based on the body bytes actually received in both directions, regardless of storage switches.

Logs and troubleshooting

Check the terminal for CLI connection errors. Read the HTTP status and transfer outcome in the request journal. Keep the tunnel token private. Use the journal to tell an Endpoint response from a response generated by the platform.

Symptom Check
CLI does not connect Check the CLI version, tunnel token, expiration, tunnel state and access to wss://cli.adal.cloud. Run a fresh client after re-enabling a tunnel.
404 tunnel_not_found Copy the full public URL from the card. Check the region and that the tunnel still exists.
403 quota_exhausted or access_disabled Check balance and account access.
503 tunnel_disabled, tunnel_not_ready, or quota_unavailable Check Enabled, refresh the connection state and confirm that CLI is connected. Check balance availability if the error names quota.
503 concurrency_limit_exceeded or service_overloaded Check Concurrent requests and reduce simultaneous calls.
502 endpoint_unavailable Call the Endpoint directly from the CLI computer. Confirm the service, port and TLS certificate.
502 cli_unavailable or tunnel_transport_error Check that CLI is connected and inspect the transfer in the journal.
400 invalid_request Check the HTTP request and its target.
500 internal_error Note the time and request ID if available for troubleshooting.
504 request_timeout Check application latency and Timeout (seconds). A response that has already begun can end as an incomplete transfer.
413, 414, 431, 417, or 501 Check body size, target length, header size, the Expect header or use of CONNECT and upgrades, respectively.

See journal and statuses and HTTP data and downloads.

Related documentation