<!-- Single-sourced snippet. Included by workshop-definition.rst,
sdk-definition.rst, and sdkcraft-definition.rst.
Do not add a top-level label; the including page provides the anchor. -->

# Tunnel interface

<!-- @artefact tunnel interface -->

The tunnel interface forwards a network address or Unix domain socket.

Both tunnel plugs and tunnel slots take a single attribute:

| Key        | Value   | Description                                                                                                                       |
|------------|---------|-----------------------------------------------------------------------------------------------------------------------------------|
| `endpoint` | string  | Network address or Unix domain socket that forms one end of the tunnel.<br/>Defaults to `localhost/tcp` for both plugs and slots. |

The `endpoint` value follows this grammar:

| Field    | Format                                                                                                                                                                                                                                                                                                        |
|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Endpoint | `<ADDRESS>/<PROTOCOL>` for network endpoints;<br/>may be shortened to `<ADDRESS>` or `<PROTOCOL>` alone.<br/><br/>`<PATH>` or `@<STRING>` for Unix domain sockets.                                                                                                                                            |
| Address  | `<HOST>:<PORT>`; may be shortened to `<HOST>` or `<PORT>`.                                                                                                                                                                                                                                                    |
| Protocol | Either `tcp` or `udp`. Defaults to `tcp`.                                                                                                                                                                                                                                                                     |
| Host     | An IPv4 or IPv6 address.<br/>When a port is supplied, IPv6 addresses must be enclosed in square brackets.<br/><br/>Supported aliases: `localhost`, `ip6-localhost`, and `ip6-loopback`.<br/>Defaults to `localhost`.                                                                                          |
| Port     | A TCP or UDP port number (1-65535).<br/>May be omitted, but only on one side of a connection; both sides then use the same port.<br/><br/>For security, tunnel plugs in the system SDK cannot use privileged ports (1-1023).                                                                                  |
| Path     | Absolute path to a Unix domain socket.<br/><br/>`$HOME` expands to the user’s home directory<br/>and `$XDG_RUNTIME_DIR` expands to the user runtime directory<br/>(typically `/run/user/1000`).<br/><br/>For security, tunnel plugs in the system SDK cannot listen on sockets outside these two directories. |
| String   | An abstract socket name.                                                                                                                                                                                                                                                                                      |

Endpoints that start with `[` or `@` must be quoted in YAML:

```yaml
endpoint: '[::1]:8080/tcp'
endpoint: '@abstract.sock'
```