Skip to content

Global Settings

Global Settings

Global settings apply to all processes and control system-wide behavior.

Configuration Structure

version: "1.0"

global:
  shutdown_timeout: 30
  log_format: json
  log_level: info
  metrics_enabled: true
  metrics_port: 9090
  metrics_path: /metrics
  api_enabled: true
  api_port: 9180
  api_auth: "your-secure-token"

Available Settings

shutdown_timeout

Type: integer (seconds) Default: 30 Description: Maximum time to wait for all processes to stop gracefully before force-kill.

global:
  shutdown_timeout: 60  # Wait up to 60 seconds

When to adjust:

  • Increase (60-120s) for processes with long cleanup (database connections, file uploads)
  • Decrease (10-20s) for fast-stopping processes (static file servers)

log_format

Type: string Options: json, text Default: json Description: Output format for structured logs.

global:
  log_format: json  # Recommended for production

Recommendations:

  • json - Production environments, log aggregation (Datadog, Splunk)
  • text - Local development, human-readable output

log_level

Type: string Options: debug, info, warn, error Default: info Description: Minimum log level to output.

global:
  log_level: info

Level Guide:

  • debug - Verbose logging for development and troubleshooting
  • info - Standard production logging (recommended)
  • warn - Warnings and errors only
  • error - Errors only (not recommended, may miss important warnings)

Advanced Logging

Global logging is limited to the three fields above (log_format, log_level, log_timestamps). Level detection, multiline reassembly, JSON parsing, filtering, and redaction are configured per process under processes.<name>.logging, not globally:

processes:
  php-fpm:
    command: ["php-fpm", "-F", "-R"]
    logging:
      min_level: info
      multiline:
        enabled: true
        pattern: '^\[|^\d{4}-|^\{'
      redaction:
        enabled: true
        patterns:
          - name: password
            pattern: 'password=\S+'
            replacement: 'password=***'

See Advanced Logging for the full per-process schema.

Restart Configuration

global:
  restart_policy: always           # always | on-failure | never
  max_restart_attempts: 5          # 0 = unlimited
  restart_backoff_initial: 5s      # Initial delay before restart
  restart_backoff_max: 60s         # Maximum delay cap
  restart_stability_window: 60s    # Uptime after which the restart budget resets
  • restart_backoff_initial and restart_backoff_max accept Go duration strings (5s, 1m, etc.).
  • Backoff grows exponentially (initial * 2^n) and is clamped by restart_backoff_max.
  • Legacy restart_backoff (integer seconds) is still accepted for backwards compatibility.
  • restart_stability_window (default 60s) gives max_restart_attempts sliding-window semantics instead of a lifetime total: once an instance has stayed up for this long it is treated as recovered and its restart counter resets to zero. This prevents a service that crashes rarely — but more than max_restart_attempts times over the container's whole lifetime — from being permanently abandoned. Set it to a negative value to disable the reset (restore the old lifetime-total behaviour).

Metrics Configuration

global:
  metrics_enabled: true
  metrics_port: 9090
  metrics_path: /metrics

Settings:

  • metrics_enabled - Enable/disable Prometheus metrics (default: false)
  • metrics_port - HTTP port for metrics endpoint (default: 9090)
  • metrics_path - URL path for metrics (default: /metrics)
  • metrics_host - Bind host for the metrics listener (default: all interfaces). Set to 127.0.0.1 to expose metrics only to a local sidecar/agent.

Access metrics:

curl http://localhost:9090/metrics

See Prometheus Metrics for complete metric documentation.

Management API Configuration

global:
  api_enabled: true
  api_port: 9180
  api_auth: "your-secure-token"

Settings:

  • api_enabled - Enable/disable TCP REST API (default: false)
  • api_port - HTTP port for API endpoints (default: 9180)
  • api_host - Bind host for the API listener (default: 127.0.0.1, loopback only). Binding beyond loopback exposes a control plane that can start, stop and reconfigure every process in the container, so cbox-init refuses to start unless you also set api_auth or an api_acl with mode: allow and a non-empty allow_list.
  • api_auth - Optional Bearer token for authentication

API Endpoints:

  • GET /api/v1/health - API health check
  • GET /api/v1/processes - List processes
  • POST /api/v1/processes/{name}/restart - Restart process

See Management API for complete API documentation.

Note: Local management still uses the Unix socket listener. Set api_enabled: true only when you need the TCP REST API, and pair it with api_auth, ACLs, or TLS for production.

Container Readiness Configuration

For Kubernetes integration, Cbox Init can manage a readiness file that indicates when all processes are healthy:

global:
  readiness:
    enabled: true
    path: "/tmp/cbox-ready"
    mode: "all_healthy"
    processes:
      - php-fpm
      - nginx

Settings:

  • enabled - Enable/disable readiness file management (default: false)
  • path - Path to the readiness file (default: /tmp/cbox-ready)
  • mode - Readiness evaluation mode: all_healthy or all_running (default: all_healthy)
  • content - Custom file content when ready (optional)
  • processes - Specific processes to track (empty = all processes)

Kubernetes readinessProbe example:

readinessProbe:
  exec:
    command: ["test", "-f", "/tmp/cbox-ready"]
  initialDelaySeconds: 5
  periodSeconds: 5

See Container Readiness for complete documentation.

Environment Variable Overrides

All global settings can be overridden via environment variables:

# Override log level
CBOX_INIT_GLOBAL_LOG_LEVEL=debug ./cbox-init

# Override shutdown timeout
CBOX_INIT_GLOBAL_SHUTDOWN_TIMEOUT=60 ./cbox-init

# Enable metrics
CBOX_INIT_GLOBAL_METRICS_ENABLED=true ./cbox-init

Pattern: CBOX_INIT_GLOBAL_<SETTING_NAME>=<value>

See Environment Variables for complete reference.

Complete Example

version: "1.0"

global:
  # Shutdown
  shutdown_timeout: 60

  # Logging (global). Advanced per-process logging lives under processes.<name>.logging
  log_format: json
  log_level: info
  log_timestamps: true

  # Observability
  metrics_enabled: true
  metrics_port: 9090

  api_enabled: true
  api_port: 9180
  api_auth: "your-secure-token-here"

  # Kubernetes Integration
  readiness:
    enabled: true
    path: "/tmp/cbox-ready"
    mode: "all_healthy"
    processes:
      - php-fpm
      - nginx

processes:
  # ... process configurations

See Also

← Previous Configuration Overview Next → Process Configuration