Difference between revisions of "Application configuration"

Latest revision as of 08:21, 29 April 2014

OpenKM configuration file

OpenKM.cfg file is the main OpenKM configuration file. You can find this file in your server in $TOMCAT_HOME/OpenKM.cfg. In older OpenKM releases based on JBoss, the configuration file is located at $JBOSS_HOME/OpenKM.cfg.

A full listing of available configuration options can be found when logged into OpenKM with an administrator role. You will only see the Administration tab if the logged in user has the ROLE_ADMIN (OpenKM 6.2) or AdminRole (OpenKM 5.1) role.

Each time you make a change to the OpenKM.cfg file, the application server must be restarted for the change to take effect.

Starting with OpenKM 5.1, these configuration properties are located in the database to ease their management. To change the configuration properties, go to Administration > Configuration.

Changing max file upload size

The default is 64MB. If you want to set the limit to 100MB:

max.file.size=100.

Since OpenKM relies on the InputStream.available() method which returns an Integer, and according to Java Primitive Data Types, you should not upload files bigger than 2GB.

Since OpenKM 5.1.10 you can disable file size checking by setting max.file.size to 0.

Since OpenKM 6.0 by default this option is set to 0, so file size check is disabled by default.

Since OpenKM Professional 6.2.21 you can use suffixes to express this amount of bytes. For example, 128MB or 512KB.

Changing repository.xml configuration filename and path

repository.config=repository.xml

Changing default repository home

OpenKM 6.2

By default, the OpenKM document repository is located at $TOMCAT_HOME/repository. To change the repository folder to another location, use the repository.home configuration property in the OpenKM.cfg file, e.g.

repository.home=C:/okmrepo

If you want to fine tune the contents of the document repository you can also use these configuration properties in the OpenKM.cfg file, e.g

hibernate.search.index.home=C:/okmrepo/index
repository.datastore.home=D:/okm/datastore
repository.cache.home=D:/okm/cache

OpenKM 5.1 and before

By default the repository is located in the $JBOSS_HOME/repository folder but you can change it with:

repository.home=repotest

Changing default user role

By default, the role required to connect to OpenKM is called ROLE_USER. You can change this to another role name. Go to Administration > Configuration and set:

default.user.role=ROLE_OTHER

Changing default admin role

By default, the admin connection role is called ROLE_ADMIN. Go to Administration > Configuration and set:

default.admin.role=ROLE_OTHER_ADMIN

You can change this to another role name. This change also needs some changes in the file located at $TOMCAT_HOME/webapps/OpenKM/WEB-INF/applicationContext.xml:

<security:intercept-url pattern="/admin/**" access="ROLE_ADMIN" />

Change max results in UI

This option limits the search results in the UI.

max.search.results=25

Since: OpenKM 4.0

Change access URL

By default OpenKM sets the access URL to http://localhost:8080/OpenKM/index.jsp, but obviously you don't want to access your OpenKM installation only from localhost. This URL is used in mail notifications and the copy-to-clipboard feature. To change this default URL use this property:

application.url=http://your-server.com/OpenKM/index.jsp

Since: OpenKM 4.0

Change principal adapter

OpenKM can handle user access using the Spring Security framework. OpenKM needs an available method for reading users and roles, so when users are stored in a database (as is the default), the class DatabasePrincipalAdapter does this job. If you configure OpenKM to authenticate against an LDAP server, you need to configure another principal adapter like LdapPrincipalAdapter. For more information take a look at OpenKM authentication and Active Directory.

principal.adapter=com.openkm.core.DatabasePrincipalAdapter

When using DatabasePrincipalAdapter you can create users and roles from OpenKM Administration. In this case you can use the principal.identifier.validation configuration property to defined a regular expression to validate user names and roles. By default is set to "^[a-zA-Z0-9_]+$" to prevent inclusion of potential problematic characters.

Since: OpenKM Professional 6.2.13

Switch OpenKM to demo mode

In demo mode some options are disabled by default.

system.demo=on

Since: OpenKM 4.0

Available only in OpenKM Professional.

Enabling OCR

To enable OCR you must set the path of your OCR engine

system.ocr=/usr/local/bin/tesseract

Starting with OpenKM 5.1 you can select between 3 OCR engines:

• Tesseract 2.x
• Tesseract 3.x
• Cuneiform 0.7.x

See Third-party software integration: OCR for more info.

Setting default language of OpenKM UI

OpenKM by default guesses the language depending on the browser user language configuration, but you can set a language for all OpenKM users to use by default:

default.lang=es-ES

Force username to lowercase

You can force all usernames to be written in lower case. It's useful for example when you integrate with microsoft active directory where the username is not case sensitive.

system.login.username.lowercase=on

Since: OpenKM 4.0

System read only

You can force the whole repository to be read only. This is useful when you're doing maintenance tasks, while doing migration and you want to continue to have the system running but you want to be sure any user will not be able to upload or change documents, etc...

system.readonly=true

Since: OpenKM 5.0

Enable document preview

Several applications are used by OpenKM to generate the document preview: OpenOffice.org, pdf2swf and convert. Read Enable PDF to SWF conversion, Enable image preview and Enable OpenOffice.org service. Also take a look at Random errors in preview in case of problems.

Enable PDF to SWF conversion

To enable the preview UI tab, OpenKM needs to convert PDF files to SWF. You must also have OpenOffice installed as a service.

system.pdf2swf=/usr/bin/pdf2swf

Starting from OpenKM 5.1 this configuration property has changed to system.swftools.pdf2swf.

Since OpenKM 5.1.9 the pdf2swf command line parameters should be added in the configuration property, for example: system.swftools.pdf2swf=/usr/bin/pdf2swf -T 9 -f ${fileIn} -o ${fileOut}

Note: Read Third-party software integration: SWFTools for more complete documentation.

Since: OpenKM 4.1

Enable PS to SWF conversion

To enable postscript document preview, OpenKM needs to convert PS files to SWF using the ps2pdf utility from Ghostscript:

system.ghostscript.ps2pdf=/usr/bin/ps2pdf

Since: OpenKM 5.1.2

Enable image preview

To enable image preview, you need to install the ImageMagick convert utility and configure it:

system.convert=/usr/bin/convert

Starting from OpenKM 5.1 this configuration property has changed to system.imagemagick.convert.

Since: OpenKM 4.1

Enable OpenOffice.org integration

OpenOffice.org is used by OpenKM to convert files to PDF and generate the preview.

system.openoffice=on

Starting with OpenKM 5.0 this property was changed to:

system.openoffice.path=/usr/lib/openoffice
system.openoffice.tasks=5
system.openoffice.port=2222

Where you should specify an OpenOffice.org installation path, the maximum number of conversion tasks before restarting the service and a port where the OpenOffice.org conversion service will be attached. Only the first property is mandatory.

If you have problems with OpenOffice / LibreOffice integration, take a look at OpenOffice configuration issues.

Note 1: Read Third-party software integration: OpenOffice.org for more up-to-date documentation.

Note 2: You can enhance OCR results by configuring an OpenOffice.org dictionary. See OpenKM 5.1 OCR configuration for more info.

Since: OpenKM 4.0

Configuring email

To configure email service, you must set subscription and notification properties. View a complete example in Notification and subscription messages.

subscription.message.subject=OpenKM - {0} - {1};
subscription.message.body=Document: <a href=\"{0}\">{1}</a>
notify.message.subject=OpenKM - NOTIFICATION - {0}
notify.message.body=Document: <a href=\"{0}\">{1}</a>

Since: OpenKM 4.1

Configuring password validation

To configure password validation, you have several properties. CompletePasswordValidator is the password validator class that comes by default with OpenKM. By default, this validator is not enabled. You can also create your own Create password validator .

You can select which validation rules you want to enable, for example if you only enable validator.password.min.length property, the validator will only validate minimum length.

validator.password=com.openkm.validator.password.CompletePasswordValidator
validator.password.min.length=numeric value greater than 0
validator.password.max.length=numeric value greater than 0
validator.password.min.lowercase=numeric value greater than 0
validator.password.min.uppercase=numeric value greater than 0
validator.password.min.digits=numeric value greater than 0
validator.password.mini.special=numeric value greater than 0

Since: OpenKM 4.1

Configuring the chat service

By default chat and chat autologin are enabled. In order to enable or disable them, values can be "on" or "off". You can change this from Administration > Profile.

Since: OpenKM 6.2

Configuring schedulers

There are some schedulers that OpenKM uses. Some internally, like mail importer and getting repository news, and others used by the user interface like dashboard refresh time and keepalive.

KeepAlive is used by the user interface to maintain the browser connected to OpenKM even when a user stays for some time without performing any operation. For this reason, it should never be lower than server session timeout ( by default set to 15 minutes ).

schedule.session.keepalive=15

Dashboard data is refreshed by default every 30 minutes.

schedule.dashboard.refresh=30

Since: OpenKM 4.1

Other repetitive actions like user mail importing are now managed from Crontab. So you can enable, disable or change the run frequency from Administration.

Since: OpenKM 6.2

Configuring wizard

You can configure a wizard to be used each time a user uploads a document. The wizard can be a sequence of property groups, keywords ( including thesaurus ) and categories. By default, wizard is disabled. You can enable wizard for properties, keywords an categories from Administration > Profile.

Since: OpenKM 6.2

Customizing application logo

You can replace the default OpenKM logo in the login page and reports.

logo.login
logo.mobile
logo.report
logo.tiny

Since OpenKM Professional 6.2.23 images are automatically resized to the recommend size.

Recommended image size:

• logo.login: 316px × 74px (background #F1F3F5)
• logo.mobile: 161px × 38px (background #F1F3F5)
• logo.report: 150px × 35px (background #FFF000)
• logo.tiny: 51px x 13px (background #E5E5E1)

You can also set a message on the login page with:

logo.text

Since: OpenKM 5.1 (configuration stored in database)

Available only in OpenKM Professional.

Configuring WebDAV access

In recent OpenKM releases, WebDAV is disabled by default. If you want to enable it, set the property system.webdav.server to on. The okm:root path may cause problems with some WebDAV clients. For this reason there is another configuration parameter system.webdav.fix which replaces a path like okm:root with okm_root. See WebDAV access for more info.

Since: OpenKM 5.1

Disable document name mismatch check

By default OpenKM will check the document name on check-in to ensure you upload another version of the same document. You can disable this behaviour with this configuration property:

system.document.name.mismatch.check=false

Since: OpenKM 5.0.1

Force keywords lowercase conversion

By default keywords are stored as is, but you can force a lowercase conversion using this configuration property:

system.keyword.lowercase

Since: OpenKM 5.1

Disable user assign on document creation

By default when a user creates a document or folder, he is added to the node with full permissions. You can disable this behaviour this way:

user.assign.document.creation=off

Since: OpenKM 5.0.2

Improve OpenKM performance

If you experience a slow down of OpenKM when the number of documents grows, you can disable user quotas or make use of the user items size cache.

To enable user items size cache:

user.item.cache=on

Starting from 5.1 user.item.cache is set to on by default.

Starting from OpenKM 5.1.6, you can disable user quotas. Go to User Profiles (Administration -> Profiles) and set Quota limit to 0 (This field is in megabytes).

Since: OpenKM 5.0.3

Change conversion cache home

In case you have little space in your application server partition, you can configure to store the conversion cache folder somewhere else. For this, use the repository.cache.home configuration property. By default, this is set to $TOMCAT_HOME/repository/cache.

Since: OpenKM 5.1.8

Re-indexing the whole repository

To re-index the whole document repository (document content will be extracted again and indexed by Lucene), follow these steps, depending on your OpenKM version:

OpenKM 6.2

• Log in as administrator.
• Go to Administration > Utilities > Rebuild indexes.
• Select the Lucene indexes option and click on Send.
• A progress indicator will be shown and the repository will be put in read-only mode until re-indexing is completed.

OpenKM can use two different ways of rebuilding Lucene indexes: sequential or parallel. By default sequential re-indexing is enabled, but you can select the mode using the hibernate.indexer.mass.indexer configuration property.

In sequential mode or you can use the hibernate.indexer.batch.size.load.objects configuration property to indicate to Hibernate how many object should handle every time. To avoid OutOfMemory problems, the repository needs to be re-indexed in batch. If the value of this property is too low, the performance will be bad but if is too high you can have OutOfMemory problems.

In parallel mode you have several configuration properties to tune its performance:

• hibernate.indexer.batch.size.load.objects: batch size used to load the root entities. Defaults to 30.
• hibernate.indexer.threads.subsequent.fetching: number of threads used to load the lazy collections related to the indexed entities. Defaults to 8.
• hibernate.indexer.threads.load.objects: number of threads used to load the root entities. Defaults to 4.
• hibernate.indexer.threads.index.writer: number of threads used to analyze the documents and write to the index. Defaults to 3.

Available only in OpenKM Professional.

OpenKM 5.1

Keep in mind that the next time you start JBoss, a process which runs the text extraction for every document in the repository will be launched and you can't use OpenKM until this process is finished.

• Stop JBoss.
• Delete the $JBOSS_HOME/repository/repository/index and $JBOSS_HOME/repository/workspaces/default/index directories.
• Start JBoss again.

Security configuration

Starting with OpenKM 6.0 you can make use of these configuration properties:

• security.access.manager: You can switch between "simple" and "recursive". This is the way the security is evaluated. With "recursive", the security is evaluated starting with the selected node until the repository root. The "simple" option only evaluates the selected node. By default, this is set to "simple".

• security.search.evaluation: Here you can choose between several search result security evaluation strategies. The fastest one is called "lucene", because it is the Lucene search engine which restricts the search results based on the node security. The others are "am_more", "am_window" and "am_limited", which make use of the AccessManager (see previous property) to restrict the search results. By default, this is set to "lucene".

By default OpenKM 6 is configured this way:

 security.access.manager = simple
 security.search.evaluation = lucene

Which provides great performance by only evaluating a single node. But if you want to evaluate every parent you can change this behavior with these settings:

 security.access.manager = recursive
 security.search.evaluation = [ am_more | am_window | am_limited ]

This will reduce OpenKM performance (at least in search) but will match customer requirements. Performance can be improved customizing com.openkm.cache.parentNodePermissions cache region definition.

Also provided is a new AccessManager: read_recursive used to prevent showing documents in search results when any folder in the path doesn't have read access for the user who ran the query. Should be used in combination with am_more.

 security.access.manager = read_recursive
 security.search.evaluation = am_more

Difference between "simple" and "recursive"

Given this repository structure:

• okm:root
  • level-1a
    • level-2a
      • level-3a
        • alpha.doc
        • beta.doc
        • gamma.doc
      • level-3b
  • level-1b
  • level-1c

When using simple if you revoke permission from the level-2a folder and the user tries to view the level-3a folder, OpenKM will still show the documents to this user. When the user performs a search, OpenKM will return these documents as search results. However, the user can't access the documents because when OpenKM tries to access the document, it will open every path location and will fail to open level-2a because the user has no rights. You need to apply revoke recursively to prevent the user from seeing these documents, so they won't be shown in the search results.

When using recursive if you revoke permission from the level-2a folder and the user tries to view the level-3a folder, OpenKM will report an error because Access Manager also evaluates the permission of the level-2a ancestor node. When the user performs a search, OpenKM won't show these documents in the search results. Keep in mind that this Access Manager implementation is slower because it needs to evaluate more nodes: the more node depth the more parent nodes need to be0 evaluated.

Since: OpenKM 6.2

Extended security

Starting with OpenKM 6.0 you can extend security to download files, start workflows, add, remove or modify property groups ( metadata ) or compact history.

The possible values are:

• DOWNLOAD = 1024;
• START_WORKFLOW = 2048;
• COMPACT_HISTORY = 4096;
• PROPERTY_GROUP = 8192;

• security.extended.mask: Here you can activate which kind of extended security you want in your OpenKM. For example to enable download and property groups you should put the mask 9216 ( 1024+8192 )

Since: OpenKM 6.0.1

Available only in OpenKM Professional.

Managing security

By default when you change the security of a node (document or folder) in OpenKM, every time you click to grant or revoke a permission, the action is performed by OpenKM. This means that if you want to change the security of 10 users, 10 commands are sent to the server to be performed. The case is worse when every change affects several hundred (or even thousands) of nodes.

In OpenKM Professional 6.2.9 you can configure an alternative security mode where the changes are only applied at the end, so it is faster. To enable this new mode you need to use the security.mode.multiple configuration property. Also, we have included an improvement in OpenKM Professional which can send these security changes as a background task if this takes too long to complete. You can fine tune this behaviour using the security.live.change.node.limit configuration property.

Since OpenKM Professional 6.2.11 you can check the progress of these pending task from Administration > Statistics > Pending tasks queue.

Since: OpenKM Professional 6.2.9 and 6.2.3 Community

AutoCAD previewer

If you have problems with AutoCAD previewer text, you should configure some URL to indicate an extra fonts repository used in AutoCAD files. Simply copy the files to some URL that can be resolved by desktop users and take into consideration that font file names should be in lower case ( rename if you have uppercase font file names). You can also enable AutoCAD previewer debug mode.

dxf.applet.debug.window=false
dxf.applet.default.bigfont=arial
dxf.applet.default.font=arial
dxf.applet.fontdir=http://fonts.openkm.com

Since: OpenKM 6.0

Available only in OpenKM Professional.

Minimum search characters

You can set the minimum characters required to execute a search. If less characters are available the search button will not be enabled. By default the minimum search characters is set to 3.

min.search.characters = 3

Since: OpenKM 6.0.0

Execution timeout

The maximum permitted time to execute a command like OCR, Antivirus, etc. After this time the child process is killed. Time given in minutes.

system.execution.timeout=5

Since: OpenKM 6.0.1

Restrict by file name

You can avoid uploading of documents by name or extension. For example, don't permit upload of AVI multimedia videos.

restrict.file.name=*.avi

You can also configure several filename rules:

restrict.file.name=*~;*.bak;*.avi

Since: OpenKM 6.2

Managed text extraction

In previous OpenKM releases, the text extraction was a transparent process where you can't do anything with the configuration. Since OpenKM 6.0 you have several configuration options to adapt the document text extraction to your needs. Let's see these parameters:

• managed.text.extraction.batch: Integer. How many documents are processed every time the text extractor worker is awoken.
• managed.text.extraction.pool.size: Integer. How many threads are launched concurrently every time. This number should be smaller or equal to the number of CPUs in the server.
• managed.text.extraction.pool.threads: Integer. How many threads will be executed in every time. If managed.text.extraction.pool.size is 8 and managed.text.extraction.pool.threads is set to 16 then all these 16 threads will be launched using this pool. If every task take the same time to complete, in theory every pool thread will execute two tasks. Of course this is not true in the real world.
• managed.text.extraction.pool.timeout: Minutes. How many minutes should the worker wait for the text extraction pool to complete the tasks. After these minutes, the remaining pool threads are interrupted.
• managed.text.extraction.schedule: Minutes. How often the text extractor worker is awoken.
• managed.text.extraction.concurrent: Boolean. If the concurrent text extraction should be enabled. By default the text extraction is serial, but you can improve the extraction performance if you have several CPUs.

Since: OpenKM 6.0.1

Available only in OpenKM Professional.

Document version numeration

Since OpenKM 6.2 we support different numeration schemas. By default OpenKM uses com.openkm.vernum.MajorMinorVersionNumerationAdapter which is similar to Jackrabbit implementation. But also have some other already implemented:

You can change the default Numeration Adapter using the version.numeration.adapter configuration property. You need to restart OpenKM every time you change this property. Also note that if already there are documents in the repository, changing the Numeration Adapter may cause problems because they are not compatible between them.

Some Numeration Adapters like PlainVersionNumerationAdapter may have additional configuration parameters like version.numeration.format which is used to define the numeration number format. By default this is "%d" but you can change to "%02d" to create versions like "01", "02", etc.

If you change the version numeration adapter you also need to update the existing numerations:

update NodeDocumentVersion ndv set ndv.name = '01' where ndv.name='1.0';
update NodeDocumentVersion ndv set ndv.name = '02' where ndv.name='1.1';
update NodeDocumentVersion ndv set ndv.name = '03' where ndv.name='1.2';
...

Since: OpenKM 6.2

Session keep alive

Some administration tasks take a long time, like repository checker and rebuild Lucene indexes. This implies that hte user session may be lost. For this reason these kinds of operations are forced to maintain the session alive. You can configure the keep alive interval using the configuration property keep.session.alive.interval. By default is set to 5 minutes.

Since: OpenKM Professional 6.2.9

Activity log actions

The table where activity log is stored may grow quickly. OpenKM can log a lot of information related to the activity of the uses, but sometimes these actions don't need to be logged and fill your activity log table. For this reason there is a configuration property called activity.log.actions where you can define which actions to log. By default this is set to the most common or interesting actions. You can use regular expressions to define these actions. Read Java Regex Tutorial for more info about Java regular expressions.

Since: OpenKM Professional 6.2.10

Safe trash purge

When you delete a document or folder from OpenKM, it goes to user trash. If the user empties the trash, the documents are permanently lost. But now you can configure a place where the documents will go after being purged from trash. You you can configure a directory in the server filesystem where an export of the trash be placed, using the repository.purgatory.home configuration property.

Since: OpenKM Professional 6.2.10

Tomcat Connector encoding

Default Tomcat Connector encoding is set to "ISO-8859-1" but you can change it with the property:

 URIEncoding="UTF-8"

OpenKM should have the same encoding for proper input. So, you have the tomcat.connector.uri.encoding configuration property. By default this is set to "ISO-8859-1", but if you set the "URIEncoding" parameter in Tomcat to "UTF-8", you also need to set this OpenKM configuration propterty to "UTF-8".

Since: OpenKM Professional 6.2.12

Password expiration

Force users to change password each period of time. The property user.password.expiration is used to indicate the number of days to force user change their password, the 0 value indicates the feature is disabled.

Since: OpenKM Professional 6.4.9

Web page import

Import a web page into OpenKM in PDF format. The property system.html2pdf is used to define the path to the wkhtmltopdf executable, needed to make a proper conversion to PDF. You can download this external utility from http://wkhtmltopdf.org/. After the conversion process, the resulting PDF will be imported into OpenKM. This parameter should be configured as follow:

 /path/to/wkhtmltopdf ${urlIn} ${fileOut}

Sometimes we have detected better results using http://cutycapt.sourceforge.net/, which seems more configurable. This utility requires an X server, so if you are running from a non-graphical environment you may need to install a virtual X server like xvfb:

 /usr/bin/xvfb-run /usr/bin/cutycapt --url=${urlIn} --out=${fileOut}

Since: OpenKM Professional 6.4.10