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

# Environment Variables

> Configuration reference for Golf Gateway environment variables in Centralized and Distributed modes

# Environment Variables

Golf Gateway uses environment variables with the `GOLF_` prefix for configuration. This reference covers all variables available when running in **Centralized** or **Distributed** mode.

<Note>
  Golf Gateway supports multiple deployment modes. This documentation covers **Centralized** and **Distributed** modes, which are the recommended configurations for production deployments.
</Note>

## Quick Start

### Centralized Mode

Minimal configuration to connect a gateway to Control Plane:

```bash theme={null}
# Gateway Identity (Required)
# Get these values from the Control Plane when creating a new gateway
export GOLF_GATEWAY_ID=<uuid-from-control-plane>
export GOLF_GATEWAY_API_KEY=<api-key-from-control-plane>
export GOLF_GATEWAY_CONTROL_PLANE_URL=https://your-control-plane.example.com

# Redis (Required)
export GOLF_CACHE_REDIS_URL=redis://localhost:6379/0
```

### Distributed Mode

Distributed mode uses a local YAML configuration file for servers while connecting to Control Plane for organization policies and monitoring. Use the same environment variables as Centralized mode, plus a `golf_gateway.yaml` configuration file.

```bash theme={null}
# Same as Centralized mode
export GOLF_GATEWAY_ID=<uuid-from-control-plane>
export GOLF_GATEWAY_API_KEY=<api-key-from-control-plane>
export GOLF_GATEWAY_CONTROL_PLANE_URL=https://your-control-plane.example.com
export GOLF_CACHE_REDIS_URL=redis://localhost:6379/0

# Plus: Create a golf_gateway.yaml file with your server configurations
```

<Info>
  In Centralized and Distributed modes, server configurations, identity providers, and security policies are managed through the Golf Control Plane or YAML file - not through environment variables.
</Info>

***

## Complete .env Template

Copy this template and customize for your environment:

```bash .env.example theme={null}
# ============================================================
# Golf Gateway Configuration - Centralized / Distributed Mode
# ============================================================

# -------------------- REQUIRED SETTINGS --------------------

# Gateway Identity [REQUIRED]
# Get these from Control Plane when creating a new gateway
GOLF_GATEWAY_ID=your-gateway-uuid-here
GOLF_GATEWAY_API_KEY=your-gateway-api-key-here
GOLF_GATEWAY_CONTROL_PLANE_URL=https://your-control-plane.example.com

# Redis [REQUIRED]
GOLF_CACHE_REDIS_URL=redis://localhost:6379/0

# -------------------- OPTIONAL SETTINGS --------------------

# Server Binding
# GOLF_SERVER_HOST=0.0.0.0
# GOLF_SERVER_PORT=8080

# Security Mode
# GOLF_SECURITY_MODE=block

# Rate Limiting
# GOLF_RATE_LIMIT_ENABLED=true
# GOLF_RATE_LIMIT_REQUESTS_PER_MINUTE=1000
# GOLF_RATE_LIMIT_WINDOW_SECONDS=60

# -------------------- EXPORT: ELASTICSEARCH ----------------

# GOLF_ELASTICSEARCH_ENABLED=false
# GOLF_ELASTICSEARCH_URL=https://localhost:9200
# GOLF_ELASTICSEARCH_API_KEY=
# GOLF_ELASTICSEARCH_INDEX_PREFIX=golf-gateway

# -------------------- EXPORT: OPENTELEMETRY ----------------

# GOLF_OTEL_ENABLED=false
# GOLF_OTEL_ENDPOINT=http://localhost:4317
# GOLF_OTEL_PROTOCOL=grpc
# GOLF_OTEL_SERVICE_NAME=golf-gateway

# -------------------- EXPORT: AZURE SENTINEL ---------------

# GOLF_SENTINEL_ENABLED=false
# GOLF_SENTINEL_DCR_IMMUTABLE_ID=
# GOLF_SENTINEL_DCR_ENDPOINT=
# GOLF_SENTINEL_TENANT_ID=
# GOLF_SENTINEL_CLIENT_ID=
# GOLF_SENTINEL_CLIENT_SECRET=

# -------------------- TLS / mTLS ---------------------------

# GOLF_TLS_SERVER_CERT_FILE=
# GOLF_TLS_SERVER_KEY_FILE=
# GOLF_TLS_MTLS_ENABLED=false
```

***

## Gateway Identity

These variables connect your gateway to the Control Plane. Get these values when creating a new gateway in the Golf Control Plane.

Environment prefix: `GOLF_GATEWAY_`

| Variable                         | Type   | Required | Description                                                 |
| -------------------------------- | ------ | -------- | ----------------------------------------------------------- |
| `GOLF_GATEWAY_ID`                | UUID   | **Yes**  | Gateway UUID from Control Plane                             |
| `GOLF_GATEWAY_API_KEY`           | string | **Yes**  | Gateway API key for authentication                          |
| `GOLF_GATEWAY_CONTROL_PLANE_URL` | string | **Yes**  | Control Plane URL (must start with `http://` or `https://`) |

<Warning>
  Keep your `GOLF_GATEWAY_API_KEY` secure. It authenticates your gateway to the Control Plane. If compromised, regenerate it in the Golf Control Plane.
</Warning>

***

## Security

Environment prefix: `GOLF_SECURITY_`

### Settings

| Variable                      | Type   | Description                                                             |
| ----------------------------- | ------ | ----------------------------------------------------------------------- |
| `GOLF_SECURITY_INTEGRITY_KEY` | string | **Required.** 64-character hex key for audit log integrity verification |

```bash theme={null}
# Generate a security key
openssl rand -hex 32
```

### Operation Mode

| Variable             | Type                 | Default | Description                                           |
| -------------------- | -------------------- | ------- | ----------------------------------------------------- |
| `GOLF_SECURITY_MODE` | `monitor` \| `block` | `block` | `monitor`: log threats only; `block`: prevent threats |

***

## Cache (Redis)

Environment prefix: `GOLF_CACHE_`

| Variable               | Type   | Default                    | Description                        |
| ---------------------- | ------ | -------------------------- | ---------------------------------- |
| `GOLF_CACHE_REDIS_URL` | string | `redis://localhost:6379/0` | **Required.** Redis connection URL |

***

## Rate Limiting

Environment prefix: `GOLF_RATE_LIMIT_`

| Variable                              | Type | Default | Description                           |
| ------------------------------------- | ---- | ------- | ------------------------------------- |
| `GOLF_RATE_LIMIT_ENABLED`             | bool | `true`  | Enable rate limiting                  |
| `GOLF_RATE_LIMIT_REQUESTS_PER_MINUTE` | int  | `1000`  | Requests per minute per user (1-5000) |
| `GOLF_RATE_LIMIT_WINDOW_SECONDS`      | int  | `60`    | Rate limit window (10-300 seconds)    |

<Note>
  The per-user limit applies to authenticated users (and falls back to per-IP for anonymous requests). System-wide (**global**) and **per-server** limits exist but are managed through the Control Plane in Centralized mode — they are not configurable via environment variables. See [Configure Rate Limiting](/gateway/guides/operations/configure-rate-limiting) for the full model.
</Note>

***

## Privacy

Environment prefix: `GOLF_PRIVACY_`

| Variable                         | Type | Default | Description                          |
| -------------------------------- | ---- | ------- | ------------------------------------ |
| `GOLF_PRIVACY_SCRUBBING_ENABLED` | bool | `true`  | Enable/disable PII scrubbing in logs |

***

## TLS/mTLS

Environment prefix: `GOLF_TLS_`

### Server TLS

| Variable                       | Type   | Default | Description                       |
| ------------------------------ | ------ | ------- | --------------------------------- |
| `GOLF_TLS_SERVER_CERT_FILE`    | string | -       | Path to server certificate (PEM)  |
| `GOLF_TLS_SERVER_KEY_FILE`     | string | -       | Path to server private key (PEM)  |
| `GOLF_TLS_SERVER_KEY_PASSWORD` | string | -       | Password for encrypted server key |

### CA Certificate

| Variable                | Type   | Default | Description                                            |
| ----------------------- | ------ | ------- | ------------------------------------------------------ |
| `GOLF_TLS_CA_CERT_FILE` | string | -       | Path to CA certificate for verifying internal services |

### Mutual TLS (mTLS)

| Variable                       | Type   | Default | Description                                |
| ------------------------------ | ------ | ------- | ------------------------------------------ |
| `GOLF_TLS_MTLS_ENABLED`        | bool   | `false` | Enable mutual TLS with client certificates |
| `GOLF_TLS_CLIENT_CERT_FILE`    | string | -       | Path to client certificate (PEM) for mTLS  |
| `GOLF_TLS_CLIENT_KEY_FILE`     | string | -       | Path to client private key (PEM) for mTLS  |
| `GOLF_TLS_CLIENT_KEY_PASSWORD` | string | -       | Password for encrypted client key          |

<Warning>
  When `GOLF_TLS_MTLS_ENABLED=true`, both `client_cert_file` and `client_key_file` are required.
</Warning>

***

## Export: Elasticsearch

Environment prefix: `GOLF_ELASTICSEARCH_`

| Variable                          | Type   | Default        | Description                          |
| --------------------------------- | ------ | -------------- | ------------------------------------ |
| `GOLF_ELASTICSEARCH_ENABLED`      | bool   | `false`        | Enable Elasticsearch export          |
| `GOLF_ELASTICSEARCH_URL`          | string | -              | Elasticsearch URL (for self-hosted)  |
| `GOLF_ELASTICSEARCH_CLOUD_ID`     | string | -              | Elastic Cloud ID (for Elastic Cloud) |
| `GOLF_ELASTICSEARCH_API_KEY`      | string | -              | Elasticsearch API key                |
| `GOLF_ELASTICSEARCH_INDEX_PREFIX` | string | `golf-gateway` | Index name prefix                    |
| `GOLF_ELASTICSEARCH_TIMEOUT`      | int    | `30`           | Request timeout (5-120 seconds)      |

<Note>
  Use either `url` (self-hosted) or `cloud_id` (Elastic Cloud), not both.
</Note>

***

## Export: OpenTelemetry

Environment prefix: `GOLF_OTEL_`

### Basic Configuration

| Variable                 | Type                                     | Default        | Description                             |
| ------------------------ | ---------------------------------------- | -------------- | --------------------------------------- |
| `GOLF_OTEL_ENABLED`      | bool                                     | `false`        | Enable OTEL export                      |
| `GOLF_OTEL_ENDPOINT`     | string                                   | -              | OTLP endpoint URL (required if enabled) |
| `GOLF_OTEL_PROTOCOL`     | `grpc` \| `http/protobuf` \| `http/json` | `grpc`         | OTLP protocol                           |
| `GOLF_OTEL_SERVICE_NAME` | string                                   | `golf-gateway` | Service name in OTEL                    |
| `GOLF_OTEL_TIMEOUT`      | int                                      | `30`           | Export timeout (5-120 seconds)          |
| `GOLF_OTEL_COMPRESSION`  | `gzip` \| `none`                         | `gzip`         | Compression method                      |
| `GOLF_OTEL_INSECURE`     | bool                                     | `false`        | Allow insecure connections              |

### Export Targets

| Variable                   | Type | Default | Description       |
| -------------------------- | ---- | ------- | ----------------- |
| `GOLF_OTEL_EXPORT_LOGS`    | bool | `true`  | Export audit logs |
| `GOLF_OTEL_EXPORT_METRICS` | bool | `false` | Export metrics    |
| `GOLF_OTEL_EXPORT_TRACES`  | bool | `false` | Export traces     |

### Batching

| Variable                     | Type | Default | Description                               |
| ---------------------------- | ---- | ------- | ----------------------------------------- |
| `GOLF_OTEL_BATCH_SIZE`       | int  | `512`   | Items per batch (1-2048)                  |
| `GOLF_OTEL_BATCH_TIMEOUT_MS` | int  | `5000`  | Batch timeout in milliseconds (100-30000) |

### Headers and Attributes

| Variable                        | Type | Default | Description                           |
| ------------------------------- | ---- | ------- | ------------------------------------- |
| `GOLF_OTEL_HEADERS`             | JSON | `{}`    | Additional headers for authentication |
| `GOLF_OTEL_RESOURCE_ATTRIBUTES` | JSON | `{}`    | Additional resource attributes        |

```bash theme={null}
# Example: OTEL with authentication header
GOLF_OTEL_HEADERS='{"Authorization": "Bearer YOUR_TOKEN"}'
GOLF_OTEL_RESOURCE_ATTRIBUTES='{"environment": "production", "region": "us-west-2"}'
```

***

## Export: Azure Sentinel

Environment prefix: `GOLF_SENTINEL_`

### Data Collection Rule (DCR)

| Variable                         | Type   | Default                 | Description                         |
| -------------------------------- | ------ | ----------------------- | ----------------------------------- |
| `GOLF_SENTINEL_ENABLED`          | bool   | `false`                 | Enable Sentinel export              |
| `GOLF_SENTINEL_DCR_IMMUTABLE_ID` | string | -                       | Data Collection Rule immutable ID   |
| `GOLF_SENTINEL_DCR_ENDPOINT`     | string | -                       | DCR logs ingestion endpoint (HTTPS) |
| `GOLF_SENTINEL_DCR_STREAM_NAME`  | string | `Custom-GolfGateway_CL` | DCR stream name                     |

### Azure AD Authentication

| Variable                      | Type   | Default | Description                 |
| ----------------------------- | ------ | ------- | --------------------------- |
| `GOLF_SENTINEL_TENANT_ID`     | string | -       | Azure tenant ID             |
| `GOLF_SENTINEL_CLIENT_ID`     | string | -       | Service principal client ID |
| `GOLF_SENTINEL_CLIENT_SECRET` | string | -       | Service principal secret    |

### Performance

| Variable                         | Type | Default | Description                               |
| -------------------------------- | ---- | ------- | ----------------------------------------- |
| `GOLF_SENTINEL_BATCH_SIZE`       | int  | `100`   | Batch size (1-500)                        |
| `GOLF_SENTINEL_BATCH_TIMEOUT_MS` | int  | `10000` | Batch timeout in milliseconds (100-30000) |
| `GOLF_SENTINEL_TIMEOUT`          | int  | `30`    | Request timeout (5-120 seconds)           |
| `GOLF_SENTINEL_MAX_RETRIES`      | int  | `3`     | Maximum retry attempts (1-10)             |

***

## Better Stack Logging

Environment prefix: `GOLF_BETTERSTACK_`

| Variable                        | Type   | Default                  | Description                                               |
| ------------------------------- | ------ | ------------------------ | --------------------------------------------------------- |
| `GOLF_BETTERSTACK_SOURCE_TOKEN` | string | -                        | Better Stack source token (required to enable)            |
| `GOLF_BETTERSTACK_HOST`         | string | `https://in.logtail.com` | Better Stack ingestion host                               |
| `GOLF_BETTERSTACK_LOG_LEVEL`    | string | `INFO`                   | Minimum log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="YAML Configuration" icon="file-code" href="/gateway/reference/yaml-schema">
    YAML configuration schema for Distributed mode deployments
  </Card>

  <Card title="Audit Log Schema" icon="scroll" href="/gateway/reference/audit-log-schema">
    Complete audit log entry structure reference
  </Card>

  <Card title="Security Overview" icon="shield" href="/gateway/concepts/security">
    Learn about Golf Gateway's security features
  </Card>

  <Card title="Deployment Guide" icon="rocket" href="/gateway/guides/deployment">
    Deploy Golf Gateway to production
  </Card>
</CardGroup>