12 Starting and Stopping the Server

This chapter describes the basic procedures to start and stop a server instance. The procedures described in this chapter apply to an Oracle Unified Directory directory server, proxy server, and replication gateway instance.

This chapter includes the following topics:

• Section 12.1, "Starting the Server"

• Section 12.2, "Stopping the Server"

• Section 12.3, "Checking if the Server is Started or Stopped"

• Section 12.4, "Running the Server as a Non-Root User"

12.1 Starting the Server

To start the server, run the start-ds command on UNIX or Linux systems or the start-ds.bat command on Windows systems. By default, the start-ds command starts the server as a background process when no options are specified. You can use the start-ds command with the --nodetach option to run the server as a foreground process. For more information, see Appendix A, "start-ds."

The start-ds command automatically attempts to find the correct Java environment to use when starting the server. You can specify the path to the Java installation, and provide additional options directly to the JVM when the directory server is starting. For more information, see Configuring the Default JVM and Java Arguments in Oracle Fusion Middleware Installation Guide for Oracle Unified Directory.

12.1.1 To Start the Server by Using start-ds

1. Change to the appropriate directory.

   (UNIX, Linux)  $ cd INSTANCE_DIR/OUD/bin
   (Windows)      C:\> cd INSTANCE_DIR\OUD\bat
   

2. Type start-ds.

   (UNIX, Linux)  $ start-ds
   (Windows)      C:\> start-ds
   

12.1.2 To Start the Server as a Foreground Process

1. Change to the appropriate directory.

   (UNIX, Linux)  $ cd INSTANCE_DIR/OUD/bin
   (Windows)      C:\> cd INSTANCE_DIR\OUD\bat
   

2. Type start-ds with -N or --nodetach.

   (UNIX, Linux)  $ start-ds --nodetach
   (Windows)      C:\> start-ds --nodetach
   

   You can stop the directory server by pressing Control-C in the terminal window in which the server is running or by running the stop-ds utility from another window.

12.1.3 To Restart the Server

1. Change to the installation directory.

   (UNIX, Linux)  $ cd INSTANCE_DIR/OUD/bin
   (Windows)      C:\> cd INSTANCE_DIR\OUD\bat 
   

2. Type stop-ds with -R or --restart.

   (UNIX, Linux)  $ stop-ds --restart
   (Windows)      C:\> stop-ds --restart
   

12.1.4 To Start the Server by Using a Script (UNIX/Linux)

The start-ds command provides a "quiet" option (-Q or --quiet) that suppresses output during the startup process unless a significant error occurs. You can use this option in a startup script.

1. Create a shell script and add the following start-ds command.

   INSTANCE_DIR/OUD/bin/start-ds --quiet 
   

2. Run the script.

12.2 Stopping the Server

On any system (whether the server is running in the foreground or the background), or even from a remote system, you can stop the server using one of the following methods. For more information about the stop-ds command, see Appendix A, "stop-ds."

12.2.1 To Stop the Server by Using stop-ds

1. Change to the appropriate directory.

   (UNIX, Linux)  $ cd INSTANCE_DIR/OUD/bin
   (Windows)         C:\> cd INSTANCE_DIR\OUD\bat
   

2. Type stop-ds

   (UNIX, Linux)  $ stop-ds
   (Windows)      C:\> stop-ds
   

12.2.2 To Stop the Server that is Running in the Foreground

This procedure assumes that the directory server is running as a foreground process (using the -N or --nodetach option).

1. Type Control-C in a terminal window on UNIX or in the Command Prompt window on Windows systems to stop the server.

   Alternatively, run the stop-ds command from another window.

12.2.3 To Stop the Server by Using a Script (UNIX/Linux)

The stop-ds command provides a "quiet" option (-Q or --quiet) that suppresses output during the stopping process unless a significant error occurs. You can use this option in a shutdown script.

1. Create a shell script and add the following stop-ds command.

   INSTANCE_DIR/OUD/bin/stop-ds --quiet
   

2. Run the script.

12.3 Checking if the Server is Started or Stopped

At any time, you can check if the server is started or stopped by using the status command.

12.3.1 To Check the Server Status

1. Change to the appropriate directory.

   (UNIX, Linux)  $ cd INSTANCE_DIR/OUD/bin
   (Windows)      C:\> cd INSTANCE_DIR\OUD\bat
   

2. Type status

   (UNIX, Linux)  $ status
   (Windows)      C:\> status
   

12.4 Running the Server as a Non-Root User

Like many network daemons, Oracle Directory Server Enterprise Edition has a setuid capability that allows it to be started as a root user but then drop privileges to run as a user with fewer capabilities. Oracle Unified Directory does not currently include this capability. However, you can install, start, and run the server as a non-root user. Note that the information in this section applies primarily to UNIX-based platforms, because Windows systems do not historically place as many restrictions on non-administrative users.

12.4.1 Reasons for Running the Server as a Non-Root User

In many cases, running the server as a non-root user from the start is a more attractive option and provides greater functionality than the setuid equivalent. Running the server as a non-root user means that administrators do not need root access to the system, which is often desirable from an operational perspective. In addition, more administrative actions can be performed with the server online, because the server can do things that might not have been available after it had dropped root privileges.

The primary reason that servers are typically started and/or run as root users is so that they can listen on a privileged port (namely, ports between 1 and 1024). The standard port for LDAP communication is port 389, and the standard port for LDAPS is 636. On most UNIX-based systems only root users are able to create processes that listen on these ports. There can be other reasons for starting as a root user (for example, the ability to use a larger number of file descriptors), but it is generally easier to configure around these other limitations.

Although the standard LDAP and LDAPS ports are 389 and 636, the server is not required to run on those ports. In some environments, it is common to run the server on ports above 1024 (such as 1389 and 1636) so that it is not necessary to be root to start it. Virtually all LDAP-enabled clients provide the ability to specify the port on which the server is listening. As long as the clients know what port the server is using, any value is allowed. For information about configuring the listen port, see Section 13.1.5.2, "Configuring the LDAP Connection Handler."

12.4.2 How to Run as a Non-Root User on the Standard LDAP Ports

If clients expect the server to be listening on port 389 or 636, other options are still available. The best option, available on Solaris systems from Solaris 10 onwards, is to use the process rights management subsystem (also called least privilege). The privileges subsystem in Solaris makes it possible to give non-root users and roles capabilities normally available only to the root user (much like the Privilege Subsystem allows within the server). In particular, the net_privaddr privilege controls which users can bind to privileged ports If this privilege is granted to a non-root user, that user can bind to privileged ports. To configure a user with this privilege, run the following command, as the root user:

# usermod -K defaultpriv=basic,net_privaddr,sys_resource,-proc_info,-file_link_any oud

This command configures the oud user so that it starts with the basic privilege set (which is what non-root users have by default). The command then adds the net_privaddr and sys_resource privileges, which allow the user to increase the number of file descriptors available, among other things. The command removes the proc_info privilege (which allows the user to see processes owned by other users) and the file_link_any privilege (which allows the user to create hard links to files that they do not own). After running this command, the oud user is able to start the server listening on a privileged port.

Even on systems without a capability like least privilege, it is possible to expose the server on a privileged port such as 389 or 636 without requiring root privileges to be able to start it. One possibility would be to run the server on an unprivileged port and use a directory proxy server listening on the privileged port to forward communication to the server on an unprivileged port. It is also possible to use network hardware to achieve the same purpose or to use firewall rules on the same system. For example, on Linux systems the following commands can be used to redirect traffic targeting port 389 to port 1389:

# iptables --append PREROUTING --table nat --protocol tcp --dport 389 \
  --jump REDIRECT --to-port 1389
# iptables -t nat -A OUTPUT -p tcp --dport 389 -j DNAT --to :1389