E.2. Administration Server Configuration

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

E.2.1. File Locations

See the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.

E.2.2. Opening the Administration 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 Administration Server prompts for the user name, password, and Administration Server location. The Administration Server location is a URL; for a standard connection, this has the http: prefix for a standard HTTP protocol. If TLS is enabled, then this uses the https: prefix for the secure HTTPS protocol.
Login Box

Figure E.2. Login Box

Note

It is possible to send the Administration 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 Administration 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 Administration Server Console, select the Administration Server instance from the server group on the left, and then click the Open at the top right of the window.
The Administration Server Console

Figure E.3. The Administration 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.3. Viewing Logs

Log files monitor activity for Administration Server and can help troubleshoot server problems. Administration Server logs use the Common Logfile Format, a broadly supported format that provides information about the server.
Administration Server generates two kinds of logs:
  • Access logs. Access logs show requests to and responses from the Administration Server. By default, the file is located at /var/log/dirsrv/admin-serv/access.
  • 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-serv/error.
The logs can be viewed through Administration Server Console or by opening the log file.

E.2.3.1. Viewing the Logs through the Console

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

E.2.3.2. Viewing Logs in the Command Line

The access log, by default, is at /var/log/dirsrv/admin-serv/error. To view the access log, open it in an editor such as vi.
Access logs show connections to the Administration 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.157345975 -0500] "GET /admin-serv/authenticate HTTP/1.0" 200 338
192.168.123.121 - cn=Directory Manager [23/Dec/2008:19:33:14.453724501 -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.573485244 -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-serv/errors. To view the error log, open it in an editor such as vi.
Error logs record any problem response from the Administration 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

[24/Mar/2017:11:14:27.110314677 +0100] - NOTICE - ldbm_back_start - total cache size: 417775616 B; 
[24/Mar/2017:11:14:27.165466639 +0100] - INFO - dblayer_start - Resizing db cache size: 1519206400 -> 132562944
[24/Mar/2017:11:14:27.650899322 +0100] - INFO - slapd_daemon - slapd started.  Listening on All Interfaces port 389 for LDAP requests
[24/Mar/2017:11:14:29.620268885 +0100] - WARN - modify_config_dse - Modification of attribute "aci" is not allowed, ignoring!

E.2.3.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.
  1. Open the Administration Server management window.
  2. Click the Configuration tab.
  3. Click Logs in the left panel.
  4. 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.
  5. Click OK to save the changes.
  6. Open the Tasks tab, and click the Restart Server button to restart the server and apply the changes.

E.2.3.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 Administration 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.
  1. Edit the Administration Server configuration entry in the Configuration Directory Server.
    1. Get the name of the Administration Server entry. Since the Administration 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 -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
    2. The Administration 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.
  2. Open the Administration Server configuration directory. 
    # cd /etc/dirsrv/admin-serv
  3. 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.
  4. Restart the Administration Server. 
    # systemctl restart dirsrv-admin.service

E.2.3.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 Administration Server. This is faster for the Administration Server, since it does not have to do a DNS lookup for every connection. It is possible to set the Administration 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 Administration Server to perform DNS lookups:
  1. Edit the console.conf file for the Administration Server. 
    # cd /etc/dirsrv/admin-serv
# vim console.conf
  2. 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.4. Changing the Port Number

The port number specifies where an instance of Administration Server listens for messages.
The default port number for Administration 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.4.1. Changing the Port Number in the Console

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

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

The port number for the Administration Server is 9830 by default.
The Administration 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 port number requires changing both settings.
  1. Edit the Administration Server configuration entry in the Configuration Directory Server.
    1. Get the name of the Administration Server entry. Since the Administration 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 -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
    2. The Administration 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.
  2. Open the Administration Server configuration directory. 
    # cd /etc/dirsrv/admin-serv
  3. Edit the Listen parameter in the console.conf file. 
    Listen 0.0.0.0:10030
  4. Restart the Administration Server. 
    # systemctl restart dirsrv-admin.service

E.2.5. Setting Host Restrictions

Connection restrictions specify which hosts are allowed to connect to the Administration 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 Administration Server. This setting allows wildcards within a domain or an IP address range to make setting connection restrictions simpler.

E.2.5.1. Setting Host Restrictions in the Console

  1. Open the Administration Server management window.
  2. Click the Configuration tab.
  3. Click the Network tab.
  4. The Connection Restrictions area displays a list of hosts allowed to connect to the Administration 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.
  5. 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.
  6. Fill in the host information, either the host name 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 Administration Server returns an error message.
  7. Click OK to close the Add... dialog box, and then click the Save button to save the new host.
  8. 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. Administration Server.

E.2.5.2. Setting Host Restrictions in the Command Line

Host restrictions sets rules for what network clients can connect to the Administration Server and, therefore, to services which use the Administration Server. There are two kinds of host restrictions, restrictions based on the host or domain name and restrictions based on the IP address.
The Administration 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 Administration Server supports both IPv4 and IPv6 addresses.
The Administration Server entry can be edited using ldapmodify.
To set host restrictions:
  1. Get the name of the Administration Server entry. Since the Administration 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 -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
  2. 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.*
  3. 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.
  4. Restart the Administration Server to apply the changes. 
    # systemctl restart dirsrv-admin.service

E.2.6. 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 Red Hat Directory Server Administration 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 Administration Server. The information for the admin user is set on the Access tab in the Console.

Note

The Administration 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 Administration Server Console.
To change the Administration Server Administrator's ID or password:
  1. Open the Administration Server management window.
  2. Click the Configuration tab.
  3. Click the Access tab.
  4. Change the admin user's name or password. The user name is the ID given for logging into the Administration Server.
  5. Click Save.

E.2.7. Working with TLS

The Administration Server can run over HTTPS (secure HTTP) if TLS is enabled on the server. There are steps to enabling TLS:
  1. Generating and submitting a certificate request.
  2. Receiving and installing the certificate.
  3. Trusting the certificate authority (CA) which issued the certificate.
  4. Changing the Administration Server configuration to allow TLS connections.

E.2.7.1. Managing Certificates for Administration Server

To request and install certificates for the Administration Server Console, follow the procedures for the Directory Server Console. See:

Important

If you use:
  • The graphical user interface, perform the steps in the Manage Certificates menu of the Administration Server Console instead of the Directory Server Console.
  • The command line, use the /etc/dirsrv/admin-serv/ instead of the /etc/dirsrv/slapd-instance_name/ directory when you manage the Network Security Services (NSS) database.
E.2.7.1.1. Using the Directory Server Private Key and Certificate for the Admin Server
The Administration Server and Directory Server use different PKI databases. When the Certificate Request Wizard for the Directory Server is passed through, the automatically generated private key is stored in the Directory Server's PKI database. However, because the same private key does not exist in both databases, a certificate issued for one cannot be installed in the other database.
Run the following commands to export the private key and certificate of the Directory Server, and import them into the Administration Server's database:
  1. Shut down the Administration Server: 
    # systemctl stop dirsrv-admin
  2. Shut down the Directory Server: 
    # systemctl stop dirsrv@instance
  3. List the contents of the Directory Server NSS database: 
    # certutil -L -d /etc/dirsrv/admin-serv/

Certificate Nickname                     Trust Attributes
                                         SSL,S/MIME,JAR/XPI

Demo CA                                  CT,,
server-cert                              u,u,u
  4. Export the private key and certificate with the name server-cert from the Directory Server's PKI database: 
    # pk12util -o /tmp/keys.pk12 -n server-cert -d /etc/dirsrv/slapd-instance/
Enter Password or Pin for "NSS Certificate DB":
Enter password for PKCS12 file: 
Re-enter password: 
pk12util: PKCS12 EXPORT SUCCESSFUL
    Enter the Directory Server's key store password, and optionally a new password for the temporarily exported file when prompted.
  5. Import the private key and certificate into the Administration Server's PKI database: 
    # pk12util -i /tmp/keys.pk12 -d /etc/dirsrv/admin-serv/
Enter a password which will be used to encrypt your keys.
The password should be at least 8 characters long,
and should contain at least one non-alphabetic character.

Enter new password: 
Re-enter password: 
Enter password for PKCS12 file:
pk12util: PKCS12 IMPORT SUCCESSFUL
    pk12util asks you to set a password for the Administration Server's key store. If you already had set one to this database before, you are prompted to enter this password instead. If you set a password on the exported file in the previous step, you are additionally asked to enter this one as well.
  6. Delete the temporarily exported file: 
    # rm /tmp/keys.pk12
  7. Trust the Demo CA: 
    # certutil -M -d /etc/dirsrv/admin-serv/ -n "Demo CA" -t CT,,
  8. Start the Directory Server: 
    # systemctl start dirsrv@instance
  9. Start the Administration Server: 
    # systemctl start dirsrv-admin

E.2.7.3. Creating a Password File for the Administration Server

Normally, if TLS is enabled, the server prompts for a security password when the Administration Server is restarted: 
Starting dirsrv-admin:
Please enter password for "internal" token:
The Administration Server can use a password file when TLS 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.
  1. Open the Administration Server configuration directory. 
    # cd /etc/dirsrv/admin-serv
  2. 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 Administration Server user and set to read-only by the Administration Server user, with no access to any other user (mode 0400).

    Note

    To find out what the Administration Server user ID is, run grep in the Administration Server configuration directory: 
    # cd /etc/dirsrv/admin-serv

# grep \^User console.conf
  3. 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
  4. Restart the Administration Server: 
    # systemctl restart dirsrv-admin.service
After TLS is enabled, then the Administration Server can only be connected to using HTTPS. All of the previous HTTP (standard) URLs for connecting to the Administration Server and its services no longer work. This is true whether connecting to the Administration Server using the Console or using a web browser.

E.2.8. Changing Directory Server Settings

The Administration 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 Administration Server configuration so that it communicates with a different Directory Server instance.

E.2.8.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.
  1. Open the Administration Server management window.
  2. Click the Configuration tab.
  3. Click the Configuration DS tab.
  4. 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 TLS.
  5. Click Save.

E.2.8.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.
Administration Server can be configured to authenticate users against multiple user directories.
To change the information for the user directory:
  1. Open the Administration Server management window.
  2. Click the Configuration tab.
  3. Click the User DS tab.
  4. Set the User Directory Server connection information.
  5. 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 TLS to connect to the user directory. Only select this if the Directory Server is already configured to use TLS.
    • 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.
  6. Click Save.