> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ultrabalancer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure UltraBalancer via CLI, YAML, or environment variables

## Quick Config

### CLI Arguments

```bash theme={null}
ultrabalancer start round-robin backend1:8080 backend2:8080 \
  --port 8080 \
  --cache \
  --compression gzip
```

### Config File (YAML)

Create `config.yaml`:

```yaml theme={null}
listen_address: "0.0.0.0"
listen_port: 8080
algorithm: "round-robin"

backends:
  - host: "192.168.1.10"
    port: 8080
    weight: 100
  - host: "192.168.1.11"
    port: 8080
    weight: 100
```

Run it:

```bash theme={null}
ultrabalancer start -c config.yaml
```

## Config Options

<AccordionGroup>
  <Accordion title="Listener">
    | Option            | Default   | Description                |
    | ----------------- | --------- | -------------------------- |
    | `listen_address`  | `0.0.0.0` | IP to bind to              |
    | `listen_port`     | `8080`    | Port to listen on          |
    | `workers`         | `auto`    | Worker threads (or number) |
    | `max_connections` | `10000`   | Max concurrent connections |
  </Accordion>

  <Accordion title="Backends">
    | Option            | Default | Description                     |
    | ----------------- | ------- | ------------------------------- |
    | `host`            | -       | Backend hostname/IP (required)  |
    | `port`            | -       | Backend port (required)         |
    | `weight`          | `100`   | Weight for weighted algorithms  |
    | `max_connections` | `1000`  | Max connections to this backend |
  </Accordion>

  <Accordion title="Health Checks">
    | Option         | Default | Description                       |
    | -------------- | ------- | --------------------------------- |
    | `enabled`      | `true`  | Enable health checking            |
    | `interval_ms`  | `5000`  | Check interval in ms              |
    | `max_failures` | `3`     | Failures before marking unhealthy |
    | `path`         | `/`     | HTTP path for checks              |
  </Accordion>

  <Accordion title="Caching">
    | Option                | Default | Description             |
    | --------------------- | ------- | ----------------------- |
    | `enabled`             | `false` | Enable response caching |
    | `max_size`            | `10000` | Max cached responses    |
    | `default_ttl_seconds` | `300`   | Default TTL             |
  </Accordion>

  <Accordion title="Compression">
    | Option      | Default | Description                 |
    | ----------- | ------- | --------------------------- |
    | `enabled`   | `false` | Enable compression          |
    | `algorithm` | `gzip`  | `gzip`, `brotli`, or `zstd` |
    | `min_size`  | `1024`  | Min bytes to compress       |
  </Accordion>

  <Accordion title="Rate Limiting">
    | Option                | Default | Description          |
    | --------------------- | ------- | -------------------- |
    | `enabled`             | `false` | Enable rate limiting |
    | `requests_per_second` | `1000`  | Global RPS limit     |
    | `per_ip_rps`          | `100`   | Per-IP RPS limit     |
  </Accordion>

  <Accordion title="TLS">
    | Option      | Default | Description               |
    | ----------- | ------- | ------------------------- |
    | `enabled`   | `false` | Enable TLS termination    |
    | `cert_path` | -       | Path to certificate (PEM) |
    | `key_path`  | -       | Path to private key (PEM) |
  </Accordion>
</AccordionGroup>

## Complete Example

```yaml theme={null}
listen_address: "0.0.0.0"
listen_port: 443
algorithm: "least-connections"

backends:
  - host: "backend1.internal"
    port: 8080
    weight: 100
  - host: "backend2.internal"
    port: 8080
    weight: 100

health_check:
  enabled: true
  interval_ms: 3000
  max_failures: 3

cache:
  enabled: true

compression:
  enabled: true
  algorithm: "gzip"

rate_limit:
  enabled: true
  requests_per_second: 10000

tls:
  enabled: true
  cert_path: "/etc/ultrabalancer/cert.pem"
  key_path: "/etc/ultrabalancer/key.pem"
```

## Environment Variables

```bash theme={null}
export ULTRA_LISTEN_ADDRESS="0.0.0.0"
export ULTRA_LISTEN_PORT="8080"
export ULTRA_ALGORITHM="round-robin"
export ULTRA_BACKENDS="backend1:8080,backend2:8080"
```

## Validate Config

```bash theme={null}
ultrabalancer validate -c config.yaml
```

## Next Steps

* [CLI Reference](/configuration/cli-reference) - All commands
* [File Config](/configuration/file-config) - YAML/TOML reference
* [Examples](/configuration/examples) - Real-world configs