Configuration

Enonic XP and 3rd party applications can easily be configured by editing the files in the $XP_HOME/config/ directory.

When changing files ending with .cfg, it’s respective application will automatically restart with the new configuration. Files ending with .properties require a full restart of Enonic XP to be applied. In a clustered environment, configuration files must be distributed to all nodes where it is relevant.

System Properties

The $XP_HOME/config/system.properties file must always be placed in this location. Any changes to this file will require a full restart of the node to take effect The standard version of this file is listed below.

$XP_HOME/config/system.properties
# Installation settings
# xp.name = demo

# Global security settings
# xp.suPassword = password
# xp.suPassword = {sha1}5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8

# Initialization settings
# xp.init.adminUserCreation = true

# Configuration FileMonitor properties
# felix.fileinstall.poll = 1000
# felix.fileinstall.noInitialDelay = true

# Config loading properties
# xp.config.paths = ${xp.home}/config

In case you cannot log in as the su user and do not have any other admin user, you can set a temporary password by setting the property xp.suPassword in system.properties and restart the node. The password value can be hashed. The hashing algorithm currently supported are: sha1, sha256, sha512 and md5.

With Enonic XP versjon 6.9 a simple but powerful feature called “Config Paths” was introduced. In addition to the default $XP_HOME/config/ directory, you may now instruct XP to scan multiple different folders when looking for config files.

This provides great flexibility and can simplify configuration management. For instance:

  • Allowing selected users to manage application config, but not system configuration
  • Overriding standard config on selected nodes only

If multiple paths are listed, each directory will be scanned in the defined order, and the first file found of each configuration, will be used.

Below is an example usage of config path where it will scan three directories in the defined order.

xp.config.paths = ${xp.home}/config,/usr/local/xp/${node.group},/etc/xp/config

Please note that ${xp.home}/config is no longer required to be in the path.

Virtual Host Configuration

Virtual hosts have their own configuration file and settings are automatically updated upon changes. A sample virtual host configuration is listed below.

$XP_HOME/config/com.enonic.xp.web.vhost.cfg
enabled = true

mapping.test.host = localhost
mapping.test.source = /
mapping.test.target = /
mapping.test.userStore = system

mapping.intranet.host = enonic.com
mapping.intranet.source = /
mapping.intranet.target = /portal/master/enonic.com
mapping.intranet.userStore = enonic

mapping.admin.host = enonic.com
mapping.admin.source = /admin
mapping.admin.target = /admin
mapping.admin.userStore = system

In this example file, three mappings are configured.

host
Host-name to match.
source
Requested path to match.
target
Path to which the request is sent.
userStore
Key of the user store associated to this virtual host (see ID Providers).

In the second example, mapping “intranet”, a site is mapped to the root of the URL, which would be normal in production environments.

In the third example, the admin site is mapped to enonic.com/admin.

Mail Configuration

The mail server used for sending email messages can be configured. A sample mail configuration is listed below.

$XP_HOME/config/com.enonic.xp.mail.cfg
smtpHost=mail.server.com
smtpPort=25
smtpAuth=true
smtpUser=user
smtpPassword=secret
smtpTLS=false
smtpHost
Host name of the SMTP server. Default localhost.
smtpPort
TCP port of the SMTP server. Default 25.
smtpAuth
Enable authentication with the SMTP server. Default false.
smtpUser
User to be used during authentication with the SMTP server, if ‘smtpAuth’ is set to true.
smtpPassword
Password to be used during authentication with the SMTP server, if ‘smtpAuth’ is set to true.
smtpTLS
Turn on Transport Layer Security (TLS) security for SMTP servers that require it. Default false.

Repo Configuration

snapshots.dir
Where to store snapshots
$XP_HOME/config/com.enonic.xp.repo.cfg
#
# Where to store snapshots.
#
snapshots.dir = ${xp.home}/snapshots

Storage Configuration

Blobstore Configuration

Main blobstore configuration is configured in com.enonic.xp.blobstore.cfg.

$XP_HOME/config/com.enonic.xp.blobstore.cfg
provider = file
cache = true
cache.sizeThreshold = 1mb
cache.memoryCapacity = 100mb
provider
The blobstore provider to be used for storing. Default value is file. Other providers will be available in future versions / enterprise-edition. Each provider will have a separate configuration file named com.enonic.xp.blobstore.<providername>.cfg
cache
Enable or disable memory caching of blobs fetched from the blobstore. Default true
cache.sizeThreshold
The maximum size for objects to be cached, defaults to 1MB. You will usually avoid filling up the cache with large blobs, but rather cache smaller objects that are used often. The size notation accepts a number plus byte-size idenfier (b/kb/mb/gb/tb/pb)
cache.memoryCapacity
The maximum memory footprint of the blob cache. Defaults to 100MB. The size notation accepts a number plus byte-size idenfier (b/kb/mb/gb/tb/pb)

File blobstore configuration

$XP_HOME/config/com.enonic.xp.blobstore.file.cfg
baseDir = ${xp.home}/repo/blob
readThrough.provider =
readThrough.enabled = false
readThrough.sizeThreshold = 100mb
baseDir
Base-directory for storing blobs. Defaults to ${xp.home}/repo/blob.
readThrough.provider = none
Readthrough provider name, if enabled. A readthrough provider stores and fetches blobs through an intermediate blobstore. Typically used for providers using a remote blobstore where caching as local files will improve performance.
readThrough.enabled = false
Enable or disable readthough provider usage. Default to false.
readThrough.sizeThreshold = 100mb
The maximum size for objects to be stored in the readthrough provider, defaults to 100MB. The size notation accepts a number plus byte-size idenfier (b/kb/mb/gb/tb/pb)

Cluster configuration

Enonic XP functions with two clusters: Elasticsearch and Ignite. The cluster configuration gathers the common configuration for both ElasticSearch and Ignite

$XP_HOME/config/com.enonic.xp.cluster.cfg
cluster.enabled = false

node.name = <generated-UUID>

discovery.unicast.hosts = 127.0.0.1
network.host = 127.0.0.1
network.publish.host = 127.0.0.1

session.replication.enabled = false
cluster.enabled
If true, the node wil try to join a cluster. Default false.
node.name
Node name. Default a generated-UUID
discovery.unicast.hosts
List of nodes in the cluster to perform discovery when new nodes are started. Default 127.0.0.1.
network.host
Set the bind address. Default 127.0.0.1. Can be an explicit IP-address, a host-name or an alias. See the section below for an overview of aliases
network.publish.host
Set the address other nodes will use to communicate with this node = 127.0.0.1. Default 127.0.0.1
session.replication.enabled
Use the web session replication between cluster nodes. Default false.

Warning

Session replication is an experimental feature

Network host aliases

  • _local_ : Will be resolved to the local ip address.
  • _non_loopback_ : The first non loopback address.
  • _non_loopback:ipv4_ : The first non loopback IPv4 address.
  • _non_loopback:ipv6_ : The first non loopback IPv6 address.
  • _[networkInterface]_ : Resolves to the ip address of the provided network interface. For example _en0_
  • _[networkInterface]:ipv4_ : Resolves to the ipv4 address of the provided network interface. For example _en0:ipv4_
  • _[networkInterface]:ipv6_ : Resolves to the ipv6 address of the provided network interface. For example _en0:ipv6_

Elasticsearch configuration

All relevant Elasticsearch settings are available.

When changing com.enonic.xp.elasticsearch.cfg, the node will automatically restart with the new configuration.

$XP_HOME/config/com.enonic.xp.elasticsearch.cfg
node.client = false
node.data = true
node.master = true

path = ${xp.home}/repo/index
path.data = ${path}/data
path.work = ${path}/work
path.conf = ${path}/conf
path.logs = ${path}/logs
path.plugins = ${path}/plugins

cluster.name = mycluster
cluster.routing.allocation.disk.threshold_enabled = false

http.enabled = false
transport.tcp.port = 9300-9400

gateway.expected_nodes = 1
gateway.recover_after_time = 5m
gateway.recover_after_nodes = 1
discovery.zen.minimum_master_nodes = 1
discovery.unicast.port = 9300
index.recovery.initial_shards = 1
node.data
Allow data to be distributed to this node. Default true.
node.master
Allow this node to be eligible as a master node. Default true.
path
Path to directory where elasticsearch stores files. Default ${xp.home}/repo/index. Should be on a local file-system, not sharded.
path.data
Path to directory where to store index data allocated for this node. Default $path/data.
path.work
Path to temporary files. Default ${xp.home}/repo/index/work.
path.conf
Path to directory containing configuration. Default $path/conf.
path.logs
Path to log files. Default ${xp.home}/repo/index/logs.
path.plugins
Path to where plugins are installed. Default $path/plugins.
cluster.name
Cluster name. Default mycluster.
cluster.routing.allocation.disk.threshold_enabled
Prevent shard allocation on nodes depending on disk usage. Default false.
http.enabled
Enable the HTTP module. Default false.
transport.tcp.port
Custom port for the node to node communication. Defaults to the range 9300-9400.
gateway.expected_nodes
Number of nodes expected to be in the cluster to start the recovery immediately. Default 1.
gateway.recover_after_time
Time to wait until recovery happens once the nodes are met. Default 5m.
gateway.recover_after_nodes
Number of nodes expected to be in the cluster to start the recovery after gateway.recover_after_time. Default 1.
discovery.unicast.port
List of ports to perform discovery when new nodes are started. Default 9300.
index.recovery.initial_shards
Number of shards expected to be found on full cluster restart per index. Default quorum.

Ignite configuration

$XP_HOME/config/com.enonic.xp.ignite.cfg
discovery.tcp.port = 47500
discovery.tcp.port.range = 0

discovery.tcp.reconnect = 10

discovery.tcp.network.timeout = 5000
discovery.tcp.socket.timeout = 2000
discovery.tcp.ack.timeout = 2000
discovery.tcp.join.timeout = 0

discovery.tcp.stat.printfreq = 0

communication.message.queue.limit = 1024
discovery.tcp.port
Local port to listen to. Default 47500.
discovery.tcp.port.range
Range for local ports. Local node will try to bind on first available port starting from discovery.tcp.port up until discovery.tcp.port + discovery.tcp.port.range. Default 0.
discovery.tcp.reconnect
Number of times the node tries to (re)establish connection to another node. Default 10.
discovery.tcp.network.timeout
Maximum network timeout to use for network operations (in ms). Default 5000.
discovery.tcp.socket.timeout
Socket operations timeout (in ms). Default 5000.
discovery.tcp.ack.timeout
Timeout for receiving acknowledgement for sent message (in ms). Default 5000.
discovery.tcp.join.timeout
Join timeout (in ms). Default 0.
discovery.tcp.stat.printfreq
Statistics print frequency. Default 0.
communication.message.queue.limit
Message queue limit for incoming and outgoing messages. Default 1024.

Admin UI Configuration

The Admin UI can be configured in the com.enonic.xp.app.main.cfg file. For now, the only option here, is to turn off the XP Tour for all users.

$XP_HOME/config/com.enonic.xp.app.main.cfg
# Disable the "Welcome tour" from the XP Home Screen. Default enabled.
tourDisabled = true

Jetty HTTP Configuration

Jetty HTTP settings can be configured using com.enonic.xp.web.jetty.cfg file.

$XP_HOME/config/com.enonic.xp.web.jetty.cfg
# Set this if host name (or ip) needs to be fixed.
host =

# Socket timeout for connections.
timeout = 60000

# True to send server header.
sendServerHeader = false

# True to enable HTTP connections.
http.enabled = true

# Http port number to use.
http.port = 8080

# Max request header size (default 32K).
http.requestHeaderSize = 32768

# Max response header size (default 32K).
http.responseHeaderSize = 32768

# Session timeout (when inactive) in minutes.
session.timeout = 60

# Cookie name to use for sessions.
session.cookieName = JSESSIONID

# Enable GZIP compression for responses.
gzip.enabled = true

# Minimum number of bytes in response to consider compressing the response.
gzip.minSize = 16

# True to enable request logging.
log.enabled = false

# Request log file.
log.file = ${xp.home}/logs/jetty-yyyy_mm_dd.request.log

# True to append to the file, or create new one when started.
log.append = true

# True to use extended format.
log.extended = true

# Timezone to display timestamp in.
log.timeZone = GMT

# Number of days to retain the logs.
log.retainDays = 31

Media Configuration

If you need extra media-type (MIME type) mappings you can add them in com.enonic.xp.media.cfg.

$XP_HOME/config/com.enonic.xp.media.cfg
# Media type mappings
ext.mp3 = audio/mpeg3
ext.p = text/x-pascal

OSGi Shell Configuration

To enable or configure OSGi shell, use com.enonic.xp.server.shell.cfg file.

$XP_HOME/config/com.enonic.xp.server.shell.cfg
#
# Remote shell configuration
#

enabled = false
telnet.ip = 127.0.0.1
telnet.port = 5555
telnet.maxConnect = 2
telnet.socketTimeout = 0

DoS Filter Configuration

The DoS (denial of service) filter can be configured using com.enonic.xp.web.dos.cfg file.

$XP_HOME/config/com.enonic.xp.web.dos.cfg
# Enable dos filter (true/false)
enabled = false

# Maximum number of requests from a connection per second. Requests in excess of this are first delayed, then throttled.
maxRequestsPerSec = 25

# Delay imposed on all requests over the rate limit. -1 = reject request, 0 delay.
delayMs = 100

# Length of time, in ms, to blocking wait for the throttle semaphore.
maxWaitMs = 50

# Number of requests over the rate limit able to be considered at once.
throttledRequests = 5

# Length of time, in ms, to async wait for semaphore.
throttleMs = 30000

# Length of time, in ms, to allow the request to run.
maxRequestMs = 30000

# Length of time, in ms, to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it.
maxIdleTrackerMs = 30000

# If true, insert the DoSFilter headers into the response.
insertHeaders = true

# If true, usage rate is tracked by session if a session exists.
trackSessions = true

# If true and session tracking is not used, then rate is tracked by IP+port (effectively connection).
remotePort = false

# A comma-separated list of IP addresses that will not be rate limited.
ipWhitelist =

Market Configuration

The market-place for installing applications can be configured using the com.enonic.xp.market.cfg file

$XP_HOME/config/com.enonic.xp.market.cfg
marketUrl = https://market.enonic.com/applications

UDC Configuration

UDC (Usage Data Collector) is collecting anonymous usage data 10 minutes after startup and every 24 hours. It is only used for finding out what platforms to focus on and improve platform stability. To switch this off, you can configure it sing the com.enonic.xp.server.udc.cfg file

$XP_HOME/config/com.enonic.xp.server.udc.cfg
#
# Set to false to disable usage data collector (UDC)
#
enabled = true

Standard ID Provider

Standard ID Provider, in charge of the login for admin by default, has a “Create Admin User” mode for new installations under specific conditions. When this mode is enabled, you also have the possibility to postpone the admin user creation and login without a user. You may turn off this capability.

$XP_HOME/config/com.enonic.xp.app.standardidprovider.cfg
# Set to false to disable the "login without user" capability of the Admin User Creation mode
loginWithoutUser = true