Application Config Schema

ClusterCockpit Application Config Schema Reference
Tags:
Categories:

A detailed description of each configuration option can be found in the configuration reference.

The configuration is split into sections. Each section is validated against its own JSON schema defined in the corresponding Go package inside the cc-backend repository.

Section main

Source: internal/config/schema.go

PropertyTypeRequiredDescription
addrstringNoAddress where the HTTP(S) server listens (e.g. "0.0.0.0:8080"). Default: localhost:8080.
api-allowed-ipsarray of stringNoIPv4 addresses from which secured API endpoints can be reached. Default: no restriction.
userstringNoDrop root permissions after port is taken. Only useful for privileged ports.
groupstringNoDrop root permissions after port is taken. Only useful for privileged ports.
disable-authenticationbooleanNoDisable authentication for API and Web-UI. Default: false.
embed-static-filesbooleanNoServe static files from within the binary. Default: true.
static-filesstringNoPath to static assets when embed-static-files is false.
dbstringNoPath to the SQLite database file. Default: ./var/job.db.
enable-job-taggersbooleanNoEnable automatic application and job-class taggers. Default: false.
validatebooleanNoValidate all input JSON documents against JSON schemas. Default: false.
session-max-agestringNoMaximum session lifetime as a time.ParseDuration string. Empty = never expires. Default: 168h.
https-cert-filestringNoPath to TLS certificate file. HTTPS is enabled when both cert and key are set.
https-key-filestringNoPath to TLS key file. HTTPS is enabled when both cert and key are set.
redirect-http-tostringNoRedirect port-80 requests to this URL when addr does not end in :80.
stop-jobs-exceeding-walltimeintegerNoAutomatically stop jobs running more than this many seconds past their walltime. 0 = disabled.
short-running-jobs-durationintegerNoHide running jobs shorter than this many seconds. Default: 300.
emission-constantintegerNoCO₂ emission factor in g/kWh. When set, the UI shows estimated CO₂ per job.
machine-state-dirstringNoDirectory for MachineState files (persists machine state across restarts).
systemd-unitstringNoSystemd unit name for the log viewer integration. Default: clustercockpit.
resamplingobjectNoEnable dynamic downsampling of metric time-series. See sub-properties below.
api-subjectsobjectNoNATS subjects for job/node events. Disables REST start/stop endpoints when set. See sub-properties below.
nodestate-retentionobjectNoAutomatic cleanup of old node-state rows. See sub-properties below.
db-configobjectNoSQLite tuning options. See sub-properties below.

resampling

PropertyTypeRequiredDescription
minimum-pointsintegerNoMinimum data points required to trigger resampling.
triggerintegerYesTrigger next zoom level when visible points fall below this value.
resolutionsarray of integerYesResampling target resolutions in seconds (e.g. [600, 300, 60]).

api-subjects

PropertyTypeRequiredDescription
subject-job-eventstringYesNATS subject for job events (start_job, stop_job).
subject-node-statestringYesNATS subject for node state updates.
job-concurrencyintegerNoConcurrent goroutines for job event processing. Default: 8.
node-concurrencyintegerNoConcurrent goroutines for node state processing. Default: 2.

nodestate-retention

PropertyTypeRequiredDescription
policystringYesdelete — remove old rows; move — archive to Parquet then delete.
ageintegerNoRetention age in hours. Rows older than this are affected. Default: 24.
target-kindstringNoTarget storage for move: file or s3. Default: file.
target-pathstringNoFilesystem path for Parquet files (target-kind: file).
target-endpointstringNoS3 endpoint URL (target-kind: s3).
target-bucketstringNoS3 bucket name (target-kind: s3).
target-access-keystringNoS3 access key (target-kind: s3).
target-secret-keystringNoS3 secret key (target-kind: s3).
target-regionstringNoS3 region (target-kind: s3).
target-use-path-stylebooleanNoUse path-style S3 URLs — required for MinIO (target-kind: s3).
max-file-size-mbintegerNoMaximum Parquet file size in MB before splitting. Default: 128.

db-config

PropertyTypeRequiredDescription
cache-size-mbintegerNoSQLite page cache size per connection in MB. Default: 2048.
soft-heap-limit-mbintegerNoProcess-wide SQLite soft heap limit in MB. Default: 16384.
max-open-connectionsintegerNoMaximum open database connections. Default: 4.
max-idle-connectionsintegerNoMaximum idle database connections. Default: 4.
max-idle-time-minutesintegerNoMaximum idle time per connection in minutes. Default: 10.
busy-timeout-msintegerNoSQLite busy timeout in ms. SQLite retries on contention for this duration before returning SQLITE_BUSY. Default: 60000.

Section auth

Source: internal/auth/schema.go

auth.jwts

PropertyTypeRequiredDescription
max-agestringYesToken validity as a time.ParseDuration string.
cookie-namestringNoCookie name to check for a JWT token.
validate-userbooleanNoDeny login for users not in the database; overwrite JWT roles with DB roles.
trusted-issuerstringNoAccept JWTs from this external issuer.
sync-user-on-loginbooleanNoAdd unknown users to the DB on login using JWT claims.
update-user-on-loginbooleanNoUpdate existing user in DB on login with JWT claims (name, roles, projects).

auth.ldap

PropertyTypeRequiredDescription
urlstringYesLDAP directory server URL.
user-basestringYesBase DN of the user tree root.
search-dnstringYesDN for LDAP admin account with read rights.
user-bindstringYesLDAP bind expression. Must contain uid={username}.
user-filterstringYesLDAP filter for user synchronization.
username-attrstringNoLDAP attribute for full user name. Default: gecos.
uid-attrstringNoLDAP attribute used as login username. Default: uid.
sync-intervalstringNoInterval for syncing user table with LDAP as a time.ParseDuration string.
sync-del-old-usersbooleanNoDelete users from DB that no longer exist in LDAP.
sync-user-on-loginbooleanNoAdd unknown users to the DB on login if they exist in LDAP.
update-user-on-loginbooleanNoUpdate existing user in DB on login with LDAP values (name, roles, projects).

auth.oidc

PropertyTypeRequiredDescription
providerstringYesOpenID Connect provider URL.
sync-user-on-loginbooleanNoAdd unknown users to the DB on login with OIDC claims.
update-user-on-loginbooleanNoUpdate existing user in DB on login with OIDC claims (name, roles, projects).

Section metric-store

Source: pkg/metricstore/configSchema.go

PropertyTypeRequiredDescription
retention-in-memorystringYesHow long to keep metrics in memory as a time.ParseDuration string (e.g. "48h").
memory-capintegerYesUpper memory cap for the metric store in GB.
num-workersintegerNoConcurrent workers for checkpoint/archive operations. Default: min(NumCPU/2+1, 10).
checkpoint-intervalstringNoInterval between checkpoints as a time.ParseDuration string. Default: "12h".
checkpointsobjectNoCheckpoint storage options. See sub-properties below.
cleanupobjectNoCleanup/archival options. See sub-properties below.
nats-subscriptionsarray of objectNoNATS subjects to subscribe to for metric data ingestion. See sub-properties below.

metric-store.checkpoints

PropertyTypeRequiredDescription
file-formatstringNowal (binary snapshot + WAL, crash-safe) or json (human-readable). Default: wal.
directorystringNoDirectory for checkpoint files. Default: ./var/checkpoints.
max-wal-sizeintegerNoMaximum WAL file size in bytes per host. 0 = unlimited. Default: 0.

metric-store.cleanup

PropertyTypeRequiredDescription
modestringNodelete (default) or archive.
directorystringRequired when mode: archiveTarget directory for archived metric data.

metric-store.nats-subscriptions items

PropertyTypeRequiredDescription
subscribe-tostringYesNATS subject name to subscribe to.
cluster-tagstringNoDefault cluster tag for lines that carry no cluster tag.

Section cron

Source: internal/taskmanager/taskManager.go

PropertyTypeRequiredDescription
commit-job-workerstringNoFrequency of the commit-job worker. Default: "2m".
duration-workerstringNoFrequency of the duration worker. Default: "5m".
footprint-workerstringNoFrequency of the footprint worker. Default: "10m".

Section archive

Source: pkg/archive/ConfigSchema.go

PropertyTypeRequiredDescription
kindstringYesArchive backend: file, s3, or sqlite.
pathstringNoJob-archive path for file backend. Default: ./var/job-archive.
db-pathstringNoSQLite database file path for sqlite backend.
endpointstringNoS3 endpoint URL for s3 backend (required for MinIO and S3-compatible services).
access-keystringNoS3 access key ID for s3 backend.
secret-keystringNoS3 secret access key for s3 backend.
bucketstringNoS3 bucket name for s3 backend.
regionstringNoS3 region for s3 backend.
use-path-stylebooleanNoUse path-style S3 URLs for s3 backend (required for MinIO).
compressionintegerNoCompress jobs older than this many days. Default: 7.
retentionobjectNoRetention policy configuration. See sub-properties below.

archive.retention

PropertyTypeRequiredDescription
policystringYesnone, delete, copy, or move.
formatstringNoOutput format for copy/move: json (default) or parquet.
include-dbbooleanNoAlso remove jobs from the database. Default: true.
omit-taggedstringNonone = process all jobs (default); all = skip any tagged job; user = skip user-tagged jobs (auto-tagger tags app/jobClass are not user tags).
ageintegerNoProcess jobs with startTime older than this many days. Default: 7.
target-kindstringNoTarget storage for copy/move: file or s3. Default: file.
target-pathstringNoFilesystem path for target storage (target-kind: file).
target-endpointstringNoS3 endpoint URL for target (target-kind: s3).
target-bucketstringNoS3 bucket name for target (target-kind: s3).
target-access-keystringNoS3 access key for target (target-kind: s3).
target-secret-keystringNoS3 secret key for target (target-kind: s3).
target-regionstringNoS3 region for target (target-kind: s3).
target-use-path-stylebooleanNoUse path-style S3 URLs for target — required for MinIO (target-kind: s3).
max-file-size-mbintegerNoMaximum Parquet file size in MB before splitting. Default: 512. Only for format: parquet.

Section nats

Source: cc-lib (external library)

PropertyTypeRequiredDescription
addressstringYesNATS server address (e.g. "nats://localhost:4222").
usernamestringNoUsername for NATS authentication.
passwordstringNoPassword for NATS authentication.
creds-file-pathstringNoPath to NATS credentials file.

Section metric-store-external

Source: internal/metricdispatch/configSchema.go

An array of external cc-metric-store instances for reading metric data. Each entry maps a scope (cluster name or * wildcard) to an external metric store.

PropertyTypeRequiredDescription
scopestringYesCluster name or * as a default fallback.
urlstringYesURL of the external cc-metric-store endpoint (e.g. "http://host:8082").
tokenstringYesJWT authentication token for the external metric store.

Section ui

Source: web/configSchema.go

ui.job-list

PropertyTypeRequiredDescription
use-pagingbooleanNoUse classic paging instead of continuous scrolling by default.
show-footprintbooleanNoShow footprint bars as first column by default.

ui.node-list

PropertyTypeRequiredDescription
use-pagingbooleanNoUse classic paging instead of continuous scrolling by default.

ui.job-view

PropertyTypeRequiredDescription
show-polar-plotbooleanNoShow the job metric footprint polar plot by default.
show-footprintbooleanNoShow the annotated job metric footprint bars by default.
show-rooflinebooleanNoShow the job roofline plot by default.
show-stat-tablebooleanNoShow the job metric statistics table by default.

ui.metric-config

Global initial metric selections for all clusters (overridable per cluster/subcluster).

PropertyTypeRequiredDescription
job-list-metricsarray of stringNoDefault metrics shown in job lists for new users.
job-view-plot-metricsarray of stringNoDefault metrics shown as plots in job view for new users.
job-view-table-metricsarray of stringNoDefault metrics shown in the job view statistics table for new users.
clustersarray of objectNoPer-cluster overrides. Each entry has name (required) and optional job-list-metrics, job-view-plot-metrics, job-view-table-metrics, and sub-clusters.

ui.metric-config.clusters[].sub-clusters items

PropertyTypeRequiredDescription
namestringYesSubcluster name.
job-list-metricsarray of stringNoOverrides global job-list metrics for this subcluster.
job-view-plot-metricsarray of stringNoOverrides global job-view plot metrics for this subcluster.
job-view-table-metricsarray of stringNoOverrides global job-view table metrics for this subcluster.

ui.plot-configuration

PropertyTypeRequiredDescription
color-backgroundbooleanNoColor metric plot backgrounds by threshold limits by default.
plots-per-rowintegerNoNumber of plots per row in job, node, and analysis views.
line-widthintegerNoInitial plot line thickness.
color-schemearray of stringNoInitial color scheme for metric plots.