Chapter 2. Installing Penrose Virtual Directory
This chapter describes the complete procedure to install Penrose Virtual Directory, along with dependencies.
Penrose Server 2.0 is supported on the following platforms:
Red Hat Enterprise Linux 4.7 i386 (32-bit)
Red Hat Enterprise Linux 4.7 x86_64 (64-bit)
Red Hat Enterprise Linux 5.2 i386 (32-bit)
Red Hat Enterprise Linux 5.2 x86_64 (64-bit)
Penrose Virtual Directory 2.0 is supported running on a virtual guest on Red Hat Enterprise Linux 5 Virtualization Server.
Penrose Virtual Directory requires Sun Java Development Kit (JDK) version 1.5.0.
Download Sun JDK 5.0 from http://java.sun.com/javase/downloads/index_jdk5.jsp.
Install the JDK. This may be downloaded as an RPM or as an executable binary. For example:
./jdk-1_5_0_17-linux-amd64.bin
A virtual directory maps information from disparate data sources, such as directory services and databases, into a single location for users to access, while keeping the virtual service lightweight and simple to administer.
Download the RPMs. There are two packages for Penrose Server, one for the core server and the other for client tools.
Install the packages. For example:
rpm -i vd-server-2.0-build#.el5.noarch.rpm vd-client-2.0-build#.el5.noarch.rpm
The Penrose Server components are installed in the /opt/vd-server-2.0 and /opt/vd-client-2.0 directories.
Make sure that the proper JDK is configured for Penrose Server to use:
Open the vd.conf file with the Penrose Server directory.
vim /opt/vd-server-2.0/etc/vd.conf
Add the JAVA_HOME environment variable, pointing to Sun JDK 1.5.0. For example:
JAVA_HOME=/usr/lib/jdk1.5.0_17/
After editing the vd.conf file, copy it into the host's /etc directory.
cp /opt/vd-server-2.0/etc/vd.conf /etc
Optionally, configure the Penrose Server to run as a service:
Open the init script directory.
cd /opt/vd-server-2.0/etc/init.d
Edit the vd-server script so that the Penrose Server home and script locations are correct. For example:
VD_SERVER_HOME=/opt/vd-server-2.0 VD_SERVER_SCRIPT=$VD_SERVER_HOME/bin/vd-server.sh
Copy the init file to the /etc/init.d directory.
cp /opt/vd-server-2.0/etc/init.d/vd-server /etc/init.d
Make the init script executable.
chmod +x /etc/init.d/vd-server
Run a configuration script to reset the server hostname, give the admin username and password, and set the port numbers and other information for the associated LDAP and JMX services. Hitting Enter accepts the defaults in the brackets.
For example:
[root@server bin]# ./vd-config.sh Configuring VD Server: ---------------------- Hostname [server.example.com]: Root DN [uid=admin,ou=system]: Root Password [*****]: secret12 User account [root]: Group account [root]: Configuring OpenDS Service: --------------------------- LDAP Enabled [true]: LDAP Port [389]: Secure LDAP Enabled [true]: Secure LDAP Port [636]: SSL Certificate Name [server-cert]: Key Store Type (JKS/PKCS12) [PKCS12]: Key Store File [config/keystore.p12]: Key Store PIN File [config/keystore.pin]: Configuring JMX Service: ------------------------ RMI Port [1099]: RMI Transport Port [40888]:
Additional libraries can be installed on Penrose Server so that extended functions can be deployed. These libraries cover a range of different Penrose functions, including JDBC drivers, custom adapters, custom modules, and other third party libraries.
Any additional libraries must be JAR files.
Copy the JAR files into the lib/ext/ directory in the Penrose Server home directory; for example:
cp /export/example.jar /opt/vd-server-2.0/lib/ext/example.jar
Restart Penrose Server.
service vd-server restart
Although some encryption support is included with the required JDK, some directory resources or clients may require additional encryption support.
Bouncy Castle Crypto package provides additional encryption methods, including SHA algorithms used by Penrose Virtual Directory, through a Java implementation. The Bouncy Castle security provider is required to run Penrose Virtual Directory and provides additional encryption and security services for Penrose Server.
JDK 1.5 or higher must be installed in the Java home directory specified in the Bouncy Castle installation.
Download the Bouncy Castle provider for the JDK from http://www.bouncycastle.org/latest_releases.html.
Copy the Bouncy Castle JAR file, such as bcprov-jdk15-140.jar, to the Java home directory, such as /usr/lib/jdk1.5.0_17/.
Open the java.security file. For example:
vim /usr/lib/jdk1.5.0_17//jre/lib/security/java.security
Add the Bouncy Castle provider to the list of registered security providers. For example:
security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.net.ssl.internal.ssl.Provider
security.provider.3=com.sun.rsajca.Provider
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=sun.security.jgss.SunProvider
security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProviderBecause of some governmental restrictions, some countries do not allow unlimited encryption strength. The JDK can be extended from its standard strong but limited encryption to unlimited strength by installing Java Cryptography Extension (JCE) files.
Download the JCE Unlimited Strength Jurisdiction Policy Files for the JDK.
Back up the existing policy files in the JDK home directory. For example:
zip security_files.zip /usr/lib/jdk1.5.0_17//jre/lib/security/
Copy the local_policy.jar and US_export_policy.jar files into the jre/lib/security directory in the JDK directory.
The Penrose Server packages can be uninstalled using Red Hat's package management tools, the same as used to install it. To remove Penrose Server, use the -e option with rpm:
rpm -ev vd-server-2.0-build#.el5.noarch vd-client-2.0-build#.el5.noarch
There is no direct upgrade or migration path to Penrose Virtual Directory 2.0. Updating the version requires updating the packages:
Stop the Penrose Server process, and verify the server is stopped.
service vd-server stop ps -ef | grep vd-server
Back up or copy the /opt/vd-server-2.0/partitions/ directory to save any custom partitions. If there are templates used for identity linking, save the templates and the federation domain's federation.xml file and configuration; it's not necessary to save the generated federation partitions.
Also back up or copy the server.xml file in the /opt/vd-server-2.0/conf/ directory. If SSL has been configured, save the cacerts file in the /opt/vd-server-2.0/conf/ directory.
Be sure to save these files to a different directory.
Uninstall all Penrose Virtual Directory RPMs. For example:
rpm -e vd-server rpm -e vd-studio rpm -e vd-client
Remove the remaining files.
rm -rf /opt/vd-server-2.0 rm -rf /opt/vd-studio-2.0 rm -rf /opt/vd-client-2.0
Install the new RPMs, and configure the services and configuation files as described in Section 2.3, “Installing Penrose Server”.
Copy in the saved partitions/ directory and the server.xml and cacerts files.
If there are templates used for identity linking, the restart the server to generate the federation partitions.
service vd-server restart
If NIS synchronization or identity federation was configured in the original Penrose Virtual Directory instance, then re-configure the /etc/yp.conf file.
Open Penrose Studio.
/opt/vd-studio-2.0/vd-studio
Expand the Federation folder in the lower left of the navigation tree.
Select the federation domain.
Open the NIS folder.
There is a tab in the main window labeled yp.conf. Copy the information there into the /etc/yp.conf file on the Penrose Server host machine.
Check that you can connect to the Penrose directory by checking the directories using LDAP tools.
For example, verify a regular virtual directory configuration:
ldapsearch -h localhost -p 389 -x -b "" -s base
If identity federation is configured, check both the local and global directories. For example:
ldapsearch -h localhost -p 389 -x -b "uid=jsmith,ou=Users,ou=local-nis,ou=NSS,dc=example,dc=com" ldapsearch -h localhost -p 389 -x -b "uid=jsmith,ou=Users,ou=Global,dc=example,dc=com"
If Penrose Server is used for user authentication, then attempt to log into a server using the proper credentials:
ldapsearch -h localhost -p 389 -x -D "uid=jsmith,ou=Users,ou=local-nis,ou=NSS,dc=example,dc=com" -w secret -b "" -s base
Last, check that NIS synchronization is working. For example:
/opt/vd-server-2.0/bin/nis.sh D uid=admin,ou=system -w secret synchronize exampleDomain otherDomain