# Installation and Upgrade Guide

# Advanced Configuration

This chapter describes the following advanced configuration options for Active Directory IDS:

1. Editing the Web.config File
2. Active Directory Server Query Timeouts
3. Active Directory Errors During GetMembers
4. Copying Help Files to the Image Service

## Editing the Web.config File

There are several configurable settings in the Web.config file that help you avoid some common error cases and define logging parameters. If you want to edit the Web.config file, it can be found in the following location: <install_dir>\ptadaws\6.2\webapp\adaws (for example, C:\bea\alui\ptadaws\6.2\webapp\adaws\Web.config).

### Logging Settings

Within the Web.config file, locate the log4net section. The default settings for the parameters in this section should be sufficient in most cases, but there are several settings that you can change.

The log files created by log4net.dll are self-cleaning based on the following parameters:

- MaximumFileSize- Specifies the maximum size a log file can be before it is rolled over into a new file if RollingStyle is set to Size.
- MaxSizeRollBackups- Sets the number of rolled-over files that are saved.

Additional log4net- Settings are based on these parameters:

- AppendToFile- Determines whether writes to the log file will be appended to the end of the file, or if the file will be overwritten. This should be set to true.
- RollingStyle- Can be set to Size or Date.
- StaticLogFileName- When set to true means that the active file name will always be ADAWSLog.txt. Rollover files will be renamed with .1, .2, .3, and so on extensions. This should be set to true.

With the default settings, the most disk space that will ever be used by logging is 100MB.

The log level can be set to INFO, ERROR, or FATAL. The default setting of INFO provides information that describes when the web service is called and what parameters are provided, as well as logging any failures and their causes. The ERROR setting logs only failures. A setting of FATAL runs silently.

Even with the log level set to INFO, the logging for a single synchronization run never exceeds 10MB.

Note: | The log4net.dll handles all log file creation and deletion. Deleting rollover files that were created by log4net while it is still running causes log4net to fail, and furthermore causes the Active Directory IDS to fail. Because of this, rollover files should not be deleted manually. If they are, restart IIS to ensure that log4net continues to run properly. The rollover files can be viewed and copied without any adverse affect.

### Logging Best Practices

When setting the logging practices, you should not delete or modify the rollover files. You should let log4net handle log file manipulation. The following three sections indicate the best settings for your environment.

#### Choosing An Appropriate Rolling Style

If several synchronization jobs are run a day, you may wish to set the RollingStyle to Size, so that the individual log files do not grow too large. If synchronization jobs are only run once a day or less, you may chose to set the RollingStyle to Date. The log files do not grow too large because they contain one run and the log for a single run never splits between two files (unless the job runs past midnight). If you choose to rollover based on Date, the MaximumFileSize setting does not take affect.

If synchronization jobs are run past midnight, using Date causes the log for a single synchronization job to be split into two files (due to the rollover at midnight). It is therefore recommended to use Size and to set the MaximumFileSize based upon the typical log size for a single run.

### Recommendation for the Number of Rollover Files

The number of rollover files you set for the MaxSizeRollBackups value depends on how much disk space you choose to devote to log files. If RollingStyle is set to Size then it is easy to calculate the amount of space used. It is the MaximumFileSize you set multiplied by the MaxSizeRollBackups value. If you rollover based on Date then you must look at the average size of the log created by a single synchronization run to determine what the total disk space is. If synchronizations are run once a week, then setting MaxSizeRollBackups to 10 provides approximately two months of job histories. If synchronizations are run on a daily basis then you may wish to increase the number of rollover files to keep a history that exceeds ten days.

### Archiving Log Files

You may wish to keep a permanent archive of all the logs on another machine, or simply wish to keep a larger history than the one determined by the MaxSizeRollBackups setting. You can manually copy the files before the rollover limit is reached and they are overwritten. You could also set up a recurring task that copies files to another location. The frequency of this task is determined by the frequency of your synchronization runs, and your logging settings.

Note: | Do not delete or move the rollover files without restarting IIS.

### IIS Session Timeouts

During large synchronizations the portal must create database objects for all the users and groups returned by the Active Directory IDS. This can cause IIS session timeouts between the calls to GetGroups, GetUsers, and GetMembers.

This timeout error can be avoided by increasing the timeout value for the sessionState object. To avoid this large timeout from applying to both authentication calls and synchronization calls, create two directories for the Active Directory IDS. Make a copy of the directory and give it a different name.

In one of the files, set the timeout to a very large minute value for synchronization. In the other file, leave it at the default or decrease it to 5 minutes for authentication.

Create two virtual directories. One directory should point to the physical directory with the large timeout value. This directory is used for the synchronization URL. The other virtual directory points to the physical directory that contains the smaller timeout value. This virtual directory is used for the authentication URL.

For a complete discussion of IIS sessions, refer to the Release Notes.

Note: | The timeout setting in the Web.config should match the session timeout for the virtual directory. See IIS Virtual Directory Settings for details on setting this timeout value.

## Active Directory Server Query Timeouts

There is the potential for an Active Directory server timeout during synchronizations of especially large query bases or difficult query filters. A Microsoft DirectoryServices.dll bug causes this timeout to occur. The effect of this bug is that no exception is thrown, and instead a partial list is returned. Refer to the Release Notes for a full discussion of the consequences. The Microsoft (MS hotfix number Q833789) patch is included in the Active Directory IDS release package.

Once the patch is installed, DirectoryServices.dll correctly passes on the timeout exception to the Web.config file.

At the top, in the configSections, you must uncomment the line with section name = “system.directoryservices”. This line also contains a PublicKeyToken value that must be set. This is the public key for your System.DirectoryServices.dll. To find this key, use the strong name tool s n.exe -T system.directoryservices.dll.

You must also uncomment the system.directoryservices section in the web.config file, and set wait ForPagedSearchData to true. Remember that if you do this, the Active Directory IDS waits and blocks until all results are returned from the Active Directory server.

## Active Directory Errors During GetMembers

Occasionally, Active Directory reports an error when it tries to get the members of a specific group. This error is a result of the server not having access to specific groups from other domains, being temporarily unavailable, or a specific group having a bad membership attribute. Normally these Active Directory errors are caught and passed on by the Active Directory IDS. When the synchronization job encounters this error, it reports a failure and ends.

If you prefer that groups that cause an Active Directory error during GetMembers are simply skipped and allow the job to continue processing other groups, then set the GetMembersActionOnError key to Skip instead of Fail in the Web.config file.

## Copying Help Files to the Image Service

During installation, the following file will be copied to the install directory: <install_dir>\ptadaws\6.2\images\imageserver.tgz (for example, C:\bea\alui\ptadaws\6.2\images\imageserver.tgz).

To copy the Active Directory IDS help files to the Image Service, open the imageserver.tgz file and extract the files to the \ptimages directory on your Image Service, making sure to use folder names.