Bundling ADAM

Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2

You can bundle Active Directory Application Mode (ADAM) with your application by having the Windows Installer package that you create for your application optionally install ADAM and then create an ADAM instance.

If your application installation package installs ADAM as part of its installation routine, it must be able to detect which version of Windows is running on the target computer, whether ADAM is installed on that computer, and, if so, what is the version of ADAM that is installed.

If your application is being installed on Microsoft Windows Server 2003 R2, your installation package must determine whether ADAM has been installed on that computer. If it has, then your application installation package need only run %windir%\ADAM\Adaminstall.exe to create the ADAM instance to be used by your application. If on the other hand ADAM has not been installed, your application installation must use the Optional Component Manager (OCM) to install ADAM before running Adaminstall.exe. To install ADAM on a computer running Windows Server 2003 R2, use the following command:

Sysocmgr /i:sysoc.inf /q /u:script.inf

The specified script file must contain the following:

[components]
adam=on

If your application is being installed on a computer running another version of Windows, your installation package must determine whether ADAM SP1 is installed. If it is not, then your installation package must run Adamsp1.exe to install ADAM SP1 before running Adaminstall.exe to create your application's ADAM instance. If ADAM SP1 is already installed, then your application installation package need only run Adaminstall.exe.

To determine whether the target computer is running Windows Server 2003 R2, call the GetSystemMetrics API with the nIndex parameter set to SM_SERVERR2 (80). If the return value is 0 (zero), then the computer is not running Windows Server 2003 R2.

To determine whether ADAM is installed on the target computer, look for any value in the following system registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\ADAM_Shared\VersionMajor

If this value is present, then ADAM is installed.

To determine whether the version of ADAM that is installed is ADAM SP1, look for a value of 1 (one) in the following system registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\ADAM_SP\SP1\Installed

You can create an ADAM instance in one of three ways:

  • Active Directory Application Mode Setup Wizard

  • Unattended ADAM install

  • Progress Mode install

Active Directory Application Mode Setup Wizard

When Adamsp1.exe is run, it installs the Active Directory Application Mode Setup Wizard. The Active Directory Application Mode Setup Wizard guides the user through creating an ADAM instance by using a series of wizard pages. To start the Active Directory Application Mode Setup Wizard from your application’s Windows Installer package, you must start Adamsp1.exe and then run Adaminstall.exe from within the package. You can start Adamsp1.exe and Adaminstall.exe from your application’s Windows Installer package through a custom action. The custom action can be scheduled to run at a certain point during application setup, or it can be triggered by means of an event, such as the user clicking a button. Custom actions can be set to return control upon completion, or they can be set to run asynchronously. To ensure that the user completes the ADAM installation before proceeding with the installation of your application, you must set the custom action to return control upon completion.

Unattended ADAM Install

An ADAM instance can be installed in an unattended (or “silent”) mode that does not require input from the user. An unattended install of ADAM is accomplished by providing a text answer file to Adaminstall.exe that contains all the necessary configuration options for the ADAM instance that is to be installed. If these options are known at the time that you write the Setup program for your directory-enabled application, a fixed version of the answer file may be included as part of your application’s Setup. However, if user input will be used to modify any of the ADAM Setup options during installation of your application, the answer file must be created dynamically and provided to Adaminstall.exe after the options have been specified by the user. A typical ADAM unattended install flow includes the following six steps:

The Windows Installer package writes configuration options to a text answer file.

  1. If needed, the Windows Installer package starts Adamsp1.exe and Adamsp1.exe decompresses ADAM files.

  2. The Windows Installer package displays the ADAM EULA.

  3. The Windows Installer package starts Adaminstall.exe.

  4. Adaminstall.exe reads installation options from the answer file.

Invoking Adaminstall.exe with the /answer parameter causes ADAM Setup to retrieve the installation settings from the specified answer file, as shown in the following example:

adaminstall /answer:answer.txt

The following is a sample answer file that installs a unique ADAM instance:

 [ADAMInstall]

; The following line specifies to install a unique ADAM instance.
InstallType=Unique

; The following line specifies the name to be assigned to the new 
; instance.
InstanceName=MyAppInstance

; The following line specifies the TCP port to use for LDAP.
LocalLDAPPortToListenOn=1129

; The following line specifies the port to use for SSL.
LocalSSLPortToListenOn=1130

; The following line specifies an application partition to create
NewApplicationPartitionToCreate="CN=Partition4,DC=cohovineyard"

; The following line specifies the directory to use for ADAM data 
; files.
DataFilesPath=C:\Program Files\Microsoft ADAM\MyAppInstance \data

; The following line specifies the directory to use for ADAM log files.
LogFilesPath=C:\Program Files\Microsoft ADAM\MyAppInstance \logs

Displaying the ADAM EULA

The command shown above installs an ADAM instance silently, but it does not allow the application Setup to display the ADAM EULA. To allow the application Setup to display the ADAM EULA, you must have previously incorporated the ADAM EULA into your application’s Setup. To obtain the ADAM EULA, the ADAM files must be extracted to a known location, as shown in the following example:

adamsp1 /t:"%temp%\adamfiles" 

After it is extracted, the ADAM EULA can be imported into the application Setup for display. The command shown above can be used during the application Setup to extract the ADAM Setup files. If the user accepts the EULA, ADAM installation can be continued by running Adaminstall.exe.

Customizing ADAM Options

If you want the ADAM instance to be customized by the user during the application setup, the answer file must be written to disk with the required options before Adaminstall.exe is run. The following table lists the valid answer file parameters that are accepted by an ADAM install when it is run in unattended mode.

Parameter Possible Values

InstallType

Unique — Create a unique instance of ADAM.

Replica — Create an instance of ADAM by replicating all or part of an existing ADAM instance.

Tools — Install ADAM tools only.

Any other value — Return an error message.

ShowOrHideProgressGUI

Show — ADAM Setup displays progress information during installation.

Hide — ADAM Setup does not display progress information during installation.

InstanceName

A valid Domain Name System (DNS) host name label, with a maximum of 63 UCS Transformation Format 8 (UTF-8) bytes.

“” (empty string) — The instance will be named Instance n, where n is the lowest number greater than 0 such that Instance n is unique on the local computer.

Any other value — Return an error message.

ApplicationPartitionsToReplicate

Specifies the distinguished names of the application partitions to replicate from the source ADAM instance. The following example specifies three application partitions to replicate:

ApplicationPartitionsToReplicate=”CN=my,O=partition” “DC=partition2” “CN=embed qu\”ote in DN”

To replicate all application partitions from the source ADAM instance, specify “*” as the value. Any value that is specified for ApplicationPartitionsToReplicate is ignored if InstallType is not set to Replica.

ReplicationDataSourcePath

Specifies the directory path to a restored copy of ADAM data. Any value that is specified for ReplicationDataSourcePath is ignored if InstallType is not set to Replica or if a value is not also specified for ReplicationLogSourcePath.

ReplicationLogSourcePath

Specifies the directory path to the log file for a restored copy of ADAM data. Any value that is specified for ReplicationLogSourcePath is ignored if InstallType is not set to Replica or if a value is not also specified for ReplicationDataSourcePath.

ReplicateOnlySpecifiedPartitions

Yes — Replicate only application partitions that are specified by ApplicationPartitionsToReplicate.

No — Replicate all application partitions from the replication source, ignoring any value that is set for ApplicationPartitionsToReplicate.

LocalLDAPPortToListenOn

389, or any unused port number between 1025 and 65535, inclusive.

Any other value — Return an error message.

LocalSSLPortToListenOn

636, or any unused port number between 1025 and 65535, inclusive.

Any other value — Return an error message.

SourceServer

Valid DNS name, network basic input/output system (NetBIOS) name, or Internet Protocol (IP) address.

Any other value — If InstallType is Replica, return an error message. Else, do nothing.

SourceLDAPPort

Either 389 or a number between 1025 and 65535.

Any other value — If InstallType is Replica, return an error message. Else, do nothing.

NewApplicationPartitionToCreate

A valid distinguished name — Creates an application partition with the specified name.

“” (empty string) — No new application partition will be created.

Any other value — If InstallType is Unique, return an error message. Else, do nothing.

DataFilesPath

A syntactically correct path name, which may include unresolved environment variables that do not contain existing ADAM files.

Any other value — Return an error message.

LogFilesPath

A syntactically correct path name, which may include unresolved environment variables that do not contain existing ADAM files.

Any other value — Return an error message.

ServiceAccount

A valid DNS domain name, followed by a backslash and the account or group name.

A valid NetBIOS domain name, followed by a backslash and the account name.

A valid user principal name (UPN).

A valid account name only (generally, not recommended, because resolving an account name that is not accompanied by a domain name requires additional processing).

Any other value — Return an error message.

AddPermissionsToServiceAccount

Yes — ADAM Setup attempts to add the Logon as a service right to the account that is specified as the service account.

Any other value — ADAM Setup does not attempt to add the Logon as a service right to the account that is specified as the service account.

ServicePassword

Any string of characters, including the empty string.

Administrator

A valid DNS domain name, followed by a backslash and the account name.

noteNote
Do not specify built-in groups or built-in accounts, such as DOMAIN\Administrators. Instead, if you want to specify a group, specify a domain group, such as domainname\Domain Admins, where domainname represents the name of your domain.

A valid NetBIOS domain name, followed by a backslash and the account name.

A valid UPN.

A valid account name only — (Generally not recommended, because resolving an account name that is not accompanied by a domain name requires additional processing.)

Any other value — Return an error message.

ShowInAddRemovePrograms

Show — List the ADAM instance in Add or Remove Programs.

Hide — Do not list the ADAM instance in Add or Remove Programs.

ImportLDIFFiles

The names of one or more optional Microsoft-supplied .ldf files (Ms-User.ldf, Ms-InetOrgPerson.ldf, Ms-UserProxy.ldf, and Ms-azman.ldf) that you want to import into the ADAM schema. The file names must be enclosed in double quotation marks and separated by a space, as shown in this example:

"Ms-User.ldf" "Ms-UserProxy.ldf"

SourceUserName

SourcePassword

The user name and password of an account that has administrative rights for an existing configuration set. Use these parameters when installing a replica that will be joined to the configuration set.

Note

The ShowAdamShortcuts parameter is no longer supported.

Progress Mode Install

When your application Windows Installer package starts ADAM Setup in unattended install mode, the user is unaware that ADAM Setup is running, and he or she may think that there is a problem with the application setup. To avoid this, you can specify ShowOrHideProgressGUI=Show in the answer file, as shown in the following example:

; The following line in the answer file will cause a progress dialog to 
; be displayed during the ADAM setup.
ShowOrHideProgressGUI=Show

This parameter causes the ADAM install to display a progress bar during its installation The user has the opportunity to cancel the installation but otherwise can only view the progress of the ADAM installation. After the ADAM installation is complete, control is returned to your application’s Windows Installer package, where the application Setup can continue.