Directory Services 7.2.5

Server processes

Start a server

  • Start the server in the background:

    $ start-ds

    Alternatively, specify the --no-detach option to start the server in the foreground.

  • (Linux) If the DS server was installed from a .deb or .rpm package, then service management scripts were created at setup time:

    centos# service opendj start

Starting opendj (via systemctl):                           [  OK  ]
    ubuntu$ sudo service opendj start

$Starting opendj: > SUCCESS.

  • (UNIX) Create an RC script, and use the script to start the server.

    Unless you run DS servers on Linux as root, use the --userName userName option to specify the user who installed the server:

    $ sudo create-rc-script --outputFile /etc/init.d/opendj --userName opendj

$ sudo /etc/init.d/opendj start

    For example, if you run the DS server on Linux as root, you can use the RC script to start the server at system boot, and to stop the server at system shutdown:

    $ sudo update-rc.d opendj defaults

update-rc.d: warning: /etc/init.d/opendj missing LSB information
update-rc.d: see <http://wiki.debian.org/LSBInitScripts>
 Adding system startup for /etc/init.d/opendj ...
   /etc/rc0.d/K20opendj -> ../init.d/opendj
   /etc/rc1.d/K20opendj -> ../init.d/opendj
   /etc/rc6.d/K20opendj -> ../init.d/opendj
   /etc/rc2.d/S20opendj -> ../init.d/opendj
   /etc/rc3.d/S20opendj -> ../init.d/opendj
   /etc/rc4.d/S20opendj -> ../init.d/opendj
   /etc/rc5.d/S20opendj -> ../init.d/opendj

    Alternatively, generate a service file with the --systemdService option, and use systemd to manage the service.

  • (Windows) Register the DS server as a Windows service:

    C:\path\to\opendj\bat> windows-service.bat --enableService

    Manage the service with Windows-native administration tools.

Stop a server

Although DS servers are designed to recover from failure and disorderly shutdown, it is safer to shut the server down cleanly, because a clean shutdown reduces startup delays. During startup, the server attempts to recover database backend state. Clean shutdown prevents situations where the server cannot recover automatically.

Clean server retirement

  1. Before shutting down the system where the server is running, and before detaching any storage used for directory data, cleanly stop the server using one of the following techniques:

    • Use the stop-ds command:

      $ stop-ds

    • (Linux) If the DS server was installed from a .deb or .rpm package, then service management scripts were created at setup time:

      centos# service opendj stop

Stopping opendj (via systemctl):                           [  OK  ]
      ubuntu$ sudo service opendj stop

$Stopping opendj: ... > SUCCESS.

    • (UNIX) Create an RC script, and then use the script to stop the server:

      $ sudo create-rc-script --outputFile /etc/init.d/opendj --userName opendj

$ sudo /etc/init.d/opendj stop

    • (Windows) Register the DS server once as a Windows service:

      C:\path\to\opendj\bat> windows-service.bat --enableService

      Manage the service with Windows-native administration tools.

    Do not intentionally kill the DS server process unless the server is completely unresponsive.

    + When stopping cleanly, the server writes state information to database backends, and releases locks that it holds on database files.

Restart a server

  • Use the stop-ds command:

    $ stop-ds --restart

  • (Linux) If the DS server was installed from a .deb or .rpm package, then service management scripts were created at setup time:

    centos# service opendj restart

Restarting opendj (via systemctl):                         [  OK  ]
    ubuntu$ sudo service opendj restart

$Stopping opendj: ... > SUCCESS.

$Starting opendj: > SUCCESS.

  • (UNIX) Create an RC script, and then use the script to stop the server:

    $ sudo create-rc-script --outputFile /etc/init.d/opendj --userName opendj

$ sudo /etc/init.d/opendj restart

  • (Windows) Register the DS server once as a Windows service:

    C:\path\to\opendj\bat> windows-service.bat --enableService

    Manage the service with Windows-native administration tools.

Server tasks

The following server administration commands can be run in online and offline mode. They invoke data-intensive operations, and so potentially take a long time to complete. The links below are to the reference documentation for each command:

When you run these commands in online mode, they run as tasks on the server. Server tasks are scheduled operations that can run one or more times as long as the server is up. For example, you can schedule the dsbackup and export-ldif commands to run recurrently in order to back up server data on a regular basis.

You schedule a task as a directory administrator, sending the request to the administration port. You can therefore schedule a task on a remote server if you choose. When you schedule a task on a server, the command returns immediately, yet the task can start later, and might run for a long time before it completes. You can access tasks by using the manage-tasks command.

Although you can schedule a server task on a remote server, the data for the task must be accessible to the server locally. For example, when you schedule a backup task on a remote server, that server writes backup files to a file system on the remote server. Similarly, when you schedule a restore task on a remote server, that server restores backup files from a file system on the remote server.

The reference documentation describes the available options for each command:

  • Configure email notification for success and failure

  • Define alternatives on failure

  • Start tasks immediately (--start 0)

  • Schedule tasks to start at any time in the future

Server recovery

DS servers can restart after a crash or after the server process is killed abruptly. After disorderly shutdown, the DS server must recover its database backends. Generally, DS servers return to service quickly.

Database recovery messages are found in the database log file, such as /path/to/opendj/db/userData/dj.log.

The following example shows two example messages from the recovery log. The first message is written at the beginning of the recovery process. The second message is written at the end of the process:

[/path/to/opendj/db/userData]Recovery underway, found end of log
...
[/path/to/opendj/db/userData]Recovery finished: Recovery Info ...

The JVM’s heap-based database cache is lost when the server stops or crashes. The cache must therefore be reconstructed from the directory database files. Database files might still be in the filesystem cache on restart, but rebuilding the JVM’s heap-based database cache takes time. DS servers start accepting client requests before this process is complete.