TL;DR gimme the packages
Ok - just go to Download
- Deployment Guide - planning your new directory server deployment
- Installation Guide - step-by-step instructions for installation, upgrade, and migration
The manual is for Red Hat Directory Server, and some of the information is different for 389. The differences are described below.
Java is required for the console
389 no longer bundles its own web server and java runtime, so the following are required
- Apache 2, worker model. This binary is generally available on RHEL and Fedora platforms as /usr/sbin/httpd.worker. It is provided via the httpd package (e.g. up2date httpd or yum install httpd). HP provides a free depot format download which includes the correct version of Apache. For other operating systems, you might have to build it yourself, if there is no pre-built Apache 2.x which uses the worker (multi-threaded) model. Especially for Solaris - the binary available from sunfreeware.com is not the worker model. Here are the build and installation instructions for building your own Apache.
- Java runtime. A JRE is required in order to use the Console. On Fedora, the IcedTea Java should work just fine. This package is called java-1.7.0-icedtea or java-1.6.0-openjdk- you should be able to yum install java-1.7.0-icedtea (or java-1.6.0-openjdk) on Fedora. On other platforms, either the Sun or the IBM JRE version 1.6.0 or later is required.
The console uses the java from your PATH. Use java -version to see what version of java you are using. If you see something that says gcj or GCJ you're using the wrong version. If you use 389-console -D 9 it will also tell you what version of java you're using.
- Enterprise Linux (Red Hat, CentOS, and derivatives of those) - You can use any Java 1.6 - OpenJDK should now be available
- yum install java-1.6.0-openjdk should work - if not, see below
- Enable the channel from the RHN -> Channels -> Red Hat Supplementary Server 5 -> Subscribe
- yum install java-1.6.0-ibm or download the rpm from the channel and do rpm -Uvh java-1.6.0-ibm
If you want the hassle of using a non-OS provided Java, you can go to the IBM or Sun websites and download a pre-built binary package for your operating system, or find an OpenJDK pre-built binary, or built it yourself.
NOTE: You need to use JRE version 1.6 for 389 versions 1.2.0 and later
If you want to install the Sun java command in /usr/bin/java, please follow the directions found here - http://fedoranews.org/mediawiki/index.php/JPackage_Java_for_FC4 NOTE: The instructions do not work for Java 6 on Fedora Core 6.
We know it's annoying to have to do all the click throughs, licenses, registration, etc. when downloading from a vendor website. Now that OpenJDK is available, this will all hopefully be easier.
NOTE: If you are installing Java from a pre-built binary from Sun or IBM, note that Java requires the package 'xorg-x11-deprecated-libs'. You will need to either
yum install xorg-x11-deprecated-libs
on Fedora Core or
NOTE: Some Java versions have a problem with window order/focus. This means that when you run 389-console, you will see only the splash screen and not the login dialog. If this occurs, please use
389-console -x nologo ... other args ...
to skip the splash screen and go straight to the login dialog.
Admin Server Issues
Please read Howto:AdminServerLDAPMgmt to diagnose any firewall or DNS issues with running the Admin Server. It is a good idea to review this before installation to avoid any problems which might be caused by firewalls or DNS configuration.
Installation via yum
389 1.1 and later are split into discrete packages with inter-dependencies. The best and easiest way to install these packages is with yum. Fedora packages are available with yum.
Enterprise Linux packages are available from EPEL - see Download for more information
If you already have installed 389 DS 1.1 or later, just use
yum upgrade [--enablerepo=repo] ...
to upgrade your installation. See Download for information about repos. NOTE that this will also upgrade OS packages. See man yum to see how to include/exclude packages/repos from the update. NOTE that you must use upgrade not update in order for the 389 packages to obsolete and replace the fedora ds packages.
If you want to install the testing packages:
yum upgrade [--enablerepo=testingrepo] ... [package to update] ....
See Download for information about repos. After the upgrade is complete, use
to update your installation. You must use setup-ds-admin.pl -u in order to refresh your admin server and console information.
yum install [--enablerepo=repo] 389-ds
See Download for information about repos. If you want to install the testing packages:
yum install 389-ds [--enablerepo=testingrepo] ...
See Download for information about repos. After install is complete, run
- Run /usr/sbin/setup-ds-admin.pl to set up the new directory server and admin server
- Fedora DS 1.0.x users can use /usr/sbin/migrate-ds-admin.pl to migrate existing directory and admin server data
NOTE: If you are upgrading from 1.0, DO NOT USE setup-ds-admin.pl - use migrate-ds-admin.pl instead
- Console - the console command is /usr/bin/389-console - startconsole and fedora-idm-console have been removed
Installation of just base DS
Just install the 389-ds-base package.
yum install 389-ds-base
Use setup-ds.pl to create an instance of directory server, or use migrate-ds.pl to migrate existing data.
Removing the directory server instances
First, remove any directory server instances and un-register them from the console. Make sure you back up your data first
This will list your directory server instances. The directory will begin with slapd-. A path whose name ends with .removed has already been removed. Then, for each instance, run
ds_removal -s slapd-INSTANCENAME -w admin_password
where slapd-INSTANCENAME is the name of the sub-directory under /etc/dirsrv, and admin_password is the password you use with the console.
If you are not using the console, you can use
remove-ds.pl -i slapd-INSTANCENAME
to remove instances.
Using ds_removal or remove-ds.pl will remove all of the instance specific files and paths except for the slapd-INSTANCENAME directory, which is just renamed to slapd-INSTANCENAME.removed. If you don't want to keep any of your configuration or key/cert data, you can erase this directory.
If you are using the console/admin server, and the machine is the one hosting the configuration directory server (i.e. this is the first machine you ran setup-ds-admin.pl on), and you just want to wipe out everything and start over, use remove-ds-admin.pl
remove-ds-admin.pl [-y] [-f]
You must specify -y in order to actually do anything. Use -f to force removal.
Removing the packages
yum erase 389-ds-base-libs 389-adminutil idm-console-framework
yum will remove all packages that depend on these packages as well. 389-ds-base-libs is for 389-ds-base and -devel - 389-adminutil will pick up 389-admin and 389-dsgw - idm-console-framework will pick up the console packages.
After removing all of the packages, you can do something like this to make sure your system is back to a clean state:
rm -rf /etc/dirsrv /usr/lib*/dirsrv /var/*/dirsrv /etc/sysconfig/dirsrv*
Installation via RPM
NOTE: This only applies to Fedora DS 1.0.4 or earlier. This installation method is not supported for Fedora DS 1.1 and later on those platforms that use yum.
Download the file fedora-ds-1.0.4-1.PLATFORM.ARCH.opt.rpm from the Download site, where PLATFORM is one of RHEL3, RHEL4, FC4, FC5, or FC6 (use RHEL4 for FC3, and RHEL3 for FC2), and ARCH is either i386 or x86_64. You can install it with the browser (it may prompt you to install it when you click on the link) or with the rpm command like this:
rpm -Uvh fedora-ds-1.0.4-1.PLATFORM.ARCH.opt.rpm
After the installation, you must run setup to configure or upgrade your servers. To run setup, open a command window and do the following:
cd /opt/fedora-ds ; ./setup/setup
This will give you several prompts. Here are the detailed setup instructions. HINT: If you are evaluating Fedora Directory Server, use a suffix of dc=example,dc=com during setup. This will allow you to load the example database files which demonstrate the basic functions of the server as well as more advanced features such as Roles, Virtual Views, and i18n handling. You can use the -k argument to setup to save the .inf file for use with subsequent silent installs. This will create a file called /opt/fedora-ds/setup/install.inf. You can edit this file and use it to perform a silent install using
./setup/setup -s -f /path/to/myinstall.inf
Note: if you are using password syntax checking, you must disable it to avoid a Constraint Violation error running setup after upgrading:
ldapmodify -x -D "cn=directory manager" -w password dn: cn=config changetype: modify replace: passwordCheckSyntax passwordCheckSyntax: off
Then, run setup as follows:
cd /opt/fedora-ds ; ./setup/setup
Then, if you are using password syntax checking, enable it again:
ldapmodify -x -D "cn=directory manager" -w password dn: cn=config changetype: modify replace: passwordCheckSyntax passwordCheckSyntax: on
Upgrading from the 7.1 release
NOTE: The migrate-ds-admin.pl script in Fedora DS 1.1 and later will migrate everything including the console information. So the steps outlined below should only be used if you are using Fedora DS 1.0.4.
Upgrading from 7.1 to 1.x will break the console. After doing an upgrade installation (see above), you must do the following steps in order to use the console:
cd /opt/fedora-ds/slapd-yourhost ./db2ldif -U -s o=netscaperoot -a /tmp/nsroot.ldif
The -U argument is important because you need to disable LDIF line wrapping for parsing purposes. Then, edit /tmp/nsroot. You will need to make the following replacements:
- replace ou=4.0 with ou=1.0
- replace ds71.jar with ds10.jar
- replace admserv70.jar with admserv10.jar
For example, the following sed command:
sed -e s/ou=4.0/ou=1.0/g -e s/ds71\\.jar/ds10.jar/g -e s/admserv71\\.jar/admserv10.jar/g /tmp/nsroot.ldif > /tmp/nsrootfixed.ldif
Then, re-import the ldif file - use ldif2db.pl for on-line import:
cd /opt/fedora-ds/slapd-yourhost ./ldif2db.pl -D "cn=directory manager" -w password -s o=netscaperoot -i /tmp/nsrootfixed.ldif
Installation from a developer build
If you built using the BUILD_RPM=1 flag (see Building), you will create the Fedora DS RPM. This gives you the same RPM that is described above. For example, if you used the dsbuild/One Step Build method using
you will have the following RPM:
This is for RHEL4 x86 32bit. Depending on your platform, you may have Linux instead of RHEL or RHEL3 or RHEL4. But the packages should end in .opt.rpm at any rate. You can install directly from the location:
rpm -ivh dsbuild/ds/ldapserver/work/fedora-ds-1.0.3-1.RHEL4.i386.opt.rpm
Then run setup as follows:
cd /opt/fedora-ds ; ./setup/setup
Here are the detailed setup instructions. HINT: If you are evaluating Fedora Directory Server, use a suffix of dc=example,dc=com during setup. This will allow you to load the example database files which demonstrate the basic functions of the server as well as more advanced features such as Roles, Virtual Views, and i18n handling. You can use the -k argument to setup to save the .inf file for use with subsequent silent installs. This will create a file called /opt/fedora-ds/setup/install.inf. You can edit this file and use it to perform a silent install using
./setup/setup -s -f /path/to/myinstall.inf
Installation via setuputil
There is no "make install" per se. The Directory Server build and packging process puts the files in a directory at the same level as the ldapserver build directory. That is, if you have ldap/ldapserver, the build process will put the installable files in ldap/MM.DD/PLATFORMDIR where MM.DD are the two digit month and day, respectively, and the PLATFORMDIR represents the OS platform. On RHEL4, this looks like the following:
For Fedora Core 4, and other Linux platforms, this will look something like this:
So the whole thing would be something like
You can override this naming convention by specifying the INSTDIR=/full/path definition on the make command line.
In the package directory, either the MM.DD/PLATFORMDIR or overridden with INSTDIR, there will be an executable called "setup". Just run the program as "./setup" and follow the prompts to install and set up the directory server. For example:
cd ldap/12.08/RHEL4_x86_gcc3_DBG.OBJ ; ./setup
Here are the detailed setup instructions. HINT: If you are evaluating Fedora Directory Server, use a suffix of dc=example,dc=com during setup. This will allow you to load the example database files which demonstrate the basic functions of the server as well as more advanced features such as Roles, Virtual Views, and i18n handling. You can use the -k argument to setup to save the .inf file for use with subsequent silent installs. This will create a file called setup/install.inf in your server root directory. You can edit this file and use it to perform a silent install using
./setup -s -f /path/to/myinstall.inf
Verifying the Installation
To test the basic operation of the server, use the ldapsearch command:
/usr/bin/ldapsearch -x [-h <your host>] [-p <your port>] -s base -b "" "objectclass=*"
If you do not have /usr/bin/ldapsearch, try /usr/lib/mozldap/ldapsearch or /usr/lib64/mozldap/ldapsearch - as above, but omit the -x argument:
/usr/lib/mozldap/ldapsearch [-h <your host>] [-p <your port>] -s base -b "" "objectclass=*"
If you are using Fedora DS 1.0.4 or earlier, ldapsearch is bundled with the server in the release directory under shared/bin.
cd /opt/fedora-ds/shared/bin ./ldapsearch [-p <your port>] -s base -b "" "objectclass=*"
(The -p <your port> may be omitted if you are using the standard LDAP port 389). This should produce the contents of the root DSE entry, which lists server vendor, version, supported extensions, controls, and naming contexts.
You can also use the console. You must first set your JAVA_HOME environment variable so that the console can find the java runtime e.g.
or wherever you have installed your jdk. You must also make sure the java command you want to run is in your PATH:
If you are running Fedora DS 1.0.4 or earlier, do the following instead:
cd /opt/fedora-ds ; ./startconsole
For the admin username and password, provide the values that you specified during setup. For the admin server url, if the field is blank, just use http://localhost:adminserverport/ where adminserverport is the port number you specified (default 9830) for the admin server during setup. If you forget what your admin server port number is, do this:
grep \^Listen /etc/dirsrv/admin-serv/console.conf
or on Fedora DS 1.0.4 and earlier:
grep \^Listen /opt/fedora-ds/admin-serv/config/console.conf
If you used a suffix of dc=example,dc=com, you can load one of the example database files. Follow the directions here for importing from the console or the command line. Here are the files you can use:
- Example.ldif - a simple database to use to test basic server functionality
- Example-roles.ldif - illustrates how Roles work and how to use them
- Example-views.ldif - illustrates how Virtual Views work and how to use them
- European.ldif - shows how the server handles 8bit character sets
Installing just the core directory server
An instance is one complete set of configuration files and databases for the Directory Server. It is possible to run multiple instances from one set of binaries.
Instance creation involves creating a base directory (a file system directory, not a directory server) that lives under the release directory, called "slapd-name" where name is usually the hostname, but it can be whatever is desired. By default, all of the server specific scripts, configuration files, and database data are placed in this directory.
Instance creation is performed using the perl script
ds_newinst.pl. The input to this script is a .inf file, the format of which is described below. This file lets you set the FQDN, the port to listen on, the default suffix, the directory manager DN and password, and the userid of the server process, as well as several other optional settings.
You can find an example .inf file in /usr/share/doc/fedora-ds-<version> (currently 1.1.0). You should make a copy of this file in another directory and edit it to suit your taste.
The script uses the information in the .inf file to create the initial configuration files, copy in several other configuration files, create many server administration scripts (e.g. ldif2db, db2ldif, etc.), create the initial database, and create the default suffix, and start up the server. See below for more information about the .inf file format.
Once this is done, the script should output a "Success" message if all went well. See FHS_Packaging for more information about where the instance specific files are created by ds_newinst.pl.
inf File Format for core directory server installation
A sample .inf file is listed below
[General] FullMachineName= myhost.mydomain.tld SuiteSpotUserID= nobody ServerRoot= /usr/lib/fedora-ds [slapd] ServerPort= 389 ServerIdentifier= myhost Suffix= dc=myhost,dc=mydomain,dc=tld RootDN= cn=Directory Manager RootDNPwd= password
The [General] and [slapd] sections are there for historical reasons and are required.
|SuiteSpotUserID||required||the Unix user that the Directory Server will run as||nobody (possibly ldap)|
|FullMachineName||required||the fully qualified host and domain name||oak.devel.example.com|
|ServerRoot||required||the base directory where the runtime files are installed||/usr/lib/fedora-ds|
|ConfigDirectoryAdminID||optional||user ID for console login||admin|
|ConfigDirectoryAdminPwd||optional||password for ConfigDirectoryAdminID||password|
|ConfigDirectoryLdapURL||optional|| LDAP URL for the Configuration Directory|
the suffix is required and will usually be o=NetscapeRoot
|AdminDomain||optional||the administrative domain this instance will belong to||devel.example.com|
|UserDirectoryLdapURL||optional||the user/group directory used by the Console||ldap://host.domain.tld:port/dc=devel,dc=example,dc=com|
|ServerPort||required||the port number the server will listen to||389|
|ServerIdentifier||required|| the base name of the directory that contains the instance|
of this server - will have "slapd-" added to it
|Suffix||required||the primary suffix for this server (more can be added later)||dc=devel,dc=example,dc=com|
|RootDN||required||the DN for the Directory Administrator||cn=Directory Manager|
|RootDNPwd||required||the password for the RootDN||itsasecret|
|InstallLdifFile||optional|| use this LDIF file to initialize the database|
the suffix must be specified in the Suffix directive
|SlapdConfigForMC||optional|| if true (1), configure this new DS instance as a|
Configuration Directory Server
|UseExistingMC||optional||if true (1), register this DS with the Configuration DS||1|
|UseExistingUG||optional|| if true (1), do not configure this DS as a user/group directory|
but use the one specified by UserDirectoryLdapURL