Edit Page

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