Configuring main Jahia features

October 8, 2024

Configuration files

Jahia features are configured in various files. The main configuration options are specified in the jahia.properties and jahia.node.properties files. The latter file is responsible only for clustering settings. The runtime data and configuration files are located outside the Web application for better maintainability and customization.

Main configuration files

The content of the digital-factory-config folder (or the one, which you’ve chosen as a target for configuration location during Jahia installation) is as follows:

digital-factory-config
`-- jahia
|-- applicationcontext-custom.xml
|-- jahia.properties
|-- jahia.node.properties
`-- license.xml

Where:

  • applicationcontext-custom.xml
    Is a Spring bean definition file where you can place custom bean definitions the Jahia definition can be overridden (a bean definition is overridden by its bean ID). The file empty by default.
  • jahia.properties
    Is the main configuration file which allows customization of most of Jahia features and services.
  • jahia.node.properties
    Is the configuration file for the clustering options
  • license.xml
    Is a file with your current Jahia license

Technical details

Technically, the digital-factory-config folder is made available to the Jahia via class path, either by adding the path location to some application server specific files or by creating a JAR file with the content of the digital-factory-config folder and deploying it to your application server. In effect the content is available for the application using the classpath lookup like:

getClass().getResource("/jahia/jahia.properties")

or in a Spring framework resource lookup format as:

classpath*:jahia/jahia.properties

Overriding configuration using environment variables

You can override default Jahia configuration settings by supplying corresponding environment variables. You can set an environment variable globally on your system or directly in the script that starts your application server (for Apache Tomcat, it is tomcat/bin/setenv.sh or bat file). If you are using Jahia in a containerized environment (like Docker), you pass the environment variable to the command that runs the container.

You must follow a naming convention to make an environment variable recognized by Jahia. It should have a prefix jahia_cfg_ (case-insensitive) and then the actual key of a Jahia property (case-sensitive), where dots are replaced with underscores (in case of an underscore in the key, it is replaced with double underscore). The following example shows how to override the Jahia cluster node ID, bind ports for JGroups and Hazelcast, as well as the Jahia SSH console port:

export jahia_cfg_cluster_node_serverId=dx1
export jahia_cfg_cluster_tcp_bindPort=27000
export jahia_cfg_cluster_hazelcast_bindPort=37000
export jahia_cfg_karaf_remoteShellPort=20101

OSGi configurations

Modules and OSGi bundles can have with their own configurations, handled by the OSGi framework. These configurations files are located in digital-factory-data/karaf/etc, and can be modified at runtime. Any modification will be taken into account immediately by the bundles using them. These files are replicated across the cluster. Examples of modules using OSGi configurations are LDAP users provider, jExperience, and GraphQL.

Personalizing URLs

URL Rewriting

Refer to the URL rewriting section in Managing URLs for more information.

Removing jsessionid from URLs

Jahia requires that the user’s session is correctly handled. Usually, applications use cookies to track the session. If cookies are not available on the client or the client connects for the first time, the application server adds a parameter in all links to handle session tracking. This parameter can create issues when indexing links by search engines. Jahia can automatically remove it from all links. This feature can be enabled in the jahia.properties file:

# Disable the jsessionid parameter added by application server to track session when no cookie is present
disableJsessionIdParameter = true

By default, the session ID parameter removal is enabled, and it won’t appear in links. If you need to support browsers which do not handle cookies, you can disable this feature.

Changing context and port numbers

During the installation

Changing the Jahia Web application context path (the default one is ROOT) as well as default Apache Tomcat port numbers – in case Tomcat pack is selected – is possible during the installation via Installer UI, by choosing and completing the “Custom install” option at the beginning. See the Apache Tomcat configuration and Web application settings for more details.

After the installation

Once you have installed Jahia, you will still be able to change those values if required. To change the port, you just need to configure it at application server level. Please refer to your application server documentation. If you need to change the context path, you will need to redeploy your Jahia application using this new context path. Refer to your application server documentation if you need some additional information about how to do this.

Permanent move for vanity URLs

In Jahia, you can define SEO friendly vanity URLs. There can be more than one URL for the same resource, whereas only one can be set as the default one. With the permanentMoveForVanityURL setting in the jahia.properties configuration file you can control access with a non-default vanity URL. Jahia should inform the client that the resource has permanently moved (HTTP status code 301). This is the default behavior. If you set the parameter to false, then Jahia will serve the request without changing the URL to the new default one.

Caching

Caches are essential to high-performing web systems such as Jahia to be able to avoid recreating dynamic content under large system loads. The image below shows the basic architecture of the cache sub-system.

The main focus in Jahia lies on the Module Cache (HTML content output cache) which is using the Ehcache implementation. Jahia uses multiple cache layers to optimize the performance of page delivery, including the:

  • Browser cache
  • Front-end HTML caches (skeleton/module cache)
  • Object caches
  • Content repository/database caches

Each of these cache layers plays a different role in making sure values are only computed once.

The browser cache layer

While not integrated in Jahia, but in the browser, the browser cache plays a critical role in guaranteeing good performance for the end-user. For example, Jahia’s usage of the GWT framework makes it possible for AJAX source code to be aggressively cached in the browser cache; therefore making sure we don’t reload script code that has not changed. Jahia also properly manages the browser cache to make sure it does not cache page content that has changed. It also controls expiration times for cached content, so that the browser does not request content that is rarely changed.

The front-end HTML cache layer

Jahia’s cache implementation, the Module Cache, integrates fragment caching at a module level, making interaction with templates very natural. Template developers usually do not have to add any markup to have their fragments correctly cached. Even when they need to control fragment generation, this is much easier to do than in previous versions of Jahia.

The HTML code of each module is aggregated on runtime to render the page for the end user. For each module, we try to maximize its sharing by building complex keys, considering several parameters like roles/templates/etc. That way we can share this rendering with a maximum number of other users that have the same rights.

We also detect cases where more than one parallel request tries to obtain the same fragment, which is not yet cached. In such cases, to not waste resources we let just one request do the work and make the other request(s) wait for it. If rendering the module takes too long, the waiting request gets cancelled with an exception saying “Module generation takes too long due to module not generated fast enough (>10000 ms)”. As such errors should be taken seriously, see How to handle module generation timeouts? for hints how to solve such issues.

Object caches

The next layer below the front-end HTML cache sub-systems are the object caches. This layer handles all Jahia objects that represent sites, users, groups, etc. It serves as a layer on top of the content repository/database caches to avoid reconstructing objects for each model request. This is all handled internally by Jahia and it is only important to interact with these caches if integrators are directly calling Jahia’s API to perform object changes that do not automatically update the caches scheduling / batching.

Content repository caches

As we moved all content objects to the Java content repository, the object and database caches are used less than in previous Jahia versions. Retrieving content objects from the JCR does not require as many additional caches as before. The content repository optimizes the performance with some internal caches. See Increasing bundleCacheSize for how to tune the content repository bundle caches for optimized performance.

Ehcache configuration

A new section has been added to the Configuration and fine tuning guide to describe cache configuration in details.

Clustering

Deploying Jahia in a cluster is a very powerful way of distributing CPU and memory load to handle larger traffic sites. A typical Jahia cluster installation is illustrated in the graph below.

All Jahia nodes, belonging to the same cluster, share the same database schema to have a common data storage. Jahia is largely based on Apache Jackrabbit and thus relies on its clustering capabilities and configuration. See http://wiki.apache.org/jackrabbit/Clustering for more details. In Jahia uses Jackrabbit’s DataStore (see http://wiki.apache.org/jackrabbit/DataStore for more details of how it works). This way it is now possible and recommended to store large files on a shared file-system, while storing everything in the database is still an option.

Indexes in Jackrabbit have to be local to each cluster node and cannot be shared.

For Jackrabbit, every change made by one cluster node is reported in a journal (database table). Cluster nodes read the journal and update their state at a configurable synchronization interval.

Ehcache is another component, which needs communication between nodes. We are using JGroups as a communication channel, by default.

Jahia uses Hazelcast as cluster communication channel for its clustered module deployment feature.

Browsing nodes

Browsing nodes are specialized Jahia nodes that only serve as content publishing nodes. They also interact with portlets to render pages. Using this node specialization allows to separate the browsing load from authoring and background processing loads.

Authoring nodes

Authoring nodes are cluster nodes that can be used to either browse or edit Jahia content. 

Processing node

In Jahia, long-running tasks such as workflow validation operations, copy and pasting, content import and indexing are executed as background tasks, which can be resource intensive. This way, while these long operations are executed, other nodes are still able to process content browsing and editing requests.

There can be only one processing node in Jahia cluster.

Configuration

It is essential that when binary data is stored on a file system (the default and preferred option), all cluster nodes should point to the same shared directory to store binary data in a common file data store. During installation of a cluster node you will be asked to enter the “Path to Data Store files” (on the step for configuring database, see Database).

To install your Jahia cluster, you will have to install your cluster nodes one after the other.

  • For the first one, proceed as if you were installing a standalone Jahia, excepted that you need to specify that you are installing a cluster at the “Operating mode” step. If you have chosen to use the bundled Tomcat as application server, do not start it at the end of the wizard.
  • For the other nodes, execute the wizard again, connecting to same database. This time just specify that the schema does not have to be created (uncheck “Create required database tables” checkbox). On the screen where you configure your cluster, take care to define a new server ID or keep <auto> for an auto-generated value. If you have already set a node to be the processing server, uncheck the option as only one node can have this role in your cluster.

The cluster configuration is by default located in the digital-factory-config/jahia/jahia.node.properties file under:

######################################################################
### Cluster settings ################################################
######################################################################

 

Sharing webapps

Web applications need to support clustering on their own to be able to fully work in a clustered Jahia environment.

You have to deploy the webapp on each node of the Jahia cluster. If this webapp stores some data, you will have to ensure that each instance of your webapp shares the same data, and do not duplicate it, otherwise you may encounter some functional issues. Refer to your webapp documentation to perform this.

Starting up

The first time the cluster is started, the processing server must be started first and standalone. Once the initialization process is completely finished, you can start the other cluster nodes.

Sticky sessions

If you are using a hardware or software load balancer in front of Jahia to handle the distribution of load among all Jahia nodes in the cluster, you will need to activate "sticky sessions" on your application server and the load balancer. This is required to force an open session to make all requests on the same server for the time of the session.

On Tomcat, this is done by adding a unique jvmRoute attribute in the server.xml file:

<Engine name="Catalina" defaultHost="localhost" jvmRoute="jvm1">

where jvm1 is the name of the worker as declared in the load-balancer. The jvmRoute attribute value can be specified during the installation of Jahia instance on the screen with cluster configuration settings (="Server ID of this node"). You can also see the reference guide for the configuration of the load balancer on the Apache web site: http://tomcat.apache.org/connectors-doc/reference/workers.html.

Distributed sessions

Distributed session module

For authenticated users, the Jahia stores data in the HTTP session. By default, this data is stored in memory of the server, where requests of a session are routed to. When the server is shut down, all this session data disappears and the user will have to login again and eventually re-do steps. For higher availability and up-time we recommend replicating the session data on all servers, so that sessions survive a stopped server and that other servers can continue working on user requests, which were previously served from the stopped server. This way the user will not even perceive that there was a problem and will not get unsatisfied. You can deploy the distributed-sessions module, which in its version 3.x.x offers the ability to distribute sessions on all servers with hazelcast. As the module’s session manager is based on Spring Session more technologies may get added in future. So, for now you just have to download and install the distributed-sessions module from our store.

Session configuration

You must uncomment the jahiaGeneratedResourcesDiskPath setting in digital-factory-config/jahia/jahia.properties and point it to a shared network folder that is accessed by all cluster nodes.

jahiaGeneratedResourcesDiskPath=${jahia.data.dir}/generated-resources/
Warning: Do not share the generated-resources folder across nodes if you perform rolling upgrades. If the folder is shared, resources may be generated on nodes with the older version of Jahia while the nodes on the new version are started.

You can configure session expiration with the following jahia.properties setting. The default value is 30 minutes.

jahia.session.timeout = 30

The following shows cookie settings with the default values (so if you use them, you do not have to configure anything):

jahia.session.cookieName = JSESSIONID
jahia.session.cookiePath = /
jahia.session.cookieMaxAge = -1
jahia.session.useHttpOnlyCookie = true

The spring-session cookie will add a new cookie for session (JSESSIONID). Note that it may override the default cookie of the app server. If you use websockets in Jahia, we recommend using another cookie name.

Hazelcast configuration file

The hazelcast configuration file used for distributed session will be created in karaf/etc/hazelcast-ds.xml the first time the module is started. This file can be modified manually, it will never be overridden again when restarting/upgrading the module. A modification in this file need to be replicated manually on all cluster nodes, and will require a restart of the module to be taken into account.

By default, tcp-ip network configuration is used. The list of members will be filled automatically based on JCR cluster members, so no members need to be configured under tcp-ip. The port used by hazelcast can be set by adding cluster.hazelcastds.bindPort in jahia.properties. If not specified, it will use cluster.hazelcast.bindPort + 1.

You can change group name and password to ensure your cluster is not connecting to another cluster (which could happen if you use other discovery than tcp-ip).

JVM Route

You have to specify/set the jvmRoute value, in jahia.node.properties like it is set in tomcat/conf/server.xml:

jahia.session.jvmRoute = node1

You do not need to set the jvmRoute (which will be appended to the session cookie name) if your load balancer does not use that cookie to ensure sticky sessions, but sets an own routing cookie. Like mentioned in section 4.4 Sticky sessions it is required in Jahia to have sticky sessions configured. Only for live mode, when the content is just read-only, sticky sessions are not mandatory. The reason is that writes to the content repository can take up to around 5 seconds to get synchronized to other cluster nodes. So to make an immediate subsequent read request see the current update, the read request needs to be served by the same server as the write request, which is ensured with sticky sessions. For some actions in administration or our tools section, we recommend bypassing the load balancer, especially for:

  • module or portlet deployment/activation
  • site import (for site import in Digital Experience Manager we do not provide failover support)
  • obtaining the status of certain cluster nodes

Before using the distributed-sessions module

Notice that for now we have tested and support the distributed-sessions module just with Tomcat. Also, before you start using the feature you need to first thoroughly test it with your application in a test environment. You need to make sure that all the custom objects you write to the HTTP session are serializable. The objects should also not be too huge in size, because the HTTPSession object now is created and deserialized on each single request (so there no longer is a HTTPSession object, which exists for the whole session lifetime). Therefore, you should also not store references to HTTPSession objects, because these just show the parameters at the time, when the session object instance was created to serve that specific request. This instance will afterwards not see changes whenever session objects are added or removed. You should also not update a mutable object held in session from some custom background thread, which does not pass through the servlet filter to write back session object changes to the external store. You should also check that your custom processing does not rely on storing or reading data on a resource, which is just available from one cluster node, because after failover to a different server node this resource will not be available.

Adding new node to the cluster

Adding a new node to an existing cluster is done by copying an existing node (usually a browsing one) and adjusting the configuration appropriately.
Follow the steps below to perform this procedure:

  1. Stop the Jahia cluster node which you will copied.
  2. Copy the complete Jahia installation folder (including the Apache Tomcat, if you use it), configuration (digital-factory-config) and data (digital-factory-data) folders (including repository indexes) to the new location.
  3. Adjust the node clustering configuration in the file digital-factory-config/jahia/jahia.node.properties:
    • cluster.node.serverId - each cluster node should have a unique ID 
    • bind address (if not empty) and port numbers for clustered communication
    • verify the value of processingServer flag (there can be only one node in the cluster, where this flag is set to true)
  4. Adjust any absolute paths, if needed, in digital-factory-config/jahia/jahia.properties as well as in your own configuration files.
  5. If the copied node is located on the same server, you will need to adjust the port numbers (jahia.node.properties, jahia.properties and Tomcat, if used) in a way, that they do not conflict.
  6. Start your new Jahia node and verify the log file of the server for correct startup.
  7. Verify (using Jahia Tools / Cluster view page) that the new node has correctly joined the cluster. The discovery can take up to some minutes.

You are done with adding a new Jahia cluster node.

Permanently removing a node from the cluster

If you are permanently removing a node from your cluster, meaning that you are stopping that node and never bringing it back up (e.g. a spare node in an elastic environment), then it is advised to run the karaf command jahia:remove-local-revisions-node to keep the revisions journal up-to-date. By doing so, the janitor job can clean up useless entries in the journal, and avoid this table to overgrow. This can be done using the Rest API:

curl -u ‘jahia:password’ -H “content-Type: text/plain” -X POST -d ‘jahia:remove-local-revisions-node 125cdf6vdv46df8vd8vdf6vdf4’ http://127.0.0.1:8080/modules/api/commands

where 125cdf6vdv46df8vd8vdf6vdf4 is the (removed) node-id.

 

LDAP

LDAP is an application protocol for querying and modifying directory services running over TCP/IP. Jahia has default connectors to retrieve users/groups from an LDAP server. Jahia supports most LDAP servers right out of the box, including OpenLDAP and ActiveDirectory. It is most commonly used with SSO technologies to provide a seamless experience to end-users. The LDAP configuration is deployed as an OSGi configuration, bound to the “Jahia LDAP connection (ldap)” module bundle, available in the Jahia Enterprise Distribution and on the Jahia store. The LDAP user and group providers can be configured during the Installation Wizard by activating “Configure an LDAP user/group provider” option and providing your LDAP server specific parameters. After the installation, an LDAP user/group provider can be configured using the administration UI under Administration > Server  > Users and Roles > User and group providers. Please visit the following documentation for more details: Customizing users and groups

Authentication

Single Sign-On: CAS

The Central Authentication Service (CAS) is a single sign-on protocol for the web. Its purpose is to permit a user to access multiple applications while providing their credentials (such as user id and password) only once.

When the client visits Jahia and wants to authenticate, Jahia redirects the user to the CAS server. CAS validates the client's authenticity, usually by checking a username and password against a database (such as LDAP or Active Directory).

If the authentication succeeds, CAS returns the client to Jahia, passing along a security ticket. Jahia then validates the ticket by contacting CAS over a secure connection and providing its own service identifier and the ticket. CAS then gives the application trusted information about whether a specific user has successfully authenticated.

Jahia uses Jasig CAS 3.1 Java client, which adds support for CAS 2.0 specification features (https://github.com/apereo/cas), like multi-tier proxy authentication etc.

The following section gives an overview of configuration options.

Jahia side

Step 1 - The first file to configure is:

<digital-factory-config>/karaf/etc/org.jahia.modules.cas.CasAuthValve.cfg

Here the values that you would want to change are:

# URL prefix of the CAS server
serverUrlPrefix=https://localhost:8443/cas

# the redirect URL to the CAS server for login
loginUrl=${serverUrlPrefix}/login

# logout URL to invalidate the user session on the CAS server
logoutUrl=${serverUrlPrefix}/logout

Please note, the CAS server should be accessed using HTTPS protocol. See Configuring ticket validator for advanced configuration. Step 2 - Add the login link in a Jahia view: In the Studio mode, you can use the “Login” component to place a link for the login page into your template. Alternatively, in your template code you can use the following expression to have a proper link (considering CAS server login page):

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<a href="<c:url value='${url.login}'/>">Log in</a>

To add only a logout URL, you can use:

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<a href="<c:url value='${url.logout}'/>">Log out</a>

The page https://wiki.jasig.org/ contains some information to configure your CAS server. The following “How-To” can be also helpful: http://jira.jahia.org/browse/JKB-22. A good architecture would separate the CAS server from the other application servers.

Configuring ticket validator

By default, Jahia uses the org.jasig.cas.client.validation.Cas20ServiceTicketValidator implementation for ticket validation, which validates Service Tickets in compliance with the CAS 2 (using /serviceValidate service endpoint). The validator implementation is pluggable and can be replaced with e.g. the org.jasig.cas.client.validation.Cas20ProxyTicketValidator one (/proxyValidate endpoint), which also supports ticket validation using configured list of proxies. To override the default implementation the following configuration option should be added into <digital-factory-config>/karaf/etc/org.jahia.modules.cas.CasAuthValve.cfg file with the ID of the Spring bean, representing the validator (implementation of the org.jasig.cas.client.validation.TicketValidator interface), for example:

ticketValidator=Cas20ProxyTicketValidator

And the corresponding bean can be defined in a Spring file, e.g. <digital-factory-config>\jahia\applicationcontext-custom.xml as follows:

<bean id="Cas20ProxyTicketValidator" class="org.jasig.cas.client.validation.Cas20ProxyTicketValidator" scope="prototype">
    <constructor-arg index="0" value="${auth.cas.serverUrlPrefix}" />
    <property name="acceptAnyProxy" value="true"/>
    <property name="allowedProxyChains">
        <value>
            http://proxy1 http://proxy2
            http://proxy3 http://proxy4
        </value>
    </property>
</bean>

The bean defines a list of proxy chains and can accept other supported parameters, like renew, encoding, proxyCallbackUrl, proxyGrantingTicketStorage, etc.

Troubleshooting

If you have errors of the form:

org.jahia.exceptions.JahiaException: User message=Cannot validate CAS credentials, System message=Cannot validate CAS credentials, root

It is most probably due to your SSL certificate, and that the JVM that runs the Jahia does not recognize it. Refer to https://wiki.jasig.org/display/CAS/Solving+SSL+issues for more details.

SSO with Kerberos

Jahia is able to plug-in different authentication policies via HTTP filters and a pipeline of authentication valves. Some filters and valves are provided and can be activated by configuration, like NTLM or the integration of a CAS (Central Authentication Service) server. We also provide a filter and valve for integration with SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) to negotiate with the client and use either Kerberos or NTLM as a fallback. This way a non-interactive login is possible, which takes the user logged in to the operating system running the browser. Such a secure solution is especially interesting for intranets running with Windows servers. This document describes how to configure such an environment.

Prerequisites

For this guide, we assume that you are using the Windows Active Directory server. If you want to use Kerberos, then all clients and servers need to be joined in the same AD domain. If this requirement is not met, then SPNEGO will fall back to NTLM.

The guide was tested on Windows Server 2019 with OpenJDK 11.0.0. All terms in angle brackets <> should be replaced by terms fitting your environment or your choice. Notice also that realm names are case-sensitive and recommended to be used in UPPER CASE. Also with Kerberos you will not be able to use IP addresses or localhost but rather you will have to use the server name (DNS must be properly set up).

It should also be possible to use other directory servers supporting Kerberos and you can take this guide to get some useful information also relevant for alternative environments.

Since Jahia 8.0.2.0 SPNEGO is provided as a separate Enterprise module (spnego-authentication-valve), ensure that you have it deployed and started in your instance. 

Set up the Service Principal Name in the Active Directory

A Service Principal Name (SPN) account needs to be created for the Jahia server. Note that this account can't be used to log in.

  1. Start the Active Directory User and Computers from the Administration Tools menu.
  2. Right click on the Users repository and select New>User.
  3. Enter the user information (<your-spn-account> for user login), press Next.
  4. Enter the <password> and select Password never expires, click on Next and then on Finish.

In a console enter the command:

setspn -U -S HTTP/<your.jahia.server.name> <your-spn-account>

This applies wo Windows Server 2019, on older Windows Server versions the command was:

setspn -A HTTP/<your.jahia.server.name> <your-spn-account>

Create the Keytab file

The Keytab file enables a trust link between the Jahia server and the Key Distribution Center (KDC). This file contains a cryptographic key. The ktpass tool  is used to generate this file. In a console, enter the command:

ktpass /out <your-spn-account>.keytab /princ HTTP/<your.jahia.server.name>@<YOUR.AD.REALM> +rndPass /mapuser <your-spn-account>@<YOUR.AD.REALM> /ptype KRB5_NT_PRINCIPAL /crypto AES256-SHA1 /kvno 0

This command will generate the <your-spn-account>.keytab file, which has to be copied to a secret place on the Jahia server, which only the Jahia server application can read.

Create Kerberos configuration file (krb5.conf)

On the Jahia server create the Kerberos configuration file (krb5.conf) and place it somewhere on the Jahia server.
Here is an example of such a file:

[libdefaults]
ticket_lifetime = 24000
default_realm = <YOUR.REALM>
default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 des-cbc-md5 des-cbc-crc
permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 des-cbc-md5 des-cbc-crc
[realms]
<YOUR.REALM> = {
kdc = <hostname.of.your.kdc>.<your.domain>
}
[domain_realm]
.<your.domain> = <YOUR.REALM>
<your.domain> = <YOUR.REALM>
[logging]
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmin.log
default = FILE:/var/log/krb5lib.log
<YOUR.REALM> is the same as the domain in uppercase letters. With evolving versions, you may, for instance, have to change the enctypes settings.

In the startup script of the Jahia server you need to add the following parameter to pick up this file:

set JAHIA_JAVA_OPTS=%JAHIA_JAVA_OPTS% -Djava.security.krb5.conf=<path>\krb5.conf

Create JAAS login configuration file (jaas-login.conf)

On the Jahia server create the JAAS login configuration file (jaas-login.conf) and place it in a secret place accessible for the Jahia server only.

Here is an example of this file:

com.sun.security.jgss.accept {
    com.sun.security.auth.module.Krb5LoginModule
    required
    storeKey=true
    keyTab="<path>/<your-spn-account>.keytab"
    doNotPrompt=true
    useKeyTab=true
    principal="HTTP/<your.jahia.server.name>@<YOUR.REALM>"
    isInitiator=false
    debug=false;
};

In the startup script of the Jahia server you need to add the following parameter to pick up this file:

set JAHIA_JAVA_OPTS=%JAHIA_JAVA_OPTS% -Djava.security.auth.login.config=<path>\jaas-login.conf
set JAHIA_JAVA_OPTS=%JAHIA_JAVA_OPTS% -Djavax.security.auth.useSubjectCredsOnly=false

Test the SPN account

As it is quite easy to make mistakes in the Kerberos configuration, you should test your configuration with the tools provided by Java, before starting Jahia. In order to have those tests work, you have to copy your krb5.conf file in your windows system directory and rename it krb5.ini (most often c:\windows\krb5.ini) Verify that you are able to read the keytab file:

%JAVA_HOME%/bin/klist -k <path>/<your-spn-account>.keytab

and

%JAVA_HOME%/bin/kinit -k -t <path>/<your-spn-account>.keytab HTTP/<your.jahia.server.name>@<YOUR.REALM>
%JAVA_HOME%/bin/klist

LDAP Connector

In order to make Jahia access the users from your Active Directory you need to make sure that you have Jahia LDAP connector installed and that you added the configuration to your Active Direcory under the User and group providers in Jahia Serrver Administration.

Activate the SPNEGO HTTP filter and authentication valve in Jahia

Kerberos authentication in Jahia is only supported with Enterprise Distribution. To activate it, you need to set the auth.spnego.enabled property to true:

Jahia 8.0.0.0 and 8.0.1.0

In jahia.properties and restart the server.

Jahia 8.0.2.0 and later

In digital-factory-data/karaf/etc/org.jahia.modules.spnego.SpnegoHttpFilter.cfg, changes are taken into account without restart.

Activate the SPNEGO filter for specific subnets only

To activate SPNEGO filter for specific subnets only, you need to specify these subnets via the auth.spnego.onlyForSubnets property: 

 Jahia 8.0.0.0 and 8.0.1.0

In jahia.properties and restart the server.

Jahia 8.0.2.0 and later

In digital-factory-data/karaf/etc/org.jahia.modules.spnego.SpnegoHttpFilter.cfg, changes are taken into account without restart.

Please note that the desired subnets have to be declared using the CIDR notation. Activating the SPNEGO filter only for some subnets still allows guest users from other IPs to access the website. CIDR notation is a compact representation of an IP address and its associated routing prefix. The notation is constructed from an IP address, a slash ('/') character, and a decimal number. The number is the count of leading 1 bits in the routing mask, traditionally called the network mask. The IP address is expressed according to the standards of IPv4 or IPv6. As example: 192.168.100.14/24 represents the IPv4 address 192.168.100.14 and its associated routing prefix 192.168.100.0, or equivalently, its subnet mask 255.255.255.0, which has 24 leading 1-bits.

CIDR  Host bits Subnet mask Addresses in subnet Typical usage
/8 24 255.0.0.0 16777216 = 224  
/9 23 255.128.0.0 8388608 = 223  
/10 22 255.192.0.0 4194304 = 222  
/11 21 255.224.0.0 2097152 = 221  
/12 20 255.240.0.0 1048576 = 220  
/13 19 255.248.0.0 524288 = 219  
/14 18 255.252.0.0 262144 = 218  
/15 17 255.254.0.0 131072 = 217  
/16 16 255.255.0.0 65536 = 216  
/17 15 255.255.128.0 32768 = 215 ISP / large business
/18 14 255.255.192.0 16384 = 214 ISP / large business
/19 13 255.255.224.0 8192 = 213 ISP / large business
/20 12 255.255.240.0 4096 = 212 Small ISP / large business
/21 11 255.255.248.0 2048 = 211 Small ISP / large business
/22 10 255.255.252.0 1024 = 210  
/23 9 255.255.254.0 512 = 29  
/24 8 255.255.255.0 256 = 28 Large LAN
/25 7 255.255.255.128 128 = 27 Large LAN
/26 6 255.255.255.192 64 = 26 Small LAN
/27 5 255.255.255.224 32 = 25 Small LAN
/28 4 255.255.255.240 16 = 24 Small LAN
/29 3 255.255.255.248 8 = 23 Smallest multi-host network
/30 2 255.255.255.252 4 = 22 "Glue network" (point to point links)
/31 1 255.255.255.254 2 = 21 Point to point links (RFC 3021)
/32 0 255.255.255.255 1 = 20 Host route
 

Set up the browser

Internet Explorer, Misrosoft Edge and Chrome (on Windows)

  1. In Windows searchbar search for Internet Options and open it.
  2. Click on the Advanced tab, ensure that in Security section the Enable Integrated Windows Authentication is checked, then click OK.
  3. Click on the Security tab, click to select Local Intranet, then click on Sites.
  4. Enter https://<your.jahia.server.name> and validate it by clicking on Add and OK.
  5. Restart open browsers.

Firefox

  1. In Firefox, enter about:config as the URL and click on Go.
  2. Search for negotiate.
  3. On the property network.negotiate-auth.trusted-uris add https://<your.jahia.server.name>.

Chrome (on Linux and MacOS)

  1. Use command-line parameter --auth-negotiate-delegate-whitelist 
    --auth-negotiate-delegate-whitelist="<your.jahia.server.name>"

Video thumbnails

For an improved media experience, Jahia offers a possibility of automatic thumbnail generation for uploaded video files. The video thumbnails service requires the ffmpeg utility (http://ffmpeg.org/) to be installed. The following two configuration parameters in digital-factory-config/jahia/jahia.properties file control the service:

######################################################################
### Video Thumbnails Service ##########################################
######################################################################
# Video thumbnails service enables automatic creation of thumbnail images
# for uploaded video files.
# Set this to true to enable the video thumbnails service
jahia.dm.thumbnails.video.enabled = false
# Video thumbnails service requires the ffmpeg utility to be installed
# The following specifies the path to the ffmpeg executable file
# Usually for Linux it is: /usr/bin/ffmpeg
# for Windows, for example: C:/Program Files (x86)/ffmpeg-20120503-git-c1fe2db-win64-static/bin/ffmpeg.exe 
# If the ffmpeg/bin folder is present in your PATH, you can
# specify only the executable name here
jahia.dm.thumbnails.video.ffmpeg = ffmpeg

The jahia.dm.thumbnails.video.ffmpeg parameter should contain an absolute path to the ffmpeg executable file or, in case the corresponding folder is included into the PATH environment variable, just the executable name, i.e. ffmpeg.

Image service

The Jahia Image Service is here to manipulate images from Jahia itself. For licensing reasons, the service is by default using a Java native API named ImageJ, but this is not a really powerful API nor really efficient. So, if you want to boost the quality of your thumbnails or the result of your other image manipulation operations, Jahia allows you to define the path to your ImageMagick installation so that we can use it instead of the ImageJ API.

Note: Jahia 8 requires ImageMagick version 6.9 or 7.

Installing ImageMagick

Follow the instructions for your system on the Image Magick Binary Releases page: http://www.imagemagick.org/script/download.php. Once ImageMagick is installed, modify your jahia.properties file to activate ImageMagick instead of the ImageJ API.

######################################################################
### Image conversion Service #########################################
######################################################################
# The image service to use
# Native java service : "ImageJImageService"
# Set to "ImageMagickImageService" to use ImageMagick. You'll then have to set
# theimageMagick path
imageService = ImageMagickImageService
# The path to image magick and exiftools
# For windows : C:\\Programs\\ImageMagick;C:\\Programs\\exiftool
imageMagickPath = /usr/bin:/usr/local/bin:/opt/local/bin

Error and thread dump directories

Error file dumper server

Jahia’s error file dumper service is used to automatically create reports when an error occurs. The location of those files is by default: ${jahia.log.dir}/jahia-errors. In case the jahia.log.dir system property is not set explicitly or detected automatically by Jahia (for Apache Tomcat servers) the following location is used: ${java.io.tmpdir}/jahia-errors. Effectively, for Apache Tomcat this is by default under: <tomcat-home>/logs/jahia-errors. It is possible to override the error folder location with a system property named jahia.error.dir, e.g. by adding -Djahia.error.dir=/var/logs/jahia/errors to the JVM options (CATALINA_OPTS for Apache Tomcat).

Thread dumps

Via a “System Health -> Memory and thread dumps” panel in Server settings or via Jahia Tools Area it is possible to perform single thread dumps as well as a series of thread dumps into a file. The location of those files is by default: ${jahia.log.dir}/jahia-threads. In case the jahia.log.dir system property is not set explicitly or detected automatically by Jahia (for Apache Tomcat servers) the following location is used: ${java.io.tmpdir}/jahia-threads. Effectively, for Apache Tomcat this is by default under: <tomcat-home>/logs/jahia-threads.

It is possible to override the error folder location with a system property named jahia.thread.dir, e.g. by adding -Djahia.thread.dir=/var/logs/jahia/threads to the JVM options (CATALINA_OPTS for Apache Tomcat).

OSGi SSH Console

Jahia provides the powerful, flexible and secure Apache Karaf SSH shell.

The SSH shell is enabled by default and listens, for the sake of security, by default only on host 127.0.0.1, i.e. on connections from localhost. The default port number is 8101.

ssh -p 8101 root@127.0.0.1

The configuration of port number and host can be found in the digital-factory-config/jahia/jahia.properties:

######################################################################
### OSGi settings ####################################################
######################################################################
# The following setting is used to change the port which the
# Apache Karaf OSGi command line shell will listen to for SSH
# connections. Set it to a negative value to disable this feature
# entirely.
karaf.remoteShell.port = 8101
# The bind address for the SSH shell. '127.0.0.1' means the SSH shell
# will only allow local connections to be established. You may want to
# define here an dedicated IP address, the console will bind to, or
# a '0.0.0.0' which will mean it will be bound to all available
# network interfaces.
karaf.remoteShell.host = 127.0.0.1

The port number for the SSH console can also be configured during the Jahia installation wizard (in Advanced install mode). The SSH console requires a login and password of a user who has access to Jahia Tools through membership in the Tools system role. For information on Jahia Tools permissions, see Managing roles and permissions.

Karaf commands can also be executed from the tools: /modules/tools/karaf.jsp

UI configuration

Drag and drop strategy

It is possible to select a drag and drop strategy in the Page Composer mode between 4 options:

######################################################################
### DRAG AND DROP CUSTOMIZATION #############################################
######################################################################
# Defines drag and drop behavior in Edit mode. You can specify the following values:
# ENABLED: All entire content is draggable
# DRAG_ZONE_IN_EDIT_AREA: A drag zone displays at the top left of the module. Content can only be dragged in this zone
# DISABLED: All dragging and dropping is disabled
#jahia.ui.dragAndDrop = DRAG_ZONE_IN_EDIT_AREA

The “ENABLED” option is the default one, and is the strategy used in the previous Jahia versions.

Automatic refresh of the left panel

Consecutive publications can lead to a “constant” refresh of the left panel in the edit mode, which can make it unusable. It is possible to deactivate this automatic refresh by adding the property jahia.ui.refreshOnExternalModification in digital-factory-config/jahia/jahia.properties and by setting it to false. In such case, when a publication occurs, a notification in the bottom of the screen is displayed and the refresh icon of the left panel changes color. This setting is advised for environments with lots of publication.

By default jahia.ui.refreshOnExternalModification is set to true, so there is an automatic refresh after every publication.

Automatically mark new content as "Work in progress"

It is possible to automatically mark a content as "Work in progress" when it is being created by using the following property:

wip.checkbox.checked = true

The behavior depends if the site is available in one or several languages:

  • One language
    The Save as work in progress checkbox is automatically selected when creating the new content
  • Several languages
    The All content option is automatically selected when creating the new content

Hide "Unpublish" option when node is not published in current language

By default, if a node does not have a translation node (meaning it has never been translated) in a given language, then the "Unpublish" option is never displayed.
However, if a content item which contains non-internationalized properties has been published in one language, then this content node and its non-internatinalized properties are still live for all the languages. In such case, the default behavior is to show the "Unpublish" option in all the languages, even if the content item as never been published in that language. This default behavior can be changed, in order to hide the "Unpublish" option in that case, by setting the property useFullPublicationInfoInMainAreaModules to true.

jQuery version

Jahia allows you to choose the jQuery version to use between 1.12.4 and 3.3.1 . The version 3.3.1 is used by default on new installations. You can switch to the version 1.x in digital-factory-config/jahia/jahia.properties:

######################################################################
### JQUERY CONFIGURATION #############################################
######################################################################
# JQuery version
# The version number will be used when using jquery in a page. The system will look for jquery-[version].min.js.
# JQuery module provides 1.12.4 and 3.3.1 , but other versions can be added in a separate module.
#jahia.jquery.version = 3.3.1
# JQuery mapping plugins
# This parameter can be used to include one or more JS files everytime jquery is called in a page
# JQuery-migrate can be added here : jahia.jquery.plugins = jquery-migrate-3.0.1.min.js
#jahia.jquery.plugins =

Please note that the following modules require jQuery 1.x to work:

  • Jahia Private App Store
  • Jahia Wiki
  • Jahia Blog
  • Jahia Job Offer
  • Jahia Form Builder
  • Portal

Versioning

Versioning in Jahia is by default on jnt:file and jmix:editorialContent, this increases performances during site import and publication. If you want to version custom types, you can override existing Jahia property jahia.publication.versionedTypes in jahia.properties file and put your custom types. If you want to version everything as in Jahia lower versions, you can put mix:versionable. You can also drop all versioning by put empty value on the property, this increases much more the performances.