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.

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

Quick Start

Centralized Mode

Minimal configuration to connect a gateway to Control Plane:

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

# 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

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.

Complete .env Template

Copy this template and customize for your environment:

.env.example

# ============================================================
# 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://`)

Keep your GOLF_GATEWAY_API_KEY secure. It authenticates your gateway to the Control Plane. If compromised, regenerate it in the Golf Control Plane.

Security

Environment prefix: GOLF_SECURITY_

Settings

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

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

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 for the full model.

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

When GOLF_TLS_MTLS_ENABLED=true, both client_cert_file and client_key_file are required.

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)

Use either url (self-hosted) or cloud_id (Elastic Cloud), not both.

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

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

YAML Configuration

YAML configuration schema for Distributed mode deployments

Audit Log Schema

Complete audit log entry structure reference

Security Overview

Learn about Golf Gateway’s security features

Deployment Guide

Deploy Golf Gateway to production

Overview

Guides

Reference

Support

Environment Variables

Environment Variables

Quick Start

Centralized Mode

Distributed Mode

Complete .env Template

Gateway Identity

Security

Settings

Operation Mode

Cache (Redis)

Rate Limiting

Privacy

TLS/mTLS

Server TLS

CA Certificate

Mutual TLS (mTLS)

Export: Elasticsearch

Export: OpenTelemetry

Basic Configuration

Export Targets

Batching

Headers and Attributes

Export: Azure Sentinel

Data Collection Rule (DCR)

Azure AD Authentication

Performance

Better Stack Logging

YAML Configuration

Audit Log Schema

Security Overview

Deployment Guide

​Environment Variables

​Quick Start

​Centralized Mode

​Distributed Mode

​Complete .env Template

​Gateway Identity

​Security

​Settings

​Operation Mode

​Cache (Redis)

​Rate Limiting

​Privacy

​TLS/mTLS

​Server TLS

​CA Certificate

​Mutual TLS (mTLS)

​Export: Elasticsearch

​Export: OpenTelemetry

​Basic Configuration

​Export Targets

​Batching

​Headers and Attributes

​Export: Azure Sentinel

​Data Collection Rule (DCR)

​Azure AD Authentication

​Performance

​Better Stack Logging

​Related Documentation

YAML Configuration

Audit Log Schema

Security Overview

Deployment Guide

Environment Variables

Quick Start

Centralized Mode

Distributed Mode

Complete .env Template

Gateway Identity

Security

Settings

Operation Mode

Cache (Redis)

Rate Limiting

Privacy

TLS/mTLS

Server TLS

CA Certificate

Mutual TLS (mTLS)

Export: Elasticsearch

Export: OpenTelemetry

Basic Configuration

Export Targets

Batching

Headers and Attributes

Export: Azure Sentinel

Data Collection Rule (DCR)

Azure AD Authentication

Performance

Better Stack Logging

Related Documentation