Step 2: Practice Working with AD LDS Instances

Applies To: Windows Server 2008

Now that you have installed the Active Directory Lightweight Directory Services (AD LDS) server role, you are ready to start working with AD LDS instances. This includes the following tasks:

• Create a new AD LDS instance

• Import data into an AD LDS instance

Create a new AD LDS instance

In AD LDS, a "service instance" (or, simply, "instance") refers to a single running copy of the AD LDS directory service. Multiple instances of AD LDS can run simultaneously on the same computer. Each instance of the AD LDS directory service has a separate directory data store, a unique service name, and a unique service description that is assigned during installation. During AD LDS installation, you have the option of creating an application directory partition if your Lightweight Directory Access Protocol (LDAP) application does not create one for you.

Install a new AD LDS instance by using the Active Directory Lightweight Directory Services Setup Wizard

You can use the Active Directory Lightweight Directory Services Setup Wizard to create AD LDS service instances.

Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. Review details about using the appropriate accounts and group memberships at Local and Domain Default Groups (https://go.microsoft.com/fwlink/?LinkId=83477). By default, the security principal that you specify as the AD LDS administrator during AD LDS setup becomes a member of the Administrators group in the configuration partition.

To create a new AD LDS instance by using the Active Directory Lightweight Directory Services Setup Wizard

1. Click Start, point to Administrative Tools, and then click Active Directory Lightweight Directory Services Setup Wizard.

2. On the Welcome to the Active Directory Lightweight Directory Services Setup Wizard page, click Next.

3. On the Setup Options page, click A unique instance, and then click Next.

4. On the Instance Name page, provide a name for the AD LDS instance that you are installing. This name is used on the local computer to uniquely identify the AD LDS instance.

   For this exercise, accept the default name of instance1, and then click Next.

5. On the Ports page, specify the communications ports that the AD LDS instance uses to communicate. AD LDS can communicate using both LDAP and Secure Sockets Layer (SSL); therefore, you must provide a value for each port.

   For this exercise, accept the default values of 389 and 636, and then click Next.

Note

If you install AD LDS on a computer where either of the default ports is in use, the Active Directory Lightweight Directory Services Setup Wizard automatically locates the first available port, starting at 50000. For example, Active Directory Domain Services (AD DS) uses ports 389 and 636, as well as ports 3268 and 3269 on global catalog servers. Therefore, if you install AD LDS on a domain controller, the Active Directory Lightweight Directory Services Setup Wizard provides a default value of 50000 for the LDAP port and 50001 for the SSL port.

6. On the Application Directory Partition page, you can create an application directory partition (or naming context) by clicking Yes, create an application directory partition. Or, you can click No, do not create an application directory partition, in which case you must create an application directory partition manually after installation.

   For this exercise, click Yes, create an application directory partition.

   Type o=Microsoft,c=US as the distinguished name of this application directory partition, and then click Next.

Note

AD LDS supports both X.500-style and Domain Name System (DNS)–style distinguished names for top-level directory partitions.

Note

If you type an application directory partition name that does not meet the established DNS name conventions or the current schema's rangeUpper constraints, you can proceed to the rest of the steps in the wizard. However, when you attempt to create an AD LDS instance, the wizard displays the following error message:
“Active Directory Lightweight Directory Services could not create the directory partition <name> on the local Active Directory Lightweight Directory Services instance. Ensure that this name is unique.”
where <name> is the application directory partition name that you typed.
Ensure that you type a valid application directory partition name. For more information, see article 909264 (https://go.microsoft.com/fwlink/?LinkID=106629) and article 556086 (https://go.microsoft.com/fwlink/?LinkId=155079) in the Microsoft Knowledge Base.

7. On the File Locations page, you can view and change the installation directories for AD LDS data and recovery (log) files. By default, AD LDS data and recovery files are installed in %ProgramFiles%\Microsoft ADAM\instancename\data, where instancename represents the AD LDS instance name that you specified on the Instance Name page.

   For this exercise, click Next to accept the default file locations.

8. On the Service Account Selection page, you select an account to be used as the service account for AD LDS. The account that you select determines the security context in which the AD LDS instance runs. The Active Directory Lightweight Directory Services Setup Wizard defaults to the Network Service account.

   For this exercise, click Next to accept the Network service account default. Or, if you are installing AD LDS on a domain controller, click This account, and then select a domain user account to use as the AD LDS service account.

9. On the AD LDS Administrators page, you select a user or group to become the default administrator for the AD LDS instance. The user or group that you select will have full administrative control of the AD LDS instance. By default, the Active Directory Lightweight Directory Services Setup Wizard specifies the currently logged on user. You can change this selection to any local or domain account or group on your network.

   For this exercise, click the default value of Currently logged on user, and then click Next.

10. On the Importing LDIF Files page, you can import schema .ldf files into the AD LDS instance.

    For this exercise, import the.ldf files in the following table.

    LDIF file name	Description
    MS-InetOrgPerson.ldf	Contains the definition of the inetOrgPerson LDAP object class.
    MS-User.ldf	Contains user and related classes object definitions.
    MS-UserProxy.ldf	Contains the simple userProxy class object definition.
    MS-UserProxyFull.ldf	Contains the full userProxy class object definition.
    MS-ADLDS-DisplaySpecifiers.ldf	Contains display specifiers. This .ldf file is required for snap-in operations. If you are planning to connect to your AD LDS instance and then manage it through the Active Directory Sites and Services snap-in, import this file now with the Active Directory Lightweight Directory Services Setup Wizard.

Note

AD LDS also allows you to make custom LDAP Data Interchange Format (LDIF) files (in addition to the default LDIF files that are provided with AD LDS) available during AD LDS setup by adding them to the %systemroot%\ADAM directory. You can create custom LDIF files by using ADSchema Analyzer. For more information, see the procedure "To create an LDIF file with ADSchemaAnalyzer" in Step 3: Practice Using AD LDS Administration Tools. Store the custom LDIF file in the %systemroot%\ADAM directory and then run the Active Directory Lightweight Directory Services Setup Wizard to create a new AD LDS instance. Your custom LDIF file will be available in the list of LDIF file names on the Importing LDIF Files page.

11. The Ready to Install page gives you an opportunity to review your installation selections. After you click Next, the Active Directory Lightweight Directory Services Setup Wizard copies files and sets up AD LDS on your computer.

12. When the Active Directory Lightweight Directory Services Setup Wizard finishes installing AD LDS, it displays this message: “You have successfully completed the Active Directory Lightweight Directory Services Setup Wizard.” When the Completing the Active Directory Lightweight Directory Services Setup Wizard page appears, click Finish to close the wizard.

Note

If the Active Directory Lightweight Directory Services Setup Wizard does not complete successfully, an error message describing the reason for the failure appears on the Summary page.

Note

If an error occurs in the Active Directory Lightweight Directory Services Setup Wizard before the Summary page, you can review the error message that appears. In addition, you can click Start, click Run, and then type either of the following:
%windir%\Debug\ADAMSsetup.log
%windir%\Debug\ADAMSsetup_loader.log
The ADAMsetup.log and ADAMsetup_loader.log files contain information that can help you troubleshoot the cause of an AD LDS setup failure.

Performing an unattended install of an AD LDS instance

You can install AD LDS without user intervention. An unattended AD LDS installation requires an answer file (Answer.txt) that contains a set of preconfigured installation options.

Membership in Administrators, or equivalent, is the minimum required to complete this procedure. Review details about using the appropriate accounts and group memberships at Local and Domain Default Groups (https://go.microsoft.com/fwlink/?LinkId=83477). By default, the security principal that you specify as the AD LDS administrator during AD LDS setup becomes a member of the Administrators group in the configuration partition.

To perform an unattended install of an AD LDS instance

1. Using any text editor, create a new text file.

   As an alternative, you can copy and paste the following sample answer file into your answer file.

   [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=MyFirstInstance
   ; The following line specifies the communications port to use for LDAP.
   LocalLDAPPortToListenOn=389
   ; The following line specifies an application partition to create
   NewApplicationPartitionToCreate="o=microsoft,c=us"
   ; The following line specifies the directory to use for ADAM data files.
   DataFilesPath=C:\Program Files\Microsoft ADAM\instance1\data
   ; The following line specifies the directory to use for ADAM log files.
   LogFilesPath=C:\Program Files\Microsoft ADAM\instance1\data
   ; The following line specifies the .ldf files to import into the ADAM schema.
   ImportLDIFFiles="ms-inetorgperson.ldf" "ms-user.ldf"
   

2. Specify the installation parameters that are described in the table that immediately follows this procedure, and then save your answer file.

3. At a command prompt (or in a batch or script file), change to the drive and directory that contains the AD LDS setup files.

   To open a command prompt, click Start, click Run, and type cmd.

4. Type the following command:

   %systemroot%\ADAM\adaminstall.exe /answer:drive:\pathname\filename.txt"
   

   where drive:\pathname\filename.txt represents the drive, path, and file name of your answer file. (The command requires the quotation marks.)

The following table shows the parameters that you can use in an AD LDS answer file. These parameters are not case sensitive. In other words, you can specify either InstallType or installtype in your answer file. However, AD LDS preserves case for the values that you specify for the instancename and servicepassword parameters.

Note

The default behavior occurs if the parameter is not present in the answer file.

Parameter	Description
InstallType Valid for all installations. Optional.	Possible values Unique: creates a unique instance of AD LDS. Replica: creates an instance of AD LDS by replicating all or part of an existing AD LDS instance, either over the network or from restored backup media. When you also specify values in the answer file for the ReplicationDataSourcePath and ReplicationLogSourcePath parameters, and when you set the value for InstallType to Replica, AD LDS setup installs an AD LDS replica instance from restored backup media. If no values for those parameters are present, AD LDS setup installs an AD LDS replica instance over the network. Any other value: AD LDS returns the error message "Invalid installation type specified in InstallType". Default behavior Same behavior as Unique.
ShowOrHideProgressGUI Valid for all installations. Optional.	Possible values Show: AD LDS setup displays progress information during installation. Hide: AD LDS setup does not display progress information during installation. Default behavior Same behavior as Hide.
InstanceName Valid for all installations. Optional.	Possible values An AD LDS instance name must meet the following requirements: It must be unique with respect to other AD LDS instances running on the same computer. It must be no longer than 44 characters. It must use characters only from the ranges of a through z, A through Z, or 0 through 9. Default behavior The AD LDS instance is named Instancen, where n is the lowest number greater than 0 and Instancen is unique on the local computer.
ApplicationPartitionsToReplicate Valid only for replica installations. Optional.	Specifies the distinguished names of the application partitions to replicate from the source AD LDS 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 AD LDS instance, specify a wildcard character (*) as the value. AD LDS ignores any value that you specify for ApplicationPartitionsToReplicate if you do not set the value of InstallType to Replica. Default behavior AD LDS does not replicate application partitions.
ReplicationDataSourcePath Valid only for replica installations. When a value for this parameter is present, AD LDS setup attempts an installation from media. If the value for this parameter is not valid, AD LDS setup writes an error to the setup log.	Specifies the directory path to a restored instance of AD LDS data. AD LDS ignores any value that you specify for ReplicationDataSourcePath if you do not set InstallType to Replica or if you do not also specify a value for ReplicationLogSourcePath. Default behavior AD LDS replicates application data over the network, rather than from a restored backup of an AD LDS instance. If you specify a value for this parameter, but not for ReplicationLogSourcePath, an error occurs.
ReplicationLogSourcePath Valid only for replica installations. When a value for this parameter is present, AD LDS setup attempts an installation from media. If the value for this parameter is not valid, AD LDS setup writes an error to the setup log.	Specifies the directory path to the log file for a restored instance of AD LDS. AD LDS ignores any value that you specify for ReplicationLogSourcePath if you do not set the value of InstallType to Replica or if you do not also specify a value for ReplicationDataSourcePath. Default behavior AD LDS replicates application data over the network, rather than from a restored backup of an AD LDS instance. If you specify a value for this parameter, but not for ReplicationDataSourcePath, an error occurs.
LocalLDAPPortToListenOn Required for all installations.	Possible values 389 or any unused port number between 1025 and 65535, inclusive. Any other value: AD LDS returns the error message "Invalid local LDAP port specified."
LocalSSLPortToListenOn Required for all installations. SourceServer Required for replica installations.	636 or any unused port number between 1025 and 65535, inclusive. Any other value: AD LDS returns the error message "Invalid local SSL port specified." Default behavior The value for the port number defaults to 636. If 636 is not available, the value defaults to the first available port number that is equal to or greater than 50000.
SourceServer Required for replica installations.	Possible values A valid DNS name or NetBIOS name. Any other value: if the value of InstallType is Replica, AD LDS returns the error message "Invalid syntax for replication source server." Default behavior If the value of InstallType is Replica, AD LDS returns the error message "Replication source server not specified.
SourceLDAPPort Required for replica installations.	Possible values 389 or a number between 1025 and 65535. Any other value: if the value of InstallType is Replica, any other value for AD LDS returns the error message "Invalid replication source port specified." Default behavior If the value of InstallType is Replica, AD LDS returns the error message "Replication source port not specified."
NewApplicationPartitionToCreate Valid for installations of new, unique AD LDS instances. Optional.	Possible values A valid distinguished name: creates an application partition with the name that you specify. An empty string (""): does not create a new application partition. Any other value: if the installation type is unique, AD LDS returns the error message "Invalid application partition syntax in NewApplicationPartitionToCreate." Default behavior Same behavior as an empty string ("").
DataFilesPath Valid for all installations. Optional.	Possible values A syntactically correct path name, which may include unresolved environment variables that do not contain existing AD LDS files. Any other value: AD LDS returns the error message "Invalid path in DataFilesPath." Default behavior Store data files in Program Files\Microsoft ADAM\instancename\data.
LogFilesPath Valid for all installations. Optional.	Possible values A syntactically correct path name, which may include unresolved environment variables that do not contain existing AD LDS files. Any other value: AD LDS returns the error message "Invalid path in LogFilesPath." Default behavior Stores log files in Program Files\Microsoft ADAM\instancename\data.
ServiceAccount Valid for all installations. Optional.	Possible values A valid DNS domain name, followed by a backslash, and then the account or group name. A valid NetBIOS domain name, followed by a backslash, and then the account name. A valid user principal name (UPN). A valid account name only. We recommend that you do not use a valid account name only because resolving an account name that is not accompanied by a domain name requires additional processing. Any other value: AD LDS returns the error message "Invalid user specified in ServiceAccount." Default behavior This instance of AD LDS runs under the Network Service account.
AddPermissionsToServiceAccount Valid for all installations. Optional.	Possible values Yes: AD LDS setup attempts to add the logon as a service right to the account that you specify as the service account. Any other value: AD LDS setup does not attempt to add the logon as a service right to the account that you specify as the service account. Default behavior AD LDS setup does not attempt to add the logon as a service right to the account that you specify as the service account.
ServicePassword Valid for all installations. Required, unless ServiceAccount is the Network Service account.	Possible values Any string of characters, including an empty string (""). Default behavior If ServiceAccount is the Network Service account, AD LDS does nothing; otherwise, it returns the error message "No password specified in ServicePassword."
Administrator Valid for all installations. Optional.	Possible values A valid DNS domain name, followed by a backslash, and then the account name. 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 then the account name. A valid UPN. A valid account name only. We recommend that you do not use a valid account name only because resolving an account name that is not accompanied by a domain name requires additional processing. Any other value: AD LDS returns the error message "Invalid user specified in Administrator." Default behavior The currently logged on user has administrator permissions on this instance of AD LDS.
ShowInAddRemovePrograms Valid for all installations. Optional.	Possible values Show: Lists the AD LDS instance in Add or Remove Programs in Control Panel. Hide: Does not list the AD LDS instance in Add or Remove Programs. Default behavior Add or Remove Programs includes the installed AD LDS instance.
ImportLDIFFiles	Possible values The optional .ldf files that you want to import into the AD LDS schema: ms-User.ldf, ms-InetOrgPerson.ldf, ms-UserProxy.ldf, and ms-azman.ldf. The file names must be enclosed in double quotation marks that are separated by a space (" "). Default behavior AD LDS imports none of the optional .ldf files.
SourceUserName SourcePassword Valid for replica installations. Optional.	Possible values The user name and password of an account that has administrative rights for an existing configuration set. Use these parameters when you install a replica that you want to join to the configuration set. Default behavior AD LDS joins the replica to the configuration set by using the credentials of the logged on user.

AD LDS uses the following registry key to return error codes and messages to the caller when you install or uninstall AD LDS: HKLM\Software\Microsoft\Windows\CurrentVersion\ADAM_Installer_Results

AD LDS setup creates this registry key and associated values only if errors or warnings occur. The following table shows values for this registry key.

Key	Contents
ADAMInstallErrorCode	The numeric error code that caused the installer to fail
ADAMInstallErrorMessage	A message that is associated with the install error code
ADAMInstallWarnings	Messages that are associated with the install warnings
ADAMUninstallErrorCode	The numeric error code that caused the uninstall to fail
ADAMUninstallErrorMessage	A message that is associated with the uninstall error code
ADAMUninstallWarnings	Messages that are associated with the uninstall warnings

Import data into an AD LDS instance

You can import data into an AD LDS instance during setup of the instance (using the Importing LDIF Files page in the Active Directory Lightweight Directory Services Setup Wizard) or manually anytime after creation of the instance by using the ldifde command-line tool, which creates, modifies, and deletes directory objects. You can also use ldifde to extend the schema and to export user and group information to other applications or services. For example, you can use ldifde to export directory objects from another directory service and then use ldifde to import the directory objects into an AD LDS instance.

Membership in the AD LDS Administrators group, or equivalent, is the minimum required to complete this procedure. Review details about using the appropriate accounts and group memberships at Local and Domain Default Groups (https://go.microsoft.com/fwlink/?LinkId=83477). By default, the security principal that you specify as the AD LDS administrator during AD LDS setup becomes a member of the Administrators group in the configuration partition.

To import or export directory objects using ldifde

1. Open a command prompt. To open a command prompt, click Start, right-click Command Prompt, and then click Run as administrator.

2. Do one of the following:

   • To import directory objects, at the command prompt, type the following command, and then press ENTER:

     ldifde -i -f <filename> -s <servername>:<port> -m -a <username> <domain> <password>
     

   • To export directory objects, at the command prompt, type the following command, and then press ENTER:

     ldifde -e -f <filename> -s <servername>:<port> -m -a <username> <domain> <password>
     

Parameter	Description
ldifde	Specifies a utility program that supports batch operations that are based on the LDIF file standard.
-i	Performs an import.
-e	Performs an export.
-f	Specifies the file to import or export.
<filename>	The name of the file to import or export.
-s	Specifies the host name and port of the AD LDS instance or other directory service.
<servername>	The host name of the AD LDS instance or other directory service.
<port>	The port for the AD LDS instance or other directory service.
-m	Ignores (that is, does not import or export) attributes that are used only by AD DS. You can use this parameter when you export directory objects from an existing AD DS forest and then import them into AD LDS.
-a	Specifies account credentials. If they are not provided, ldifde uses the credentials of the currently logged on user.
<username>	The user name of the account to be used to bind to the specified directory service.
<domain>	The domain name of the account to be used to bind to the specified directory service.
<password>	The password of the account to be used to bind to the specified directory service.
-h	Allows the importing of passwords using simple authentication and security layer (SASL) encryption.
-c <String1> <String2>	Replaces all occurrences of String1 with String2. With AD LDS, you can use the constants #schemaNamingContext and #configurationNamingContext in place of the distinguished names of the schema directory partition and configuration directory partition when you replace strings in .ldf files.

To view the complete syntax for this command, at a command prompt, type the following command, and then press ENTER:

ldifde /?