Skip to main content

Mango Properties Reference

This page provides a comprehensive reference of the settings available in the mango.properties configuration file. Properties can also be set via environment variables or Java system properties. See Configuring Mango Properties for details on configuration methods and precedence.

Configuration Reloading​

# Mango automatically reloads settings when the config file changes
# Note: not all settings support hot reloading
properties.reloading=true

Web Server​

HTTP/HTTPS Ports​

# HTTP port for browser connections
web.port=8080

# Host interface to bind to (0.0.0.0 binds to all interfaces)
web.host=0.0.0.0

# Open a browser window on startup (if possible)
web.openBrowserOnStartup=true

Caching​

# Disable caching entirely
web.cache.noStore=false
web.cache.noStore.rest=true
web.cache.noStore.resources=false

# Max age of cached files in seconds (only if noStore=false)
web.cache.maxAge=0
web.cache.maxAge.rest=0
web.cache.maxAge.resources=86400
web.cache.maxAge.versionedResources=31536000

File Upload​

# Maximum individual file size for multipart form uploads (in bytes, use -1 to disable)
web.fileUpload.maxSize=262144000
# Maximum total request size for multipart form uploads (in bytes, use -1 to disable)
web.fileUpload.maxRequestSize=524288000

Forwarded Headers (Reverse Proxy)​

# Enable when running behind a reverse proxy that sends Forwarded headers
web.forwardedHeaders.enabled=true
# Trusted IP ranges for forwarded headers
web.forwardedHeaders.trustedIpRanges=127.0.0.0/8,::1

Thread Pool​

# Idle thread timeout (ms)
web.threads.msIdleTimeout=30000
# Max threads (defaults to 10x CPU cores or 200, whichever is greater)
web.threads.maximum=
# Min threads (defaults to max threads or 8, whichever is lesser)
web.threads.minimum=
# Request queue size (default 1280)
web.requests.queueSize=

WebSocket​

# WebSocket idle timeout (ms)
web.websocket.idleTimeoutMs=30000
# Ping/pong timeout for response from browser (ms, must be lower than idleTimeoutMs)
web.websocket.pingTimeoutMs=10000
# Input/output buffer sizes per connection (bytes)
web.websocket.inputBufferSize=4096
web.websocket.outputBufferSize=4096
# Maximum message sizes (bytes)
web.websocket.maxTextMessageSize=65536
web.websocket.maxBinaryMessageSize=65536

HTTP Connector​

# HTTP/HTTPS connector socket idle timeout (ms)
web.socketIdleTimeout=70000

Default Servlet​

web.defaultServlet.dirAllowed=false
web.defaultServlet.maxCacheSize=256000000
web.defaultServlet.maxCachedFileSize=200000000
web.defaultServlet.maxCachedFiles=2048
web.defaultServlet.etags=false
# Minimum file size (bytes) eligible for memory-mapped serving. -1 = Jetty's default 1 MB threshold.
# Set to Integer.MAX_VALUE to disable mapping entirely. Resolved default is OS-aware: Windows = MAX_VALUE.
#web.defaultServlet.minMappedFileSize=-1

SSL/TLS​

# Enable SSL/TLS (also enables HSTS by default)
ssl.on=true
ssl.port=8443

# Keystore configuration (PKCS#12 or JKS)
ssl.keystore.location=${pki.keyStore}
ssl.keystore.password=${pki.keyStorePassword}
#ssl.key.password=

# Watch keystore file for changes and auto-reload
ssl.keystore.watchFile=true

# Socket idle timeout (ms)
ssl.socketIdleTimeout=70000

# HTTP/2 support via ALPN
ssl.alpn.on=true

# HSTS (HTTP Strict Transport Security)
ssl.hsts.enabled=true
ssl.hsts.maxAge=31536000
ssl.hsts.includeSubDomains=false

Database​

General Settings​

# Database type: h2 or mysql
db.type=h2

# JDBC connection URL (relative to paths.data unless absolute)
db.url=jdbc:h2:databases/mah2
db.username=
db.password=

# H2-specific: compact database on shutdown
db.h2.shutdownCompact=false

# Connection pool
db.pool.maxActive=100
db.pool.maxIdle=10

# Query metrics logging
db.useMetrics=false
db.metricsThreshold=100

# Fetch size for JDBC driver (-1 = driver default)
db.fetchSize=-1
# Transaction retry count
db.transaction.retries=5
# Max IN() clause operands (default varies by database, typically 1000)
#db.maxInParameters=
# Number of queries to batch when inserting/updating (default typically 1000)
#db.batchSize=
# Number of queries to batch when deleting (default typically 1000)
#db.batchDeleteSize=

MySQL Configuration​

#db.type=mysql
#db.url=jdbc:mysql://localhost/<schema>
#db.username=<username>
#db.password=<password>
#db.mysqldump=<path to mysqldump>
#db.mysql=<path to mysql>
#db.mysql.extraDumpArgs=--single-transaction,--skip-lock-tables

Database Conversion​

# Convert from one database type to another
# First upgrade, then convert (do not perform both in one step)
convert.db.type=
convert.db.url=
convert.db.username=${db.username}
convert.db.password=${db.password}

NoSQL (Time Series Database)​

# Enable NoSQL module
db.nosql.enabled=true
# Base storage path (relative to paths.data)
db.nosql.location=databases
# Point value store folder name
db.nosql.pointValueStoreName=mangoTSDB
# Max open files
db.nosql.maxOpenFiles=500
# Shard stale period (ms)
db.nosql.shardStalePeriod=36000000
# Flush interval (ms)
db.nosql.flushInterval=300000
# File access type: INPUT_STREAM, FILE_CHANNEL, RANDOM_ACCESS_FILE, MAPPED_BYTE_BUFFER
db.nosql.shardStreamType=MAPPED_BYTE_BUFFER
# Enable reverse indexing for faster queries (slight disk increase)
db.nosql.reversible=true
# Convert existing store: NONE, REVERSIBLE, UNREVERSIBLE
db.nosql.convert=NONE
db.nosql.convertThreads=4
# Corruption scan on startup (only if database is dirty)
db.nosql.runCorruptionScan=false
db.nosql.disableDirtyFiles=true
db.nosql.onlyScanDirty=true
db.nosql.deleteEmptyDirsAtStartup=true

TSL Aggregation (Time Series Library)​

The full set of db.tsl.* connection and aggregation properties for ClickHouse and TimescaleDB lives on the TSL Module Configuration page. Below are the aggregation-scheduling properties added in 5.6.6 / 5.7.1 — they apply on top of the existing aggregation.period, aggregation.boundary, aggregation.overlap, and aggregation.zone settings documented there.

# (Since 5.6.6 / 5.7.1) Run the aggregation sweep less often than aggregation.period.
# Each sweep batches all unprocessed windows since the last run, so a longer schedule
# only delays the appearance of new aggregate values — no data is lost.
# Defaults to one sweep per aggregation.period when unset.
#db.tsl.clickhouse.aggregation.schedule=1 HOURS
#db.tsl.timescale.aggregation.schedule=1 HOURS

# (Since 5.6.6 / 5.7.1) ClickHouse aggregation chunk width, in series IDs per chunk.
# Smaller chunks share the server more cleanly with ingest, queries, and merges.
#db.tsl.clickhouse.aggregation.chunkSize=100000

Security​

Password Hashing​

# Hash algorithm: BCRYPT, SHA-1, NONE (BCrypt is recommended)
#security.hashAlgorithm=BCRYPT
#security.bcrypt.log2Rounds=10

Caching​

# Role inheritance cache size
cache.roles.size=1000
# Cache all users in memory
cache.users.enabled=true
# Permission cache size
cache.permission.size=1000

Content Security Policy​

web.security.contentSecurityPolicy.enabled=false
web.security.contentSecurityPolicy.reportOnly=false
web.security.contentSecurityPolicy.defaultSrc='self'
web.security.contentSecurityPolicy.scriptSrc='self' 'unsafe-eval'
web.security.contentSecurityPolicy.styleSrc='self' 'unsafe-inline'
web.security.contentSecurityPolicy.connectSrc='self' ws: wss:
web.security.contentSecurityPolicy.imgSrc='self' data:
web.security.contentSecurityPolicy.fontSrc='self'

See Content Security Policy for detailed configuration guidance.

iFrame Security​

# X-Frame-Options: SAMEORIGIN, DENY, ANY, or a specific domain
web.security.iFrameAccess=SAMEORIGIN
# Follow symbolic links when serving files
web.security.followSymlinks=true

Rate Limiting​

# Anonymous REST API rate limiting
rateLimit.rest.anonymous.enabled=true
rateLimit.rest.anonymous.burstQuantity=40
rateLimit.rest.anonymous.quanitity=5
rateLimit.rest.anonymous.period=1
rateLimit.rest.anonymous.periodUnit=SECONDS

# Authenticated user REST API rate limiting
rateLimit.rest.user.enabled=false
rateLimit.rest.user.burstQuantity=20
rateLimit.rest.user.quanitity=10
rateLimit.rest.user.period=1
rateLimit.rest.user.periodUnit=SECONDS

# Per-IP authentication rate limiting
rateLimit.authentication.ip.enabled=true
rateLimit.authentication.ip.burstQuantity=5
rateLimit.authentication.ip.quanitity=1
rateLimit.authentication.ip.period=1
rateLimit.authentication.ip.periodUnit=MINUTES

# Per-username authentication rate limiting
rateLimit.authentication.user.enabled=true
rateLimit.authentication.user.burstQuantity=5
rateLimit.authentication.user.quanitity=1
rateLimit.authentication.user.period=1
rateLimit.authentication.user.periodUnit=MINUTES

See Request Rate Limiting for details.

QoS Filter​

web.qos.enabled=false
web.qos.maxRequests=10
web.qos.waitMs=50
web.qos.suspendMs=30000

DoS Filter​

web.dos.enabled=false
web.dos.maxRequestsPerSec=75
web.dos.delayMs=100
web.dos.maxWaitMs=50
web.dos.throttledRequests=5
web.dos.throttleMs=30000
web.dos.maxRequestMs=120000
web.dos.maxIdleTrackerMs=30000
web.dos.insertHeaders=true
web.dos.trackSessions=true
web.dos.remotePort=false
web.dos.ipWhitelist=

Low Resource Management​

web.lowResource.enabled=false
web.lowResource.checkPeriod=10000
web.lowResource.lowResourcesIdleTimeout=1000
web.lowResource.monitorThreads=true
web.lowResource.maxMemory=
web.lowResource.maxLowResourceTime=5000
web.lowResource.acceptingInLowResources=true
web.connectionLimit=0

REST API​

rest.enabled=true
rest.indentJSON=false
rest.disableErrorRedirects=false

# CORS settings
rest.cors.enabled=false
rest.cors.allowedOrigins=
rest.cors.allowedMethods=PUT,POST,GET,OPTIONS,DELETE,HEAD
rest.cors.allowedHeaders=content-type,x-requested-with,authorization
rest.cors.exposedHeaders=
rest.cors.allowCredentials=false
rest.cors.maxAge=3600

# Temporary resource settings
rest.temporaryResource.expirationPeriods=1
rest.temporaryResource.expirationPeriodType=HOURS
rest.temporaryResource.timeoutPeriods=3
rest.temporaryResource.timeoutPeriodType=HOURS

Swagger API Documentation​

swagger.enabled=false
springfox.documentation.swagger.v2.path=/swagger/v2/api-docs
swagger.apidocs.protected=true

Authentication​

authentication.token.enabled=true
authentication.basic.enabled=true
authentication.basic.realm=Mango
authentication.session.maxSessions=10
authentication.oauth2.enabled=false
# Allow minting new JWTs from an existing JWT-authenticated session (default false)
authentication.mango-jwt.allowTokenCreation=false

OAuth2 / OpenID Connect​

# Comma-separated list of client registration IDs to enable
oauth2.client.registrationIds=

# Provider-specific settings (replace {registrationId} with your provider)
#oauth2.client.registration.{registrationId}.provider=onelogin
#oauth2.client.registration.{registrationId}.clientId={your client id}
#oauth2.client.registration.{registrationId}.clientSecret={your client secret}

# User mapping defaults (OpenID Connect claim names)
oauth2.client.default.userNameAttributeName=sub
oauth2.client.default.userMapping.issuer=iss
oauth2.client.default.userMapping.subject=sub
oauth2.client.default.userMapping.username=preferred_username
oauth2.client.default.userMapping.roles=roles
oauth2.client.default.userMapping.roles.sync=true

# HTTP client timeouts (apply to all OAuth2/OIDC HTTP clients used during login)
oauth2.client.connectTimeout=30 seconds
oauth2.client.readTimeout=30 seconds

Session Cookies​

# Use Mango GUID as session cookie name
sessionCookie.useGuid=true
sessionCookie.name=
sessionCookie.domain=
sessionCookie.persistent=true
sessionCookie.persistPeriodSeconds=30
sessionCookie.maxAge=-1

Paths​

# Installation directory (defaults to working directory or MA_HOME)
#paths.home=
# Data directory (relative to paths.home unless absolute)
#paths.data=
# Filestore directory
filestore.location=filestore
# Module data directory
moduleData.location=data
# Log files directory
paths.logs=logs
# Backup directory
paths.backup=backup
# Overrides directory (FreeMarker templates, web overrides)
paths.overrides=overrides
# PID file
paths.pid.file=ma.pid

Runtime​

# Parallel startup/shutdown threads
#runtime.datasource.startupThreads=1
#runtime.datasource.shutdownThreads=1
#runtime.publisher.startupThreads=1
#runtime.publisher.shutdownThreads=1

# Data point startup threads (default: CPU core count)
#runtime.datapoint.startupThreads=8
#runtime.datapoint.startupThreads.pointsPerThread=1000

# Poll abort logging frequency (ms)
runtime.datasource.pollAbortedLogFrequency=3600000

# JavaScript execution metrics
runtime.javascript.metrics=false

# Task queue settings
runtime.realTimeTimer.defaultTaskQueueSize=0
runtime.realTimeTimer.flushTaskQueueOnReject=false
runtime.taskRejectionLogPeriod=10000

# Shutdown timeout (seconds)
runtime.shutdown.medLowTimeout=60
runtime.shutdown.highTimeout=60

Internal Monitoring​

# Internal metrics poll period (ms)
internal.monitor.pollPeriod=10000
# Disk usage poll period (ms)
internal.monitor.diskUsage.pollPeriod=1200000
internal.monitor.diskUsage.monitorDirectories=false
internal.monitor.diskUsage.monitorSql=false
internal.monitor.diskUsage.monitorTsdb=false
# Enable OS/hardware info via OSHI
internal.monitor.enableOperatingSystemInfo=true

Logging​

# Mango logger
logger.mango.level=info
logger.mango.includeLocation=true

# Script logger
logger.script.level=trace
logger.script.includeLocation=false

# Root logger
logger.root.level=warn
logger.root.includeLocation=true

# Console appender
appender.stdout.level=trace
appender.stdout.pattern=%-5p %d{ISO8601} (%C.%M:%L) - %m%n

# Log file appender
appender.logfile.level=trace
appender.logfile.pattern=%-5p %d{ISO8601} (%C.%M:%L) - %m%n
appender.logfile.size=100MB
appender.logfile.delete.age=30d
appender.logfile.delete.count=1000
appender.logfile.delete.size=1GB

# Script log file appender
appender.script.level=trace
appender.script.pattern=%-5p %d{ISO8601} %c - %m%n
appender.script.size=100MB
appender.script.delete.age=30d
appender.script.delete.count=1000
appender.script.delete.size=1GB

# Custom log4j2 configuration file
#log4j2.configurationFile=path/to/log4j2.xml

Serial Port​

serial.port.linux.regex=((cu|ttyS|ttyUSB|ttyACM|ttyAMA|rfcomm|ttyO|COM)[0-9]{1,3}|rs(232|485)-[0-9])
serial.port.linux.path=/dev/
serial.port.linux.readPeriods=500
serial.port.linux.readPeriodType=MILLISECONDS
serial.port.osx.path=/dev/
serial.port.osx.regex=(cu|tty)..*
serial.port.eventQueueSize=10000

Public Key Infrastructure (PKI)​

pki.enabled=true
pki.publicKey=certificates/instance.pub
pki.privateKey=certificates/instance.key
pki.certificate=certificates/instance.crt
pki.keyStore=certificates/instance.p12
pki.keyStorePassword=password
pki.keyAlgorithm=EC
pki.keyParameters=secp256r1
pki.signatureAlgorithm=SHA256withECDSA
pki.providerName=BC

# Certificate monitoring and auto-renewal
pki.monitor.checkPeriod=10 minutes
pki.monitor.autoRenewEnabled=true
pki.monitor.expiringSoonThreshold=25%

# Certificate Authority
pki.ca.name=defaultCertificateAuthority
pki.ca.publicKey=certificates/ca.pub
pki.ca.privateKey=certificates/ca.key
pki.ca.certificate=certificates/ca.crt
pki.ca.caCertificateValidity=10 years
pki.ca.certificateValidity=1 days

gRPC​

# Server
grpc.server.enabled=true
grpc.server.port=9090
grpc.server.reflectionEnabled=true
grpc.server.tlsEnabled=true
grpc.server.certChain=${pki.certificate}
grpc.server.privateKey=${pki.privateKey}
grpc.server.rootCerts=${pki.ca.certificate}
grpc.server.clientAuth=REQUIRE

# Client (used by gRPC publishers and Mango's internal channels)
grpc.client.certChain=${pki.certificate}
grpc.client.privateKey=${pki.privateKey}
grpc.client.rootCerts=${pki.ca.certificate}

gRPC Channel Deadlines​

# Default in-process channel — used by Mango's internal gRPC calls
grpc.channel.default.deadline=30 seconds
grpc.channel.default.streaming-deadline=1 minutes

# gRPC-Web gateway channel — used by browser clients via grpc-web proxy
grpc.channel.grpcweb.deadline=30 seconds
grpc.channel.grpcweb.streaming-deadline=10 minutes

See gRPC Publisher for certificate setup instructions.

Module/Core Upgrade Store​

# Maven repository URL and artifact coordinates used to resolve Mango upgrades
store.upgrade.url=https://maven.radixiot.run/mango
store.upgrade.groupId=com.radixiot.mango
store.upgrade.artifactId=mango-bundle

# Private repository credentials (commented; uncomment for password-protected repos)
#store.upgrade.username=
#store.upgrade.password=

# Cap upgrade resolution to versions strictly below this maximum
#store.upgrade.maxVersion=

# Validation policies — fail / warn / ignore
store.upgrade.checksumPolicy=fail
store.upgrade.signaturePolicy=fail

# Additional PGP key for verifying signatures on private/custom bundles
# (path is relative to paths.data, or absolute)
#store.upgrade.additionalSignatureKey=certificates/store.pub

# Signature policy for modules uploaded via the REST API
store.upload.signaturePolicy=fail

Miscellaneous​

# Mango store URL (legacy store; Maven-based upgrades use store.upgrade.url above)
store.url=https://store.mango-os.com
store.disableUpgrades=false

# Disable the entire web server (HTTP and HTTPS)
web.enabled=true

# System timezone (blank = JVM default)
timezone=

# Bootstrap-time locale override
# Format: language[_country[_variant]] e.g. en_US, es_MX, zh-CN
#systemSettings.language=

# Distributor
distributor=IA

# File watch interval for SSL certificate changes
fileWatchService.checkInterval=10 seconds

web.enabled (new in 5.7) and systemSettings.language (new in 5.7) are listed above. The system-settings page also exposes a runtime locale override; systemSettings.language here is consulted only at bootstrap to seed the system setting.

Initial Admin User​

# Only used on first start -- DO NOT set in mango.properties for production
# Use environment variables or Java system properties instead
initialize.admin.create=true
initialize.admin.username=admin
initialize.admin.password=admin
initialize.admin.email=admin@localhost