From 42685584724a3aca1653056e7cf0941586b8e908 Mon Sep 17 00:00:00 2001 From: Romeo Mlinar Date: Wed, 2 Sep 2026 16:53:44 +0100 Subject: [PATCH 1/2] RDTKF-25112 Clarify --proxy scope and document relay-server pattern --proxy only covers the Cloud Connector to Private Gateway connection; the connection to each remote-host is always dialed directly. Also documents that outsystemscc is a raw TCP/UDP passthrough (no Host header or SNI rewriting) and that a relay server is the supported way to terminate TLS or present a different hostname to the destination. --- README.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3aa948c..9c9d7ad 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ The OutSystems Cloud Connector establishes an outbound secure WebSocket (WSS) co No inbound firewall rules are required. The connector only needs the ability to initiate outbound connections. -If the network requires outbound traffic to route through a proxy, you specify that using the `--proxy` option. +If the network requires outbound traffic to route through a proxy, you specify that using the `--proxy` option. `--proxy` applies only to this connection, from Cloud Connector to the Private Gateway. The connection from Cloud Connector to each `` is dialed directly by the host's local network stack and never passes through `--proxy`. #### Layer 7 (Application-Level) Firewalls @@ -157,6 +157,16 @@ In the above example you create a tunnel to connect two endpoints. One, as befor You can create a tunnel to any endpoint that's network accessible over TCP or UDP from the system on which `outsystemscc` is run, whether identified by IP address or hostname/FQDN. If the connection is over UDP, add `/udp` to the end of the remote port. +#### Raw passthrough, hostname routing, and relay servers + +`outsystemscc` creates a raw TCP/UDP tunnel to ``. It doesn't parse or rewrite any part of the traffic it carries, so it never touches an HTTP `Host` header or a TLS Server Name Indication (SNI). Whatever hostname the connecting app dials arrives at `` unchanged. + +`` doesn't need to be the final destination. Since `outsystemscc` only opens a plain TCP connection to it, you can point `` at a relay that then forwards to the real destination, for example to reach a service that isn't directly reachable from the private network, or that expects a different hostname or certificate than the connecting app presents. + +This matters for TLS in particular. `outsystemscc` only trusts certificates signed by a public/verified Certificate Authority (CA) for the endpoints it connects to, so a destination presenting an internal or self-signed certificate can't be reached directly. Terminate TLS at the relay instead, using a certificate signed by a public CA, and have the relay talk to the real destination however that destination expects, over internal TLS with its own certificate, or over plain TCP if that segment is trusted. + +If the destination routes requests based on the `Host` header, rewrite the header at the connecting application, since `outsystemscc` passes it through unchanged. If the destination validates the TLS SNI instead, rewriting the `Host` header doesn't help, since the SNI is set during the TLS handshake before any HTTP-layer code runs. Terminating TLS at a relay is the way to present the SNI the destination expects. + To learn more about using connected endpoints in app development go to the [ODC documentation site](https://www.outsystems.com/goto/secure-gateways). Be sure to share the list of connected endpoint(s) of the form `secure-gateway:` and any associated swagger specification file(s) with members of your team responsible developing apps in ODC Studio. You can also use the connected endpoint(s) in custom code development using the External Libraries feature, see the [External Libraries SDK documentation](https://www.outsystems.com/goto/external-logic-private-gateway) for guidance. @@ -244,8 +254,10 @@ If your organization uses a centralized log management product, see its document disconnection. Defaults to 5 minutes. --proxy, An optional HTTP CONNECT or SOCKS5 proxy which will be - used to reach the server. Authentication can be specified - inside the URL. + used to reach (the Private Gateway). This proxy applies + only to that connection. The connection to each is + always dialed directly and never passes through --proxy. + Authentication can be specified inside the URL. For example, http://admin:password@my-server.com:8081 or: socks://admin:password@my-server.com:1080 From 9b33cb91968c2c2e3b6000a03d0f22761cf18ce3 Mon Sep 17 00:00:00 2001 From: Romeo Mlinar Date: Wed, 2 Sep 2026 17:03:14 +0100 Subject: [PATCH 2/2] RDTKF-25112 Move concept to Overview, rewrite negatives per style guide Moves the raw-passthrough/relay-server explanation from Usage into Overview, where it belongs conceptually, and trims it to the new information it adds over the existing TLS/CA note already in Usage. Rewrites negated statements as positive ones per MSSG/GDSG guidance. --- README.md | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 9c9d7ad..db3641e 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,8 @@ You run `outsystemscc` on a system in your private network—an on-premise netwo `outsystemscc` creates a fast TCP/UDP tunnel, with transport over HTTP via WebSockets, secured via SSH using ECDSA with SHA256 keys. The connection is established to either the built-in domain for the stage (for example `.outsystems.app`) or a custom domain configured for the stage (for example `example.com`). In both cases, the connection is over TLS and always encrypted with a valid X.509 certificate. +Past that tunnel, `outsystemscc` forwards traffic to each `` as a raw TCP/UDP passthrough, carrying HTTP and TLS content through exactly as the connecting client sends it. An HTTP `Host` header or a TLS Server Name Indication (SNI) reaches `` unchanged. Because `outsystemscc` treats `` as an opaque TCP/UDP endpoint, `` can itself be a relay rather than the final service: point it at an intermediary that terminates TLS or presents a different hostname when the real destination requires that. + The following diagram is an example of a ODC customer setup for a Private Gateway active on two stages. ![Private gateways diagram](images/private-gateways-diag.png "Private gateways diagram") @@ -89,7 +91,7 @@ The OutSystems Cloud Connector establishes an outbound secure WebSocket (WSS) co No inbound firewall rules are required. The connector only needs the ability to initiate outbound connections. -If the network requires outbound traffic to route through a proxy, you specify that using the `--proxy` option. `--proxy` applies only to this connection, from Cloud Connector to the Private Gateway. The connection from Cloud Connector to each `` is dialed directly by the host's local network stack and never passes through `--proxy`. +If the network requires outbound traffic to route through a proxy, you specify that using the `--proxy` option. `--proxy` applies only to this connection, from Cloud Connector to the Private Gateway. `outsystemscc` dials the connection to each `` directly through the host's local network stack, bypassing `--proxy`. #### Layer 7 (Application-Level) Firewalls @@ -157,16 +159,6 @@ In the above example you create a tunnel to connect two endpoints. One, as befor You can create a tunnel to any endpoint that's network accessible over TCP or UDP from the system on which `outsystemscc` is run, whether identified by IP address or hostname/FQDN. If the connection is over UDP, add `/udp` to the end of the remote port. -#### Raw passthrough, hostname routing, and relay servers - -`outsystemscc` creates a raw TCP/UDP tunnel to ``. It doesn't parse or rewrite any part of the traffic it carries, so it never touches an HTTP `Host` header or a TLS Server Name Indication (SNI). Whatever hostname the connecting app dials arrives at `` unchanged. - -`` doesn't need to be the final destination. Since `outsystemscc` only opens a plain TCP connection to it, you can point `` at a relay that then forwards to the real destination, for example to reach a service that isn't directly reachable from the private network, or that expects a different hostname or certificate than the connecting app presents. - -This matters for TLS in particular. `outsystemscc` only trusts certificates signed by a public/verified Certificate Authority (CA) for the endpoints it connects to, so a destination presenting an internal or self-signed certificate can't be reached directly. Terminate TLS at the relay instead, using a certificate signed by a public CA, and have the relay talk to the real destination however that destination expects, over internal TLS with its own certificate, or over plain TCP if that segment is trusted. - -If the destination routes requests based on the `Host` header, rewrite the header at the connecting application, since `outsystemscc` passes it through unchanged. If the destination validates the TLS SNI instead, rewriting the `Host` header doesn't help, since the SNI is set during the TLS handshake before any HTTP-layer code runs. Terminating TLS at a relay is the way to present the SNI the destination expects. - To learn more about using connected endpoints in app development go to the [ODC documentation site](https://www.outsystems.com/goto/secure-gateways). Be sure to share the list of connected endpoint(s) of the form `secure-gateway:` and any associated swagger specification file(s) with members of your team responsible developing apps in ODC Studio. You can also use the connected endpoint(s) in custom code development using the External Libraries feature, see the [External Libraries SDK documentation](https://www.outsystems.com/goto/external-logic-private-gateway) for guidance. @@ -253,11 +245,10 @@ If your organization uses a centralized log management product, see its document --max-retry-interval, Maximum wait time before retrying after a disconnection. Defaults to 5 minutes. - --proxy, An optional HTTP CONNECT or SOCKS5 proxy which will be - used to reach (the Private Gateway). This proxy applies - only to that connection. The connection to each is - always dialed directly and never passes through --proxy. - Authentication can be specified inside the URL. + --proxy, An optional HTTP CONNECT or SOCKS5 proxy used to reach + (the Private Gateway). Applies only to that connection: + outsystemscc dials the connection to each directly, + bypassing --proxy. Authentication can be specified inside the URL. For example, http://admin:password@my-server.com:8081 or: socks://admin:password@my-server.com:1080