ars.cfg

ars.cfg is the main IBM CMOD configuration file. The default OnDemand configuration file doesn't contain all of the parameters that are recognized by the server - those parameters are listed at the end of this article. This configuration file is from IBM Content Manager OnDemand 10.1 for Linux.

ars.cfg Header, License, & Language CMOD Configuration

Sample Content Manager OnDemand Configuration File

# # ars.cfg - OnDemand Configuration File # # 5622-662 (C) COPYRIGHT IBM CORPORATION 2001 # All Rights Reserved # Licensed Materials - Property of IBM # # US Government Users Restricted Rights - Use, duplication or # disclosure restricted by GSA ADP Schedule Contract with IBM Corp. # # This program sample is provided on an as-is basis. # The licensee of the OnDemand product is free to copy, revise, # modify, and make derivative works of this program sample # as they see fit. # # File Format: # 1) Comments must begin with a # in the first column # 2) Comments cannot exist on the same line as a PARM # 3) PARM=VALUE, no spaces before PARM, no spaces after VALUE, # and no spaces before/after the equal sign. # 4) Blank lines are ignored. # # NOTE: Please see documentation for configuring these parameters. # ####################### # OnDemand Parameters # ####################### # # Number of client licenses (Library Server Only) # # - This should be set to however many licenses are purchased # ARS_NUM_LICENSE=1 # # Language used to create the database (Library Server Only) # - This should be set during installation and should never be changed # ARS_LANGUAGE=ENU

ARS_NUM_LICENSE

This parameter determines the number of permitted end-user licenses that CMOD is configured to allow. When the server exceeds this number, the non-compliant use is permitted, but messages are logged into the OnDemand System Log to notify the administrator. Contact your software procurement team to determine the number of licenses your organization is entitled to.

ARS_LANGUAGE

This is the three-alpha ISO code for the language you would like CMOD to use for messages and output.

Also: Unlisted CMOD Server Options.

CMOD Object Server Configuration

This block is largely deprecated. Maintaining separate CMOD object and library servers is uncommon now that limitations on the amount of storage any one server can access has been eliminated by technologies like NFS, SAN, and Cloud-based storage.

Sample Content Manager OnDemand Object Server Configuration

# # Object Server/Library Server definitions (Object Server Only) # # If Object Server then set # # ARS_SRVR=<server> # <server> is name of the OnDemand Library Server # # ARS_LOCAL_SRVR=<server> # <server> is name of the local OnDemand Object Server # # For Example: # # Server Type (hostname) # |----------------------| # | ObjServer (ObjSrv1)| # |----------------------| # # |----------------------| # | LibServer (LibSrvr)| # |----------------------| # # |----------------------| # | ObjServer (ObjSrv2)| # |----------------------| # # LibSrvr: # Neither Variable should be set # # ObjSrv1: # ARS_SRVR=LibSrvr # ARS_LOCAL_SRVR=ObjSrv1 # # ObjSrv2: # ARS_SRVR=LibSrvr # ARS_LOCAL_SRVR=ObjSrv2 # # NOTES: # - These names should be exactly what is specified for the server # in the storage node # - If CICS client is being used you must specifiy the machines # internet address instead of hostname or alias. # # ARS_SRVR= ARS_LOCAL_SRVR=

ARS_SRVR

The hostname of the CMOD Library Server. This name should be a fully qualified domain name for reliability. (Library.cmod.example.com)

ARS_LOCAL_SRVR

The hostname of the CMOD Object Server. This name should be a fully qualified domain name for reliability. (Object1.cmod.example.com, Object2.cmod.example.com)

CMOD Database Configuration

Sample Content Manager OnDemand Database Configuration

# # Number of Database SubServers (Library Server Only) # 0 - Defaults to connection per client # Otherwise - The number of Database SubServers to handle connections # to the database (minimum of 2) # ARS_NUM_DBSRVR=4 # # Database for OnDemand to use (Library Server Only) # ARS_DB_ENGINE=DB2 # # Used for arstblsp command and reloading migrated tables (Library Server Only) # 0 (import) # 1 (load w/TSM - DB2 only) # 2 (load w/DISK - DB2 only, using ARS_TMP) # ARS_DB_IMPORT=0 # # Used to specify if the database supports partitioning (Library Server Only) # Blank (No partition support) # ARS_DB_PARTITION= ######################################## # DB2 Parameters (Library Server Only) # ######################################## DB2INSTANCE=archive

ARS_NUM_DBSRVR

The ARS_NUM_DBSRVR parameter specifies the number of 'subservers' or database connections to create to the database. In larger systems, increasing this number may have performance benefits, at the expense of using additional RAM.

Increasing ARS_NUM_DBSRVR number too high may result in poor performance if not enough RAM is available.

Setting ARS_NUM_DBSRVR to 0 (zero) on large systems may cause performance issues during spikes in activity, as each new connection to CMOD creates a new Subserver, which may consume all available RAM.

ARS_DB_ENGINE

Specifies the database engine to be used. This parameter must be one of the following values: DB2, ORACLE, or MSSQL.

ARS_DB_IMPORT

In the early days of CMOD, when storage space was prohibitively expensive, OnDemand had the ability to 'archive' infrequently used database tables in the same way that it archived data to TSM. As storage prices have fallen and data compression in database engines has become common, this method of reducing the use of disk space has become essentially obsolete. v9.5

ARS_DB_PARTITION

If your database engine supports partitioning, change this parameter to 1 on the library server. Application Groups which should support partitioning must have a field defined to hold the partition data.

This configuration parameter is only intended for the very largest of CMOD servers holding hundreds of billions of documents, and serving tens of thousands concurrent users. v9.5

DB2INSTANCE

Specifies the name of the database to use for storing document metadata.

CMOD Database Creation

Sample Content Manager OnDemand Database Creation Parameters
# # These parameters used only during database creation # ARS_DB2_DATABASE_PATH=/arsdb ARS_DB2_PRIMARY_LOGPATH=/arsdb_primarylog ARS_DB2_ARCHIVE_LOGPATH=/arsdb_archivelog ARS_DB2_LOGFILE_SIZE=1000 ARS_DB2_LOG_NUMBER=40

These parameters should be defined before issuing the arsdb command with the -c, -r, or -t options.

ARS_DB2_DATABASE_PATH

This parameter describes where the main database should be created. Additional storage can be defined in the ars.dbfs configuration file.

ARS_DB2_PRIMARY_LOGPATH

This is where the databases transaction logs will be stored while CMOD is in operation.

The filesystems specified for storing database transaction logs should be the fastest and most reliable storage your organization has to offer.

ARS_DB2_ARCHIVE_LOGPATH

This is the filesystem where transaction logs will be 'archived' to create space for new transaction logs.

The size of this filesystem will be largely determined by how much logging and loading is done with CMOD.

ARS_DB2_LOGFILE_SIZE

The size of an individual database transaction log file. The size is this parameter (default of 1000) is multiplied by your database's page size (default of 4 kilobytes).

It's is strongly suggested to tune the size of this file to be up to 250MB in size for CMOD servers to reduce overhead in managing transaction logs.

ARS_DB2_LOG_NUMBER

This parameter specifies the number of transaction log files to keep.

The number of logs multiplied by the log file size parameter above determines how large your primary log filesystem should be, and how large your archive filesystem should be.

Sample Content Manager OnDemand DB2 TSM Configuration Parameters
# # DB2/TSM Parameters # ARS_DB2_TSM_CONFIG=/opt/tivoli/tsm/client/api/bin/dsm.opt.db2

ARS_DB2_TSM_CONFIG

This is the configuration file for Tivoli Storage Manager used by DB2 for transaction log archiving and automatic backup & restores.

Sample Content Manager OnDemand Oracle Configuration Parameters
########################################### # ORACLE Parameters (Library Server Only) # ########################################### ARS_ORACLE_HOME=/oracle

ARS_ORACLE_HOME

Points CMOD to the directory where oracle is installed.

CMOD Miscellaneous Configuration

Sample Content Manager OnDemand Miscellaneous Configuration Parameters
# # OnDemand Temporary Work Directory (Library/Object Server) # # NOTE: This directory should have permissions just like /tmp # drwxrwxrwt /tmp These perms are 1777 # ARS_TMP=/tmp ARS_PRINT_PATH=/tmp ARS_MESSAGE_OF_THE_DAY= ARS_TRACE_SETTINGS=

ARS_TMP

This specifies the temporary directory where Content Manager OnDemand should place its temporary files during processing.

ARS_PRINT_PATH

This specifies the temporary directory used for creating temporary files for printing.

ARS_MESSAGE_OF_THE_DAY

Specifies a text file that will be displayed when users log in. Excellent for advising all users of upcoming outages or maintenance, or problems experienced by the CMOD server.

ARS_TRACE_SETTINGS

When tracing is enabled, these settings determine the level of information written to the trace file.

Special Considerations for IBM CMOD temporary files

Some of the files that OnDemand stores are extremely large. It's a good idea to set aside a separate 'temporary' filesystem with it's own storage that is NOT shared with the operating system, database, or other data. Using the operating system's default temporary directory can cause problems on the server if the filesystem becomes full. You may experience problems like being unable to log in, being unable to list directory contents, or run basic commands that create temporary files.

CMOD LDAP Configuration

Sample Content Manager OnDemand LDAP Configuration Parameters

########################################### # LDAP Parameters (Library Server Only) # ########################################### ARS_LDAP_SERVER=server1.ldap.example.com ARS_LDAP_PORT= ARS_LDAP_USE_SSL=FALSE ARS_LDAP_BASE_DN=ou=examplegroup,o=example.com ARS_LDAP_BIND_ATTRIBUTE=userid ARS_LDAP_MAPPED_ATTRIBUTE=userid ARS_LDAP_ALLOW_ANONYMOUS=TRUE ARS_LDAP_BIND_MESSAGES_FILE=/var/log/IBM_CMOD_LDAP_messages.log ARS_LDAP_IGN_USERIDS=ADMIN,ARSLOAD,ARSMAINT ARS_LDAP_BIND_MESSAGES_FILE=/opt/IBM/ondemand/V9.5/config/arsldap.ini

ARS_LDAP_SERVER

The fully qualified domain name for your organization's LDAP server.

ARS_LDAP_PORT

The TCP/IP port number used by your LDAP server's software.

The default port is 389 if no value is specified.

A popular alternate port number is 3389.

ARS_LDAP_BASE_DN

The LDAP Base Distinguishing Name.

ARS_LDAP_BIND_DN

If your LDAP server requires a User ID and password to authenticate, this is the user name parameter.

ARS_LDAP_BIND_DN_PWD

If your LDAP server requires a User ID and password to authenticate, this is the password parameter.

ARS_LDAP_BIND_ATTRIBUTE

The name of the attribute that will be searched for on the LDAP server, and returned to CMOD.

ARS_LDAP_MAPPED_ATTRIBUTE

This value can be the same as, or different from the ARS_LDAP_MAPPED_ATTRIBUTE.

Specify the LDAP field that should be returned and used as the CMOD User ID.

ARS_LDAP_ALLOW_ANONYMOUS

Set to TRUE if your LDAP server allows access without authentication.

Set to FALSE if your LDAP server requires a Distinguishing Name ("ARS_LDAP_BIND_DN") and password ("ARS_LDAP_BIND_DN_PWD").

Also: Unlisted CMOD LDAP Options.

CMOD Storage Management Configuration

Sample Content Manager OnDemand TSM Configuration Parameters

###################################################### # Storage Manager Parameters (Library/Object Server) # ###################################################### # # Storage Manager for OnDemand to use # ARS_STORAGE_MANAGER=TSM ####################################### # TSM Parameters (Object Server Only) # ####################################### DSMSERV_DIR=/opt/tivoli/tsm/server/bin DSMSERV_CONFIG=/opt/tivoli/tsm/server/bin/dsmserv.opt DSM_DIR=/opt/tivoli/tsm/client/api/bin64 DSM_CONFIG=/opt/tivoli/tsm/client/api/bin64/dsm.opt DSM_LOG=/tmp DSMG_DIR=/opt/tivoli/tsm/client/api/bin64 DSMG_CONFIG=/opt/tivoli/tsm/client/api/bin64/dsm.opt DSMG_LOG=/tmp DSMI_DIR=/opt/tivoli/tsm/client/api/bin64 DSMI_CONFIG=/opt/tivoli/tsm/client/api/bin64/dsm.opt DSMI_LOG=/tmp

The majority of these configuration parameters are only of interest if you are using the ars_adsm script. Only the DSM_CONFIG and DSMI_CONFIG parameters are required if your TSM server is on another separate server.

DSMSERV_DIR

The directory where Tivoli Storage Manager (now Spectrum Protect) is installed.

DSMSERV_CONFIG

The configuration file for the TSM server.

If your TSM/SP server is remote, these files aren't used.

DSM_DIR / DSMG_DIR / DSMI_DIR

The directory where the 64-bit TSM/SP Client API is installed.

DSM_CONFIG / DSMG_CONFIG / DSMI_CONFIG

Points to the file containing the TSM Configuration file.

DSM_LOG / DSMG_LOG / DSMI_LOG

Points to the directory where the TSM Client files should be written.

Special Considerations for TSM Log files

The configuration parameters above that end in _LOG are log files. By default, the logs all go to /tmp, which is, frankly, a terrible idea. Instead, these log files should all go to a directory specifically for IBM CMOD Logs. This will prevent errors arising from conflicting permissions, or filling up the server's temporary space. Also, these logs should be rotated on a regular basis. If you feel the need to place these log files in a 'standardized' space, place them in /var/log, but also create the files in advance, and provide them with generous permissions, to minimize frustration and errors.

Unlisted Parameters

These parameters aren't listed in the CMOD Configuration File by default.

IBM CMOD Server Parameters

ARS_ORIGINAL_CODEPAGE

When upgrading a server from v7.1.x to v8.5 and above, you must specify the original codepage of the database for Unicode support.

Set this value to the numeric codepage value of the database. This allows OnDemand to translate the contents of the database to Unicode.

Where possible, servers should be migrated to support Unicode in their databases.

ARS_DB_TABLESPACE

Set this value to an already-existing tablespace name to keep the OnDemand configuration database tables in.

ARS_DB_TABLESPACE_USEREXIT

Specify the full directory path to the User Exit that is called when creating CMOD tablespaces.

The tablespace user exit allows you to customize the creation of tablespaces, tables, and indexes for CMOD metadata tables.

ARS_SUPPORT_CFSOD

Set this parameter to 1 if you are licensed to use the Content Federation System for OnDemand ("CFS:OD") feature.

ARS_SUPPORT_HOLD

Set this parameter to 1 if you are licensed to use the Content Manager OnDemand Enhanced Retention Management ("IBM CMOD ERM") feature.

ARS_USE_OLD_STYLE_CASE

Use the old (pre-v8.5) method for converting the case of characters not in the current codepage. IBM PM82660 & IBM Technote & ODNews Q1 2014

ARS_USER_EXITS_DIR

Custom user exits need to live in a directory separate from those provided by IBM. Specify the directory with this parameter.

Consider locating your exits in the CMOD instance owners' home directory, with the following structure: /home/archive/exits/ or /home/odadmin/exits

See a post on this topic on the IBM CMOD User Group Forums.

ODWEK Load Parameters

When loading data via the ODWEK Java API, attempts to load may fail with the error "The server failed while storing a document", because there in not enough space available in the ARS_TMP filesystem to complete the load. You can specify a separate temporary directory for downloaded data to be loaded into IBM CMOD:

ARS_DOWNLOAD_DIR

The directory where data is stored in preparation for ODWEK loading.

ARS_DOWNLOAD_TMP_DIR

The directory where temporary files created during ODWEK loading will be stored.

CMOD LDAP Parameters

ARS_LDAP_IGN_USERIDS

Populate with a list of CMOD User IDs that are exempt from LDAP authentication, who will be authenticated by the password stored in the local OnDemand database.

It's a very good idea to include CMOD administrators in this list, so they can still log in when your organization's LDAP server is down.

If you have separate UserIDs for loading ("ARSLOAD") and maintenance ("ARSMAINT") it's a terrific idea to add them to this list of CMOD User ID's, so that normal production processing can continue, in the event of an LDAP server failure.

See also: CMOD LDAP Configuration