Configuration

Anonymous editing has been temporarily disabled. Please create an account in order to leave feedback or test wiki functionality.

Please contribute to the JAMWiki project by helping to improve this article. Add to or expand some of the existing information, fix an error, or share your own knowledge to improve this subject! Don't worry about making mistakes - there will always be someone who can correct any errors later.

JAMWiki configuration provides the ability to change system settings, handle spam, manually address server issues, and perform other needed tasks.

Look and Feel

Most site administrators will want to immediately change the look & feel of their wiki. There are four topics that directly affect the look and feel of the wiki, and each of these are by default editable only by the site administrator:

StyleSheet - The CSS style sheet. Modifying this stylesheet requires at least a minimal knowledge of Cascading Style Sheets.
LeftMenu - The left navigation menu.
BottomArea - The footer.
StartingPoints - The default front page for the wiki.

Other aspects of the site's look and feel, including the default logo, can be modified by an administrator using the Special:Admin tools.

Administrative Tools

Most JAMWiki configuration settings are available from the Special:Admin tools. Admin users can access these tools by clicking on the "Admin" link which appears at the top of the screen, or by visiting the Special:Admin topic. The following configuration settings are available:

General settings

Default topic: The name of the default topic for new virtual wikis. The default topic is the topic shown when the root page of the wiki (such as http://jamwiki.org/wiki/en/) is requested. By default this value is StartingPoints. Note that to change the default for an existing virtual wiki the Special:Maintenance page provides a list of existing virtual wikis and their default topics.
Logo image: The default wiki image that appears on the top of the left-navigation bar on all pages. The image name must be relative to the /images folder found in the root wiki install directory, and the file must exist in that directory. As an example, on http://jamwiki.org/ the logo image is specified as logo_oliver.gif< and the path to the image is http://jamwiki.org/wiki/images/logo_oliver.gif.
Image resize increment (pixels): When uploaded images are displayed on the wiki a maximum width/height value may be specified, such as [[Image:Example.jpg|300px]]. JAMWiki will specify the selected width/height value in the generated HTML image tag, but a resized copy of the original image will only be created if the specified width/height is more or less than the specified pixel increment. Decreasing this value will improve image display quality but it can have significant performance impact as image resizing is a resource-heavy process.
Default number of recent changes displayed: The number of results to display by default on Special:RecentChanges. Users have the option to display more or less changes using a drop-down. Increasing this value to a very large number can negatively affect performance.
Enable spam filter: By default JAMWiki will use a regular-expression based spam filter to block some edits - see the section on spam handling below for details. This checkbox provides an option to disable the spam filter.
Use Preview: It is helpful to editors to allow them to preview their changes before saving. This setting allows administrators to disable the preview option if desired.
Use WYSIWYG editor: JAMWiki offers WYSIWYG editing buttons to editors that makes utilizing wiki syntax easier. This setting allows those edit buttons to be hidden.
Open printable page links in new window: By default when the "Print" tab is chosen a print-friendly version of the topic opens in the same window. This option will open the print-friendly version in a new window.
Open external links in new window: By default when a link within a wiki topic is clicked that leads to an external site the link opens in the same window. This option will open the link in a new window.
HTML meta description: The HTML meta description is a description of a wiki page that can be used by search engines and other tools to describe a page. Variables that can be used in the meta description include: {0} page topic (may be empty)

Parser settings

Parser: JAMWiki supports the use of different Wiki syntax engines. The default parser implements the Mediawiki syntax.
Use table of contents: When a topic contains at least three headings then a table of contents will be displayed with the article unless this option is de-selected.
Maximum table of contents depth: Set this value from 1-6 to determine how much nesting is allowed within a topic's table of contents.
Allow HTML: By default HTML tags may be used in topics, but for wikis that need higher levels of control this option can be disabled.
Allow Javascript: Allowing Javascript opens up a wiki to cross-site scripting attacks and other potential issues, and Javascript is disabled by default. This option should only be enabled when wiki editors can be trusted not to create malicious content.
Allow Wiki templates: JAMWiki allows the use and creation of Mediawiki templates unless this option is disabled.
Pattern for user name in signatures: This option controls how user signatures (~~~~) will be displayed. Key: {0} = user page; {1} = user contributions page; {2} = user comments page; {3} = user login; {4} = user display name; {5} = user email; {6} = user id
Pattern for dates in signatures: This option controls how dates will be displayed. The pattern should follow the format used for the Java SimpleDateFormat.

Persistence settings

File-system directory: An existing directory in which JAMWiki system files can be stored. Information stored in this directory include the system cache, the search index files, and HSQL database files when JAMWiki is used without an external database.
Persistence: Selecting "Internal Database" will cause a version of the HSQL database to be installed and used by JAMWiki for data storage. "External Database" indicates that the system administrator will use a separate database that is not installed by JAMWiki.
JDBC driver class: When using an external database this value is set to the JDBC driver class. See your database documentation for information on what value to use.
Database type: When using an external database this value indicates the database type. If your specific database is not listed then selecting "ansi" will utilize an ANSI SQL compliance mode that should work with most databases.
Database URL or JNDI DataSource name: When using an external database this value indicates the JDBC URL. See your database documentation for information on what value to use. Alternatively this field may be used to specific a JNDI datasource for systems using JNDI database connections.
Database Username: When using an external database this value indicates the database user login. The user account must have permission to create and modify tables.
Database Password: When using an external database this value indicates the password for the database user login.
Max number of active connections: When using an external database this value specifies the maximum number of database connections that can be opened. For smaller wikis the default value should be sufficient.
Max number of idle connections: When using an external database this value specifies the maximum number of database connections that can be idle before being released. A negative value indicates an unlimited number of idle connections. For smaller wikis the default should be sufficient.
Test connections on borrow: When using an external database this value specifies whether or not to test a database connection when it is retrieved from the connection pool. If the connection fails validation it will be returned to the database and a new connection will be retrieved. Selecting this option may improve wiki reliability while disabling it may offer a very small performance improvement.
Test connections on return: When using an external database this value specifies whether or not to test a database connection when it is returned to the connection pool. Selecting this option may improve wiki reliability while disabling it may offer a very small performance improvement.
Test idle connections: When using an external database this value specifies whether or not to test a database connection when it has been unused for a length of time. Selecting this option may improve wiki reliability while disabling it may offer a very small performance improvement.
Min idle eviction time: When using an external database this value specifies the minimum amount of time (in seconds) a connection may sit in the connection pool before it is considered a candidate for idle connection eviction. If this value is negative then connections will never be evicted solely for being idle.
Time (in seconds) between eviction runs: When using an external database this value specifies the minimum amount of time a connection may sit in the connection pool before it is tested to ensure that it is still valid. If this value is negative then connections will never be evicted solely for being idle.
Number of tests per eviction run: When using an external database this value specifies the sets the max number of objects to examine during each run of the idle object evictor thread (if any). In general the default value should be a good selection for most setups.
Action to take when pool is exhausted: When using an external database this value indicates what the system should do when trying to retrieve a connection when the connection pool is exhausted. "Grow" indicates that a connection should be created, "Block" indicates that the system should wait for a connection to become available, and "Fail" indicates that an error should be thrown.

File upload settings

Maximum upload filesize (KB): The maximum allowed size for files uploaded to the wiki by users. If a file is uploaded that exceeds this size an error will be returned and no record will be created in the wiki. A value of -1 indicates that no maximum is set.
File upload directory: The directory in which to store uploaded files, and from which files will be downloaded.
Relative file upload root: Root path used in <img> and <a> tags; if the file upload directory is /docroot/wiki-files/, then the relative path is /wiki-files/.
Allowed file upload types

JAMWiki allows file uploads to be blocked using either a whitelist or a blacklist if desired. A whitelist will allow only uploads of file types that are listed on the whitelist, while a blacklist will allow uploads of any type except for those listed on the blacklist.

Upload blacklist: When using a blacklist, this list contains file extensions for file types that may NOT be uploaded to the wiki, separated by commas. Example: "jsp,bin,bat". The list is case-insensitive.
Upload whitelist: When using a whitelist, this list contains file extensions for file types that may be uploaded to the wiki, separated by commas. Example: "jpg,gif,txt". The list is case-insensitive.

User authentication settings

WARNING: LDAP support is experimental at this time. Please also note that some LDAP systems may need to support different login patterns than what is shipped by default with JAMWiki. This setting cannot be configured using Special:Admin, but it is possible to change it by modifying the /WEB-INF/class/jamwiki.properties file and either adding or editing the pattern-login-valid property to match the settings for your LDAP system (example: pattern-login-valid=([A-Za-z0-9_\\.]+)).

User information persistence: User information such as login and password can be retrieved either from the JAMWiki database or from an external LDAP system.
LDAP factory class: For setups that use LDAP this value specifies the LDAP factory driver class. See your LDAP documentation for details.
LDAP server URL: For setups that use LDAP this value specifies the LDAP connection URL. See your LDAP documentation for details.
LDAP context: For setups that use LDAP this value specifies the LDAP context to use when searching for users, such as "ou=people,dc=jamwiki,dc=org". See your LDAP documentation for details.
LDAP security authentication: For setups that use LDAP this value specifies the LDAP security authentication mechanism. This value will usually be "none", "simple", "strong" or "DIGEST-MD5". See your LDAP documentation for details.
LDAP login: For setups that use LDAP this value specifies a fully-qualified LDAP user login such as "cn=name,dc=jamwiki,dc=org", if such a value is needed. If no login is required the value may be left empty. See your LDAP documentation for details.
LDAP password: For setups that use LDAP this value specifies the password for the LDAP login. This value may be empty if no login is required. See your LDAP documentation for details.
LDAP "userid" field: For setups that use LDAP this value specifies the name of the LDAP field that holds user logins. See your LDAP documentation for details.
LDAP "first name" field: For setups that use LDAP this value specifies the name of the LDAP field that holds user first name. See your LDAP documentation for details.
LDAP "last name" field: For setups that use LDAP this value specifies the name of the LDAP field that holds user last name. See your LDAP documentation for details.
LDAP "email" field: For setups that use LDAP this value specifies the name of the LDAP field that holds user email. See your LDAP documentation for details.

Cache settings

Maximum number of cached elements: The maximum number of elements that can be cached in memory for all caches. A larger value improves performance but increases system memory usage. For most setups the default should be acceptable.
Maximum number of cached elements per cache: The maximum number of elements that can be cached in memory for any specific cache. A larger value improves performance but increases system memory usage. For most setups the default should be acceptable.
Maximum cache element age (in seconds): The maximum length of time that a value can be kept in the cache before being evicted.
Maximum cache element idle age (in seconds): The maximum length of time that a value can remain unaccessed in the cache before being evicted.

RSS settings

Provide RSS feed: This option enables an RSS feed for recent changes on the wiki.
RSS feed title: The title used for the RSS feed.

Hidden preferences

Due to the danger of entering invalid values several preferences cannot be modified through a GUI interface, but can be changed by advanced users directly by changing values in the /WEB-INF/classes/jamwiki.properties file. These properties include:

pattern-valid-login: This value controls what is a valid pattern for a user logins. Sites using LDAP may want to change this value to (for example) allow logins with periods in them. The value is a Java regular expression, meaning all regex characters must be double escaped; for example:pattern-login-valid=([A-Za-z0-9_\\.]+).
pattern-topic-name-invalid: This value controls what characters cannot be used in topic names. The value is a Java regular expression, meaning all regex characters must be double escaped; for example:pattern-topic-name-invalid=([\\n\\r\\\\<>\\[\\]?\#]+).
pattern-role-name-invalid: This value controls what characters can be used in wiki role names; for the most part sites should not need to change this value unless roles are being retrieved from an external system. The value is a Java regular expression, meaning all regex characters must be double escaped; for example:pattern-role-name-invalid=([A-Za-z0-9_\\.]+).

System Maintenance

The Special:Maintenance page provides additional options to site administrators for performing tasks such as manually clearing the cache, reloading spam patterns, etc. The options available on this page are:

Add Virtual Wiki: Create a new virtual wiki. Additional configuration (described above) must also be performed before the virtual wiki will be active.
Rebuild Search Index: The search engine index should be automatically kept up-to-date, but if a topic is manually changed in the database or a server problem occurs this button provides a way of parsing all topics on the wiki and rebuilding the search index.
Reload Recent Changes: The results on the Special:RecentChanges page are updated automatically, but this button provides a way of forcing those values to be reloaded in the case of a system problem or other issue.
Clear Cache: For performance reasons JAMWiki caches data on disk. The cache is updated automatically, but this button provides a way to force a reload in case of system problems.
Reload Spam Filter Patterns: The spam filter uses a list of regular expressions in the /WEB-INF/classes/spam-blacklist.txt file to block edits containing spam patterns. When that file is updated either the application server must be restarted or else this button should be clicked to activate any changes.
Reset User Password: This functionality allows wiki system administrators to reset a user's password by entering the login, new password, and a confirmation of the new password. The user's password will be immediately changed to the new value. This feature will be released with JAMWiki 0.6.6.
Export Internal Database to CSV: (Experimental) This option is only available for wikis that are setup to use the "internal database" setting, and provides a way to export the contents of that database to CSV files. The exported files will be available in the "database" directory found within the wiki's file-system directory (see Special:Admin for that setting). This feature will be released with JAMWiki 0.6.6.
Migrate Wiki to new Database: (Experimental) Wiki system administrators may choose to migrate all data in the wiki from one database to another. This command will create the required tables in the new database and then copy data from the old database to the new database, and will finally update the wiki setup to point to the new database. This feature will be released with JAMWiki 0.6.6.

User Permissions / Roles

Security within JAMWiki is primarily handled through the Special:Roles interface. The security code works by allowing specific users or groups the permission to perform certain tasks, while forbidding them from performing other tasks. For example, by default all logged-in users can upload files, but anonymous users cannot.

The two default JAMWiki groups are GROUP_ANONYMOUS and GROUP_REGISTERED_USER. Any user who is not logged in is automatically a member of GROUP_ANONYMOUS, while logged in users are automatically assigned to GROUP_REGISTERED_USER. Each of these groups can be assigned roles, which allow the members of the groups to perform wiki tasks. The default roles are:

ROLE_ADMIN: All users assigned ROLE_ADMIN will have permission to delete topics as well as to edit those topics that are marked admin-only (which can be done from the "Manage" tab for each topic).
ROLE_EDIT_EXISTING: This role provides the ability to edit existing wiki topics.
ROLE_EDIT_NEW: This role provides the ability to create new wiki topics.
ROLE_DELETE: This role is unused and will be removed in JAMWiki 0.6.1. To allow a user to delete topics they must be assigned ROLE_ADMIN.
ROLE_MOVE: Only those users with ROLE_MOVE will see the "Move" tab, which allows topics to be renamed.
ROLE_SYSADMIN: This role allows a user to access Special:Admin, Special:Roles, and Special:Maintenance.
ROLE_TRANSLATE: This role allows a user to access Special:Translation and update translation files.
ROLE_UPLOAD: In order to upload files to the wiki from Special:Upload a user must have this role.
ROLE_VIEW: ROLE_VIEW is the default role that is required for viewing any other wiki page not covered by the other roles. Without this role a user would be able to do little more than view the login screen.

In addition to group roles, individual users may also be assigned roles. This functionality is useful for roles such as ROLE_SYSADMIN; it is unlikely that a wiki would allow all logged-in users to modify system settings, so it makes sense to assign this role to only a handful of individual users. Note that when roles are assigned to individual users they will have both the roles assigned to them as an individual and those roles that are assigned to GROUP_REGISTERED_USER.

Translations

All labels in JAMWiki (such as page titles, button labels, etc) can be translated into different languages. Translations can be added to JAMWiki either by manually creating or updating an appropriate "ApplicationResources.properties" file in the /WEB-INF/classes directory of the JAMWiki installation, or more easily by using the Special:Translation tool (admin only). Note that when using the Special:Translation tool, the web application server must be restarted for new translation values to appear on the site. Individuals creating or updating translation files are encouraged to submit them back to the JAMWiki project so that they can be included in future releases - please leave a message on the Feedback page if you are interested in contributing translations.

Virtual Wikis

Virtual wikis provide the capability to have multiple wikis running on the same application server without creating new webapp instances. For example, if JAMWiki is running on http://jamwiki.org/wiki/ it will by default create a virtual wiki "en" that will be accessible as http://jamwiki.org/wiki/en/. The same web application instance could also run other virtual wikis, each with its own stylesheet, recent changes, etc.

The steps for creating a new virtual wiki are:

Access the Special:Maintenance page.
Scroll down to the "add virtual wiki" box, enter a name (one word, no spaces) and click add.
Shut down the web application server.

Edit the web application web.xml file. There will be a mapping of the form:

    <servlet-mapping>
        <servlet-name>jamwiki</servlet-name>
        <url-pattern>/en/*</url-pattern>
    </servlet-mapping>

Create a new servlet-mapping, replacing "en" in the above example with the name of the new virtual wiki.
Restart the web application server.
A new virtual wiki will now be available from URLs of the form http://server/context/virtual-wiki/.

Links can be made between virtual wikis by using the virtual wiki as a prefix in the link, for example [[:en:StartingPoints]].

Handling Spam

Spam is an unfortunate reality on the internet today, and the sad truth is that while new and more sophisticated methods of dealing with spam will always be created, as long as unscrupulous individuals want to produce spam the problem will never fully go away.

JAMWiki currently (as of version 0.5.x) deals with spam in four ways:

JAMWiki adds the rel="nofollow" attribute for all external links. Most wiki spam is an attempt to fool search engines into indexing spam sites, and this attribute is a way of indicating to a search engine that a link should not be followed.
JAMWiki implements a regular-expression based spam blacklist. Every edit to the wiki is compared against the blacklist, and if a matching pattern is found then the edit is blocked.
JAMWiki implements a whitelist/blacklist for uploaded files. Spammers and other malicious individuals will often try to attack a site by uploading scripts or spam-filled files, so the whitelist/blacklist allows site administrators to block certain file types from being uploaded.
JAMWiki offers limited capabilities to control user account creation and prevent anonymous users from making edits or uploading files. Since many wikis encourage all users, including anonymous users, to contribute this feature is often of limited use.

spam-blacklist.txt

By default the JAMWiki spam-blacklist.txt file includes many expressions that have been used by spammers, but most sites will need to update this file. To make changes, first add your expression to the file, which can be found in your wiki installation directory at /WEB-INF/classes/spam-blacklist.txt. Entries MUST be valid regular expressions, meaning that periods, dashes, etc. should be escaped with a forward-slash: spam\.somesite\.com. More advanced regular expressions such as buy[ _\-\.](item1|item2) can also be used.

Once the blacklist has been modified the file must be reloaded in JAMWiki by using the "Reload Spam Filter Patterns" button on the Special:Maintenance screen. This option will verify that the file contains valid regular expressions, and if no errors are found will prevent future edits containing blacklisted patterns.

Upload whitelist/blacklist

Spammers also attack sites by uploading objectionable content. In many cases the content is in the form of a script, an HTML file, or an image. To combat this sort of attack JAMWiki offers the ability to blacklist certain file upload types, or alternatively to create a whitelist of valid upload types.

Upload blacklist/whitelist settings can be modified from the Special:Admin page under the "File Upload Settings" section. First, determine whether a blacklist or whitelist should be used, and then add appropriate patterns. Note that a blacklist will ALLOW uploads of all file types EXCEPT for those found on the blacklist, while a whitelist will BLOCK uploads of all file types EXCEPT for those found on the whitelist.

Other configuration settings

Logging

JAMWiki uses the java.util.logging package for logging. The logging configuration property file can be found in the web application /WEB-INF/classes/ directory and is named logging.properties. By default JAMWiki logs are written to the web application server's temp directory and into a file named jamwiki.log.X, where "X" is a number from 0 to 5 (logs are automatically rotated). To change this location simply modify the org.jamwiki.pattern value. For example:

org.jamwiki.pattern=/var/log/jamwiki.log.%g

The Javadoc for the java.util.logging.FileHandler class has additional details about the log file configuration. Patterns that may be used when specifying the log file location include:

"/" the local pathname separator
"%t" the system temporary directory
"%h" the value of the "user.home" system property
"%g" the generation number to distinguish rotated logs
"%u" a unique number to resolve conflicts
"%%" translates to a single percent sign "%"

Inter-wiki Links

JAMWiki 0.3.5 introduced support for inter-wiki links, allowing special syntax to be used for linking to other sites.

The syntax for an inter-wiki link is: [[Wikitravel:Falkland Islands]]

Which produces the link: Wikitravel:Falkland Islands

Additional sites for inter-wiki links can be set up by editing the /WEB-INF/classes/interwiki.properties file and adding new patterns. For example, the current pattern for Wikitravel is:

Wikitravel=http://wikitravel.org/en/{0}

In this pattern, "Wikitravel" is the value to use in the inter-wiki link, and the pattern "http://wikitravel.org/en/{0}" links to English Wikitravel, with the "{0}" being replaced by the topic included in the inter-wiki link (for example, "Falkland Islands" in the above example).

Alternate parser for JAMWiki

The Wikipedia API from Java Wiki Engine with Wikipedia syntax support, written by Axel Kramer, can be used as an alternative parser for the http://www.jamwiki.org project. You can also test the parser with the Eclipse Wikipedia Editor plugin which uses this parser to render the wiki texts to html. As of JAMWiki 0.5.0 this parser is included in the JAMWiki distribution and can be installed by selecting it in the admin tool.

This parser allows syntax such as the following:

 {{hello world|Hello|World}} 

 [[Template:hello world]]

Now create the Template text by clicking on the Template:hello world link. and write for example:

This is the {{{1}}} {{{2}}} template