5. Configuration
To enable Tigase Message Archiving Component you need to add following block to etc/config.tdsl file:
message-archive () {
}
It will enable component and configure it under name message-archive. By default it will also use database configured as default data source to store data.
5.1. Custom Database
You can specify a custom database to be used for message archiving. To do this, define the archive-repo-uri property.
'message-archive' () {
'archive-repo-uri' = 'jdbc:mysql://localhost/messagearchivedb?user=test&password=test'
}
Here, messagearchivedb hosted on localhost is used.
5.2. XEP-0136 Support
To be able to use Message Archiving component with XEP-0136: Message Archiving protocol, you additionally need to enable message-archive-xep-0136 SessionManager processor:
sess-man {
message-archive-xep-0136 () {
}
}
This is required for some advanced options.
5.3. Support for MAM
If you want to use Message Archiving component with XEP-0313: Message Archive Management protocol, then you need to enable urn:xmpp:mam:1 SessionManager processor:
sess-man {
'urn:xmpp:mam:1' () {
}
}
5.4. Setting default value of archiving level for message on a server
Setting this property will change default archiving level for messages for every account on server for which per account default archiving level is not set. User will be able to change this value setting default modes as described in XEP-0136 section 2.4
Possible values are:
- false
Messages are not archived
- body
Only message body will be stored. Message without a body will not be stored with this value set
- message
While message stanza will be archived (if message should be stored, see Saving Options)
- stream
In this mode every stanza should be archived. (Not supported)
To set default level to message you need to set default-store-method of message-archive processor to message:
sess-man {
message-archive {
default-store-method = 'message'
}
}
5.5. Setting required value of archiving level for messages on a server
Setting this property will change required archiving level for messages for every account on server. User will be able to change this to any lower value by setting default modes as described in XEP-0136 section 2.4 but user will be allowed to set higher archiving level. If this property is set to higher value then default archiving level is set then this setting will be used as default archiving level setting.
Possible values for this setting are the same as values for default archiving level setting, see Setting default value of archiving level for message on a server for list of possible values.
To set required level to body you need to set required-store-method of message-archive processor to body:
sess-man {
message-archive {
required-store-method = 'body'
}
}
5.7. Configuration of automatic archiving of MUC messages
As mentioned above no additional configuration options than default configuration of Message Archiving component and plugin is needed to let user decide if he wants to enable or disable this feature (but it is disabled by default). In this case user to enable this feature needs to set settings of message archiving adding muc-save attribute to <default/> element of request with value set to true (or to false to disable this feature).
To configure state of this feature on installation level, it is required to set store-muc-messages property of message-archive SessionManager processor:
sess-man {
message-archive {
store-muc-messages = 'value'
}
}
where value may be one of following values:
userallows value to be set on domain level or by user if domain level setting allows that
trueenables feature for every user in every hosted domain (cannot be overridden by on domain or user level)
falsedisables feature for every user in every hosted domain (cannot be overridden by on domain or user level)
To configure state of this feature on domain level, you need to execute vhost configuration command. In list of fields to configure domain, field to set this will be available with following values:
userallows user to stat of this feature (if allowed on installation level)
trueenables feature for users of configured domain (user will not be able to disable)
falsedisables feature for users of configured domain (user will not be able to disable)
5.8. Purging Information from Message Archive
This feature allows for automatic removal of entries older than a configured number of days from the Message Archive. It is designed to clean up database and keep its size within reasonable boundaries. If it is set to 1 day and entry is older than 24 hours then it will be removed, i.e. entry from yesterday from 10:11 will be removed after 10:11 after next execution of purge.
There are 3 settings available for this feature: To enable the feature:
'message-archive' {
'remove-expired-messages' = true
}
This setting changes the initial delay after the server is started to begin removing old entries. In other words, MA purging will not take place until the specified time after the server starts. Default setting is PT1H, or one hour.
'remove-expired-messages-delay' = 'PT2H'
This setting sets how long MA purging will wait between passes to check for and remove old entries. Default setting is P1D which is once a day.
'remove-expired-messages-period' = 'PT2D'
You may use all settings at once if you wish.
NOTE that these commands are also compatible with unified-archive component, just replace message with unified.
5.8.1. Configuration of number of days in VHost
VHost holds a setting that determines how long a message needs to be in archive for it to be considered old and removed. This can be set independently per Vhost. This setting can be modified by either using the HTTP admin, or the update item execution in adhoc command.
This configuration is done by execution of Update item configuration adhoc command of vhost-man component, where you should select domain for which messages should be removed and then in field XEP-0136 - retention type select value Number of days and in field XEP-0136 - retention period (in days) enter number of days after which events should be removed from MA.
In adhoc select domain for which messages should be removed and then in field XEP-0136 - retention type select value Number of days and in field XEP-0136 - retention period (in days) enter number of days after which events should be removed from MA.
In HTTP UI select Other, then Update Item Configuration (Vhost-man), select the domain, and from there you can set XEP-0136 retention type, and set number of days at XEP-0136 retention period (in days).
5.9. Using separate store for archived messages
It is possible to use separate store for archived messages, to do so you need to configure new DataSource in dataSource section. Here we will use message-archive-store as a name of a data source. Additionally you need to pass name of newly configured data source to dataSourceName property of default repository of Message Archiving component.
Example:
dataSource {
message-archive-store () {
uri = 'jdbc:postgresql://server/message-archive-database'
}
}
message-archive {
repositoryPool {
default () {
dataSourceName = 'message-archive-store'
}
}
}
It is also possible to configure separate store for particular domain, i.e. example.com. Here we will configure data source with name example.com and use it to store data for archive:
dataSource {
'example.com' () {
uri = 'jdbc:postgresql://server/example-database'
}
}
message-archive {
repositoryPool {
'example.com' () {
# we may not set dataSourceName as it matches name of domain
}
}
}
Note
With this configuration messages for other domains than example.com will be stored in default data source.
5.10. Setting Pool Sizes
There are a high number of prepared statements which are used to process and archive messages as they go through the server, and you may experience an increase in resource use with the archive turned on. It is recommended to decrease the repository connection pool to help balance server load from this component using the Pool Size property:
'message-archive' (class: tigase.archive.MessageArchiveComponent) {
'archive-repo-uri' = 'jdbc:mysql://localhost/messagearchivedb?user=test&password=test'
'pool-size' = 15
}
5.11. Message Tagging Support
Tigase now is able to support querying message archives based on tags created for the query. Currently, Tigase can support the following tags to help search through message archives: - hashtag Words prefixed by a hash (#) are stored with a prefix and used as a tag, for example #Tigase - mention Words prefixed by an at (@) are stored with a prefix and used as a tag, for example @Tigase
NOTE: Tags must be written in messages from users, they do not act as wildcards. To search for #Tigase, a message must have #Tigase in the <body> element.
This feature allows users to query and retrieve messages or collections from the archive that only contain one or more tags.
5.11.1. Activating Tagging
To enable this feature, the following line must be in the config.tdsl file (or may be added with Admin or Web UI)
'message-archive' (class: tigase.archive.MessageArchiveComponent) {
'tags-support' = true
}
5.11.2. Usage
To execute a request, the tags must be individual children elements of the retrieve or list element like the following request:
<query xmlns="http://tigase.org/protocol/archive#query">
<tag>#People</tag>
<tag>@User1</tag>
</query>
You may also specify specific senders, and limit the time and date that you wish to search through to keep the resulting list smaller. That can be accomplished by adding more fields to the retrieve element such as 'with', 'from', and 'end' . Take a look at the below example:
<iq type="get" id="query2">
<retrieve xmlns='urn:xmpp:archive'
with='[email protected]'
from='2014-01-01T00:00:00Z'
end='2014-05-01T00:00:00Z'>
<query xmlns="http://tigase.org/protocol/archive#query">
<tag>#People</tag>
<tag>@User1</tag>
</query>
</retrieve>
</iq>
This stanza is requesting to retrieve messages tagged with @User1 and #people from chats with the user juliet@capulet.com between January 1st, 2014 at 00:00 to May 1st, 2014 at 00:00.
NOTE: All times are in Zulu or GMT on a 24h clock.
You can add as many tags as you wish, but each one is an AND statement; so the more tags you include, the smaller the results.