4.6. Silent Setup

Silent setup uses a file to predefine all the Directory Server configuration parameters that are normally supplied interactively with the setup program. The silent functionality allows you to script the setup of multiple instances of Directory Server.

4.6.1. Silent Setup for Directory Server and Admin Server

Silent setup is useful at sites where many server instances must be created, especially for heavily replicated sites that will create a large number of consumer servers. Silent setup uses the same scripts that are used to create instances of Directory Server and Admin Server, with a special option signaling that the script is to be run silently. Silent mode requires referencing a setup parameter file (-s -f setup.inf) or setting Directory Server parameters on the command line.
To run a silent setup of both the Directory Server and Admin Server:
  1. Install the Directory Server packages as in Section 3.1, “Installing the Directory Server Packages”.
  2. Make the setup .inf file. It must specify the following directives: 
    [General] 
FullMachineName= dir.example.com 
SuiteSpotUserID= nobody 
SuiteSpotGroup= nobody 
AdminDomain= example.com 
ConfigDirectoryAdminID= admin 
ConfigDirectoryAdminPwd= admin 
ConfigDirectoryLdapURL= ldap://dir.example.com:389/o=NetscapeRoot 

[slapd] 
SlapdConfigForMC= Yes 
UseExistingMC= 0 
ServerPort= 389 
ServerIdentifier= dir 
Suffix= dc=example,dc=com  
RootDN= cn=Directory Manager 
RootDNPwd= secret
ds_bename=exampleDB 
AddSampleEntries= No

[admin] 
Port= 9830
ServerIpAddress= 111.11.11.11 
ServerAdminID= admin 
ServerAdminPwd= admin
    There are three sections of directives in the .inf file to create the default Directory and Admin Servers: [General], [slapd], and [admin]. Creating an additional instance, or installing a single instance of Directory Server using setup-ds.pl, only requires two sections, [General] and [slapd].

    Important

    Red Hat strongly recommends to change the default Directory Server user values and to create a dirsrv:dirsrv user instead of using the default nobody:nobody user.
    This parameters correspond to the information supplied during a typical setup. The .inf file directives are described more in Section 4.6.5.1, “.inf File Directives”.
  3. Run the setup-ds-admin script with the -s and -f options. 
    # setup-ds-admin.pl -s -f /export/ds-inf/setup.inf
    Running setup-ds-admin installs both the Directory Server instance and the Admin Server instance. This means that the setup file must specify parameters for both the Directory Server and the Admin Server. -s runs the script in silent mode, and -f /export/ds-inf/setup.inf specifies the setup file to use.
After the script runs, the new Directory Server and Admin Server instances are configured and running, as with a standard setup.

4.6.2. Silent Directory Server Instance Creation

Like setting up both the Directory Server and Admin Server, silent setup for a single instance is useful for configuring multiple instances quickly. Silent setup uses the same scripts that are used to create a new instances of Directory Server, with a special option signaling that the script is to be run silently and referencing the setup file to use.
To run a silent setup of a Directory Server instance:

Note

When creating a single instance of Directory Server, the Directory Server packages must already be installed, and the Admin Server must already be configured and running.
  1. Make the setup .inf file. It must specify the following directives: 
    [General] 
FullMachineName= dir.example.com 
SuiteSpotUserID= nobody 
SuiteSpotGroup= nobody 

[slapd] 
ServerPort= 389 
ServerIdentifier= dir 
Suffix= dc=example,dc=com  
RootDN= cn=Directory Manager 
RootDNPwd= secret 
ds_bename=exampleDB
SlapdConfigForMC= Yes 
UseExistingMC= 0 
AddSampleEntries= No
    There are two sections of directives in the instance creation: [General] and [slapd]. Installing the Admin Server, which is done in a default setup file, requires a third parameter as well, [admin], for the Admin Server.

    Important

    Red Hat strongly recommends to change the default Directory Server user values and to create a dirsrv:dirsrv user instead of using the default nobody:nobody user.
    This parameters correspond to the information supplied during a typical setup. The .inf file directives are described more in Section 4.6.5.1, “.inf File Directives”.
  2. Run the setup-ds-admin.pl script with the -s and -f options. 
    # setup-ds-admin.pl -s -f /export/ds-inf/setup-single.inf
    Running setup-ds-admin.pl installs only a Directory Server instance, so the setup file must specify parameters only for the Directory Server. -s runs the script in silent mode, and -f /export/ds-inf/setup.inf specifies the setup file to use.
After the script runs, the new Directory Server instance is configured and running, as with a standard setup.

4.6.3. Sending Parameters in the Command Line

The setup utility, setup-ds-admin.pl, allows settings for all three configuration components — General (host server), slapd (LDAP server), and admin (Admin Server) — to be passed directly in the command line. Command-line arguments correspond to the parameters and values set in the .inf file. The arguments used with setup-ds-admin.pl specify the .inf setup file section (General, slapd, or admin), parameter, and value in the following form: 
section.parameter=value
For example, to set the machine name, suffix, and Directory Server port of the new instance, the command is as follows: 
# setup-ds-admin.pl General.FullMachineName=ldap.example.com “slapd.Suffix=dc=example,dc=com” slapd.ServerPort=389

Note

Passing arguments in the command line or specifying an .inf sets the defaults used in the interactive prompt unless they are used with the s (silent) option.
Argument values containing spaces or other shell special characters must quoted to prevent the shell from interpreting them. In the previous example, the suffix value has a space character, so the entire parameter has to be quoted. If many of the parameters have to be quoted or escaped, use an .inf file instead.
You can use an .inf file in conjunction with command line parameters. Parameters set in the command line override those specified in an .inf file, which is useful for creating an .inf file to use to set up many Directory Servers. Many of the parameters can be the same, such as ConfigDirectoryLdapURL, ones specific to the host, such as FullMachineName have to be unique. For example: 
# setup-ds-admin.pl -s -f common.inf General.FullMachineName=ldap37.example.com slapd.ServerIdentifier=ldap37
This command uses the common parameters specified in the common.inf file, but overrides FullMachineName and ServerIdentifier with the command line arguments.

Note

The section names and parameter names used in the .inf files and on the command line are case sensitive. See Table 1.1, “setup-ds-admin Options” to check the correct capitalization.

4.6.4. Using the ConfigFile Parameter to Configure the Directory Server

The ConfigFile parameter in the .inf is an extremely useful tool to configure the directory from the time it is set up. The ConfigFile parameter specified an LDIF file to import into the directory. Since the ConfigFile parameter can be used multiple times, it is a good idea to have multiple LDIF files so that the individual entries are easy to manage.
The ConfigFile parameter is set in the [slapd] section of the .inf.
For example, to configure a new Directory Server instance as a supplier in replication, ConfigFile can be used to create the replication manager, replica, and replication agreement entries: 
[slapd]
...
ConfigFile = repluser.ldif
ConfigFile = changelog.ldif
ConfigFile = replica.ldif
ConfigFile = replagreement.ldif
...
The LDIF file contains the entry information. For example, the replica.ldif contains the information to configure the new Directory Server instance as a supplier: 
dn: cn=replica,cn=dc=example\,dc=com,cn=mapping tree,cn=config
changetype: add
objectclass: top
objectclass: nsds5replica
objectclass: extensibleObject
cn: replica
nsds5replicaroot: dc=example,dc=com
nsds5replicaid: 7
nsds5replicatype: 3
nsds5flags: 1
nsds5ReplicaPurgeDelay: 604800
nsds5ReplicaBindDN: cn=replication manager,cn=config
For more information on LDIF, see the Directory Server Administrator's Guide.
The ConfigFile parameter can be used to create special user entries like the replication manager, to configure views or classes of service, to add new suffixes and databases, to create instances of the Attribute Uniqueness plug-in, and to set many other configurations for Directory Server.

4.6.5. About .inf File Parameters

With a silent setup, all of the configuration information that is normally supplied interactively with the setup program must be included in the .inf file or passed in the command line with the setup-ds-admin.pl command.

Note

Providing configuration parameters with the setup-ds-admin.pl command is described in Section 1.3, “About the setup-ds-admin.pl Script”.
The .inf file has three sections:
  • General — which supplies information about the server machine; these are global directives that are common to all your Directory Servers.
  • slapd — which supplies information about the specific Directory Server instance; this information, like the port and server ID, must be unique.
  • admin — which supplies information specific to the Admin Server instance; this is not used when creating additional Directory Server server instances or setting up a single Directory Server instance.
The format of the .inf file is as follows: 
[General] 
directive=value 
directive=value 
directive=value 
...
[slapd] 
directive=value
directive=value 
directive=value 
...
[admin]
directive=value 
directive=value 
directive=value
The .inf file directives are explained more in the following sections.

4.6.5.1. .inf File Directives

Table 4.2. [General] Directives

Directive Description Required Example
FullMachineName Specifies the fully qualified domain name of the machine on which you are installing the server. The default is the local host name.

Note

The given host name must be a fully-qualified domain name that can be resolved using gethostname() and then can be reverse-resolved by IP address back to the original host name. If either name resolution attempt fails, then the setup script records a warning message in stdout and in the installation log.
No ldap.example.com
SuiteSpotUserID Specifies the user name as which the Directory Server instance runs. This parameter does not apply to the user as which the Admin Server runs. The default is user nobody on Linux. This should be changed for most deployments. No nobody
SuiteSpotGroup Specifies the group as which the servers will run. The default is group nobody on Linux. This should be changed for most deployments. No nobody
ConfigDirectoryLdapURL Specifies the LDAP URL that is used to connect to your configuration directory. LDAP URLs are described in the Directory Server Administrator's Guide. Yes ldap://ldap.example.com:389/o=NetscapeRoot
AdminDomain Specifies the administration domain under which this Directory Server instance is registered. See Section 1.2.11, “Administration Domain” for more information about administration domains. No example.com
ConfigDirectoryAdminID Specifies the user ID of the user that has administration privileges to the configuration directory. This is usually admin. No admin
ConfigDirectoryAdminPwd Specifies the password for the admin user. Yes  

Table 4.3. [slapd] Directives

Directive Description Required Example
ServerPort Specifies the port the server will use for LDAP connections. For information on selecting server port numbers, see Section 1.2.2, “Port Numbers”. No 389
ServerIdentifier
Specifies the server identifier. This value is used as part of the name of the directory in which the Directory Server instance is installed. For example, if the machine's host name is phonebook, then this name is the default, and selecting it installs the Directory Server instance in a directory labeled slapd-phonebook.
The server identifier must not contain a period (.) or space character.
No phonebook
Suffix Specifies the suffix under which to store the directory data. For information on suffixes, see Section 1.2.9, “Directory Suffix”. No dc=example,dc=com
RootDN Specifies the distinguished name used by the Directory Manager. For information on the Directory Manager, see Section 1.2.6, “Directory Manager”. No cn=Directory Manager
RootDNPwd Specifies the Directory Manager's password.

Important

Do not use curly braces ({}) in the password. The root password is stored in the format {password-storage-scheme}hashed_password. Any characters in curly braces are interpreted by the server as the password storage scheme for the root password. If that text is not a valid storage scheme or if the password that follows is not properly hashed, then the Directory Manager cannot bind to the server.
Yes  
AddOrgEntries If yes, this directive creates the new Directory Server instance with a suggested directory structure and access control. If this directive is used and InstallLdifFile is also used, then this directive has no effect. The default is no. No Yes
AddSampleEntries Sets whether to load an LDIF file with entries for the user directory during configuration. The default is no. No AddSampleEntries = yes
InstallLdifFile Populates the new directory with the contents of the specified LDIF file. Using suggest fills in common container entries (like ou=People). Entering a path to an LDIF file imports all of the entries in that file. No InstallLdifFile = /tmp/entries/myldif.ldif
SchemaFile Lists the full path and file name of additional schema files; this is used if there is custom schema with the old Directory Server. This directive may be specified more than once. No SchemaFile= /tmp/slapd-example/config/custom.ldif
ConfigFile Lists the full path and file name of additional configuration to add to the new dse.ldif. This could include additional suffixes, databases, replication, or other configuration. This directive may be specified more than once. No ConfigFile= /path/to/mysuffix-db-config.ldif
ds_bename Sets the database name to use for the user database. If this is not specified, the default is userRoot. No ds_bename= exampleDB
SlapdConfigForMC Sets whether to store the configuration data in the new Directory Server instance. If this is not used, then the default is yes, meaning the configuration data are stored in the new instance. No SlapdConfigForMC = no
UseExistingMC Sets whether to store the configuration data in a separate Configuration Directory Server. If this is not used, then the default is 0, meaning the configuration data are stored in the new instance. No UseExistingMC = 1

Table 4.4. [admin] Directives

Directive Description Required Example
SysUser Specifies the user as which the Admin Server will run. The default is user nobody on Linux. This should be changed for most deployments. For information as to what users your servers should run, see Section 1.2.5, “Directory Server User and Group”. Yes nobody
Port Specifies the port that the Admin Server will use. The default port is 9830. No 9830
ServerAdminID Specifies the administration ID that can be used to access this Admin Server if the configuration directory is not responding. The default is to use the value specified by the ConfigDirectoryAdminID directive. See Section 1.2.7, “Directory Administrator”. No admin
ServerAdminPwd Specifies the password for the Admin Server user. No  
ServerIpAddress Specifies the IP address on which the Admin Server will listen. Use this directive if you are installing on a multi-homed system and you do not want to use the first IP address for the Admin Server.
Both IPv4 and IPv6 addresses are supported.
No  

4.6.5.2. Sample .inf Files

Example 4.1. .inf File for a Custom Installation

[General]
FullMachineName=         ldap.example.com
SuiteSpotUserID=         nobody
SuiteSpotGroup=          nobody
AdminDomain=             example.com
ConfigDirectoryAdminID=  admin
ConfigDirectoryAdminPwd= Admin123
ConfigDirectoryLdapURL=  ldap://ldap.example.com:389/o=NetscapeRoot
[slapd]
SlapdConfigForMC=        Yes
UseExistingMC=           0
ServerPort=              389
ServerIdentifier=        example
Suffix=                  dc=example,dc=com
RootDN=                  cn=directory manager
RootDNPwd=               Secret123
InstallLdifFile=         suggest
AddOrgEntries=           Yes
[admin]
SysUser=                 nobody
Port=                    9830
ServerIpAddress=         10.14.0.25
ServerAdminID=           admin
ServerAdminPwd=          Admin123

Important

Red Hat strongly recommends to change the default Directory Server user values and to create a dirsrv:dirsrv user instead of using the default nobody:nobody user.

Example 4.2. .inf File for Registering the Instance with a Configuration Directory Server (Typical Setup)

[General] 
FullMachineName= dir.example.com 
SuiteSpotUserID= nobody 
SuiteSpotGroup= nobody 
AdminDomain= example.com 
ConfigDirectoryAdminID= admin 
ConfigDirectoryAdminPwd= admin 
ConfigDirectoryLdapURL= ldap://dir.example.com:25389/o=NetscapeRoot 

[slapd] 
SlapdConfigForMC= No 
UseExistingMC= 1 
UseExistingUG= No 
ServerPort= 18257 
ServerIdentifier= directory 
Suffix= dc=example,dc=com 
RootDN= cn=Directory Manager 
UseReplication= No 
AddSampleEntries= No 
InstallLdifFile= suggest 
AddOrgEntries= Yes 
DisableSchemaChecking= No 
RootDNPwd= admin123 

[admin] 
Port= 33646 
ServerIpAddress= 111.11.11.11 
ServerAdminID= admin 
ServerAdminPwd= admin

Important

Red Hat strongly recommends to change the default Directory Server user values and to create a dirsrv:dirsrv user instead of using the default nobody:nobody user.