config.yaml.example

# ===========================================================================
# UCM Name Lookup Service — Configuration (Example)
# ===========================================================================
#
# Copy this file to config.yaml and customize for your environment:
#
#   cp config.yaml.example config.yaml
#
# config.yaml is gitignored so your local settings won't conflict with
# upstream changes.
#
# This file contains all non-sensitive configuration for the service.
# Sensitive values (TLS private keys) should be provided via Gunicorn
# command-line arguments or environment variables — never in this file.
#
# Specify a custom path to this file with the CONFIG_FILE environment
# variable (default: config.yaml).
#
# The LOG_LEVEL environment variable, if set, overrides the value here.
# ===========================================================================

# ---------------------------------------------------------------------------
# Security Mode (IMPORTANT — read before first run)
# ---------------------------------------------------------------------------
#
# This service is SECURE BY DEFAULT. It will NOT start unless:
#   1. TLS certificates are configured (tls_cert_file and tls_key_file
#      below, or certs/server.crt and certs/server.key for Gunicorn).
#   2. At least one cluster is defined (see the clusters section below)
#      to restrict access to trusted UCM servers.
#
# For development or testing without TLS or clusters, you must
# explicitly enable insecure mode by uncommenting the line below and
# setting it to true. When insecure_mode is enabled:
#   - A prominent warning banner is displayed at startup.
#   - A security warning is logged every hour.
#   - All traffic is transmitted in unencrypted plaintext HTTP.
#   - The cluster requirement is relaxed (clusters are optional).
#
# NEVER enable insecure_mode in production. Use ./setup_certs.sh to
# generate certificates for TLS/mTLS instead.
#
# insecure_mode: true

# ---------------------------------------------------------------------------
# PII Obfuscation
# ---------------------------------------------------------------------------
#
# When enabled, phone numbers and display names are replaced with
# salted HMAC-SHA256 hashes in all log output. The format is:
#
#   {! <24-char-hex-hash> !}
#
# A random salt is generated from a CSPRNG at each startup and kept
# only in memory — never logged or persisted. This prevents rainbow-
# table reversal of hashed phone numbers. The same input produces the
# same hash within a single process lifetime, allowing operators to
# correlate repeated values. Hashes are not comparable across restarts.
# Useful for environments that must comply with privacy regulations.
#
# obfuscate_pii: true

# Path to the phone directory CSV file.
csv_file_path: phone_directory.csv

# Logging level: DEBUG, INFO, WARNING, ERROR
log_level: INFO

# Directory for log files. When set, the application writes rotating log
# files here in addition to stdout/stderr. Gunicorn access and error logs
# are also written to this directory.
# The directory must be writable by the application user.
# log_dir: logs

# Maximum size (in bytes) of a single log file before rotation (default: 10 MB).
# log_max_bytes: 10485760

# Number of rotated log files to keep (default: 5).
# log_backup_count: 5

# Flask development server bind address and port.
flask_host: 0.0.0.0
flask_port: 5000

# TLS certificate and key for the Flask development server.
# For production, configure TLS through Gunicorn's --certfile / --keyfile.
# tls_cert_file: certs/server.crt
# tls_key_file: certs/server.key

# ---------------------------------------------------------------------------
# UCM Cluster Definitions
# ---------------------------------------------------------------------------
#
# Each cluster entry defines the access rules for one UCM cluster.
# A connecting client must match ALL rules defined for at least ONE cluster
# to be granted access to the /curri endpoint.
#
# Every rule uses DENY-BY-DEFAULT semantics: omitting a rule blocks
# all traffic for that criterion rather than allowing it. A cluster
# must explicitly list what it permits.
#
# Per-cluster settings:
#   allowed_ips      - List of IP addresses and/or CIDR networks whose
#                      requests are accepted. An empty or missing list
#                      denies ALL source IPs for this cluster.
#   ca_file          - Path to the CA certificate (PEM) that signed the
#                      client certificates for this cluster. Must be a
#                      root CA certificate (CA:TRUE), not a leaf cert.
#                      When ca_bundle_path is set, all cluster ca_file
#                      entries are auto-concatenated into a single bundle
#                      for Gunicorn's --ca-certs at startup.
#   allowed_subjects - List of expected Common Name (CN) and/or Subject
#                      Alternative Name (SAN) values for client certificates
#                      from this cluster. An empty or missing list denies
#                      ALL certificate subjects for this cluster.
#
# When insecure_mode is disabled (the default), at least one cluster
# MUST be defined or the service will refuse to start. This ensures
# that only trusted UCM servers can reach the /curri endpoint.
#
# When insecure_mode is enabled (development/testing only), clusters
# are optional — if none are defined, all clients are accepted.
#
# Example:
#
# clusters:
#   headquarters:
#     allowed_ips:
#       - 10.1.1.10
#       - 10.1.1.11
#       - 10.1.2.0/24
#     ca_file: certs/hq-CallManager.pem
#     allowed_subjects:
#       - cucm-pub.example.com
#       - cucm-sub1.example.com
#       - cucm-sub2.example.com
#
#   branch-office:
#     allowed_ips:
#       - 10.2.1.0/24
#     ca_file: certs/branch-CallManager.pem
#     allowed_subjects:
#       - cucm-branch.example.com
#
# Optional: path to write a combined CA bundle file at startup.
# When set, the application concatenates all unique cluster ca_file
# entries into a single PEM file at this path. Use this file with
# Gunicorn's --ca-certs option for production mTLS.
# Note: in Docker, if certs/ is mounted read-only, use a writable
# path such as /tmp/ca-bundle.pem instead.
# ca_bundle_path: certs/ca-bundle.pem