> ## 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 policy violations only; `block`: enforce RBAC and security blocks |

***

## 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.