- Introduction
- Standalone configuration
- Listeners
- Authentication Mechanisms
- Authenticators
- Authorizers
- Token Managers
- Mongo Client Provider
- MongoService: MongoDB REST and Websocket API
- MongoDB GraphQL Service
- Proxied resources
- Static Web Resources
- Other services
- Logging
- Metrics
- Core module configuration
- Connection options
Default Configuration
Introduction
This page presents the RESTHeart default configuration splitting it in different sections.
The default configuration applies when RESTHeart is started without specifying a configuration file:
$ java -jar restheart.jar
The default configuration template can be printed out with the following command:
$ java -jar restheart.jar -t
Note
|
The default configuration is fine most of the times. You just want to change few options and the suggested way is using the default configuration with the needed overrides. See modify the configuration with overrides |
Standalone configuration
The default configuration enables several plugins that require MongoDB. If you are using RESTHeart without MongoDB an alternative default configuration can be used with the -s
option, where s
stands for standalone.
This configuration enables the fileRealmAuthenticator
and the fileAclAuthorizer
and disables the MongoDB data APIs.
It defines the user admin
but the password must be set overriding the configuration. The following command sets the password of the admin
user as secret
using the RHO
environment variable:
$ RHO="/fileRealmAuthenticator/users[userid='admin']/password->'secret'" java -jar core/target/restheart.jar -s
Listeners
# RESTHeart Configuration File.
## See https://restheart.org/docs/setup/#configuration-files
---
# HTTP Listener
# WARNING: Using the http listener is not secure.
http-listener:
enabled: true
host: localhost
port: 8080
# HTTPS Listener
https-listener:
enabled: false
host: localhost
port: 4443
# The https listener requires setting up a TLS certificate.
# See https://restheart.org/docs/security/tls/
keystore-path: null
keystore-password: null
certificate-password: null
# AJP Listener
ajp-listener:
enabled: false
host: localhost
port: 8009
Authentication Mechanisms
# Auth Token Authentication
# The verified token is generated by the enabled token manager
# see https://restheart.org/docs/security/authentication#token-authentication
tokenBasicAuthMechanism:
enabled: true
# Basic Authentication
# see https://restheart.org/docs/security/authentication#basic-authentication
basicAuthMechanism:
enabled: true
authenticator: mongoRealmAuthenticator
# JSON Web Token Authentication
# see https://restheart.org/docs/security/authentication#jwt-authentication
jwtAuthenticationMechanism:
enabled: false
algorithm: HS256
key: secret
base64Encoded: false
usernameClaim: sub
rolesClaim: roles
fixedRoles: []
# - jwt-role
issuer: restheart.org
audience: null
# Digest Authentication
# see https://restheart.org/docs/security/authentication#digest-authentication
digestAuthMechanism:
# digest authentication is disabled by default
# because it requires the passwords to be stored in plaintext
# and mongoRealmAuthenticator hashes the passwords by default (bcrypt-hashed-password: true)
enabled: false
realm: RESTHeart Realm
domain: localhost
authenticator: mongoRealmAuthenticator
# For development purposes. Always authenticate the request with the given user
# see https://restheart.org/docs/security/authentication#identity-authentication
identityAuthMechanism:
enabled: false
username: admin
roles:
- admin
- user
Authenticators
# fileRealmAuthenticator defines users credentials and roles in a simple yml file.
# see https://restheart.org/docs/security/authentication#file-realm-authenticator
fileRealmAuthenticator:
enabled: false
#conf-file: ./users.yml
users:
- userid: admin
password: null
roles: [admin]
# mongoRealAuthenticator authenticates users defined in a MongoDB collection.
# see https://restheart.org/docs/security/authentication#mongo-realm-authenticator
mongoRealmAuthenticator:
enabled: true
users-db: restheart
users-collection: users
prop-id: _id
prop-password: password
json-path-roles: $.roles
bcrypt-hashed-password: true
bcrypt-complexity: 12
enforce-minimum-password-strength: false
# Integer from 0 to 4
# 0 Weak (guesses < 3^10)
# 1 Fair (guesses < 6^10)
# 2 Good (guesses < 8^10)
# 3 Strong (guesses < 10^10)
# 4 Very strong (guesses >= 10^10)
minimum-password-strength: 3
create-user: true
create-user-document: '{"_id": "admin", "password": "$2a$12$lZiMMNJ6pkyg4uq/I1cF5uxzUbU25aXHtg7W7sD2ED7DG1wzUoo6u", "roles": ["admin"]}'
# create-user-document.password must be hashed when bcrypt-hashed-password=true
# default password is 'secret'
# see https://bcrypt-generator.com but replace initial '$2y' with '$2a'
cache-enabled: false
cache-size: 1000
cache-ttl: 60000
cache-expire-policy: AFTER_WRITE
# Cookie Authentication
# see: https://restheart.org/docs/security/authentication#cookie-authentication
# Sets the auth cookie when the request has been successfully authenticated
# and the query parameter '?set-auth-cookie' is present
# The cookie is populated from the auth token generated by the currently enabled Token Manager.
# It is compatible with both rndTokenManager and jwtTokenManager
authCookieSetter:
enabled: false # Not enabled by default
name: rh_auth # The name of the cookie to be set
domain: localhost # The domain within which the cookie is valid.
path: / # The cookie path, applicable to the entire domain.
http-only: true # If true enhances security by making the cookie inaccessible to JavaScript.
same-site: true # Restricts the cookie to first-party contexts, preventing CSRF attacks.
same-site-mode: strict # Strictly prevents the cookie from being sent along with cross-site requests.
expires-ttl: 86400 # Defines the duration (in seconds, default 1 day) for which the cookie is valid.
# Constructs the Authorization header using the auth cookie,
# It is compatible with both Basic and JWT authentication mechanisms.
# It reads the auth cookie (if present) and formats the value appropriately
# to create an Authorization header.
authCookieHandler:
enabled: false # Not enabled by default
# This service handles the clearing of the auth cookie in response to a POST /logout request.
# When this endpoint is called, it effectively wipes the auth cookie from the user's browser,
# effectively logging out the user.
authCookieRemover:
enabled: false # Not enabled by default
secure: false # If request to clean the cookie should be authenticated
defaultUri: /logout # The endpoint that triggers this service.
Authorizers
# fileAclAuthorizer authorizes requests according to the Access Control List defined in a YAML file.
# see https://restheart.org/docs/security/authorization#file-acl-authorizer
fileAclAuthorizer:
enabled: false
#conf-file: ./acl.yml
permissions:
- role: admin
predicate: path-prefix('/')
priority: 0
# mongoAclAuthorizer authorizes requests according to the Access Control List defined in a MongoDB collection.
# see https://restheart.org/docs/security/authorization#mongo-acl-authorizer
mongoAclAuthorizer:
enabled: true
acl-db: restheart
acl-collection: acl
# clients with root-role can execute any request
root-role: admin
cache-enabled: true
cache-size: 1000
cache-ttl: 5000
cache-expire-policy: AFTER_WRITE
# originVetoer protects from CSRF attacks by forbidding requests whose Origin header is not whitelisted
# see https://restheart.org/docs/security/authorization#originvetoer
originVetoer:
enabled: false
whitelist:
- https://restheart.org
- http://localhost
# optional list of paths for whose the Origin header
# is not checked. values can be absolute paths
# or patterns like /{var}/path/to/resource/*
# ignore-paths:
# - /{tenant}/bucket.files/{id}/binary
# - /coll/docid
# fullAuthorizer authorizes all requests
fullAuthorizer:
enabled: false
authentication-required: true
Token Managers
# Token Manager
# see https://restheart.org/docs/security/authentication#token-managers
# If a token-manager is configured, RESTHeart will use it to generate
# and verify auth tokens.
# If more than one token-manager are defined, the first one will be used
# The token is returned to the caller via auth-token header when the user
# autheticates successfully. The token can be used by Authentication Mechanisms.
# rndTokenService generates auth tokens using a random number generator.
rndTokenManager:
enabled: true
ttl: 15
srv-uri: /tokens
# jwtTokenManager generates JWT auth tokens.
# Use this in clustered deployments, since all nodes sharing the key
# can verify the token independently
jwtTokenManager:
enabled: false
key: secret
ttl: 15
srv-uri: /tokens
issuer: restheart.org
audience: null
# additional JWT claims from accounts properties
account-properties-claims:
# - foo # property name
# - /nested/property # xpath expr for nested properties
Mongo Client Provider
# Provide the MongoClient via @Inject('mclient') and @Inject('mclient-reactive')
mclient:
# see https://docs.mongodb.com/manual/reference/connection-string/
connection-string: mongodb://127.0.0.1
MongoService: MongoDB REST and Websocket API
# MongoDB REST and Websocket API
# see https://restheart.org/docs/tutorial
# MongoDB REST and Websocket API
# see https://restheart.org/docs/tutorial
mongo:
enabled: true
uri: /
# Use mongo-mounts to expose MongoDb resources binding them to API URIs.
#
# The parameter 'what' identifies the MongoDb resource to expose.
# The format is /db[/coll[/docid]]
# Use the wildcard '*' to expose all dbs.
#
# The parameter 'where' defines the URI to bind the resource to.
# It can be an absolute path (eg. /api) or path template (eg. /{foo}/bar/*).
# The values of the path templates properties are available:
# - in the 'what' property (e.g. what: /{foo}_db/coll)
# - programmatically from MongoRequest.getPathTemplateParamenters() method.
#
# It is not possible to mix absolute paths and path templates: 'where' URIs
# need to be either all absolute paths or all path templates.
#
# Examples:
# The following exposes all MongoDb resources.
# In this case the URI of a document is /db/coll/docid
#
# - what: "*"
# where: /
#
# The following binds the URI /database to the db 'db'
# In this case the URI of a document is /database/coll/docid
#
# - what: /db
# where: /database
#
# The following binds the URI /api to the collection 'db.coll'
# In this case the URI of a document is /api/docid
#
# - what: /db/coll
# where: /api
mongo-mounts:
- what: /restheart
where: /
# Default representation format https://restheart.org/docs/mongodb-rest/representation-format/#other-representation-formats
default-representation-format: STANDARD
# Default etag check policy https://restheart.org/docs/mongodb-rest/etag/#etag-policy
etag-check-policy:
db: REQUIRED_FOR_DELETE
coll: REQUIRED_FOR_DELETE
doc: OPTIONAL
# get collection cache speedups GET /coll?cache requests
get-collection-cache-enabled: true
get-collection-cache-size: 100
get-collection-cache-ttl: 10_000 # Time To Live, default 10 seconds
get-collection-cache-docs: 1000 # number of documents to cache for each request
# Check if aggregation variables use operators. https://restheart.org/docs/mongodb-rest/aggregations/#security-considerations
aggregation-check-operators: true
# default-pagesize is the number of documents returned when the pagesize query
# parameter is not specified
# see https://restheart.org/docs/read-docs#paging
default-pagesize: 100
# max-pagesize sets the maximum allowed value of the pagesize query parameter
# generally, the greater the pagesize, the more json serializan overhead occurs
# the rule of thumb is not exeeding 1000
max-pagesize: 1000
# local-cache allows to cache the db and collection properties to drammatically
# improve performaces. Without caching, a GET on a document would requires
# two additional queries to retrieve the db and the collection properties.
# Pay attention to local caching only in case of multi-node deployments (horizontal scalability).
# In this case a change in a db or collection properties would reflect on other
# nodes at worst after TTL milliseconds (cache entries time to live).
# In most of the cases Dbs and collections properties only change at development time.
local-cache-enabled: true
# TTL in milliseconds; specify a value < 0 to never expire cached entries
local-cache-ttl: 60000
# cache for JSON Schemas
schema-cache-enabled: true
# TTL in milliseconds; specify a value < 0 to never expire cached entries
schema-cache-ttl: 60000
# The time limit in milliseconds for processing queries. Set to 0 for no time limit.
query-time-limit: 0
# The time limit in milliseconds for processing aggregations. Set to 0 for no time limit.
aggregation-time-limit: 0
MongoDB GraphQL Service
# MongoDB GraphQL API
# see https://restheart.org/docs/mongodb-graphql/
graphql:
uri: /graphql
db: restheart
collection: gql-apps
# app cache can be disabled if needed, such as during testing or development
app-cache-enabled: true
# app cache entries are automatically revalidated every TTR milliseconds
app-cache-ttr: 60_000 # in msecs
# default-limit is used for queries that don't not specify a limit
default-limit: 100
# max-limit is the maximum value for a Query limit
max-limit: 1000
# The time limit in milliseconds for processing queries. Set to 0 for no time limit.
query-time-limit: 0
verbose: false
Note
|
app-cache-enabled and app-cache-ttr are available from v8.0.9 and v8.0.11, respectively. Earlier versions use an expiring cache policy with TTL configurable via the now-deprecated graphql/app-def-cache-ttl option. See issue #523.
|
Proxied resources
# Proxied resources - expose exrernal API with RESTHeart acting as a reverese proxy
# see https://restheart.org/docs/proxy
# options:#
# - location (required) The location URI to bound to the HTTP proxied server.
# - proxy-pass (required) The URL of the HTTP proxied server. It can be an array of URLs for load balancing.
# - name (optional) The name of the proxy. It is required to identify 'restheart'.
# - rewrite-host-header (optional, default true) should the HOST header be rewritten to use the target host of the call.
# - connections-per-thread (optional, default 10) Controls the number of connections to create per thread.
# - soft-max-connections-per-thread (optional, default 5) Controls the number of connections to create per thread.
# - max-queue-size (optional, default 0) Controls the number of connections to create per thread.
# - connections-ttl (optional, default -1) Connections Time to Live in seconds.
# - problem-server-retry (optional, default 10) Time in seconds between retries for problem server.
proxies:
# - location: /anything
# proxy-pass: https://httpbin.org/anything
# name: anything
Static Web Resources
# Static Web Resources - serve static files with RESTHeart acting a web server
# see https://restheart.org/docs/static-resources
static-resources:
# - what: /path/to/resources
# where: /static
# welcome-file: index.html
# embedded: false
Other services
# Service to GET and DELETE (invalidate) the user auth token generated by the TokenManager
authTokenService:
uri: /tokens
# Simple ping service
ping:
enabled: true
msg: Greetings from RESTHeart!
# Returns the roles of the authenticated user
roles:
uri: /roles
# a global blacklist for mongodb operators in filter query parameter
filterOperatorsBlacklist:
blacklist: [ "$where" ]
enabled: true
# bruteForceAttackGuard defends from brute force password cracking attacks
# by returning `429 Too Many Requests` when more than
# `max-failed-attempts` requests with wrong credentials
# are received in last 10 seconds from the same ip
bruteForceAttackGuard:
enabled: false
# max number of failed attempts in 10 seconds sliding window
# before returning 429 Too Many Requests
max-failed-attempts: 5
# if true, the source ip is obtained from X-Forwarded-For header
# this requires that header beeing set by the proxy, dangerous otherwise
trust-x-forwarded-for: false
# when X-Forwarded-For has multiple values,
# take into account the n-th from last element
# e.g. with [x.x.x.x, y.y.y.y., z.z.z.z, k.k.k.k]
# 0 -> k.k.k.k
# 2 -> y.y.y.y
x-forwarded-for-value-from-last-element: 0
# Sets the X-Powered-By: restheart.org response header
xPoweredBy:
enabled: true
# Sets the Date response header
dateHeader:
enabled: true
Logging
# Logging
# see https://restheart.org/docs/logging
# Options:
# - log-level: to set the log level. Value can be OFF, ERROR, WARN, INFO, DEBUG, TRACE and ALL. (default value is INFO)
# - log-to-console: true => log messages to the console (default value: true)
# - ansi-console: use Ansi console for logging. Default to 'true' if parameter missing, for backward compatibility
# - log-to-file: true => log messages to a file (default value: false)
# - log-file-path: to specify the log file path (default value: restheart.log in system temporary directory)
# - packages: only messages form these packages are logged, e.g. [ "org.restheart", "com.restheart", "io.undertow", "org.mongodb" ]
# - full-stacktrace: true to log the full stacktrace of exceptions
# - requests-log-mode: 0 => no log, 1 => light log, 2 => detailed dump (use 2 only for development, it can log credentials)
# - tracing-headers (default, empty = no tracing): add tracing HTTP headers (Use with %X{header-name} in logback.xml); see https://restheart.org/docs/auditing
logging:
log-level: INFO
log-to-console: true
ansi-console: true
log-to-file: false
log-file-path: restheart.log
packages: [ "org.restheart", "com.restheart" ]
full-stacktrace: false
requests-log-mode: 1
tracing-headers:
# - x-b3-traceid # vv Zipkin headers, see https://github.com/openzipkin/b3-propagation
# - x-b3-spanid
# - x-b3-parentspanid
# - x-b3-sampled # ^^
# - uber-trace-id # jaeger header, see https://www.jaegertracing.io/docs/client-libraries/#trace-span-identity
# - traceparent # vv opencensus.io headers, see https://github.com/w3c/distributed-tracing/blob/master/trace_context/HTTP_HEADER_FORMAT.md
# - tracestate # ^^
Metrics
# Metrics
# see https://restheart.org/docs/metrics
requestsMetricsCollector:
enabled: false
uri: /metrics
include: [ "/*" ]
exclude: [ "/metrics", "/metrics/*" ]
jvmMetricsCollector:
enabled: false
Core module configuration
# base configuration for core module
core:
# The name of this instance. Displayed in log, also allows to implement instance specific custom code
name: default
# The directory containing the plugins jars.
# The path is either absolute (starts with /) or relative to the restheart.jar file
# Just add the plugins jar to plugins-directory and they will be automatically
# added to the classpath and registered.
plugins-directory: plugins
# Limit the scanning of classes annotated with @RegisterPlugin
# to the specified packages. It can speedup the boot time
# in case of huge plugin jars. It is usually not required.
# Use an empty array to not limit scanning.
# Alsways add the package org.restheart to the list
plugins-packages: []
# Set to true for verbose logging of jar scanning for plugins
plugins-scanning-verbose: false
# Optionally define the base url of this instance
# Useful when RESTHeart is mediated by a reverse proxy or an API gateway to determine the instance's correct URL
base-url: null
# Number of I/O threads created for non-blocking tasks. Suggested value: core.
# if <= 0, use the number of cores.
io-threads: 0
# Initial number of platform carrier threads for executing worker virtual threads in blocking operations.
# Suggested value: 1.5*core.
# if <= 0, use 1.5 times the number of cores.
workers-scheduler-parallelism: 0
# Max number of platform carrier threads for executing worker virtual threads in blocking operations.
workers-scheduler-max-pool-size: 256
# set to true to pool buffers for io-threads. buffers pooling is always disabled for virtual worker threads.
buffers-pooling: true
# Use 16k buffers for best performance - as in linux 16k is generally the default amount of data that can be sent in a single write() call
# Setting to 1024 * 16 - 20; the 20 is to allow some space for getProtocol headers, see UNDERTOW-1209
buffer-size: 16364
# Specifies whether the buffer pool for I/O threads should use direct buffers.
# Direct buffers enable the JVM to leverage native I/O operations if supported by the system.
# Virtual working threads always use heap buffers because they are faster for their operations.
direct-buffers: true
# In order to save bandwitdth, force requests to support the giz encoding (if not, requests will be rejected)
force-gzip-encoding: false
# true to allow unescaped characters in URL
allow-unescaped-characters-in-url: true
Connection options
# Connection Options
connection-options:
# Enable HTTP/2 support
# Note: HTTP2 as implemented by major browsers requires the use of TLS
# How to enable TLS https://restheart.org/docs/security/tls/
# How to check HTTP/2 protocol https://stackoverflow.com/a/54164719/4481670
ENABLE_HTTP2: true
# The maximum size of a HTTP header block, in bytes.
# If a client sends more data that this as part of the request header then the connection will be closed.
# Defaults to 1Mbyte.
MAX_HEADER_SIZE: 1048576
# The default maximum size of a request entity.
# Defaults to unlimited.
MAX_ENTITY_SIZE: -1
#The default maximum size of the HTTP entity body when using the mutiltipart parser.
# Generall this will be larger than MAX_ENTITY_SIZE
# If this is not specified it will be the same as MAX_ENTITY_SIZE
MULTIPART_MAX_ENTITY_SIZE: -1
# The idle timeout in milliseconds after which the channel will be closed.
# If the underlying channel already has a read or write timeout set
# the smaller of the two values will be used for read/write timeouts.
# Defaults to unlimited (-1).
IDLE_TIMEOUT: -1
# The maximum allowed time of reading HTTP request in milliseconds.
# -1 or missing value disables this functionality.
REQUEST_PARSE_TIMEOUT: -1
# The amount of time the connection can be idle with no current requests
# before it is closed;
# Defaults to unlimited (-1).
NO_REQUEST_TIMEOUT: -1
# The maximum number of query parameters that are permitted in a request.
# If a client sends more than this number the connection will be closed.
# This limit is necessary to protect against hash based denial of service attacks.
# Defaults to 1000.
MAX_PARAMETERS: 1000
# The maximum number of headers that are permitted in a request.
# If a client sends more than this number the connection will be closed.
# This limit is necessary to protect against hash based denial of service attacks.
# Defaults to 200.
MAX_HEADERS: 200
# The maximum number of cookies that are permitted in a request.
# If a client sends more than this number the connection will be closed.
# This limit is necessary to protect against hash based denial of service attacks.
# Defaults to 200.
MAX_COOKIES: 200
# The charset to use to decode the URL and query parameters.
# Defaults to UTF-8.
URL_CHARSET: UTF-8
# If this is true then a Connection: keep-alive header will be added to responses,
# even when it is not strictly required by the specification.
# Defaults to true
ALWAYS_SET_KEEP_ALIVE: true