31 lines
2.8 KiB
Markdown
31 lines
2.8 KiB
Markdown
# TCP and UDP Streams
|
|
|
|
The **Streams** workspace forwards non-HTTP TCP or UDP traffic through dedicated sockets. It is separate from Vhost HTTP routing. Suitable examples include selected private TCP application ports and UDP protocols that need basic forwarding rather than HTTP features.
|
|
|
|
## Configure a Stream
|
|
|
|
1. Open **Streams → Add** and choose `TCP` or `UDP`, a unique name/ID and enabled state.
|
|
2. Set the listening IP/port and an upstream address, or configure a backend pool.
|
|
3. If using several backends, select weights, balancing, health checks and draining appropriately.
|
|
4. Configure connection/session limit, TCP connect timeout and idle timeout.
|
|
5. Save, restart RustProxy if the listener change requires it, then test with a real client and inspect Stream metrics.
|
|
|
|
The source model supports a legacy single-upstream configuration or a backend list (up to the validated per-host limit), with pool-based load balancing and health observations. Do not assume HTTP health-check response codes can be applied to a UDP-only application: use the probe options actually supported by the Stream type.
|
|
|
|
The backend editor groups connection/capacity settings separately from active health-check options. When **Health checks** is Off, probe tuning fields are hidden; selecting TCP connect/UDP probe reveals them without erasing their values. Hidden fields are excluded from browser validation.
|
|
|
|
## Behavior and boundaries
|
|
|
|
- **TCP** forwards a bidirectional byte stream. The proxy does not interpret application messages or terminate application TLS.
|
|
- **UDP** maintains bounded per-client forwarding sessions; datagrams and inactivity timeouts behave differently from TCP connections.
|
|
- **Not available:** HTTP Vhost routing, Host/path matching, HTTP cookies, WebSocket logic, shared HTTP cache, HTTP Basic/Tinyauth, HTTP header rules or frontend HTTP/3/TLS termination. Protect these endpoints with firewall rules and protocol-specific backend authentication/encryption.
|
|
- Listeners and backend IP/ports must be concrete, valid and nonconflicting with other RustProxy/admin/exporter sockets. Resource limits and network policy still apply.
|
|
|
|
## Status and testing
|
|
|
|
Stream views/Overview include sessions, connections, traffic, rejected/errors and backend health/capacity when enabled. Counter reset or no-data state after service restart is normal.
|
|
|
|
The source package includes `scripts/start_stream_backends.sh`, `scripts/test_stream_tcp.py` and `scripts/test_stream_udp.py` for isolated test networks. Their mock selftests alone do **not** establish that RustProxy forwarding works; run end-to-end client traffic through the configured Stream listener.
|
|
|
|
If clients cannot connect, inspect listen IP/port, host firewall, TCP vs UDP selection, routing to the chosen backend, backend health and stream logs. See [Security](SECURITY.md) and [Monitoring](MONITORING.md).
|