Documente Academic
Documente Profesional
Documente Cultură
ABSTRACT
This white paper is step-by-step guide for Content Server 7.1 installation on AIX
Platform with DB2 database as backend. It explains installation requirements
and provides detailed steps for setting up environment, installation, install
verification and troubleshooting issues.
December, 2013
TABLE OF CONTENTS
ABSTRACT ............................................................................................................................................. 1
TABLE OF CONTENTS ............................................................................................................................. 2
INTRODUCTION ..................................................................................................................................... 3
Intended audience .............................................................................................................................. 3
Terminology ....................................................................................................................................... 3
CONTENT SERVER INSTALLATION MODEL ............................................................................................. 3
Installation Requirements .................................................................................................................... 4
Hardware / Software Requirements ................................................................................................. 4
Other Requirements....................................................................................................................... 4
PRE-INSTALLATION TASKS .................................................................................................................... 5
Installation Owner User Account ........................................................................................................... 5
Docbase Owner User Account ............................................................................................................... 5
Environment Settings .......................................................................................................................... 6
E-Mail Configuration ............................................................................................................................ 8
Ports Reservation ................................................................................................................................ 8
Operating System Settings ................................................................................................................... 9
DB2 Database .................................................................................................................................... 9
Database Creation ......................................................................................................................... 9
Database Configuration ................................................................................................................. 10
DB2 Client Configuration ............................................................................................................... 12
INSTALLATION .................................................................................................................................... 13
Content Server Installation.................................................................................................................. 14
License Configuration ......................................................................................................................... 18
Docbroker Configuration ..................................................................................................................... 20
Docbase Configuration ........................................................................................................................ 23
POST-INSTALLATION TASKS ............................................................................................................... 31
Installation / Configuration Logs Review ............................................................................................... 31
Content Server Installer Logs ......................................................................................................... 31
Server Configuration Program Logs................................................................................................. 32
Docbroker Logs ............................................................................................................................ 32
Docbase Logs............................................................................................................................... 32
Method Server Logs ...................................................................................................................... 32
Dar Install Logs ............................................................................................................................ 32
Other Logs .................................................................................................................................. 32
E-Mail Address Configuration ............................................................................................................... 32
Keystore Backup ................................................................................................................................ 33
TROUBLESHOOTING ............................................................................................................................ 33
CONCLUSION ....................................................................................................................................... 34
REFERENCES ........................................................................................................................................ 35
CONTACT US ........................................................................................................................................ 35
INTRODUCTION
Content Server release 7.1 adds support for AIX and Solaris platforms. With AIX, DB2 database and with Solaris, Oracle
database is supported. This white paper provides detailed steps for preparing the environment and installing Documentum
Content Server 7.1 on AIX operating system with DB2 database as backend.
Intended audience
This document is intended for system administrators responsible for installing and configuring Content Server.
Terminology
Connection Broker / Docbroker: A connection broker or Docbroker is name server for Content Server.
Repository / Docbase: A repository or docbase is logical entity that provides abstraction to storage that stores native content
files and RDBMS that stores content metadata.
Installation Owner: The installation owner account is an operating system account with appropriate permissions to install
Content Server and create repositories.
Docbase Owner / Database Owner: The Docbase owner or database owner account is database user account with the
database owner role having read and write access rights to the database.
RDBMS: Relational Database Management System
Figure 1 shows key components. Apart from these, Method Server (JBoss Application Server) is installed with every Content
Server installation. In Pre Installation Tasks section, detailed steps are provided for creating and configuring database assuming
that DB2 Server is already installed on machine 2.
Installation Requirements
This section describes minimum hardware and software requirements for Content Server installation and use. For production
systems, use system sizing / capacity planning tool to establish estimated resources required, taking into account the users,
sessions and other information.
2.
40 GB
RAM
8 GB
Swap Space
8 GB
2 GB
AIX
RDBMS
DB2 server can be on any supported operating system, but for purpose of this paper, all steps are provided considering DB2
server is installed on AIX platform. Check DB2 documentation for more details on hardware / software requirements on this
machine.
Other Requirements
Apart from above requirements, below are the prerequisites for installation:
Administrative privileges needed on the machine where you are installing Content Server
XWindows must be installed on the AIX host to run the graphical installation program.
Database Administrator account needed for DB2 Server.
Working knowledge of AIX & DB2.
For more information, refer EMC Documentum Environment and System Requirements Guide version 7.1, which contains
detailed system hardware and software requirements.
PRE-INSTALLATION TASKS
Installation Owner User Account
The installation owner account is an operating system account with appropriate permissions to install Content Server and create
repositories. Follow below steps to create installation owner user account:
1.
Create a group account whose members are installation owner, docbase owners and Content Server administrators. Use
mkgroup command to create a new group. Below command will create group named dmadmin:
mkgroup dmadmin
2.
Create installation owner user, add it to Content Server administrators group and optionally set its home directory and shell.
For example, if installation owner user name is dmadmin and group name is dmadmin, then execute below command as
root to create AIX user and set its login shell to C shell:
useradd -d /export/aix01-4/dmadmin -g dmadmin -s /bin/csh dmadmin
3.
4.
Grant owner privileges to installation owner user and group for user's home directory using chown and chgrp commands:
chown -R dmadmin /export/aix01-4/dmadmin
chgrp -R dmadmin /export/aix01-4/dmadmin
5.
Verify that installation owner has read/execute permissions to database client, if not then grant required permissions.
6.
Verify that installation owner has read, write and execute permissions on /tmp directory, if not then grant required
permissions.
Create an AIX user account on Content Server host for docbase owner user and add user to docbase owners group created
earlier. Below command will create user docbase1 and add it to group dmadmin:
useradd -g dmadmin -s /bin/csh docbase1
2.
# passwd docbase1
3.
If DB2 is using host operating system for authentication, create user account with same name on DB2 host for Database
owner.
Note: On AIX, for new user accounts, user is required to reset password on first login. So before proceeding further, login with
the user created and reset the password or disable this behavior for the user using pwdadm command. For example execute
below command:
pwdadm -c <user>
Environment Settings
1.
Plan for installation directory. Verify that enough space is available for installation. Use df command which displays total
space and available space on the file system to check space available:
df -g
You can create installation directory before installation or you can allow installer to create installation directory by reading
$DOCUMENTUM environment variable. If you are creating installation directory, set the owner of installation directory to
installation owner and group to administrators group:
# mkdir /export/aix01-3/documentum
# chown -R dmadmin /export/aix01-3/documentum
# chgrp -R dmadmin /export/aix01-3/documentum
Note: Installation directory name or path should not contain any spaces.
2.
Installation owner should have full permissions on the installation directory, including data and share directories. Grant
permission for install owner and group to install directory:
% chmod 751 /export/aix01-3/documentum
By default, data directory is created inside $DOCUMENTUM, if data directory location is changed, then similarly set
owner/group to installation owner/group and grant full permissions to installation owner for data directory.
3.
Description
DOCUMENTUM
DM_HOME
The
product
version
subdirectory
in
the
Content
Server
installation
directory:
LC_ALL
DB2_BASE
DB2INSTANCE
DB2_HOME
DB2_OWNER
Instance owner
INSTHOME
DB2DIR
LIBPATH
DISPLAY
Put these environment variables in installation owners .cshrc file (for C shell) and source it. Below are the contents of
sample .cshrc file:
setenv DB2INSTANCE
db2inst1
4.
Copy Content Server build to some directory. The installation owner must have write permission on the directory from which
installer is run.
5.
6.
Ensure that you have execute permission on the serverSetup.bin file. If not, add execute permission to the file by running
below command:
chmod +x serverSetup.bin
E-Mail Configuration
E-Mail configuration is required on Content Server host for enabling e-mail notification functionality for features like workflow
tasks, jobs, registered events etc. On AIX, Content Server use mail utility by default for e-mail notifications. This section
describes steps to configure an SMTP based mail server for e-mail notifications. It is assumed that you have setup SMTP mail
server and have working TCP/IP connection between Content Server host and mail server. Below are the steps to configure mail
client on AIX to use SMTP server:
1.
2.
In the configuration file /etc/sendmail.cf, add SMTP relay hostname by modifying the line with DS and specifying your mail
server as below:
# "Smart" relay host (may be null)
DS<mail_server_host_or_ip>
DSplepmo-vm5.dctmlabs.com
3.
4.
5.
Test whether installation owner account can send and receive mails. Login as installation owner and execute below
command:
echo <mail_body> | /usr/bin/mail -s <subject> <to_address>
Ports Reservation
Content Server and other components use a number of ports on the host:
1.
The application server listens on a port (9080 by default) for standard administration connections, and starting at this port,
a total of 20 consecutive ports must be reserved for use by the application server.
2.
The connection broker requires two consecutive ports (1489 and 1490 by default) on which to listen: one for native
connections and the other for secure connections (SSL).
3.
Docbase service requires two consecutive ports, one for native connection and other for secure connection. Reserve two
ports by creating entry in services file (/etc/services) even if Content Server is installed in native mode and not using secure
connections. Service name need not be same as docbase name. Edit services file and add entries for docbase service:
<service_name>
<port1>/tcp
<service_name>_s
<port2>/tcp
docbase1
28000/tcp
docbase1_s
28001/tcp
Make sure none of the reserved ports are being used for other purposes by checking services file (/etc/services). The port
numbers can be any unused port numbers greater than 1024 as port numbers up to 1024 are reserved for system use. If
possible, stay away from using the ephemeral port range which is 32768-65535 on AIX by default, as they are used by the OS.
Use below command to check ephemeral port range on AIX:
#
On Linux machines, Content Server requires at least 4 MB of shared memory to be allocated and that semaphores are
enabled. On AIX, shared memory and semaphores are automatically tuned by kernel, so this configuration is not required.
2.
You might need to increase the number or user processes in the OS to some higher value since workflows and jobs can start
multiple processes. Use below command to check maximum number of processes allowed per user:
# lsattr -E -l sys0 -a maxuproc
maxuproc 256 Maximum number of PROCESSES allowed per user True
To change the value of maximum allowed processes, execute below command as root:
chdev -l sys0 -a maxuproc=<no_of_processes>
DB2 Database
Assuming DB2 Server is installed on AIX operation system and default instance is created on RDBMS host, this section describes
database creation, database configuration and DB2 client configuration steps using command line.
Database Creation
Follow below steps to create database on DB2 host:
1.
2.
Setup the DB2 instance environment by sourcing db2profile (for Bourne or Korn shell) or db2cshrc (for C shell) in the sqllib
directory. For C shell, execute below command where INSTHOME represents the home directory of the DB2 instance:
source INSTHOME/sqllib/db2cshrc
3.
Start DB2 instance if its not running. Use below command to start DB2 instance:
$ db2start
11/13/2013 00:00:35
SQL1063N
4.
SQL1063N
Before creating database, disable the DB2CODEPAGE environment variable using db2set command:
$ db2set DB2CODEPAGE=
Note: For db2set command, there should be no spaces before or after equal sign.
5.
6.
You can create database using CREATE DATABASE command. Define character set for database using codeset and territory.
Use Unicode code page (UTF-8) that can store characters from all supported languages. Page Size needs to be 8kb. Sample
DB2 command to create database is given below. It is not required to have database name same as Docbase name.
CREATE DATABASE <database_name> ON '<path>' ALIAS <database_alias> USING CODESET <codeset> TERRITORY
<territory> PAGESIZE <pagesize>
7.
8.
From the command line, set the DB2CODEPAGE environment variable to 1208:
$ db2set DB2CODEPAGE=1208
Database Configuration
Follow below steps to configure database and set parameter values as required by Content Server:
1.
2.
10
DB20000I
3.
Set the number of primary transaction log files to 18 & secondary log files to 10. Set the log file sizes to 1024. Set log
buffer size to 128.
update db cfg for <dbname> using logfilsiz 1024 logprimary 18 logsecond 10 logbufsz 128
db2 => update db cfg for docbase1 using logfilsiz 1024 logprimary 18 logsecond 10 logbufsz 128
DB20000I
4.
Set the maximum storage for lock list, maximum percent of lock list before escalation and maximum number of active
applications.
update db cfg for <dbname> using locklist 2048 maxlocks 80 automatic maxappls 200 automatic
db2 => update db cfg for docbase1 using locklist 2048 maxlocks 80 automatic maxappls 200 automatic
DB20000I
5.
Set the sort heap and buffer page sizes. If the Content Server and the DB2 server are on different machines, it is
recommended to set buffer page size to 80% of the available physical memory divided by the page size of your table space.
If you are running more than one repository and database on the same DB2 server, the percentage recommended for buffer
pool is for the sum of all databases. In all cases, ensure that the buffer page size is a minimum of 6000.
update db cfg for <dbname> using sortheap 1138 automatic
update db cfg for <dbname> using buffpage <buffpage>
db2 => update db cfg for docbase1 using sortheap 1138 automatic
DB20000I
The BUFFPAGE parameter will only be used if one of the buffer pools
If you see the SQL1482W error message: "The BUFFPAGE parameter will only be used if one of the buffer pools is defined
with a size of -1, change the buffer pool size to -1. -1 indicates that the buffer pool is to use the BUFFPAGE parameter as
the number of buffer pool pages.
ALTER BUFFERPOOL buffpoolname SIZE -1
6.
From the command line, restart DB2 using db2stop & db2start commands:
$ db2stop force
11
11/13/2013 02:14:11
SQL1064N
SQL1064N
$ db2start
11/13/2013 02:14:38
SQL1063N
SQL1063N
Note: Do not set the environment variable DB2OPTIONS. If set to T, the DB2 CLP uses a semicolon (;) as the statement
termination character. Content Server does not install properly on AIX with DB2 when DB2OPTIONS is set.
Setup the DB2 instance environment by sourcing db2profile (for Bourne or Korn shell) or db2cshrc (for C shell) in the sqllib
directory. For C shell, execute below commands where INSTHOME represents the home directory of the DB2 instance:
source INSTHOME/sqllib/db2cshrc
2.
3.
db2 => CATALOG TCPIP NODE pleaix01 REMOTE pleaix02 SERVER 50000
DB20000I
DB21056W
refreshed.
4.
db2 => CATALOG DATABASE docbase1 as docbase1 at node pleaix01 AUTHENTICATION server
DB20000I
DB21056W
refreshed.
5.
12
6.
Start db2 CLP and check whether entry has been made for database.
db2 => list database directory
Database 1 entry:
7.
Database alias
= DOCBASE1
Database name
= DOCBASE1
Node name
= PLEAIX01
= f.00
Comment
= Remote
Authentication
= SERVER
= -1
Verify that you can connect to the database by using database client. From db2 CLP, execute below command:
connect to <database_alias> user <user_id> using <password>
Database server
= DB2/AIX64 10.1.2
SQL authorization ID
= DB2INST1
= DOCBASE1
db2 =>
INSTALLATION
This section describes installation flow. First, install Content Server using serverSetup.bin. Then proceed with license
configuration, docbroker configuration and docbase configuration using server configuration program.
13
2.
14
3.
Software License is displayed. Accept the license and click Next to continue.
4.
Set administrator password and listening port for embedded application server.
5.
15
Verify installation directory displayed and click Install to install content server.
6.
After Content Server installation, installer provides option to enter licenses for optional modules. Licenses can be entered
later too using server configuration program. We will proceed by selecting option no and show in next section how licenses
can be configured later.
7.
16
8.
Installer asks root password and dmadmin group (group whose members are docbase owners) name to grant necessary
permissions to some files. Enter root password and dmadmin group name and click Enter to continue.
17
9.
Installer provides option to launch Content Server configuration program and continue with docbase configuration or
configure this later using server configuration program. Configure now is express mode in which configuration program
does not provide options to configure docbroker and select connection modes. docbroker is created automatically using
default docbroker ports. We are selecting Configure later and exiting from the installer. Make note of Server Configuration
Program location displayed by the installer.
Verify the log files generated by installer, as mentioned in section Content Server installer logs.
License Configuration
1.
2.
18
Select Licensing and click Next to enter licenses for optional modules.
3.
Enter Licenses for modules you want to enable and click Next to continue.
4.
Select Finish Configuration and click Next to exit server configuration program or select Perform additional configuration
to go back to first screen.
19
Docbroker Configuration
20
1.
2.
3.
Select Add a Connection Broker to create a docbroker and click Next to continue.
4.
Installer provides options for docbroker connection modes. We have selected the default Native mode. For more
information on Secure mode configuration, refer Content Server version 7.1 Installation Guide.
21
22
5.
6.
7.
Select Finish Configuration and click Next to exit server configuration program or select Perform additional configuration
to go back to first screen.
Check log files mentioned in section Server Configuration Program Logs and Docbroker Logs to verify that docbroker was started
successfully.
Docbase Configuration
23
1.
2.
3.
4.
Provide path for data directory. We have selected default data directory which is inside $DOCUMENTUM directory. Click
Next to continue.
24
25
5.
6.
26
7.
8.
9.
10. Select option Create a new DB2 user account and database if you want installer to grant required privileges to OS user
needed for Database owner.
27
11. Select the database created for docbase from Data Source dropdown list. Provide DB2 administrator name and password.
Provide the docbase owner account created for this docbase.
28
12. Content Server creates database managed space (DMS) type table spaces for data and index table spaces. Provide path for
table space container files. Either absolute or relative file name can be provided. The file name, if not absolute, is relative to
the database directory.
13. Specify if you want to use the docbase created as global registry docbase and provide user name and password. Back-up
global registry user account information.
29
14. Select modules that you want to enable for docbase. For XML Store and RSA Key Manager, additional configuration is
required which is not shown here. Please refer Content Server version 7.1 Installation Guide for more details.
15. When docbase configuration is complete, summary is displayed. Review summary and click Next to continue.
30
16. Select Finish configuration and click Next to exit server configuration program.
POST-INSTALLATION TASKS
After installation is complete, verify installation and other logs given in next section.
Current working directory (the directory from which you started the program)
The parent directory of the current working directory, if the installation owner does not have write permission on the
current working directory.
The user s home directory, if the installation owner does not have write permission on the parent
31
logs/install.log
logs/install.log.yyyy.mm.dd.hh.mm.ss
logs/Content_Server_Install_ mm_dd_yyyy_hh_mm_ss.log
logs/Documentum_DFC_Environment_Install_ mm_dd_yyyy_hh_mm_ss.log
$DM_HOME/install/logs/install.log
$DM_HOME/install/<install_owner>.ServerConfigurator.log
<installation_owner_home_directory>/UniversalServerConfigurator_Install_ mm_dd_yyyy_hh_mm_ss.log
Docbroker Logs
Check
whether
docbroker
started
successfully
by
inspecting
docbroker
logs
created
in
below
location:
$DOCUMENTUM/dba/log/docbroker.<hostname>.<docbroker_port>.log
Docbase Logs
Check docbase logs created at below location:
$DOCUMENTUM/dba/log/<docbase_name>.log
$DOCUMENTUM/jboss7.1.1/server/DctmServer_MethodServer/log
$DOCUMENTUM/jboss7.1.1/server/DctmServer_MethodServer/logs
Other Logs
Each script that runs during docbase configuration creates a log file. These are stored in below location:
$DOCUMENTUM/dba/config/<docbase_name>
b.
32
Keystore Backup
Take backup of keystore files created in $DOCUMENTUM/dba/secure directory, especially aek.key.
TROUBLESHOOTING
1.
SQL30082N Security processing failed with reason "24" ("USERNAME AND/OR PASSWORD INVALID")
During docbase configuration, below error is thrown in docbase logs:
[DM_SESSION_I_RETRYING_DATABASE_CONNECTION]info:
database connection:
Security processing
SQLSTATE=08001
User account for database owner provided during installation does not exist on DB2 server host
Resolution: Create a user account on DB2 server host for database owner and verify that same username and password is
entered during installation.
2.
Security processing
SQLSTATE=08001
This error is returned when database owner password has expired. One of the possible reasons this can happen is that AIX
requires password to be changed on first login but password for database owner account was not reset after account was
created.
Resolution: Reset database owner password.
3.
When database transaction log is full, creating new objects or saving objects fails with this error. This error is caused when
the database log file is not large enough for the application.
Resolution: You might need to increase the log file size and the number of primary and secondary log files:
33
a.
Stop docbase
b.
Determine the current DB2 log file configuration. Execute below command from DB2 CLP:
(LOGFILSIZ) = 1024
(LOGPRIMARY) = 18
(LOGSECOND) = 10
Increase log file size (LOGFILSIZ) and number of primary (LOGPRIMARY) and secondary (LOGSECOND) log files
using below command:
db2 => update db cfg for <database> using logfilsiz <sz> logprimary <n> logsecond <m>
4.
d.
e.
Start docbase
Content Server creates database managed space (DMS) table space for data and index table spaces. One of the likely cause
of this error is all containers assigned to the table space are full.
Resolution: You need to add new container to table space:
a.
Check whether all containers for table space are full using list tablespaces command:
db2 => list tablespaces show detail
b.
c.
5.
Server configuration program hangs while Docbase configuration or following error is thrown by server configuration
program:
Failed to execute command: <$DM_HOME>/bin/dmdb2utils -getalias -o /tmp/db2Output18163068785715652.txt;
Failed to execute command: <$DM_HOME>/bin/dmdb2utils -getalias -o /tmp/db2Output18163068785715652.txt
Check whether all DB2 environment variables are set properly, stop the program and start again.
CONCLUSION
This white paper provides information required for understanding and quickly getting started with the process of installing
Documentum Content Server 7.1 on AIX operating system with DB2 database. For more details refer product documentation and
references provided in next section.
34
REFERENCES
CONTACT US
To learn more about how
EMC products, services, and
solutions can help solve your
business and IT challenges,
contact your local
representative or authorized
reselleror visit us at
www.EMC.com.
www.EMC.com
35