Enabling system maintenance and read-only modes

The system maintenance modes can be enabled/disabled by using the following URL:

http://{servername}{:port}{/context}/modules/tools/maintenance.jsp

Maintenance mode

When the maintenance mode is activated, the server blocks all the requests but the one to the modules/tools/maintenance.jsp tools area. This means that the webprojects are not accessible for editing or in live mode and administrative access is also blocked. Jobs/rules/events can still be triggered and operate modifications on the contents/DB/file system.

This only applies to the server/cluster node for which the maintenance mode is activated, therefore you might need to repeat the operations on all cluster nodes.

Please note that if you switch the maintenance mode flag, the changes are only valid during server runtime and are not persisted between server restarts.
If you would like to persist the flag value, set the maintenanceMode property to true in the jahia.properties file:

maintenanceMode = true

The maintenance mode can be turned on a Jahia server also by directly calling the following URL as a user who is a member of the System administrator system role. For information on Jahia Tools permissions, see Managing roles and permissions.

http://{servername}{:port}{/context}/modules/tools/maintenance.jsp?maintenance=true

And deactivated by using false as a parameter value.

Customizing allowed URLs when maintenance mode activated ?

While maintenance mode is activated, some URLs are still available by default. Those URLs are customizable in a dedicated OSGI bundle configuration file :

1. edit /var/jahia/karaf/etc/org.jahia.bundles.maintenanceFilter.yml
2. add/remove some URLs pattern (regular expression) according to your needs
3. wait for the modification to be effective (a log is displayed when it's done)
4. try to access URLs according to your modification when maintenance is active

Be aware that some ressources are needed for the "Maintenance" page to be correctly rendered (like css or images) or to access tools interface to manage maintenance mode status. Removing URLs could make the system unreachable !

By default, maintenance mode configuration looks like :

allowedResource:
  - ^/css/.*
  - ^/engines/images/.*
  - ^/icons/.*
  - ^/tools$|^/tools/.*
  - ^/modules/tools/.*
  - ^/cms/login

You can for exemple add a new regular expression like "^/modules/testme/*" at the end of the list to add an access to your module while maintenance mode is activated.

Read-only mode

When the read-only mode is activated, the server blocks the requests to the Page Composer, jContent, administration, and Studio. This means that the webprojects are still accessible in live, but not for editing and administrative access is blocked. Jobs/rules/events can still be triggered and operate modifications on the contents/DB/file system.
This only applies to the server/cluster node for which the read-only mode is activated, therefore you might need to repeat the operations on all cluster nodes.
The read-only mode is usually used in cluster environments to prevent the access to the edition interfaces on the browsing nodes.
Please note that if you switch the read-only mode flag, the changes are only valid during server runtime and are not persisted between server restarts.
If you would like to persist the flag value, set the maintenanceMode property to true in the jahia.properties file:

readOnlyMode= true

The read only mode can be turned on a Jahia server also by directly calling the following URL as a user who is a member of the System administrator system role. For information on Jahia Tools permissions, see Managing roles and permissions.

http://{servername}{:port}{/context}/modules/tools/maintenance.jsp?readOnlyMode=true

And deactivated by using false as a parameter value.

Full read-only mode

The full read-only mode is an extended version of the read-only mode, as the Page Composer, jContent, administration, and Studio are not accessible, as well as the user dashboards. Once the full read-only mode is activated, most of the writing operations are blocked, preventing everyone (including job, rules, events) to modify the jcr/database/filesystem. Please note that logs will still be written on the file system though. However, creation of user generated contents will fail, with no proper error message to the user. Please consult the techwiki to properly disable the creation of UGC when the full read-only mode is activated.

The full read-only mode is intended for hot backups of the environment, while the live versions of the webprojects are accessible to the visitors. Please consult our documentation regarding the backup and restoration of an environment.

Full read-only mode can be used both with a standalone instance or with a cluster. In a clustered environment, the full read-only mode should activated/deactivated from the processing node so that the change can be propagated to the other nodes (doing so from a browsing node will only apply the change to that node).

The full read-only mode can be activated either from the Tools UI or by calling the following URL as a user who is a member of the System administrator system role. For information on Jahia Tools permissions, see Managing roles and permissions.

http://{servername}{:port}{/context}/modules/tools/maintenance.jsp?fullReadOnlyMode=true

And deactivated by using false as a parameter value.

This can also be achieved from the Karaf console, by using the following OSGI command:

jahia:full-read-only [ON/OFF]

To consult the current status of full read-only mode (ie. whether it is enabled or disabled), one can use the Tools UI:

http://{servername}{:port}{/context}/modules/tools/maintenance.jsp

or the Karaf console, by executing the following OSGI command:

jahia:full-read-only

Cache and full read-only mode

A new cache key part generator was introduced which is able to extend the cache keys to store the read only mode info when it’s necessary. Now it is possible to create components, that will render different HTML results in case the server is in full read only mode.

Example of scenario to handle:

• user is viewing a page and is able to add comments using a commentable component
• administrator switches the server in full read only mode
• user reloads the page, the commentable component is able to detect that the server is in read only mode, it does not display the comment input field during the time the site is in full read-only mode.

Usage:

A new view property has been introduced:
cache.readOnly = true

You can use this view property with any component view, by creating a new properties file in the same folder of the view using the naming convention: name_of_the_view.properties

For example, there exist 2 views for a component commentable:

• commentable.jsp
• commentable.detailed.jsp

These two jsp views create different code in case the server is in read only mode or not.

So just create 2 properties files like this:

• commentable.jsp
• commentable.properties
• commentable.detailed.jsp
• commentable.detailed.properties

Each *.properties file contains this line: cache.readOnly = true

By doing this the full read only mode info, will be stored in the cache key of the component. There will be two different cache entries depending on the state of the full read-only mode.

Limitations and advice

• Already connected users will not be logged out, even if they were in editing content: the content creation or modification operations will fail
• An error message will be displayed when trying to access editing and administration interfaces when the full read-only mode is activated

Therefore, we advise you to notify all the potential contributors that server maintenance operations will be performed, blocking the access to the editing interfaces, as well as failing all the attempts to create or update contents (in the case of a contributor being already connected when the full read-only mode is turned on).

• The REST API is still capable of content queries
• Do not activate the full read-only mode when contribution is expected to happen, especially when “heavy” contribution operations are happening, such as site import, as it will result in an incomplete operation/import
• Do not perform module management operations (deploy, start, stop, update, install new versions of modules) when the full read-only mode is activated on at least a cluster node. Prefer the maintenance or read-only mode in such cases.
• Do not add a new node to the cluster when at least one node is in full read-only mode (as some module management operations can be automatically executed during the new node startup)
• In a remote publication environment, the authoring server in full read-only mode will not trigger scheduled remote publications. If a remote publication is sent to a remote server in full read-only mode, the execution of this remote publication will fail.
• When maintenance mode is enabled, access to tools is not possible, only "modules/tools/maintenance.jsp" will be accessible.

For switching to the full read-only mode we recommend:

• Switch to readonly mode when there is not much traffic on the cluster nodes
• Always switch all cluster nodes to full read-only mode - do not keep some nodes in full read-only and others not.
• Choose a timeslot where there are no (minimum) edits going on, since editors can lose their changes (and inform your editors about this)
• Choose a timeslot where there are no (minimum) scheduled jobs (like visibility conditions, publications, exports/imports, cleanup jobs etc.)