E.2. Admin Server Configuration

The Admin Server is a separate server from Red Hat Directory Server or Red Hat Certificate System, although they work interdependently. The Admin Server processes, file locations, and configuration options are also separate. This chapter covers the Admin Server information, including starting and stopping the Admin Server, enabling SSL, viewing logs, and changing Admin Server configuration properties, such as the server port number.

E.2.1. Directory Server File Locations

Red Hat Admin Server conforms to the Filesystem Hierarchy Standards. For more information on FHS, see the FHS homepage, http://www.pathname.com/fhs/.

There are slight difference in the file locations depending on the platform, so the default Red Hat Enterprise Linux FHS locations (used in the examples) may not match every installation. Some platforms treat the Admin Server as optional software and therefore, under FHS, store Admin Server files in /opt directories.

The files and directories installed with Directory Server are listed in the tables below for each supported platform.

Table E.1. Red Hat Enterprise Linux 4 and 5 (x86 and x86_64)

File or Directory	Location
Log files	`/var/log/dirsrv/admin-serv/`
Configuration files	`/etc/dirsrv/admin-serv/`
Instance directory	`/usr/lib/dirsrv/admin-serv/`
Database files	`/var/lib/dirsrv/admin-serv/`
Runtime files	`/var/lock/dirsrv/admin-serv.` `/var/run/dirsrv/admin-serv.`
Init scripts	`/etc/rc.d/init.d/dirsrv-admin/` `/etc/sysconfig/dirsrv-admin`
Tools	`/usr/bin/` `/usr/sbin/`

E.2.2. Starting and Stopping the Admin Server

The Admin Server is running when the setup-ds-admin.pl configuration script completes. Avoid stopping and starting the server to prevent interrupting server operations.

When starting in SSL, the start script prompts for the password for the security (SSL certificate) database. It is possible to restart in SSL without being prompted for a password by using a password file. See Section E.2.9.4, “Creating a Password File for the Admin Server” for more information.
If there is not password file, then the Admin Server cannot be restarted in SSL through the Console, only the command-line scripts.
Rebooting the host system can automatically start the Admin Server's httpd process. The directory provides startup or run command (rc) scripts. On Red Hat Enterprise Linux, use the chkconfig command to enable the Admin Server to start on boot.

E.2.2.1. Starting and Stopping Admin Server from the Console

Start the Console, and open the Admin Console.

/usr/bin/redhat-idm-console -a http://localhost:9830

In the Tasks tab, click Restart Server or Stop Server.

When the Admin Server is successfully started or stopped from the Console, the server displays a message box stating that the server has either started or shut down.

E.2.2.2. Starting and Stopping Admin Server from the Command Line

There are two ways to start, stop, or restart the Admin Server:

There are scripts in the /usr/sbin directory.
```
/usr/sbin/{start|stop|restart}-ds-admin
```
The Admin Server service can also be stopped and started using system tools on Red Hat Enterprise Linux 6 (64-bit) using the service command. For example:
```
service dirsrv-admin {start|stop|restart}
```
Note
The service name for the Admin Server process on Red Hat Enterprise Linux 6 (64-bit) is dirsrv-admin.

E.2.3. Opening the Admin Server Console

There is a simple script to launch the main Console. On Red Hat Enterprise Linux, run the following:

/usr/bin/redhat-idm-console

When the login screen opens, the Admin Server prompts for the user name, password, and Admin Server location. The Admin Server location is a URL; for a standard connection, this has the http: prefix for a standard HTTP protocol. If SSL/TLS is enabled, then this uses the https: prefix for the secure HTTPS protocol.

Note

It is possible to send the Admin Server URL and port with the start script. For example:

/usr/bin/redhat-idm-console -a http://localhost:9830

The a option is a convenience, particularly for logging into a Directory Server for the first time. On subsequent logins, the URL is saved. If the Admin Server port number is not passed with the redhat-idm-console command, then the server prompts for it at the Console login screen.

This opens the main Console window. To open the Admin Server Console, select the Admin Server instance from the server group on the left, and then click the Open at the top right of the window.

Figure E.3. The Admin Server Console

Note

Make sure that the Oracle Java Runtime Environment (JRE) or OpenJDK version 1.8.0 is set in the PATH before launching the Console. Run the following to see if the Java program is in the PATH and to get the version and vendor information:

java -version

E.2.4. Viewing Logs

Log files monitor activity for Admin Server and can help troubleshoot server problems. Admin Server logs use the Common Logfile Format, a broadly supported format that provides information about the server.

Admin Server generates two kinds of logs:

Access logs. Access logs show requests to and responses from the Admin Server. By default, the file is located at /var/log/dirsrv/admin-servaccess.
Error logs. Error logs show messages for errors which the server has encountered since the log file was created. It also contains informational messages about the server, such as when the server was started and who tried unsuccessfully to log on to the server. By default, the file is located at /var/log/dirsrv/admin-serverror.

The logs can be viewed through Admin Server Console or by opening the log file.

E.2.4.1. Viewing the Logs through the Console

Open the Admin Server management window.
Click the Configuration tab.
Expand the Logs directory, and click the log file name, either Accesses or Error.

E.2.4.2. Viewing Logs in the Command Line

The access log, by default, is at /var/log/dirsrv/admin-servaccess. To view the access log, open it in an editor such as vi.

Access logs show connections to the Admin Server based on the IP address of the client, the user name, and the method that the request was sent. Each line has the following format:

ip_address - bind_DN [timestamp -0500] "GET|POST cgi" HTTP_response bytes

Example logs are shown in Example E.1, “Example Access Logs”.

Example E.1. Example Access Logs

127.0.0.1 - cn=directory manager [23/Dec/2008:19:32:52 -0500] "GET /admin-serv/authenticate HTTP/1.0" 200 338
192.168.123.121 - cn=directory manager [23/Dec/2008:19:33:14 -0500] "POST /admin-serv/tasks/Configuration/ServerSetup HTTP/1.0" 200 244
192.168.123.121 - cn=directory manager [23/Dec/2008:19:33:16 -0500] "GET /admin-serv/tasks/Configuration/ReadLog?op=count&name=access HTTP/1.0" 200 10

The error log, by default, is at /var/log/dirsrv/admin-serverrors. To view the error log, open it in an editor such as vi.

Error logs record any problem response from the Admin Server. Like the access log, error logs also records entries based the client's IP address, along with the type of error message, and the message text:

[timestamp] [severity] [client ip_address error_message

The severity message indicates whether the error is critical enough for administrator intervention. [warning], [error], and [critical] require immediate administrator action. Any other severity means the error is informational or for debugging.

Example logs are shown in Example E.2, “Example Error Logs”.

Example E.2. Example Error Logs

[Mon Dec 22 23:44:59 2008] [notice] [client 127.0.0.1] admserv_host_ip_check: ap_get_remote_host could not resolve 127.0.0.1
[Mon Dec 22 23:44:59 2008] [notice] [client 127.0.0.1] admserv_host_ip_check: host [localhost.localdomain] did not match pattern [*.example.com] -will scan aliases
[Mon Dec 22 23:44:59 2008] [notice] [client 127.0.0.1] admserv_host_ip_check: host alias [localhost] did not match pattern [*.example.com]
[Mon Dec 22 23:44:59 2008] [notice] [client 127.0.0.1] admserv_check_authz(): passing [/admin-serv/authenticate] to the userauth handler
[Mon Dec 22 23:45:16 2008] [notice] [client 192.168.123.121] admserv_host_ip_check: ap_get_remote_host could not resolve 192.168.123.121

E.2.4.3. Changing the Log Name in the Console

The access and error log files' names can be changed to rotate the files. This rotation has to be done manually to create new files if the existing log files become too large.

Open the Admin Server management window.
Click the Configuration tab.
Click Logs in the left panel.
In the Logs window on the right, enter the new log file name.
Warning
The path to the log file is absolute and cannot be changed.
Click OK to save the changes.
Open the Tasks tab, and click the Restart Server button to restart the server and apply the changes.

E.2.4.4. Changing the Log Location in the Command Line

The access and error log files' names and locations can be changed to rotate the files. This rotation has to be done manually to create new files if the existing log files become too large. The location can be changed if the default location in /var/log/dirsrv/admin-serv does not meet the application needs.

The Admin Server configuration is stored in two locations. The main entry is an LDAP entry in the Configuration Directory Server's o=NetscapeRoot database. The other is the console.conf file. Changing the log settings requires changing both settings.

Edit the Admin Server configuration entry in the Configuration Directory Server.

Get the name of the Admin Server entry. Since the Admin Server entry has a special object class, nsAdminConfig, it is possible to search for the entry using that object class to retrieve the DN.

ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -x -b "o=NetscapeRoot" "(objectclass=nsAdminConfig)" dn   

version:1
dn: cn=configuration,cn=admin-serv-example,cn=Red Hat Administration Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot

The Admin Server entry can be edited using ldapmodify. The access and error log settings are stored in the nsAccessLogs and nsErrorLogs attributes, respectively. For example:

ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=configuration,cn=admin-serv-example,cn=Red Hat Administration Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot
changetype:modify
replace:nsAccessLog
nsAccessLog:/var/log/dirsrv/admin-serv/access_new

Hit Enter twice to submit the operation, and then Control+C to close ldapmodify.

Open the Admin Server configuration directory.
```
cd /etc/dirsrv/admin-serv
```
Edit the console.conf file. For the access log, edit the path and filename in the CustomLog parameter. For the error log, edit the path and filename in the ErrorLog parameter.
```
CustomLog /var/log/dirsrv/admin-serv/access_new common
ErrorLog /var/log/dirsrv/admin-serv/error_new
```
Leave the term common after the access log path; this means that the access log is in the Common Log Format.
Restart the Admin Server.
```
service dirsrv-admin restart
```

E.2.4.5. Setting the Logs to Show Hostnames Instead of IP Addresses

By default, the logs show the IP address of the clients which connect to the Admin Server. This is faster for the Admin Server, since it does not have to do a DNS lookup for every connection. It is possible to set the Admin Server to perform a DNS lookup so that host names are used in the logs. Along with being friendlier to read and search, using host names instead of IP addresses also removes some unnecessary error messages about being unable to resolve host names.

To configure the Admin Server to perform DNS lookups:

Edit the console.conf file for the Admin Server.
```
cd /etc/dirsrv/admin-serv
vim console.conf
```
Set the HostnameLookups parameter to on. By default, this is turned off, so that IP addresses are recorded in logs instead of host names.
```
HostnameLookups on
```

E.2.5. Changing the Port Number

The port number specifies where an instance of Admin Server listens for messages.

The default port number for Admin Server is set when the instance is first installed and the configuration script, such as setup-ds-admin.pl, is run. The default port number is 9830, although if that number is in use, then the setup program will use a randomly-generated number larger than 1024 or one can assign any port number between 1025 and 65535.

E.2.5.1. Changing the Port Number in the Console

Open the Admin Server management window.
Click the Configuration tab.
Click the Network tab.
Enter the port number for the Admin Server instance in the Port field. The Admin Server port number has a default number of 9830.
Click OK.
Open the Tasks tab, and click the Restart Server button to restart the server and apply the changes.
Close the Console, and then restart the Console, specifying the new Admin Server port number in the connection URL.

E.2.5.2. Changing the Port Number in the Command Line

The port number for the Admin Server is 9830 by default.

Edit the Admin Server configuration entry in the Configuration Directory Server.

Get the name of the Admin Server entry. Since the Admin Server entry has a special object class, nsAdminConfig, it is possible to search for the entry using that object class to retrieve the DN.

ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -x -b "o=NetscapeRoot" "(objectclass=nsAdminConfig)" dn   

version:1
dn: cn=configuration,cn=admin-serv-example,cn=Red Hat Administration Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot

The Admin Server entry can be edited using ldapmodify. The port number is set in the nsServerPort attribute. For example:

ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=configuration,cn=admin-serv-example,cn=Red Hat Administration Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot
changetype:modify
replace:nsServerPort
nsServerPort:10030

Hit Enter twice to submit the operation, and then Control+C to close ldapmodify.

Open the Admin Server configuration directory.
```
cd /etc/dirsrv/admin-serv
```
Edit the Listen parameter in the console.conf file.
```
Listen 0.0.0.0:10030
```
Restart the Admin Server.
```
service dirsrv-admin restart
```

E.2.6. Setting Host Restrictions

Connection restrictions specify which hosts are allowed to connect to the Admin Server. You can list these hosts by DNS name, IP address, or both. Only host machines listed within the connection restriction parameters are allowed to connect to the Admin Server. This setting allows wildcards within a domain or an IP address range to make setting connection restrictions simpler.

E.2.6.1. Setting Host Restrictions in the Console

Open the Admin Server management window.
Click the Configuration tab.
Click the Network tab.
The Connection Restrictions area displays a list of hosts allowed to connect to the Admin Server. The drop-down list specifies whether the list entries are added by DNS name or by IP address. The list is evaluated first by host names, and then by IP addresses.
Click the Add button to add another host to the list of allowed computers. To add a host name, make sure the drop-down list at the top reads Host Names to allow; to add an IP address, select IP Addresses to allow.
Fill in the host information, either the host ame or an IPv4 or IPv6 address.
The * wildcard can be used to specify a group of hosts. For instance, *.example.com allows all machines in the example.com domain to access the instance. Entering 205.12.*. allows all hosts whose IP addresses begin with 205.12 to access the instance.
When specifying IP address restrictions, include all three separating dots. If you do not, the Admin Server returns an error message.
Click OK to close the Add... dialog box, and then click the Save button to save the new host.
Open the Tasks tab, and click the Restart Server button to restart the server and apply the changes.

To change the information for a host or IP address listed, click the Edit button and change the given information. To remove an allowed host or IP address, select the host from the list, and click Remove. Admin Server.

E.2.6.2. Setting Host Restrictions in the Command Line

Host restrictions sets rules for what network clients can connect to the Admin Server and, therefore, to services which use the Admin Server. There are two kinds of host restrictions, restrictions based on the host or domain name and restrictions based on the IP address.

The Admin Server host restrictions are set in the main configuration entry in the Configuration Directory Server's o=NetscapeRoot database. There are two attributes for setting host restrictions, nsAdminAccessAddresses and nsAdminAccessHosts for IP addresses and host names, respectively.

Note

The Admin Server supports both IPv4 and IPv6 addresses.

The Admin Server entry can be edited using ldapmodify.

To set host restrictions:

Get the name of the Admin Server entry. Since the Admin Server entry has a special object class, nsAdminConfig, it is possible to search for the entry using that object class to retrieve the DN.

ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -x -b "o=NetscapeRoot" "(objectclass=nsAdminConfig)" dn   

version:1
dn: cn=configuration,cn=admin-serv-example,cn=Red Hat Administration Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot

To set IP address-based restrictions, edit the nsAdminAccessAddresses attribute. Either IPv4 or IPv6 addresses can be used.
```
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=configuration,cn=admin-serv-example,cn=Red Hat Administration Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot
changetype:modify
replace:nsAdminAccessAddresses
nsAdminAccessAddresses:72.5.*.*
```
Hit Enter twice to submit the operation, and then Control+C to close ldapmodify.
The nsAdminAccessAddresses value can use wildcards to allow ranges. Either IPv4 or IPv6 addresses can be used.
For example, to allow all IP addresses:
```
nsAdminAccessAddresses:*
```
To allow only a subset of addresses on a local network:
```
nsAdminAccessAddresses:192.168.123.*
```

To set host name or domain-based restrictions, edit the nsAdminAccessHosts attribute.

ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=configuration,cn=admin-serv-example,cn=Red Hat Administration Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot
changetype:modify
replace:nsAdminAccessHosts
nsAdminAccessHosts:*.example.com

Hit Enter twice to submit the operation, and then Control+C to close ldapmodify.

Restart the Admin Server to apply the changes.
```
service dirsrv-admin restart
```

E.2.7. Changing the Admin User's Name and Password

During installation, you are asked to enter a user name and password for the Configuration Administrator, the user authorized to access and modify the entire configuration directory. The Configuration Administrator entry is stored in the directory under the following DN:

uid=userID,ou=Administrators,ou=TopologyManagement,o=NetscapeRoot

The Configuration Administrator's user name and password are managed through the Directory Server and are represented in an LDAP entry; this is described in the Directory Server Administrator's Guide.

During installation, the Configuration Administrator's user name and password are used to automatically create the Administration Server Administrator. This user can perform a limited number of administrative tasks, such as starting, stopping, and restarting servers in a local server group. The Administration Server Administrator is created for the purpose of logging into the Console when the Directory Server is not running.

The Administration Server Administrator does not have an LDAP entry; it exists only as an entity in a local configuration file, /etc/dirsrv/admin-serv/admpw.

Even though they are created at the same time during installation, and are identical at that time, the Configuration Administrator and Administration Server Administrator are two separate entities. If you change the user name or password for one in the Console, the Console does not automatically make the same changes for the other.

The Administration Server Administrator has full access to all configuration settings in the Admin Server. The information for the admin user is set on the Access tab in the Console.

Note

The Admin Server administrator user name and password are stored in the /etc/dirsrv/admin-serv/admpw file. For example:

admin:{SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g=

The password is encrypted and cannot be changed directly in the admpw file. The user name can be changed in this file, but cannot be used to log into the Console unless the password is updated in the Console first. For this reason, it is better to edit the Administration Server Administrator user name and password only through the Admin Server Console.

To change the Administration Server Administrator's ID or password:

Open the Admin Server management window.
Click the Configuration tab.
Click the Access tab.
Change the admin user's name or password. The user name is the ID given for logging into the Admin Server.
Click Save.

E.2.8. Managing SELinux for the Admin Server

SELinux is a security function in Linux that categorizes files, directories, ports, processes, users, and other objects on the server. Each object is placed in an appropriate security context to define how the object is allowed to behave on the server through its role, user, and security level. These roles for objects are grouped in domains, and SELinux rules define how the objects in one domain are allowed to interact with objects in another domain.

SELinux itself is much more complex to manage and implement than what is described here. This section is concerned only with giving the SELinux details for the Administration Server. For more general information about SELinux, see the Red Hat Enterprise Linux 6 Security-Enhanced Linux User Guide.

Note

SELinux is a feature of Red Hat Enterprise Linux and, as such, is covered in the Red Hat Enterprise Linux Scurity-Enhanced Guide at https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Security-Enhanced_Linux/index.html.

E.2.8.1. SELinux Definitions for the Admin Server

SELinux has three different levels of enforcement: disabled (no SELinux), permissive (where the rules are lax), and enforcing (where all rules are strictly enforced). Red Hat Directory Server and the Admin Server have defined SELinux policies that allow them to run as normal under strict SELinux enforcing mode.

By default, the Admin Server runs confined by SELinux policies.

There are two SELinux security contexts that apply to the Admin Server. When the server starts, it starts within its own Admin Server-specific SELinux domain, dirsrvadmin_t, where the Admin Server scripts are confined. However, the Admin Server process is simply the Apache web server daemon, httpd. So, once the Admin Server process is started, it transitions into the existing httpd_t domain on Red Hat Enterprise Linux.

Note

For the Admin Server to start with the process properly confined, it must be started or restarted using the service command. For example:

service dirsrv-admin restart

The start-ds-admin script is not supported by SELinux.

All CGIs invoked by the Admin Server, such as scripts for Admin Express, run in a special confined security domain, httpd_dirsrvadmin_script_t, which is separate from the dirsrvadmin_t or httpd_t domains.

Table E.2, “Summary of Admin Server SELinux Policies” lists the security contexts and domains for the major components of the Admin Server.

Table E.2. Summary of Admin Server SELinux Policies

File Path	Security Context	Description
dirsrvadmin_t Domain
/usr/sbin/[start\|stop\|restart]-ds-admin	dirsrvadmin_exec_t	The Admin Server start, stop, and restart scripts
/etc/dirsrv/admin-serv/*	dirsrvadmin_config_t	Admin Server configuration files, such as `adm.conf`
httpd_dirsrvadmin_script_t Domain
/usr/lib[64]/dirsrv/cgi-bin/*	httpd_dirsrvadmin_script_exec_t	The CGI scripts and files used by Admin Server web services, like Admin Express
httpd_t Domain^[a]
/var/log/dirsrv/admin-serv/*	httpd_log_t	The log files for the Admin Server
/var/run/dirsrv/admin-serv.*	httpd_var_run_t	The PID file for the Admin Server process
Ports 80, 443, and the Admin Server HTTP port (9830 by default)	http_port_t	The ports used by the Apache web server and the Admin Server web services, including the default HTTP and HTTPS Apache ports and whatever the configured HTTP port^[b] for the Admin Server is
^[a] There are more contexts configured by default within the httpd_t domain, but they are not relevant to the Admin Server SELinux policies. ^[b] Only the HTTP port is configured for the Admin Server when it is set up, so only this port is added to the SELinux configuration automatically. The HTTPS port must be added manually, as described in Section 1.10.6, “Labeling SSL/TLS Ports”.

The Admin Server SELinux policies are configured when the server is set up (when setup-ds-admin.pl or register-ds-admin.pl are run). These policies are removed when the Admin Server is uninstalled.

E.2.8.2. Viewing SELinux Policies for the Admin Server

All Admin Server policies are located in /usr/share/selinux/strict/dirsrv-admin.pp. The configured policies can be viewed using the SELinux Administration GUI.

Open the Systems menu.
Open the Administration menu, and select the SELinux Management item.
Note
You can launch the GUI from the command line using system-config-selinux.

To check the version of the Admin Server SELinux policy installed, click the Policy Module link.

To view the policies set on the individual files and processes, click the File Labeling link. To view the policies for the port assignments for the server, click the Network Port link.

E.2.8.3. Labeling SSL/TLS Ports

When the Admin Server is first set up, the given HTTP port is labeled for SELinux (the default is port 9830). However, SSL/TLS is set up separately, after the Admin Server is already configured, so the HTTPS port for the Admin Server is not automatically labeled.

The default HTTPS port, 443, is already labeled as part of the Apache web service policies. If the Admin Server uses a port other than the default for its SSL/TLS connections, however, then an administrator must label the port manually. This can be done in the SELinux administrative interface show in Section 1.10.3, “Viewing and Editing SELinux Policies for the Directory Server”. It can also be done easily using the semanage script.

Use the port subcommand, the -t option to identify the security context, and the -p option to identify the port. The -a option adds the port label. For example:

semanage port -a -t http_port_t -p tcp 1443

To delete a port label, use the -d option. For example:

semanage port -d -t http_port_t -p tcp 1443

E.2.8.4. Starting the Admin Server Confined by SELinux

The Admin Server's httpd process initially starts in its own dirsrvadmin_t, and then transitions to the http_t domain after starting. This daemon only runs confined in the appropriate SELinux policies when the service command is used to run the Admin Server.

service dirsrv-admin start|stop|restart

E.2.9. Working with SSL

The Admin Server can run over HTTPS (secure HTTP) if SSL is enabled on the server. There are steps to enabling SSL:

Generating and submitting a certificate request.
Receiving and installing the certificate.
Trusting the certificate authority (CA) which issued the certificate.
Changing the Admin Server configuration to allow SSL connections.

E.2.9.1. Requesting and Installing a Server Certificate

The Admin Server Console has a tool, the Certificate Request Wizard, which generates a valid certificate request to submit to any certificate authority (CA).

In the Admin Server Console, select the Tasks tab, and click Manage Certificates.
Create a certificate request.
1. Select the Server Certs tab, and click the Request button.
  Click Next.
2. Enter the Requester Information in the blank text fields, then click Next.
  - Server Name. The fully qualified host name of the Directory Server as it is used in DNS and reverse DNS lookups; for example, server.example.com. The server name is critical for client-side validation to work, which prevents man-in-the-middle attacks.
    Important
    This must be a valid host name that can be resolved correctly by all Admin Server clients, or TLS/SSL will not work.
  - Organization. The legal name of the company or institution. Most CAs require this information to be verified with legal documents such as a copy of a business license.
  - Organizational Unit. Optional. A descriptive name for the organization within the company.
  - Locality. Optional. The company's city name.
  - State or Province. The full name of the company's state or province (no abbreviations).
  - Country. The two-character abbreviation for the country's name (ISO format). The country code for the United States is US.
3. Enter the password that used to protect the private key, and click Next.
  The Next button is grayed out until a password is supplied.

The Request Submission dialog box provides two ways to submit a request: directly to the CA (if there is one internally) or manually. To submit the request manually, select Copy to Clipboard or Save to File to save the certificate request which will be submitted to the CA.

To submit the request to a CA manually, either email it or use the web form for the CA, if one is available. Copy the certificate request information and submit it using the appropriate method.

-----BEGIN NEW CERTIFICATE REQUEST----- 
MIIBrjCCARcCAQAwbjELMAkGA1UEBhMCVXMxEzARBgNVBAgTCkNBTElGT1J 
OSUExLDAqBgVBAoTI25ldHNjYXBlIGNvbW11bmljYXRpb25zIGNvcnBvcmF 
0aW9uMRwwGgYDVQQDExNtZWxsb24ubmV0c2NhcGUuY29tMIGfMA0GCSqGSI 
b3DQEBAQUAA4GNADCBiQKBgQCwAbskGh6SKYOgHy+UCSLnm3ok3X3u83Us7 
ug0EfgSLR0f+K41eNqqRftGR83emqPLDOf0ZLTLjVGJaH4Jn4l1gG+JDf/n 
/zMyahxtV7+mT8GOFFigFfuxaxMjr2j7IvELlxQ4IfZgWwqCm4qQecv3G+N 
9YdbjveMVXW0v4XwIDAQABoAAwDQYK 
------END NEW CERTIFICATE REQUEST-----

Wait for the CA to respond with the server certificate; this can be as short as a few hours for an internal CA or as long as several weeks for a third-party CA.
Save the issued certificate to a file.
Note
Keep a backup of the certificate data in a safe location. If the system ever loses the certificate data, the certificate can be reinstalled using the backup file.
Install the certificate.
1. Select the Tasks tab, and click Manage Certificates.
2. Select the Server Certs tab, and click Install.
3. Give the absolute path to the certificate (In this file radio button) or paste the certificate text in the text box (In the following encoded text block radio button), then click Next.
4. Check that the certificate information displayed is correct, and click Next.
5. Name the certificate, and click Next.
6. Provide the password that protects the private key. This password is the same as the one provided in step c.

After installing the server certificate, configure the Admin Server to trust the CA which issued the server's certificate.

E.2.9.2. Installing a CA Certificate

To configure the Admin Server to trust the CA, obtain the CA's certificate and install it into the server's certificate database. Some commercial CAs provide a web site that allow users to automatically download the certificate, while others will email it back to users.

After receiving the CA certificate, use the Certificate Install Wizard to configure the Admin Server to trust the CA.

In the Admin Server Console, select the Tasks tab, and click Manage Certificates.
Go to the CA Certs tab, and click Install.
If the CA's certificate is saved to a file, enter the path in the field provided. Alternatively, copy and paste the certificate, including the headers, into the text box. Click Next.
Click Next to move through the panels that show the CA certificate information and the certificate name.
Select the purpose of trusting this certificate authority; it is possible to select both options:
- Accepting connections from clients (Client Authentication). The server checks that the client's certificate has been issued by a trusted certificate authority.
- Accepting connections to other servers (Server Authentication). This server checks that the directory to which it is making a connection (for replication updates, for example) has a certificate that has been issued by a trusted certificate authority.
Click Done.

After installing the CA certificate, it is listed in the CA Certificates tab in the Console.

Note

If a CA certificate is incorrectly generated, it is listed in the Server Certificates tab in the Console rather than the CA Certificates tab. The certificate still works as a CA certificate, even though it is listed in the wrong tab.

Still, request certificates from a real certificate authority to minimize the risk of using an incorrectly generated certificate and breaking SSL/TLS in the Admin Server.

E.2.9.3. Enabling SSL

Open the Admin Server management window.
Click the Configuration tab.
Click the Encryption tab.
Select the Enable SSL for this server check box.
Select the Use this cipher family: RSA check box.
Choose the security device where the key is stored. By default, the key is stored in the local key database, Internal (Software-based). If the key is stored on an external device (such as a smart card), select that device from the menu.
Choose the server certificate to use with SSL.
The certificates available in the token certificate database are listed in the drop-down menu.
Click the Settings button to set the ciphers that the Admin Server accepts for SSL/TLS connections.
Set whether to require client authentication to the Admin Server. Client authentication means that the server checks that the client's certificate has been issued by a trusted CA.
Click Save.

E.2.9.4. Creating a Password File for the Admin Server

Normally, if SSL is enabled, the server prompts for a security password when the Admin Server is restarted:

Starting dirsrv-admin:
Please enter password for "internal" token:

The Admin Server can use a password file when TLS/SSL is enabled so that the server restarts silently, without prompting for the security password.

Warning

This password is stored in clear text within the password file, so its usage represents a significant security risk. Do not use a password file if the server is running in an unsecured environment.

Open the Admin Server configuration directory.
```
cd /etc/dirsrv/admin-serv
```
Create a password file named password.conf. The file should include a line with the token name and password, in the form token:password. For example:
```
internal:secret
```
For the NSS software crypto module (the default software database), the token is always called internal.
The password file should be owned by the Admin Server user and set to read-only by the Admin Server user, with no access to any other user (mode 0400).
Note
To find out what the Admin Server user ID is, run grep in the Admin Server configuration directory:
```
cd /etc/dirsrv/admin-serv

grep \^User console.conf
```

In the /etc/dirsrv/admin-serv directory, edit the nss.conf file to point to the location of the new password file.

#   Pass Phrase Dialog:
#   Configure the pass phrase gathering process.
#   The filtering dialog program (`builtin' is a internal
#   terminal dialog) has to provide the pass phrase on stdout.
NSSPassPhraseDialog  file://etc/dirsrv/admin-serv/password.conf

Restart the Admin Server. For example:
```
service dirsrv-admin restart
```

After TLS/SSL is enabled, then the Admin Server can only be connected to using HTTPS. All of the previous HTTP (standard) URLs for connecting to the Admin Server and its services no longer work. This is true whether connecting to the Admin Server using the Console or using a web browser.

E.2.10. Changing Directory Server Settings

The Admin Server stored information about the Directory Server Configuration Directory (which stores the instance configuration information) and the Directory Server User Directory (which stores the actual directory entries). These can be the same directory instance, but they do not have to be. The settings for both of those databases can be edited in the Admin Server configuration so that it communicates with a different Directory Server instance.

E.2.10.1. Changing the Configuration Directory Host or Port

Configuration data are stored under o=NetscapeRoot in the Configuration Directory. The configuration database contains server settings such as network topology information and server instance entries. When server configuration changes are stored in the configuration directory subtree.

Warning

Changing the Directory Server host name or port number impacts the rest of the servers in the server group. Changing a setting here means the same change must be made for every server in the server group.

Open the Admin Server management window.
Click the Configuration tab.
Click the Configuration DS tab.
Set the Configuration Directory Server connection information.
- The LDAP Host is the host name, IPv4, or IPv6 address of the Configuration Directory Server machine.
- The LDAP Port is the port number to use for the Directory Server instance. The regular LDAP port is 389; the default LDAPS (secure) port number is 636.
- Check the Secure Connection check box to use the secure port. Before checking this box, make sure that the Configuration Directory Server has enabled SSL.
Click Save.

E.2.10.2. Changing the User Directory Host or Port

The user directory is used for authentication, user management, and access control. It stores all user and group data, account data, group lists, and access control instructions (ACIs).

There can be multiple user directories in a single deployment because using multiple user directories enhances overall performance for organizations which are geographically spread out, which have high usage, or have discrete divisions which benefit from individual directories.

Admin Server can be configured to authenticate users against multiple user directories.

To change the information for the user directory:

Open the Admin Server management window.
Click the Configuration tab.
Click the User DS tab.
Set the User Directory Server connection information.
Edit the user directory information.
The Use Default User Directory radio button uses the default user directory associated with the domain. To use multiple Directory Server instances or to use a different instance, select the Set User Directory radio button and set the required information:
- The LDAP Host and Port field specifies the location of the user directory instance, using the format hostname:port or ip_address:port, with an IPv4 or IPv6 address.
  It is possible to configure multiple locations for the user directory for authentication and other directory functions; separate each location with a space. For example:
```
server.example.com:389 alt.example.com:389
```
  Note
  If more than one location is given in the LDAP Host and Port field, the settings for the remaining fields will apply to all of those instances.
- Check the Secure Connection box to use SSL to connect to the user directory. Only select this if the Directory Server is already configured to use SSL.
- Give the User Directory Subtree. For example:
```
dc=example,dc=com
```
  Every location listed in the LDAP Host and Port field must contain that subtree and the subtree must contain the user information.
- Optionally, enter the Bind DN and Bind Password for the user which connects to the user directory.
Click Save.

Where did the comment section go?

Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.