[direct-certificate-discovery-tool] r409 committed - Edited wiki page TAR_Install_Guide through web user interface.

[direct-certifica...@googlecode.com]

Revision: 409
Author: amy....@nitorgroup.com
Date: Tue Nov 13 15:21:12 2012
Log: Edited wiki page TAR_Install_Guide through web user interface.
http://code.google.com/p/direct-certificate-discovery-tool/source/detail?r=409

Modified:
/wiki/TAR_Install_Guide.wiki

=======================================
--- /wiki/TAR_Install_Guide.wiki Tue Nov 13 14:59:19 2012
+++ /wiki/TAR_Install_Guide.wiki Tue Nov 13 15:21:12 2012
@@ -534,7 +534,7 @@

2. Type the IP address assigned to the server in the *IP Address* textbox.

-3. Accept the default value for time-to-live in the TTL textbox or adjust
it.
+3. Accept the default value for time-to-live in the *TTL* textbox or
adjust it.

4. Click the *Add Record* button.

@@ -633,28 +633,28 @@
===3.5.1 STARTING THE JAMES MAIL SERVER===
To create Direct Addresses, you must start the James Mail Server (“James”):

- # Open a shell (command line) and change directory to
$DIRECT_HOME/james-2.3.2/bin.
+1. Open a shell (command line) and change directory to
$DIRECT_HOME/james-2.3.2/bin.

{{{
cd $DIRECT_HOME/james-2.3.2/bin
}}}

-# Change permission on the setdomain.sh and the run.sh scripts to make
both executable.
+2. Change permission on the setdomain.sh and the run.sh scripts to make
both executable.

{{{
chmod u+x setdomain.sh
chmod u+x run.sh
}}}

-# Use setdomain to set the domain for James to your registered Test Health
Domain.
+3. Use setdomain to set the domain for James to your registered Test
Health Domain.

{{{
./setdomain.sh testteam.us
}}}

-# Edit james-2.3.2/apps/james/SAR-INF/config.xml and uncomment the
line '<server>127.0.0.1</server>' to allow James to use the RI’s DNS server.
+4. Edit james-2.3.2/apps/james/SAR-INF/config.xml and uncomment the
line '<server>127.0.0.1</server>' to allow James to use the RI’s DNS server.

-# Start James.
+5. Start James.

{{{
./run.sh
@@ -664,20 +664,241 @@
===3.5.2 CREATING A DIRECT ADDRESS===
To create a new Direct Address hosted by James:

-# Telnet to the James administration port from the command line.
+1. Telnet to the James administration port from the command line.

{{{
telnet localhost 4555
}}}

-# When prompted for the user, type root.
+2. When prompted for the user, type *root*.

-# When prompted for the password, type root.
+3. When prompted for the password, type *root*.

-# Create the Direct Address using the adduser command by specifying the
address, without the domain, followed by the password for the address. In
the example below, the address is “dts500,” and the password is
“dts500pass”.
+4. Create the Direct Address using the adduser command by specifying the
address, without the domain, followed by the password for the address. In
the example below, the address is “dts500,” and the password is
“dts500pass”.

{{{
adduser dts500 dts500pass
}}}

Repeat Step 4 until you’ve created all of the required Direct Addresses.
To end the telnet session, type quit and hit Enter.
+
+
+==3.6 Populating LDAP==
+As part of configuring the Tool, you must populate LDAP with the
appropriate certificates, as identified in the “Certificates” table on the
Install Worksheet, as described in Section 2.1.2.3, “Certificates.” The
Tool uses Apache Directory Server for LDAP.
+
+===3.6.1 STARTING LDAP===
+The Tool requires two instances of LDAP, the default instance and one
called domain2ldap1. To start the instances:
+1. Navigate to $DIRECT_HOME/apacheds/bin folder.
+
+{{{
+cd $DIRECT_HOME/apacheds/bin
+}}}
+
+2. Update the permissions for apacheds.sh to make it executable.
+
+chmod u+x apacheds.sh
+
+3. Launch the default instance of Apache Directory Server.
+
+{{{
+sudo -E./apacheds
+}}}
+
+4. Verify the default instance is up. A screenshot is shown here:
+
+http://direct-certificate-discovery-tool.googlecode.com/files/Tar_34.png
+
+5. Launch the domain2ldap1 instance.
+
+{{{
+sudo –E ./apacheds domain2ldap1
+}}}
+
+6. Verify the domain2ldap1 instance is up.
+
+7. In order to change the port number that the LDAP server runs on by
default:
+
+a. Shutdown the apache instance by typing Control + C.
+
+b. Open the $DIRECT_HOME/apacheds/Instances/domain2ldap1/conf/config.ldif
file.
+
+c. Set the “ads-systemport:” variable to the desired port. Use 10389 for
the “default” instance, which was started in step 3 above and 11389 for the
domain2ldap1 instance, started in step 5 above.
+
+d. Repeat steps 3 and 5 to restart the apache directory studio instances
and have them run on the new ports.
+
+8. Confirm that the SRV records in created in Section 3.4.6.5, Setting Up
Service ("SRV") Records, map to the correct ports. The “default” apache
directory studio instance will be loaded with the data from ldap_1.ldif in
section 3.6.2 and the “domain2ldap1” instance is loaded with the data from
ldap_2.ldif.
+
+===3.6.2 HOSTING THE CERTIFICATES IN LDAP===
+Some certificates must be hosted in LDAP for the Tool to work correctly.
The Tool comes packaged with two LDIF files, located in
$DIRECT_HOME/Tools/ldif, for populating the two LDAP instances with the
correct certificates. Prior to importing the LDIF files, you must edit
them to ensure that they have the correct information for your environment.
+
+You can use the sed utility to quickly update the files, as follows:
+
+{{{
+sed 's/testteam.us/yourdomain.com/g' ldap_1.ldif >> ldap_1_updated.ldif
+sed 's/testteam.us/yourdomain.com/g' ldap_2.ldif >> ldap_2_updated.ldif
+}}}
+
+These two commands produce two new LDIF files, “ldap_1_updated.ldif” and
“ldap_2_updated.ldif,” with all instances of “testteam.us” replaced with
“yourdomain.com.” (Be sure to substitute your environment’s registered
Test Health Domain for “yourdomain.com” when you run the commands.)
+
+When you’re done editing the files, replace the old files with the new by
running the following commands:
+
+{{{
+mv ldap_1_updated.ldif ldap_1.ldif
+mv ldap_2_updated.ldif ldap_2.ldif
+}}}
+
+Optionally, if the Direct Addresses differ significantly from the Public
Tool’s addresses, so that you can’t update the files using sed, you will
need to edit the files by hand:
+
+1. Open ldap_1.ldif in your preferred text editor.
+
+2. Look for the entry for DTS 500 (an address-bound certificate):
+
+{{{
+dn: cn=dts500,ou=system
+objectClass: top
+objectClass: inetOrgPerson
+objectClass: person
+objectClass: organizationalPerson
+cn: dts500
+sn: Test Case
+mail: dts...@direct1.testteam.us
+o: onctest
+userCertificate::
+}}}
+
+3. Replace the mail value (dts...@direct1.testteam.us) with the Direct
Address for DTS 500 from the target environment.
+
+4. Repeat Steps 2 and 3 for DTS 505, 506, 517, and 520.
+
+5. Look for the entry for DTS 501 (an organization-bound certificate):
+
+{{{
+dn: cn=dts501,ou=system
+objectClass: top
+objectClass: inetOrgPerson
+objectClass: person
+objectClass: organizationalPerson
+cn: dts501
+sn: Test Case
+mail: direct1.testteam.us
+o: onctest
+userCertificate::
+}}}
+
+6. Replace the mail value (direct1.testteam.us) with the value for Domain
1 from the target environment.
+
+7. Repeat Steps 5 and 6 for DTS 515 and 520.
+
+8. Save the changes and close ldap_1.ldif.
+
+9. Repeat the same process for ldap_2.ldif. All entries in the file are
for address-bound certificates.
+
+===3.6.3 LINUX INSTRUCTIONS FOR UPDATING / ADDING LDAP ENTRIES===
+1. Open a Terminal window in your “X11” program and ssh into the instance.
Here you should be able to run the ApacheDirectoryStudio.
+
+2. Next, follow the steps 1 through 4 in section 7.1 of the following
guide in order to establish a connection between LDAP Directory Studio and
LDAP Server:
+http://modularspecs.siframework.org/file/view/Direct-Certificate-Discovery-TI-Instruction-Guide.pdf
+
+3. Import the .ldif file you created earlier into the LDAP server by
clicking the “Import” option from the “File” menu in Directory Studio.
Choose the “LDIF” option from the LDAP Browser folder. Click next. Browse
to the LDIF file you just created and then browse to the LDAP Server
connection in the “Import into” field. Click Finish.
+
+4. Once the inetOrgPerson entries are in the LDAP server, click on an
entry and then double click on userCertificate for an entry. This will open
a dialog-box which allows to load any certificate for that entry. Click on
Load Certificate on this screen (see the figure) and upload the certificate.
+
+http://direct-certificate-discovery-tool.googlecode.com/files/Tar_30.png
+
+==3.7 Configuring the Tool==
+The last activity you must complete before running the Tool is to
configure the Tool to recognize where to find certificates in the target
environment, and how to recognize the Direct Addresses and certificates
associated with the test cases. The directions that follow describe how to
configure the Tool appropriately.
+
+NOTE: These instructions cover Tomcat, which is the current application
server used by the Tool. Adapting these instructions for other application
servers is not covered in the Guide.
+
+===3.7.1 SETTING UP THE CONFIGURATION DIRECTORY===
+
+The TAR file comes with a ready-to-go configuration directory, populated
with the required configuration files, located in
$DIRECT_HOME/config/direct. The configuration directory includes the
following configuration files that the Tool uses to recognize where to find
certificates in the target environment, and how to recognize the Direct
Addresses and certificates associated with the test cases:
+
+{{{
+config.properties
+email.properties
+log4j.properties
+}}}
+
+To enable the Tool to recognize the configuration directory, set the
CONFIG_DIR environment variable, as follows:
+
+1. Navigate to the tomcat home directory
+
+{{{
+cd $DIRECT_HOME/apache-tomcat-7.0.27/bin
+}}}
+
+2. Open the catalina.sh file
+
+{{{
+vi catalina.sh
+}}}
+
+3. Edit this line: JAVA_OPTS="$JAVA_OPTS
-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"
+
+4. Change it to this: JAVA_OPTS="-DCONFIG_DIR=$DIRECT_HOME/config/direct
$JAVA_OPTS
-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"
+
+===3.7.2 CONFIGURING LOGGING===
+The Tool uses Log4J for logging. To configure the location of the log
file:
+
+1. Navigate to $DIRECT_HOME/config/direct:
+
+{{{
+cd $DIRECT_HOME/config/direct
+}}}
+
+2. Edit the log4j.properties file for the two appenders to point to where
you would like your logging files located:
+
+a. Find log4j.appender.certDiscAppender.File
+
+b. Set it equal to the location of the log file:
+
+{{{
+log4j.appender.certDiscAppender.File=$DIRECT_HOME/apache-tomcat-7.0.27/logs/certDiscovery.log
+}}}
+
+c. Find log4j.appender.emailMessageAppender.File
+
+d. Set it equal to the location of the log file:
+
+{{{
+log4j.appender.emailMessageAppender.File=$DIRECT_HOME/apache-tomcat-7.0.27/logs/emailMessage.log
+}}}
+
+===3.7.3 CONFIGURE LOCATION OF CERTIFICATES===
+By default the location of the .pem certificate files you created in
Section 3.3.2, Converting .p12 Certificates to .pem Files, are stored in
$DIRECT_HOME/Tools/Certificates/converted. If you chose a different
location to store the .pem certificate files, then you will need to update
the CertLocation property in $DIRECT_HOME/config/direct/ config.properties:
+
+http://direct-certificate-discovery-tool.googlecode.com/files/Tar_31.png
+
+===3.7.4 CONFIGURE DESTINATION ADDRESSES===
+Unless you’ve made significant changes to the Direct Addresses from the
“Addresses” table on the Install Worksheet, you shouldn’t need to do
anything other than update the registered domain portion of each
Destination Direct Address. You can update the registered domain using the
sed utility as follows:
+
+1. From the command line, navigate to $DIRECT_HOME/config/direct:
+
+{{{
+cd $DIRECT_HOME/config/direct
+}}}
+
+2. Use sed to replace “testteam.us” with your registered domain: (NOTE:
replace “yourdomain.com” in the statement below with your domain.)
+
+{{{
+sed 's/testteam.us/yourdomain.com/g' config.properties >>
config_updated.properties
+mv config_updated.properties config.properties
+}}}
+
+
+If you’ve made significant changes to the Direct Addresses (or just feel
more comfortable using an editor to edit the configuration file), update
each of the Direct Addresses in the config.properties file to match the
addresses in use in your target environment. For example, if you were
updating the address for DTS 500, you would replace the text to the right
of the “=” (“dts...@direct1.testteam.us”) with the correct address:
+
+http://direct-certificate-discovery-tool.googlecode.com/files/Tar_32.png
+
+===3.7.5 CONFIGURE CERTIFICATE NAMES===
+Unless you’ve modified the name from the “Name” column in the
“Certificates” table from the Install Worksheet, you should not need to
edit the certificate names in config.properties.
+
+If you have modified the name, you will need to reflect that in
config.properties. (Note that the certificate name to use is the original
base name (minus the .p12 suffix) of the .p12 certificate. This name is
expanded by the tool to find the “…_cert.pem” and “…_key.pem” files.) For
example, if you changed the name for CERT_1, you would replace the text to
the right of the “=” (“dts500_valid_cert_record”) with the correct name:
+
+http://direct-certificate-discovery-tool.googlecode.com/files/Tar_33.png
+
+To manually troubleshoot decryption problems, the openssl commands shown
may be attempted at the command line.
+
+
+