Skip to content

ClusterControl Proxy

ClusterControl Proxy is the next-generation ClusterControl manager which creates a unified view of multiple ClusterControl controllers and providing web services, effectively removing dependencies for Apache or nginx web servers to serve ClusterControl GUI components. It is developed to purposedly handle the ClusterControl GUI component provided by package clustercontrol-mcc.

Having said that, when installing ClusterControl GUI (package name: clustercontrol-mcc), ClusterControl Proxy (package name: clustercontrol-proxy) is expected be installed together.

ClusterControl Manager

The ClusterControl Manager binary called ccmgr is the main process (default port: 19501) which serves the web contents of ClusterControl GUI and acts as a proxying layer to all ClusterControl controllers added into it. The process is controlled by a systemd unit file located at /etc/systemd/system/cmon-proxy.service. Hence, the service management should follow the standard systemd format:

  • Starting the service:
systemctl start cmon-proxy
  • Stopping the service:
systemctl stop cmon-proxy
  • Restart the service:
systemctl restart cmon-proxy

The main binary is installed at /usr/bin/ccmgr and comes with the following options:

Option Description
--debug-cmon-rpc Debug log RPC requests to cmon
--debug-web-rpc Debug web RPC requests to cmon-proxy
--basedir= The basedir of configuration (default: /usr/share/ccmgr/)

This binary is expected to be running as a service. Use ClusterControl Manager Admin CLI to manage the ClusterControl Manager.

ClusterControl Manager Admin CLI

The ccmgradm is a command-line interface to manage ClusterControl Manager users, passwords and controllers. Run ccmgradm --help to see all available commands.

Example

$ ccmgradm  --help
ClusterControl Manager - admin CLI v2.2
Usage: ccmgradm <command> [<args>]

Options:
--help, -h             display this help and exit

Commands:
dropuser
adduser
setpassword
dropcontroller
addcontroller
init
updatecontroller
listcontrollers
enableMcc

For every available command, there is a further help instruction:

Example

$ ccmgradm adduser --help
ClusterControl Manager - admin CLI v2.2
Usage: ccmgradm adduser [--email EMAIL] [USERNAME [PASSWORD]]

Positional arguments:
USERNAME
PASSWORD

Options:
--email EMAIL, -e EMAIL
--help, -h             display this help and exit

You may use the ccmgradm client to interact with the ccmgr service or use the ClusterControl Ops-C web GUI client to manage users and controllers.

Configuration file

By default, ClusterControl Proxy comes with a default configuration in YAML format, available at /usr/share/ccmgr/ccmgr.yaml:

filename: /usr/share/ccmgr/ccmgr.yaml
webapproot: /var/www
fetch_jobs_hours: 12
fetch_backups_days: 7
timeout: 30
logfile: /var/log/ccmgr.log
frontend_path: /app
port: 19051
tls_cert: /usr/share/ccmgr/server.crt
tls_key: /usr/share/ccmgr/server.key
session_ttl: 1800000000000
single_controller: ""

The following is an example content of the configuration file with one ClusterControl instance:

filename: ccmgr.yaml
instances: # List of controller
    - xid: chebjd8gfi863qqhrolg # Controller id. Generated automatically
      url: hostname:9443/api # Controller api URL
      name: Controller name
      username: admin
      password: password
      frontend_url: http://hostname:9443/ # Url of Cluster Control web interface
      cmon_ssh_host: 127.0.0.1:9511 # cmon-ssh host and port, used for web ssh console. Default for single controller - 127.0.0.1:9511
      cmon_ssh_secure: false # if true - use TLS for cmon-ssh connection
    - xid: cnoi4d3fo0o9e9m7hap0 # Controller id. Generated automatically
      # ....
timeout: 30 # request timeout in seconds. Default 30
logfile: ccmgr.log # cmon proxy log file. Default ccmgr.log
users: # Cmon proxy users, can be set via ccmgradm setpassword <username> <password>
    - username: admin
      passwordhash: <hash>
frontend_path: /app # Path to static files that cmon proxy can serve
port: 19051
tls_cert: server.crt # Default server.crt can be set from env TLS_CERTIFICATE_FILE variable
tls_key: server.key # Default server.key can be set from env TLS_KEY_FILE variable
session_ttl: 3600000000000 # Session time to live in nanoseconds. Default 1 hour
fetch_backups_days: 7 # How many days in the past cmon-proxy should look for backup data. Default is 7 days
fetch_jobs_hours: 12 # How many hours in the past cmon-proxy should look for jobs data. Default is 12 hours
single_controller: chebjd8gfi863qqhrolg # ID of single controller, if it is set - multi-controller is disabled
k8s_proxy_url: http://127.0.0.1:8080 # Kubernetes proxy URL. Default is http://127.0.0.1:8080
kubernetes_enabled: true # Enable Kubernetes proxy. Default is true
license_proxy_url: "https://severalnines.com/service/lic.php" # URL to request demo license during registration. Default - https://severalnines.com/service/lic.php
http_port: 80 # Port for the plain HTTP server used for ACME challenges and redirection to HTTPS. Default is 80

# Let's Encrypt settings for automatic TLS certificates
acme_enabled: false # Enable Let's Encrypt. Default is false
acme_staging: false # Use Let's Encrypt staging environment. Default is false
acme_domains: [] # List of domains to obtain certificates for.
acme_email: "" # Email address for Let's Encrypt registration and notifications.
acme_cache_dir: "autocert-cache" # Directory to cache ACME certificates. Default is "autocert-cache" in the base directory.
acme_directory_url: "" # The ACME directory URL. Defaults is empty (using library pre-defined), or staging (https://acme-staging-v02.api.letsencrypt.org/directory) if acme_staging is true.
acme_accept_tos: true # Automatically accept the ACME provider's Terms of Service. Default is true.
acme_renew_before: "720h" # Renewal window before certificate expiration (a Go duration string, e.g., "720h" for 30 days). Default is 30 days (720h).
acme_host_policy_strict: false # If true, strictly enforce that certs are only issued for domains in acme_domains. Recommended for production. Default is false.
web_server:
  trusted_proxies: [] # List of trusted proxy IPs. Default is empty.
  trusted_platform: "" # Platform header for identifying client IPs (e.g., "X-Forwarded-For"). Default is empty.
  security:
    frame_deny: true # Sets X-Frame-Options to DENY. Default is true.
    sts_seconds: 31536000 # HSTS max-age in seconds. Default is 31536000 (1 year).
    sts_include_subdomains: true # Include subdomains in HSTS policy. Default is true.
    sts_preload: true # Enable HSTS preload. Default is true.
    force_sts_header: true # Force HSTS header even for non-TLS requests. Default is true.
    content_type_nosniff: true # Sets X-Content-Type-Options to nosniff. Default is true.
    browser_xss_filter: false # Disables the browser's XSS filter. Default is false.
    content_security_policy: "default-src 'self'; ..." # Content Security Policy. See below for details.
    content_security_policy_report_only: true # Use CSP in report-only mode. Default is true.
    referrer_policy: "strict-origin-when-cross-origin" # Referrer-Policy header. Default is "strict-origin-when-cross-origin".
    permissions_policy: "camera=(), microphone=(), geolocation=()" # Permissions-Policy header. Default is "camera=(), microphone=(), geolocation=()".
  cors:
    allow_origins: [] # List of allowed origins for CORS. Default is empty.
    allow_methods: [] # List of allowed methods for CORS. Default is empty.
    allow_headers: [] # List of allowed headers for CORS. Default is empty.
    expose_headers: [] # List of headers to expose for CORS. Default is empty.
    allow_credentials: true # Allow credentials for CORS. Default is true.
    max_age_seconds: 0 # Max age for preflight requests. Default is 0.
  gzip:
    level: 1 # Gzip compression level (1 to 9). Default is 1 (BestSpeed).
  frontend:
    nonce_replacement_files: ["index.html"] # Files to replace CSP nonce in. Default is ["index.html"].

Configure custom SSL certificates

The default directory /usr/share/ccmgr shall contain the configuration files and TLS certificates and keys, as well as the logs of the cmon-proxy application. You can put your own TLS cert (a combined full chain, so the main cert and all the CAs together, or just a self signed one) and key into your data directory using the following file names - server.crt and server.key.

Web server: headers and simple examples

The ClusterControl configuration supports security headers which can be configured in the ccmgr.yaml. This section simplifies web_server settings and details the headers they add. These settings do not change the app logic; they only affect how requests are interpreted and what security headers are sent.

Content Security Policy (CSP)

The Content Security Policy (CSP) limits where scripts, styles, and images can load from. The inline scripts can be safely allowed with support for a per-response nonce and it can run in report‑only mode while you test your policy (report-only by default).

How to apply the configuration:

  • Configure web_server.security.content_security_policy as a string. Use {{nonce}} where a nonce should appear (e.g., in script-src).

  • For HTML files listed in web_server.frontend.nonce_replacement_files (default: index.html), the server:

    1. Generates a fresh nonce per request

    2. Replaces NONCE in your HTML with that nonce

    3. Sends CSP header with {{nonce}} replaced

    4. Disables caching for those HTML responses

  • If content_security_policy_report_only: true, the header is sent as Content-Security-Policy-Report-Only and the directive upgrade-insecure-requests is removed automatically for compatibility.

Example configuration and usage:

web_server:
  security:
    content_security_policy: "default-src 'self'; script-src 'self' 'nonce-{{nonce}}' 'strict-dynamic'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;"
    content_security_policy_report_only: true
  frontend:
    nonce_replacement_files: ["index.html"]

<!-- index.html -->
<script nonce="__NONCE__">/* inline boot script */</script>

Resulting header (report‑only example):

Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self' 'nonce-<random>' 'strict-dynamic'; style-src 'self' 'unsafe-inline'; img-src 'self' data:

CORS (Cross-Origin Resource Sharing)

The CORS is a security mechanism built into web browsers that controls how resources (like APIs, images, fonts, or scripts) can be requested from a domain different from the one that served the original web page. If the frontend (browser app) is served from a different origin (domain/port) than this API.

Example configuration: 

web_server:
  cors:
    allow_origins: ["https://ui.example.com"]
    allow_methods: ["GET", "POST", "PUT", "PATCH", "DELETE"]
    allow_headers: ["Content-Type", "Authorization"]
    expose_headers: ["X-Request-Id"]
    allow_credentials: true
    max_age_seconds: 600

Typical preflight (OPTIONS) response:

Access-Control-Allow-Origin: https://ui.clustercontrol.com
Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE
Access-Control-Allow-Headers: Content-Type,Authorization
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 600

HTTPS enforcement (HSTS)

The HSTS is a web security policy mechanism that tells browsers to always use HTTPS (encrypted connection) when communicating with a website. Without HSTS, if a client types http://example.com (or clicks an old http link), the browser will first connect over HTTP, then get redirected to HTTPS. That short HTTP step is vulnerable to man-in-the-middle (MITM) attacks, where an attacker could intercept or modify the redirect.

Example of headers sent:

Strict-Transport-Security: max-age=31536000; includeSubDomains

The max-age for 1 year (31536000) indicate the browser must only use HTTPS for the site and includeSubDomains configuration apply to all the subdomains.

Copyright © 2014-2025 Severalnines AB. All rights reserved.

Severalnines and ClusterControl are registered trademarks in the US, UK, and EU. The 3rd-party trademarks on this site are property of their respective owners and are used for referential purposes only.

Made with Material for MkDocs