Skip to main content

Create an advanced service

While a simple service is ideal for quick point-to-point connections, an advanced service provides granular control by allowing you to define multiple configurations (or no configurations) to manage how traffic is intercepted and offloaded. This method is primarily used for complex scenarios requiring multiple intercept points or broad port ranges within a single service definition.

Advanced services require you to manually attach configuration objects that define the "how" and "where" of your traffic:

  • intercept.v1: Defines how the client-side "catches" traffic (e.g., specific hostnames and port ranges) to send into the overlay.
  • host.v1: Defines how the hosting identity "offloads" that traffic to the destination server once it exits the overlay.

For more info, see Configurations.

Prerequisites​

Before creating an advanced service, ensure you have:

  • Policy knowledge: A basic understanding of service policies and service router policies. Unlike simple services, these aren't created automatically and must be configured manually to authorize traffic.
  • Configuration strategy: Determination of which configuration types (if any) are required for your specific use case.
Deployment note

While you can create a service without them, you eventually need online identities and routers to form a circuit and pass traffic.

Part 1: Create the advanced service​

  1. From the console, select your network from the dropdown in the left-hand menu.

  2. Click Services from the same menu, then the plus icon (+) to create a new service.
  3. Click Create advanced service.
  4. Enter a unique Service Name.
  5. (Optional) Assign Service Attributes (#) to group this service for policy management.
  6. (Optional) Add Configurations: Define how traffic enters or exits the overlay. While an advanced service can be created with no configurations, they're required when using NetFoundry tunnelers to bridge traditional underlay networks:
    • Intercepting side: Define an intercept.v1 configuration to "catch" traffic from the client-side underlay.
    • Hosting side: Define a host.v1 (or host.v2) configuration to "offload" traffic to the destination underlay.

Part 2: Define the intercept (client side)​

When using a tunneler to bridge your local network, the intercept.v1 configuration tells the edge client which traffic to "intercept" (or "catch") from the underlay to send into the overlay network.

  1. From the Select a Config dropdown, choose intercept.v1.

  2. For the Add a New Config dropdown, leave it as-is to add a new config.

    If you want to add an existing config, search for it and click Attach to Service, then skip to the next section.

  3. Enter a unique Config Name (e.g., RDP-intercept-config).

  4. Configure the interception parameters:

    • Port Ranges: Define the ports to intercept. Unlike simple services, you can specify individual ports or ranges (e.g., 3380-3390).

    • Addresses: Enter the hostname(s) or IP addresses the client will use to reach the service (e.g., sg3.rdp.internal).

      note

      These names don't need to be valid, registered FQDNs. OpenZiti uses its Private DNS feature to intercept these names locally on the device. It's often desirable to invent descriptive, easy-to-remember names (like my.secure.app) because they only exist within your authorized overlay and won't conflict with the public internet.

    • Allowed Source Addresses: Define which client-side addresses are allowed to access the service. To allow connections from any source, leave this field empty. To restrict access, enter a specific CIDR range (e.g., 10.0.0.0/24) or a comma-separated list of addresses.

  5. Dial Options:

    • Identity: Use this field for addressable terminators or to explicitly route traffic to a specific hosting identity. If left empty, the controller automatically determines the optimal path to an available destination.

  6. Select the Protocol: TCP, UDP, or both.

  7. (Optional) Source IP: Define the source address the hosting tunneler should use when it connects to the destination application.

    • This allows you to "spoof" the originating client's details using variables like $src_ip and $src_port.
    • You can also use identity metadata, such as $tunneler_id.name to resolve the client's identity name.
    • Note: If used, the hosting tunneler will validate this against the host.v1 Allowed Source Addresses; if they don't match, the connection will be blocked.

  8. Click Create and Attach.

Part 3: Define the host (server side)​

The host configuration tells the hosting identity where to send the traffic once it exits the overlay network.

  1. Click Add a New Config and select host.v1.

  2. For the Add a New Config dropdown, leave it as-is to add a new config.

    If you want to add an existing config, search for it and click Attach to Service, then skip to the next section.

  3. Enter a unique Config Name (e.g., RDP-host-config).

  4. Configure the destination and forwarding parameters:

    • Protocol: Choose a specific protocol (e.g., tcp) or toggle Forward Protocol to YES to match the intercepted protocol. These must match or the connection will be dropped.
    • Address: Enter the internal IP or hostname of the destination server (e.g., 127.0.0.1), or toggle Forward Address to YES to use the intercepted address (required for wildcard intercepts like *.my.domain).
    • Port: Enter a specific destination port (e.g., 3389), or toggle Forward Port to YES to preserve the port requested by the client.

  5. Configure security filters and address translations:

    • Allowed Source Addresses: Enter a comma-separated list of client-side addresses (IPs, CIDR ranges, or hostnames) allowed to offload to this host. To allow all source traffic, leave this field empty.
    • Forward Address Translations: Use this to map forwarded (intercepted) addresses to a specific set of IPv4 or IPv6 addresses. This is often used with wildcard intercepts to ensure that traffic reaches the correct internal destination according to a translation table.

  6. (Optional) Expand the advanced sub-sections to configure specialized behaviors:

    See Advanced options explained for a breakdown of these fields. :::
    • HTTP checks: Configure Layer 7 health checks (URL, status codes, and body expectations) to monitor web service availability.
    • Listen options: Define specialized binding behaviors, including Bind using edge identity, connection limits, and routing precedence.
    • Port checks: Configure Layer 4 TCP health checks to ensure the destination port is reachable.
    • Proxy: Define the proxy address and type (http or socks5) if the host requires a proxy to reach the destination.

  7. Click Create and Attach.

Part 4: Configure global service options (optional)​

After attaching your configurations, you can define global behaviors for the service:

  1. Toggle the Show More Options switch to ON.
  2. Configure the global service parameters:
    • Terminator Strategy: Select the load-balancing method for the service:
      • Smart routing: (Default) Routes based on the fastest path through the fabric.
      • Sticky: Persists a client session to the same host terminator for the duration of the connection.
      • Weighted: Routes based on assigned costs or priorities.
      • Random: Distributes traffic randomly across available host terminators.
    • Encryption: Toggle Require encryption to YES to ensure all traffic is end-to-end encrypted through the overlay.
  3. Custom tags: Click + New Tag to add metadata for organizational or automation purposes.

Part 5: Save the service​

  1. Review your attached configurations in the right-hand panel to ensure both the intercept.v1 and host.v1 are present.
  2. Click Save.

Part 6: Authorize the service​

Creating the service is only the first step. For traffic to flow through the overlay, you must authorize the connection by creating the following policies:

Troubleshooting

For help, see our service troubleshooting guide. Common issues often include missing edge router policies (ERPs), which authorize an identity to connect to a specific router. Without a valid ERP, the circuit can't be completed even if the service itself is configured correctly.

Advanced options explained​

You can configure the following optional settings within the host.v1/host.v2 configurations:

HTTP checks​

Use these settings to monitor the health of a web-based service. The service is only advertised to the overlay if these checks pass:

  • Actions: (Optional) Define how the fabric responds to health state changes.
    • Action: Enter a specific fabric command. The fabric only recognizes specific strings: mark healthy, mark unhealthy, increase cost [number], decrease cost [number], or send event.
    • Consecutive events: Define how many times a check must result in the same state before the action is triggered.
    • Duration: The time window (e.g., 10s, 1m) in which the consecutive events must occur.
    • Trigger: Select the state change that initiates the action (fail, pass, or change).
  • Body: Define a specific payload to send to the health check endpoint.
  • Expect in body: Define a specific string to look for in the response body to verify health.
  • Expect status: The required numeric HTTP response code (defaults to 200).
  • Interval: How often the check is performed (e.g., 10s).
  • Method: Select the HTTP verb for the check.
  • Timeout: How long to wait for a response before marking the check as failed.
  • URL: The full endpoint to monitor (e.g., http://127.0.0.1:8080/health).

Listen options​

These settings control how the hosting identity binds the service to the fabric:

  • Bind using edge identity: Toggle to YES to allow the identity's name to be used as a reachable address for addressable terminators (equivalent to setting Identity to $tunneler_id.name).
  • Connect timeout: The time limit for the initial connection attempt (supports duration strings like 5s or 500ms).
  • Connect timeout seconds: The specific numeric value for the timeout in seconds (e.g., 5).
  • Cost: A numeric value between 0-65535 to influence traffic routing. The fabric always prefers the lowest-cost available path.
  • Identity: Specify a specific identity for binding. This field supports dynamic metadata variables like $tunneler_id.name or $tunneler_id.tag[tagName].
  • Max connections: Limit the total number of simultaneous connections allowed (must be 1 or greater; defaults to 3).
  • Precedence: Select the priority level for the terminator:
    • default: The terminator is used normally based on cost and load balancing.
    • required: The terminator must be used if it is available; other terminators are ignored.
    • failed: The terminator is manually marked as down and won't receive traffic.

Port checks​

Use these for Layer 4 health monitoring of non-web services (e.g., RDP or SSH). The service is only advertised to the overlay if these connectivity checks pass:

  • Address: The internal hostname or IP and port to check (e.g., 127.0.0.1:3389).
  • Actions: (Optional) Define how the fabric responds to health state changes.
    • Action: Enter a specific fabric command. The fabric only recognizes specific strings: mark healthy, mark unhealthy, increase cost [number], decrease cost [number], or send event.
    • Consecutive Events: Define how many times a check must result in the same state before the action is triggered (e.g., 3 failed checks).
    • Duration: The time window (e.g., 10s, 1m) in which the consecutive events must occur.
    • Trigger: Select the state change that initiates the action (fail, pass, or change).
  • Interval: The frequency of the connectivity check (e.g., 1m).
  • Timeout: The wait time for a successful TCP handshake before marking the check as failed.

Proxy​

Configure these if the hosting identity must navigate a local proxy to reach the destination server:

  • Address: The address of the proxy server in host:port format (e.g., 10.0.0.50:3128).
  • Type: Select the proxy protocol. The hosting tunneler supports http proxies.