> ## Documentation Index > Fetch the complete documentation index at: https://docs.siderolabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Connect Machines to Omni Through a Corporate Proxy > Register and manage Talos machines with Omni when the only outbound path is a corporate HTTP proxy. Talos machines can register with Omni and be managed from sites where the only outbound path is a corporate HTTP proxy. This page covers the requirements specific to Omni. For general proxy configuration in Talos, see [Corporate Proxies](https://docs.siderolabs.com/talos/v1.14/networking/corporate-proxies.md). ## How SideroLink works behind a proxy Omni manages machines over SideroLink, an overlay network built on WireGuard. WireGuard runs over UDP, which an HTTP proxy cannot carry. The SideroLink gRPC tunnel solves this by carrying WireGuard traffic inside a TCP connection to the SideroLink API endpoint. Proxy settings on a Talos machine are environment variables that apply to the whole node. Traffic to the SideroLink overlay and traffic the machine sends to itself would also go to the proxy, which cannot route either, so both must be excluded with `no_proxy`. A machine has no configuration at first boot. The tunnel and proxy settings therefore go into the installation media, and the proxy settings are passed as kernel arguments. Omni keeps the kernel arguments from the media when Talos is installed, so the same proxy settings apply after installation and when the machine joins a cluster. ## Requirements The network and the tools listed in this section must be in place before creating installation media. ### Network requirements The network must provide proxy access to Omni and to the Talos egress domains, along with DNS and time services: * **Proxy access to the SideroLink API endpoint**: Machines connect to Omni through the **SideroLink API Endpoint**, shown in the Omni UI under **Home** > **General Information**. The proxy must allow `CONNECT` to this endpoint's hostname and port, which is 443 on Omni SaaS. Allow both the hostname and the IP addresses it resolves to, because machines connect to the endpoint by both. With the gRPC tunnel enabled, the UDP **SideroLink Endpoint** is not used. * **Proxy access to Talos egress domains**: Machines pull installation media and container images through the proxy, so the proxy must allow the domains listed in [Egress Domains](https://docs.siderolabs.com/talos/v1.14/networking/egress-domains.md), along with any registry you mirror or host. The list includes `discovery.talos.dev`, which clusters use unless they enable Omni's embedded discovery service. * **DNS**: The machine must resolve the SideroLink API endpoint hostname itself, even when all other traffic goes through the proxy. Without a reachable DNS resolver, the machine cannot register. * **An internal time server**: NTP runs over UDP, so it cannot pass through an HTTP proxy. Configure an internal time source with `TimeSyncConfig` or by [overriding the NTP servers](https://docs.siderolabs.com/omni/cluster-management/override-ntp-servers.md). Without one, the machine stops at time synchronization, because `bootTimeout` waits indefinitely by default. > [!WARNING] > > Many corporate proxies permit `CONNECT` to port 443 only. If a self-hosted Omni serves the SideroLink API on another port, such as `8090`, either allow that port on the proxy or serve the SideroLink API on port 443. > [!NOTE] > > Proxy topology and bypass rules differ between networks, and Omni cannot infer them. The network operator is responsible for a correct proxy URL and a complete `no_proxy` list. ### Tools and values Creating the installation media requires the following: * The proxy URL, including credentials if the proxy requires them. * `omnictl` at a version that matches your Omni instance. See [Install and Configure omnictl](https://docs.siderolabs.com/omni/getting-started/install-and-configure-omnictl.md). ## Register a machine through the proxy The following steps create installation media with the tunnel and proxy settings, then register one machine to confirm that the media works. The media is created from an installation media preset, a named set of media options stored in Omni that can be used to download media repeatedly. For all preset options, see the [`omnictl media preset create` reference](../reference/cli#omnictl-media-preset-create). To enable the tunnel without a preset, see [Other ways to enable the tunnel](#other-ways-to-enable-the-tunnel). 1. Create an installation media preset with the tunnel and proxy settings, replacing `` with a name for the preset, `` with `amd64` or `arm64`, `` with the proxy URL, and `` with the IPv4 and IPv6 subnets the machines get their addresses from: ```bash theme={null} omnictl media preset create --arch --use-siderolink-grpc-tunnel \ --extra-kernel-args "talos.environment=https_proxy=" \ --extra-kernel-args "talos.environment=no_proxy=fdae:41e4:649b:9303::/64,0.0.0.0," ``` > [!NOTE] > > SideroLink connections use `https_proxy` for proxy selection, and `http_proxy` has no effect on them. The `no_proxy` list contains three kinds of entries: * `fdae:41e4:649b:9303::/64` is the SideroLink overlay prefix, the same for every Omni deployment. Omni is reachable at `fdae:41e4:649b:9303::1` inside the overlay, and each machine's overlay address comes from the same `/64`. * `0.0.0.0` covers node-internal traffic that no CIDR entry matches. * The machine subnets cover traffic a machine sends to its own addresses. Without them, the proxy rejects that traffic and the control plane does not become ready. Add any other destinations your network requires to `no_proxy`, separated by commas. Entries follow Go's standard matching rules and can be hostnames, IP addresses, or CIDR ranges. 2. Confirm that the preset stored both settings: ```bash theme={null} omnictl get installationmediaconfigs -o yaml ``` The spec contains `grpctunnel: 1` and a `kernelargs` field with both `talos.environment` arguments. 3. Download the installation media, setting `` to `iso`, `raw`, `qcow2`, or `pxe`, where `pxe` prints a PXE boot URL instead of downloading a file: ```bash theme={null} omnictl media download --format ``` 4. Boot one machine from the media, and confirm that it appears in Omni and reaches a connected state: ```bash theme={null} omnictl get machines ``` The machine appears in the list with `CONNECTED` set to `true`. Omni cannot deliver corrections to a machine that cannot reach it, so validate the media on one machine before booting the rest of the site. The machine can now be added to a cluster like any other machine. Presets persist in Omni after the media is downloaded. To delete the preset when it is no longer needed, run `omnictl media preset delete `. ## Manage machines behind a proxy A registered machine needs no further proxy-specific steps unless the network changes or the machine loses its connection to Omni. The following sections cover both cases. ### Change proxy settings When the proxy address or the required `no_proxy` entries change, the settings on registered machines must be updated. The proxy settings are stored in each machine's kernel arguments. To change them, [update the machine's kernel arguments](https://docs.siderolabs.com/omni/infrastructure-and-extensions/modify-kernel-arguments.md#update-kernel-arguments-on-existing-machines). ### Recover a machine that cannot reach Omni A wrong proxy setting can disconnect a machine from Omni. Omni delivers machine configuration over SideroLink, so it cannot deliver a corrected configuration to a disconnected machine. [Break glass](https://docs.siderolabs.com/omni/security-and-authentication/break-glass-emergency-access.md) access can reach the machine, but its `os:operator` role cannot apply machine configuration. It is limited to inspection and operator-level recovery. To recover the machine, restore SideroLink connectivity, or work out of band. Use the machine's BMC or Redfish interface to return it to maintenance mode, or [wipe the machine](https://docs.siderolabs.com/omni/cluster-management/wipe-a-machine.md) and rejoin it with corrected media. ## Other ways to enable the tunnel Installation media presets are one of four ways to enable the gRPC tunnel. The tunnel can also be enabled on a join configuration, as an account-wide default, or on a single machine. ### On a join configuration For machines that join with a join configuration rather than generated media, `omnictl jointoken kernel-args` and `omnictl jointoken machine-config` both accept `--use-grpc-tunnel`. To print kernel arguments with the tunnel enabled, run: ```bash theme={null} omnictl jointoken kernel-args --use-grpc-tunnel ``` > [!WARNING] > > Do not enable the tunnel by passing a `siderolink.api` value to `--extra-kernel-args`. The tunnel setting is a query parameter inside the `siderolink.api` URL, and `--extra-kernel-args` only appends arguments. The result is two `siderolink.api` arguments, and the tunnel stays disabled. Passing `talos.environment` arguments with `--extra-kernel-args` is not affected. ### As the account-wide default The account-wide default applies when media is generated without an explicit tunnel flag. To read the current setting, run: ```bash theme={null} omnictl get connectionparams -o yaml ``` The `usegrpctunnel` field holds the setting. The output also includes your join token, so redact it before sharing. On self-hosted Omni, the `--siderolink-use-grpc-tunnel` server flag enables the tunnel for every machine, regardless of individual settings. On Omni SaaS, [Sidero Labs support](https://www.siderolabs.com/support-and-services/) can change the default. ### On a single machine After Omni has discovered a machine, its connection mode can be set individually. Run the following command, replacing `` with the machine's UUID: ```bash theme={null} omnictl configure machine --siderolink-connection http-tunnel ``` The `--siderolink-connection` flag accepts the following values: * `udp` uses WireGuard over UDP. * `http-tunnel` uses the gRPC tunnel. * `auto` removes the override, and the machine uses the mode from its join configuration. The machine applies the change on its next connection attempt. Because the setting requires a known machine UUID, it cannot configure a machine's first boot. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.