Gentoo Wiki


Please browse through this whole document before starting. You might find that you'll want to compile/recompile everything in one shot before you get down to the DS build.



May 10, 2007:
I originally built Fedora DS version 1.0.2 using older versions of some of the following libraries. Over time I upgraded things and stuff continued to operate ok. I started getting some emails from people saying they were having problems building 1.0.2 or running 1.0.3/4. I recently had a chance to build/install ds 1.0.4 on a freshly installed amd64 Gentoo system and I ran into the same problem where 1.0.2 (which I had running at home just fine) wouldn't build because mod_nss failed and 1.0.3/4 would build but I couldn't connect to the server using the console. It seemed that the credentials I input to the login box for the console was not properly getting passed to the directory server. I spent some time in #fedora-ds troubleshooting and ended up figuring I'd give a different version of apache a try as the problem seemed to be with the administration server. mod_nss from ds 1.0.2 won't build with apache 2.0.x greater than 2.0.54 (which has been removed from the portage tree for quite a while) and ds 1.0.3/4 wasn't working with 2.0.58. The only other version of apache in portage was 2.2.4 but it was masked so I unmasked it, built it, built ds 1.0.2 against it and it worked. I then tried 1.0.4 and it also worked so I would recommend Gentoo users unmask apache 2.2.4 and use that if they'd like to use the console with fedora ds. The directory server itself was working fine throughout all of this. The only reason I upgraded apache was to get the console GUI working.


If you'd like to use the latest (as of 05/10/2007) version of Fedora DS which is 1.0.4:
I'm using the following versions of software/libraries (Go here for the official list of libraries for a Fedora/RHEL install, should be the same for Gentoo):

Unmasking apache 2.2.4 (if necessary, also if you don't have apache installed yet, read below about the worker/threading bit before you install it so you can avoid compiling it twice):
This will unmask ONLY version 2.2.4 so if another "testing" version of apache comes out your system won't try to upgrade.

#echo =www-servers/apache-2.2.4 >> /etc/portage/package.keywords
#echo =app-admin/apache-tools-2.2.4 >> /etc/portage/package.keywords

I don't know exactly what JDKs will/will not work, but I've successfully used blackdown 1.4.2 and Sun JDK 1.5 as well. We're going to use the SUN JDK. I'm assuming apache is already installed. If not, hang on and read below a bit to avoid compiling it twice:

# emerge -av libtermcap-compat mit-krb5 net-snmp ant-core sun-jdk

The build script is expecting to find apxs and not apxs2 so make a symlink for apxs pointing to apxs2:

# ln -s /usr/sbin/apxs2 /usr/sbin/apxs

If you are going to install the administration server (which is needed to use the console, which is highly recommended) then you'll need to fake out the install script again because of the way Gentoo names stuff

# ln -s /usr/sbin/apache2 /usr/sbin/httpd
# ln -s /usr/lib64/apache2/modules/ /usr/modules

Also, the admin server requires "an Apache compiled with the worker model" so you might need to add "mpm-worker" to your use flags and recompile apache2. Alternatively add "net-www/apache mpm-worker" to your /etc/portage/package.use file (what I did). If you use PHP or Perl with apache you'll need to toggle the thread setting for those as well and rebuild. There's a lot of warnings in these packages when you enable these options. I'm not saying you won't have any problems, but I have yet to have any issues on 2 different boxes with PHP or Perl.

# echo "net-www/apache mpm-worker" >> /etc/portage/package.use
# echo "dev-lang/perl ithreads" >> /etc/portage/package.use
# echo "sys-devel/libperl ithreads" >> /etc/portage/package.use
# echo "dev-lang/php threads" >> /etc/portage/package.use
# emerge -av net-www/apache dev-lang/perl sys-devel/libperl www-apache/mod_perl dev-lang/php


It appears that the NSS components can benefit from some environment variables, so if you have a 64bit system do the following (and for the newbies out there remember that if you're using multiple terminals that an "export" is only good for the session you do it in).:

export USE_64=1

and this one you should set regardless, otherwise you'll get a debug build of NSS:

export BUILD_OPT=1

Using directions from here: The dsbuild script is pretty nice, it slurps down all the sources it needs, configures and builds everything automatically. As long as you have all the prerequisites taken care of this should make it all the way through.

# cd /usr/local/src
# wget
# tar xzf dsbuild-fds104.tar.gz
# cd dsbuild-fds104/meta/ds
# make

The below error happened when I was building 1.0.2 a while back, I haven't had the problem since but I'll leave the fix here just in case somene else could use it: During the make I ran out of memory during the java compile for the console so if that happens to you just edit the build.xml to allow more ram and then kick off make again and it should start the build for the console again and pick up where it left off. Add the following line within the javac build target of the build.xml file (around line 171):

nano /usr/local/src/dsbuild-fds102/ds/console/work/fedora-console-1.0.2/build.xml


Run the setup script which will copy all the needed files to the installation directory and configure the server based on your answers:

# /usr/local/src/dsbuild-fds102/ds/ldapserver/work/pkg/setup

The admin server points to a MIMEMagicFile that doesn't exist under Gentoo so go ahead and fix it to point to one that does exist. On my system the line to change is 307 and the line contains MIMEMagicFile /usr/conf/magic:

 # nano <server-root>/admin-serv/config/httpd.conf

Change MIMEMagicFile /usr/conf/magic to be MIMEMagicFile /etc/apache2/magic. BTW, I don't even know what this does...I just saw a message in the logs complaining about the magic file not existing.

Gentoo init scripts

First off, this is my absolute first time making these scripts and I know they are really simple so if you have some ideas for improving them feel free to let me know.

  • SERVER_ROOT is the base install dir you chose during setup script, for me it's /opt/fedora
  • INSTANCE_NAME is the server instance name you chose during setup script. If you do an ls under your SERVER_ROOT you should see a slapd-something. "something" is the instance name for the ldap server. For me it's erma.

The directory server doesn't require the admin server to be running. If you have multiple instances of directory server installed, you can do something similar to how the Gentoo handbook says to add multiple net.eth# scripts. After you make the first, just copy and rename. Don't forget to also copy the conf.d script and change the INSTANCE_NAME in there to your extra instance name.

# cat /etc/init.d/fedora-ds

depend() {
        need net

start() {
        ebegin "Starting Fedora Directory Server"
        eend $?

stop() {
        ebegin "Stopping Fedora Directory Server"
        eend $?

Change the SERVER_ROOT and INSTANCE_NAME to suit your system:

# cat /etc/conf.d/fedora-ds
#leave the trailing slash off the server-root please

The admin server needs a "configuration" directory server which I have assumed is the only slapd instance you have on your system so I added the "need fedora-ds" dependency. If you basically used the defaults during the setup script than this is the case for you as well. If your configuration directory server is on a different machine then you can remove that line.

# cat /etc/init.d/fedora-admin

depend() {
        need net
        need fedora-ds

start() {
        ebegin "Starting Fedora Administration Server"
        eend $?

stop() {
        ebegin "Stopping Fedora Administration Server"
        eend $?

Again, change the SERVER_ROOT to match your config:

# cat /etc/conf.d/fedora-admin
#leave the trailing slash off the server-root please

I'm not making any guarantees for anyone else, but they work on my system:

erma init.d # /etc/init.d/fedora-admin start
 * Starting Fedora Directory Server ...                                   [ ok ]
 * Starting Fedora Administration Server ...                              [ ok ]
erma init.d # /etc/init.d/fedora-admin stop
 * Stopping Fedora Administration Server ...                              [ ok ]
erma init.d # /etc/init.d/fedora-admin start
 * Starting Fedora Administration Server ...                              [ ok ]
erma init.d # /etc/init.d/fedora-ds stop
 * Stopping Fedora Administration Server ...                              [ ok ]
 * Stopping Fedora Directory Server ...                                   [ ok ]
erma init.d # /etc/init.d/fedora-admin start
 * Starting Fedora Directory Server ...                                   [ ok ]
 * Starting Fedora Administration Server ...                              [ ok ]
erma init.d # eselect rc add fedora-admin default
Adding fedora-admin to following runlevels
  default                   [done]

Console on Windows

I don't have an X server installed on my server so I need remote administration and I'm in Windows at the moment. I'll probably add a section for running the console under Gentoo (my desktop) at some point in the future.

Follow the Howto here:

Screenshot of the console running on windows connected to my Gentoo server

Create password files for LDAP and Admin Server in SSL mode

This is so you can start the servers automatically when they are operating in SSL mode without them prompting for password on stdout. They both use a password file, but the implementation is different. Having the password files also lets you restart the servers from the console gui instead of requiring you to use a terminal.

BTW, I've left out the juicy middle part of actually getting and installing the certs and enabling SSL in the servers (Hint: look at the documentation/howtos on the fedora directory server wiki). Personally I created a P12 using openssl containing the cert/key from my webserver then imported that p12 into the cert/key dbs for the admin serv and ldap serv using pk12util (which is installed under <server-root>/shared/bin).


First the LDAP:

  • <server-root> is the base install dir you chose during setup script, for me it's /opt/fedora/
  • <instance-name> is the server instance name you chose during setup script. If you do an ls under your <server-root> you should see a slapd-something. "something" is the instance name for the ldap server. For me it's erma.
  • xxxxxx is the password you created for the security device when you went through the keygen/cert request/cert install process
  • user and group are the user and group you told the server to run as (for me it's nobody/nobody)
# echo "Internal (Software) Token:xxxxxx" > <server-root>/alias/slapd-<instance-name>-pin.txt
# chmod 600 <server-root>/alias/slapd-<instance-name>-pin.txt
# chown user:group <server-root>/alias/slapd-<instance-name>-pin.txt

Here's the one for my specific case (minus password, of course):

# echo "Internal (Software) Token:xxxxxx" > /opt/fedora/alias/slapd-erma-pin.txt
# chmod 600 /opt/fedora/alias/slapd-erma-pin.txt
# chown nobody:nobody /opt/fedora/alias/slapd-erma-pin.txt

Test out that it works...if you don't get prompted for a password and it drops you back to prompt, you're fine:

# <server-root>/slapd-<instance-name>/restart-slapd

Or if you have the init scripts working:

# /etc/init.d/fedora-ds restart

Admin Server

Now the admin server:

  • <server-root> is the base install dir you chose during setup script, for me it's /opt/fedora/
  • xxxxxx is the password you created for the security device when you went through the keygen/cert request/cert install process (this may be different than the one for ldap depending on your user input)
  • user and group are the user and group you told the server to run as (for me it's nobody/nobody)

You need to create the password.conf file and then edit the nss.conf file to enable use of the password.conf.

# echo "internal:xxxxxx" <server-root>/admin-serv/config/password.conf
# chmod 600 <server-root>/admin-serv/config/password.conf
# chown user:group <server-root>/admin-serv/config/password.conf

Now edit the nss.conf to tell it to use the password.conf we just created. The line you're looking to edit contains "NSSPassPhraseDialog builtin" which for appears on line 48.

# nano -w <server-root>/admin-serv/config/nss.conf

Comment out the line (in case you want to go back to stock setup) containing:

NSSPassPhraseDialog  builtin

and add a line below it containing:

NSSPassPhraseDialog file:<server-root>/admin-serv/config/password.conf

Same as above but for my specific setup:

# echo "internal:xxxxxx" /opt/fedora/admin-serv/config/password.conf
# chmod 600 /opt/fedora/admin-serv/config/password.conf
# chown nobody:nobody /opt/fedora/admin-serv/config/password.conf
# nano -w /opt/fedora/admin-serv/config/nss.conf

As before, restart the server to see if it was successful. If you're not prompted for a password everything's fine:

# <server-root>/restart-admin

Renew SSL certs

Last night I restarted my server and neither the LDAP server nor the admin server came up. I saw this in the logs:

 * Starting Fedora Directory Server ...
[10/Nov/2006:03:29:19 -0500] - SSL alert: CERT_VerifyCertificateNow: verify certificate failed for cert of family cn=RSA,cn=encryption,cn=config (Netscape Portable Runtime error -8181 - Peer's Certificate has expired.)
[10/Nov/2006:03:29:19 -0500] - SSL failure: None of the cipher are valid 
 * ERROR:  cannot start fedora-admin as fedora-ds could not start

I use CACert for my ssl certs. I use the same cert/key for ldap/admin server as I do for apache. (I know I probably shouldn't, but I'm lazy.) I had already renewed the certificate and installed it for apache but I forgot to put in the new cert for the fedora servers. Fear's relatively easy to get back in business. I have the pem (aka base64) encoded certificate on the filesystem so I used the following commands to add the new certificate to the certificate databases for the ldap and admin servers.

First cd to wherever the base of the Fedora DS install is. For me that's /opt/fedora-ds then go into alias. This is where the NSS key/cert databases live. They are exactly the same as the ones that hold your crypto info for Mozilla/Firefox/Thunderbird.

 # cd /opt/fedora-ds/alias

Now do an ls and figure out your prefixes. You need the 2 values that precede "cert8.db" and "key3.db". If you look at the output of my ls below you'll see the 2 prefixes I need to take note of are "admin-serv-erma-" and "slapd-erma-".

 # ls
 admin-serv-erma-cert8.db  secmod.db            slapd-erma-pin.txt
 admin-serv-erma-key3.db   slapd-erma-cert8.db             slapd-erma-key3.db

Now you just need to add the new cert to the db. Copy the cert to this directory temporarily and then run the following commands to import the certificate into both of the databases. If you are using different certificates for the admin server and the ldap server then make sure you upload the correct certificate to each otherwise the public/private keys won't match up and you'll be in the same boat you are now with nothing working.

  • What the switches mean below:
    • -A means add a cert to the db.
    • -d is the directory containing the "security databases" as NSS calls them, that is the present directory (you are in alias right?).
    • -P is the prefix, by default it just tries to operate on cert8.db and key3.db so we need this.
    • -n is the nickname, use the same one as you are currently using or you will have to change a setting in the GUI for the ldap server/admin server and since they won't start because they are SSL enabled and the cert is expired you might run into trouble if you use a different one. (You can figure this out by first using the List option of certutil, change the prefix to suit your case: ../shared/bin/certutil -L -d . -P slapd-erma- It's going to be the one with u,u,u at the end of the line.)
    • -t is trust, use what I've got below which is not adding any implicit trust. The certificate should inherit trust from the root which is set to trusted in the db. If you happen to be using a self-signed cert you should probably use "T,," which will trust it for SSL use and NOT for email/code signing.
    • -i is the input file which, in this case, is the certificate in question.
 #../shared/bin/certutil -A -d . -P slapd-erma-  -n -t ",," -i
 #../shared/bin/certutil -A -d . -P admin-serv-erma- -n -t ",," -i

Now check your work by using the List option to certutil again, this time specify the nickname of the cert you just added. You should see 2 certificates "pretty printed" with the first one being the new one. Leave the -n option off and you'll see a list similar to below. Don't worry that you have 2 certificates with the same nickname. NSS is smart. It knows the server is configured to use a certificate with, in my case, "" as its nickname. It will automatically use the certificate that is valid and ignore the expired one. The same thing would happen if you are using CRLs and have a revoked certificate mixed in there.

 # ../shared/bin/certutil -L -d . -P slapd-erma-
 CA Cert Signing Authority                                    CT,,                                                u,u,u                                                u,u,u
  • If you're really feeling frisky you can use certutil to check the cert now, if it passes here there is no reason the server shouldn't start up in the next step:
    • -V means to verify
    • -u V means verify the cert for SSL Server usage
    • -e means verify the signature on the cert
    • The rest are the same as above
#../shared/bin/certutil -V -d . -P slapd-erma- -u V -e -n
Enter Password or Pin for "NSS Certificate DB":
certutil-bin: certificate is valid

Now really check your work by trying to start the servers up. I just try to start the admin server because it depends on the ldap and it will start both anyway.

 # /etc/init.d/fedora-admin start
 * Starting Fedora Directory Server ...                                   [ ok ]
 * Starting Fedora Administration Server ...                              [ ok ]

All done.

Upgrading Fedora Directory Server

If anyone has done it already and wants to contribute some info, have at it. One of these days I'll get around to it. I've slowly grown into a "If it ain't broke, don't fix it" mentality with Gentoo. You have to be very careful about using emerge -avuND world carelessly. Since I now use the LDAP for samba and apache authentication I'm not in a huge rush to break things. I don't foresee it being that hard though. I'm thinking it goes like this: Just in case back up the certs/keys from the alias directory (pk12util), go into the console and do a db backup to LDIF and then you can practically wipe the directory (after saving a backup copy, right?) and install the new one and then import the stuff back in and configure SSL in the console.


If you don't feel confident in my abilities you can also go straight to the real experts at They have some mailing lists and an IRC channel. Good luck!

Last modified: Fri, 05 Sep 2008 08:05:00 +0000 Hits: 6,083