QUESTION: How do I set up an additional ClearDDTS installation? ANSWER: For a variety of reasons, you may need to set up ClearDDTS on a separate machine. Although the precise steps differ according to the nature of your requirements, there are a set of steps that are common among all of them. To address these requirements in an efficient fashion, this FAQ is arranged in a modular format. Choose the sections relevant to your requirement and perform the procedures covered by that section. The sections of this document are: Part 1: The 'ddts' Userid Part 2: Email Routing Part 3: Moving/Copying the DDTS Site to a New Machine Part 4: Client Access Part 5: Testing and Cutting Over to Production For example, here is a chart illustrating some typical scenarios and the sections of this document you should consult for advice: Purpose See Parts... ====================================================== ============== Moving DDTS from one machine to another 1, 2, 3 Setting up an additional DDTS installation, to 1, 2, 3, 4 separate workload onto different sites Testing new DDTS releases prior to rolling them out 1, 2, 3, 4, 5 for general use. Providing a "safe sandbox" environment in which you 1, 2, 3, 4, 5 can make and test your DDTS customizations prior to rolling them out for general use. There are several other specific purposes for which these techniques can provide the solution. If you are faced with an issue similar to these and need to use these procedures, if you have any question about which parts are applicable to your situation please call DDTS Tech Support for help. PLEASE NOTE: The older FAQ titled "How do I set up multiple DDTS installations under one NIS domain?" has been incorporated into this FAQ and is now obsolete. ---------------------------------------------------------------------------- Part 1: The 'ddts' Userid Every ClearDDTS installation is owned by a special administrative user called "ddts". The home directory of this userid is the directory containing the ClearDDTS installation. If you are moving an existing DDTS installation from one machine to another, you need to take this into account by adjusting the home address of the DDTS userid to point to the new location. If you are trying to set up an additional DDTS installation, the requirement to have the 'ddts' userid "point to" the home directory of DDTS introduces an ambiguity: which one should it "point to?" To work around this issue, do the following: A. For one installation (call it site "XXXxx"), define the 'ddts' userid in NIS, with the home directory pointing to the path to site XXXxx's DDTS installation. Install DDTS in this directory using the standard installation procedures. B. For a subsequent site (call it site "YYYyy"), choose a separate machine as the ClearDDTS server and define a local 'ddts' userid using appropriate procedures for that UNIX architecture (i.e., make an entry for ddts in that machine's /etc/passwd file). You must use the same UID and GID numbers as the 'ddts' userid defined in NIS but you should specify a different home directory. C. After creating the local login on the second host, you can install ClearDDTS on that machine following the standard installations procedures. Make sure you are logged-in (as ddts) to the DDTS server host for site YYYyy when doing the installation (so you will cd to the right directory and not overlay site XXXxx's files!). ---------------------------------------------------------------------------- Part 2: Email Routing DDTS uses email to communicate to end-users (notification mail), DDTS administrators (reports and error alerts), and to communicate between DDTS installations when multiple DDTS sites are connected using DDTS's distributed capabilities. When establishing a second DDTS installation, whether for the purpose of establishing a second production site or establishing a location for testing, care must be taken to ensure that messages from/to the DDTS sites will be handled appropriately. There are several aspects to the issue of email routing. These are treated in detail below: Issue: Email from/to DDTS Sites You must separately consider incoming and outgoing mail to/from each site: - If incoming mail is generally sent to a globally-mounted mail spool (e.g. /var/spool/mail/ddts) then you must take action to ensure that the right messages will go to the right file to be seen by the right DDTS installation. - If email sent by user 'ddts' would normally pass through a mail hub which would reformat the "From:" and "To:" lines, you must take action to ensure that this will not interfere with DDTS's ability to communicate back to the sender by replying to the original message. This can be accomplished by a variety of methods depending on the email system's topology: - If the sites are in different NIS domains and do not NFS-mount the same mail spool, then no action is required. - If the sites are in the same NIS domain but can be separately addressed by email (for example, if ddts@hostname.domainname.com works) and the systems do not mount a common mail spool, then no action is required. - If the site's normal methodolgy is to reformat "From:" and "To:"" addresses in mail passing through a central mail hub, then care must be taken to ensure that ambiguity will not result and that the mail remains deliverable. To be specific, for each pair of DDTS sites you must consider the following questions: a. From userid 'ddts' on the DDTS server machine for site "XXXxx"", is there a way to specify an email address for site "YYYyy" which will cause the message to be delivered to the ddts userid on site YYYyy? b. For the message mentioned in the previous paragraph, if user 'ddts' on site "YYYyy" receives the message and replies (using the "From:"" address of the original message as the "To:" address of the reply), will that reply reach userid 'ddts' on site XXXxx? If the answers to both of these questions are "yes"", then no further action is required. If the answer to either question is "no" then action will be required by your mail system administrator to ensure successful delivery of DDTS-related mail. One common case which will cause the requirements stated above to fail is an enviroment where the machines all mount a common mail spool. In such an environment, userid 'ddts's mailbox is in a path like /var/spool/mail/ddts. This causes an ambiguity, as both 'ddts' userids will try to access this same file to receive mail. The solution to this problem is to use email aliasing: - Set up an email userid for the test installation (call it 'ddtsYYY' for the sake of example). The UNIX userid associated with this mail alias must have the same UID and GID numbers as the 'ddts' userid to ensure proper ownership and file permissions of the incoming mail mailbox (to ensure that 'ddts' can read the mailbox). - Tell DDTS on the test system to read mail from the alternate spool file. > For DDTS release 3.1, do this by creating a script to front-end the mail.in daemon: cd ~ddts/bin mv mail.in mail.in.bin Create a script called 'mail.in' consisting of: #!/bin/sh /bin/mail.in.bin -b /var/spool/mail/ddtsYYY chmod +x mail.in You would also need to set up a crontab entry to run 'mail.in' periodically (perhaps every 10-15 minutes), because the mechanism used to detect incoming mail does not "know about" the alternate mailbox. > For releases 3.2 and above, this is simpler: create a file ~ddts/conf/mailfile containing the pathname to the spool file; for example, ~ddts/conf/mailfile on site "YYYyy" (the test site) could contain: /var/spool/mail/ddtsYYY NOTE: If you are setting up a test DDTS installation but you do not actually want it to receive any mail, you can use a path to a nonexistant mailbox file in place of '/var/spool/mail/ddtsYYY' in my example; that will not allow DDTS to recieve mail but it *will* at least ensure that the DDTS test system will not steal mail from the production system. That handles incoming mail. If the two sites need to be connected via DDTS's connected sites facility, then you will also need to handle outgoing mail. If you take only the steps listed so far, if userid 'ddts' on site YYYyy sends mail to userid 'ddts' on site XXXxx, the mail will be delivered fine but it will arrive with a "From:" address of 'ddts' (since site YYYyy's DDTS daemons are running as that userid; see Part 1 for details). If ddts on site XXXxx replies to the mail, the mail will not be delivered to site YYYyy. It will bounce back to ddts on site XXXxx. The solution is to configure the sendmail daemon to rewrite the "From:"" address of messages sent by user 'ddts' on site YYYyy by adding the following to the sendmail.cf file on site YYYyy's ClearDDTS server. Make sure to make a backup copy of the sendmail.cf file before making the changes. # Sender Field Pre-rewriting S1 Rddts $@ddtsYYY Rddts<@machYYY> $@ddtsYYY # Recipient Field Pre-writing S2 Rddts $@ddtsYYY Rddts<@machYYY> $@ddtsYYY ...where 'machYYY' is the hostname of site YYYyy's DDTS server machine and 'ddtsYYY' is the email alias set up above. NOTE: The white space on the "R" lines above must be composed of TAB characters, not spaces! See the UNIX documentation for 'sendmail' for more detail. Having taken these steps, the machines now meet the requirements stated above (an email message from one site to the other will arrive at the correct site, and will arrive in such a a way that a reply to it will be properly delivered to the original sender). ISSUE: Email with Copied Defects If the site you are cloning (the original site) has any sites connected to it using DDTS's connection and subscription capabilities, you will need to be very careful about the relationship between defect data and the identity of other DDTS sites on which copies of the defect exist. For example, if you have a production site (call it "AAAaa") which has a connected site (call it "BBBbb"), and you copy site AAAaa's installation to another machine (see Part 3 for details) to create a test site (call it "CCCcc"), then the defects you copied from AAAaa to CCCcc will retain, as part of their defect data, information about their relationship to site BBBbb. If you do not take precautions, changes you make to the defect on the test site CCCcc will be sent back to production site BBBbb via email. Clearly, you do not want that to happen; you do not want the changes you make on your test system CCCcc to be posted back to the defect's owning site BBBbb. To ensure that this does not happen, two strategies are available: 1. Do not copy "live" defect data to the new system; start "fresh"" with newly-created test defects. 2. Modify the test system to disable mail delivery, so that when you post defect modifications and the system tries to notify the owning site (BBBbb in my example), the messages will not be delivered. To implement strategy #1, merely omit the allbugs directory tree from the 'tar' command you use to copy the ~ddts directory from the old system to the new (and create allbugs and its subdirectories manually on the test system), or remove all files under allbugs/* after copying. The easiest way to implment strategy #2 is to disable outgoing connected-site email from site CCCcc. To do this, just before you run 'ddtsinstall' to install site CCCcc, make the following changes: - Identify the relevant 'bin' subdirectory. Explanation: DDTS keeps binaries for different platforms in a set of directories called "~ddts/XXX_bin/"", where "XXX" takes on a different value depending on the architecture: aix.3.2.5_bin dec_alpha_bin hp800_bin sgi_bin sol2x_bin sun4_bin Choose the appropriate architecture-specific directory. If you are not sure which one to use, run a script called ddts_archdir.sh. You can find a copy of this in any of the '*_bin' directories; they are all the same so it does not matter which one you run. The output will be the architecture-specific binary subdirectory name appropriate for your architecture. - Identify the current location of the bin directory: > If you are using "Method #3B" from Part 3, this will be ~ddts/XXX_bin, where "XXX" is the architecture-specific part from the previous step. > If you are using "Method #3C"", this will be ~ddts/NEWCLEARDDTS/XXX_bin. - Go to that directory and disable the net.out daemon: cd DDTS_bin_directory (from above) mv net.out net.out.bin Using vi, create a shell script called 'net.out' consisting of: #!/bin/sh echo "net.out `today -l` Daemon Started - $$ " >> spool/LOG for x in `ls spool/net.out/`; do echo "net.out `today -l` Discarded spool/net.out/$x " >> spool/LOG rm -f spool/net.out/$x done echo "net.out `today -l` Daemon Terminated normally - $$ " >> spool/LOG Mark the program executable: chmod +x net.out This will ensure that although the system will still have defects that are "linked to" other production sites, modifications to those defects on the test site will *not* be propagated to the real site. ---------------------------------------------------------------------------- Part 3: Moving/Copying the DDTS Site to a New Machine To implement the new DDTS installation on the new machine, there are three basic methods; choose the one most appopriate to meet your needs: Method #3A: Shut down DDTS, move it, and reactivate it - Advantages: Simplicity! Documented in the manual; relatively quick. - Disadvantages: Production users will be out of service while you shut down, port, and reactivate; also this procedure makes no accomodation for testing the new installation prior to disabling the old one. Method #3B: Copy your DDTS installation to the new machine, then modify it to be distinct from the old installation. - Advantage: Easier and more reliable inclusion of all your site's locally-customized components into the new system. - Disadvantage: Requires a short interruption of service to production users. Unless you really need to test your new site for a significant period of time (longer than your users will tolerate being out-of-service), Method #3A is preferable over Method #3B because it has *significantly* fewer steps. Method #3C: Install DDTS on the new site directly from the DDTS CDRom, then migrate your site's customizations and data. - Advantage: Provides a "fresh start" with the new software and lets you exercise great control over which components get migrated forward from the old system. Requires no outage on your production system. - Disadvantages: You will use non-DDTS-standard methods (copying directories) to copy your customizations and other components from the old system to the new; therefore there is a higher likelihood of forgetting a component or leaving the system in an inconsistent state. Unless you are sure you know *exactly* what you are doing with this method, Method #3B is a better choice because it does not require "grafting in" DDTS components from one system to the other. Each method is discussed in more detail below. Method #3A: Shut down DDTS, move it, and reactivate it If you simply want to move your existing DDTS installation to a different machine, that procedure is already documented in the manual: see page 6-5 of the Admin Guide under the heading "Moving the ClearDDTS database". An additional consideration is that you may get a message when running 'ddtsinstall' in step 9, that the directory already contains an installed copy of DDTS. If you get that message, move ~ddts/NEWCLEARDDTS to some other name and rerun ddtsinstall. If you are willing to live with this method's limitations (provides no capability to test the new site before disabling the old; users will see an outage of the production system during the move), this is the best method to use because it has by far the simplest procedure. If you are unable/unwilling to live with these limitations, then continue reading and use Method #3B or #3C. For Methods #3B or #3C, begin by selecting and preparing the target machine (the machine to host the new installation): - The target machine must be a UNIX host separate from the old DDTS server with adequate disk space (use 'du' to get the size of the old installation if necessary, and 'df' to check available space in filesystems on the new server). - Create a local 'ddts' userid with its home directory pointing to the new installation, as described in Part 1 of this FAQ. - Make sure there is no crontab entry for user 'ddts' (i.e. make sure there isn't one left-over from a previous DDTS installation on this machine). You will properly establish the crontab entry for the new system later, but for now make sure there isn't one (see if there is one using 'crontab -l', and if you find one remove it with 'crontab -r'). Method #3B: Copy your DDTS installation to the new machine, then modify it to be distinct from the old installation. - Prepare the source machine: - If the old and new machines are different architectures, install the DDTS platform binaries for the new machine into the old installation. - Put the old site into maintenance mode to facilitate a "clean"" copy: "adminbug smnt"" - Copy the installation: Log in to new host as 'ddts' cd ~ddts (cd /path_to_old_installation ; tar cpf - .) | tar xvpBf - - Put old site back into operation ("adminbug emnt") - Modify the new installation to be separate from the old one: - Take steps to "isolate" your test system from your production system to ensure that it does not inadvertently "steal" mail or participate in DDTS remote-site project sharing: - Set up the conf/mailfile as described in Part 2 of this FAQ. - Rename the conf/imports and conf/exports files to ensure that no DDTS projects from this site will be visible to other sites (e.g., rename import to import.SAVE, and export to export.SAVE). - Disable the net.out daemon as described in Part 2 under the heading "Issue: Email with Copied Defects". - Run the command "ddtsinstall" to redo certain steps of the initial installation. NOTE: In order for ddtsinstall to redo *all* the steps for installation, you must touch ~ddts/conf/status before running ddtsintall. - Enter a *different* site ID than the production machine, so that any defects you create on the test system will be easy to distinguish from real production defects. - Re-enter your license information from your License Certificate. Method #3C: Install DDTS on the new site directly from the DDTS CDRom, then migrate your site's customizations and data. NOTE: This procedure requires detailed knowledge of DDTS's filesystem structure and its mechanisms for storing class/project/defect data. If you are unsure how these structures work, Method #3B (described above) would be a better choice. Perform the following steps to establish a test site using this method: - Begin installing DDTS from the CDRom using the installation process as documented in the Installation & Licensing Guide (Chapter 1). Proceed only as far as the 'tar' commands in step 4 under "Extracting the Software". **STOP** before you get to the the step where you run the 'ddtsinstall' script and perform the following: - Create NEWCLEARDDTS/conf/mailfile as described in Part 2 above. This will ensure that when you complete your installation, the test installation will not "steal" mail from the production installation. - "Graft in" components of your old system by copying them to the new system. Specifically, you will need to copy class and project definitional data for any classes and projects you are carrying over, and defect files for any defects in those projects that you want to carry over for testing. To do this, identify the items (classes, projects, and defects) you want from the old system, and copy them to corresponding locations below the NEWCLEARDDTS directory on the new sytem: From here Item on the old system... To here on the new system... ======= ======================== ================================== Class class/CLASSNAME NEWCLEARDDTS/class/CLASSNAME Project projects/PROJECTNAME NEWCLEARDDTS/projects/PROJECTNAME Defect allbugs/NN/BUGno12345 NEWCLEARDDTS/allbugs/NN/BUGno12345 Note: All pathnames are relative to the 'ddts' user's home directory on the respective site. Note: For classes and projects, the indicated component is a whole directory (make sure to copy its subdirectories too!). For defects, identify the specific file that contains that defect's data by examining the defect ID. Defects are stored in files whose filename is the same as the defect ID, in a directory whose pathname is ~ddts/allbugs/NN, where "NN" is the last two digits of the defect ID. So for the example shown above (defect ID "BUGno12345"), the full path to the defect file would be ~ddts/allbugs/45/BUGno12345. - Disable the net.out daemon as described in Part 2 under the heading "ISSUE: Email with Copied Defects". - Resume the normal installation process as documented under "Running the Installation Script"", making sure to enter a *different* site ID than the production machine, so that any defects you create on the test system will be easy to distinguish from real production defects. This procedure is simplest if you follow the steps listed above and "graft in" the desired components from the old system prior to running ddtsinstall on the new system. If you should need to copy additional components after the new system has been installed, follow these procedures: To copy a class: Log in to the new host as 'ddts' cd ~ddts (cd /path_to_old_installation ; tar cpf - class/CLASSNAME) | \ tar xvpBf - projstat -a If desired, you could move several classes at once by specifying multiple paths on the first tar command. To copy a project: Log in to the new host as 'ddts' cd ~ddts (cd /path_to_old_installation ; \ tar cpf - projects/PROJECTNAME proj.info/PROJECTNAME) | \ tar xvpBf - Edit the projects/PROJECTNAME/PROJECTNAME file and change the site ID on the Path-to-owner line from the old site ID to the new. projstat -a projck The "projck" command at the end verifies the integrity of the project definitional data. If successful, it does not produce any output. If it outputs any messages these indicate errors in the project file setup and you should correct the errors before proceeding. If desired, you could move several projects at once by specifying multiple paths on the first tar command. To copy defects: Log in to the new host as 'ddts' cd ~ddts (cd /path_to_old_installation ; \ tar cpf - allbugs/NN/BUGno99999) | \ tar xvpBf - adminbug dbms If desired, you could move more than one defect's data by including several pathnames in the first 'tar' command. ---------------------------------------------------------------------------- Part 4: Client Access ClearDDTS client applications (the programs users interact with to manipulate defect data) can be told to "toggle" between several sites rather easily. For UNIX client access (xddts, ddts, findbug, etc): - Have users adjust their path variable to point to the desired site's bin directory. Note that there are several 'bin' directories by UNIX architecture; to select the one appropriate for the client machine on which the user is logged in, use the 'ddts_archdir.sh' program. See the ClearDDTS User's Guide, Appendix B, for details. - Set the environment variable DDTSHOME to point to the top of the DDTS directory tree for the desired site (i.e. ~ddts, as seen from the DDTS server for that site). NOTE: If the old site is older than 4.5, and the new site is 4.5 or above, and you are using the Pure database, the db client software from one release, will not work with the other. In other words, you cannot access your 4.5 or later database with a 4.1 db client (like findbug) by pointing DDTSHOME to the 4.5 db, and vice versa. For more information see the FAQ titled "Why do I get an SQL error when running findbug or ddtssql after upgrading to 4.5?"" Assuming both sites are NFS-accessible from a user's workstation, they can easily "toggle" between the sites by changing their path and DDTSHOME settings. To make the test installation available via the web, establish a second web server as follows: - Select the machine on which the web server will run. The simplest approach is to install a web server locally on the UNIX host you are using for the second DDTS installation. If that is not possible, an acceptable alternative is to install a web server on another machine, and set up a local 'ddts' userid on that machine such that the home address of the userid points to the location of the test DDTS site. - Establish Alias and ScriptAlias definitions in the new server which point to the new installation in the same manner described in the manual (pp.1-8..1-9 of the Installation & Licensing Guide). Users can easily "toggle" between the test and production sites by pointing to the URL for the appropriate site. ------------------------------------------------------------------------------ Part 5: Testing and Cutting Over to Production If you are establishing a test installation so you can test a new DDTS release or major new DDTS customizations, perform those changes on the test site and test them extensively. NOTE: During this phase, you must tightly control modifications to the production system. Any administrative activities like adding or modifying classes, projects, templates, oneofs, etc. will need to be replicated onto the test server. Failure to do so will cause these changes to be lost when you cut over to the new system as described below. To assist in testing, users can "toggle" between the test and production installations as described in Part 4 of this FAQ. When you are satisfied that your changes are operating correctly on the test installation, you are ready to implement them into production. There are two main methods to accomplish this: Port the changes back to the existing production site, or cut users over to the new site so it becomes the production site. Choose one of these methods based primarily on which machine you want to end up with as your production server. These methods are described in more detail below: Method A: Back-port changes to production server To implement your changes in production using this method, for whatever steps you performed on the test system, repeat them on the production system. Depending upon the details of the tasks being performed, it might be appropriate to put the DDTS installation into maintenance mode (adminbug smnt) while performing your changes. You should also alert end-users on UNIX user interfaces (e.g. xddts) to terminate their sessions and restart them after you have made your changes. Method B: Cut users over to the new server To switch to the new server as the production DDTS site, you will need to do the following: - Put the old system into maintenance mode and inform all end-users to shut down any interactive sessions (i.e. xddts, ddts): adminbug smnt -Give it the same site id as the old site: adminbug dsbl adminbug inst -- Respond with the same site ID as the old system; this changes the site ID in the def.seq file (but also resets the sequence number to 00001; see next step) and fixes project ownership in the proj.info and projects files. Copy the file ~ddts/conf/def.seq from the old system to the new -- This resets the sequence number to the same number it left off at on the old host. - If any changes (creation/modification/customization to classes or projects) have been made to the old system since you copied its class and project data in Part 3, reincorporate those changes on the new system by running appropriate adminbug commands (for example, use 'adminbug aprj' to add a new project). If any class customizations (e.g. master.tmpl changes) have been made on the old system, incorporate them onto the new system using tools such as 'diff', 'vi', and 'cp'. NOTE: You will enjoy much better results if you plan ahead for this step by rigidly controlling the changes you allow on the production system after it was copied in Part 3. If any changes must be made, perform them in parallel on the old system and the new, and then test the changes on the new system thoroughly in advance of the cutover to the new system. It is best if there are no additional changes to be made at this point. - If you removed or moved the ~ddts/conf/import and ~/conf/export files in setting up the test site (Part 3), put them back to their production status at this time by copying them from the old system to the new. - To incorporate defect modifications that have been made on the production system after it was copied in Part 3, re-port the defect data from the old system to the new. To do this, remove the allbugs/ and dbms/ directory trees from the new system, then copy the corresponding directories (including all subdirectories!) from the old system: Log in to the new system as 'ddts' cd ~ddts rm -rf allbugs dbms (cd /path_to_old_installation ; tar cpf - allbugs dbms) | tar xvpBf - -- See the 'tar' manpage for information about these options to 'tar' - Adjust the home directory of the DDTS userid, UNIX mounts/automounts, and web server Alias/ScriptAlias definitions using appropriate procedures for your site. Ensure that whatever mechanism your users typically use to access DDTS from UNIX and web clients, that they will now point to the new installation. - If you wish to copy existing user preferences (default class, name, email address, saved queries, etc.) from the old site's WebDDTS installation to the new, follow the instructions that apply to you: Old and New sites 4.5 or later: Copy all files below ~ddts/www/user_prefs/ from the old installation to the the corresponding directory on the new installation. If the relative path to the DDTS home directory as seen by your web server has changed (it probably will change), use the ddts dbm script to adjust the user:PDDTS_HOME value. Old and New sites earlier than 4.5: Copy all files below ~ddts/www/output/ from the old installation to the the corresponding directory on the new installation. If the relative path to the DDTS home directory as seen by your web server has changed (it probably will change), you might need to write a scirpt to adjust the PDDTS_HOME value. (Please continue with Part 2). Rational Customer Service Policies and Information: http://www.rational.com/support/info.jsp