From Fedora Directory Server
Contents |
Fedora Directory Server Setup
Setup in Fedora DS 1.1 and later is a bit different than in 1.0 and earlier. There are some new commands and new usage.
This page is mostly a man page for setup. If you are looking for comprehensive installation and setup information, see Install_Guide.
Common Usage
All of the programs mentioned below have very similar usage.
Usage
Usage: name [--options] -- [args]
Command line options
| Name | Description |
|---|---|
| --help | A help message. The version and general usage information. |
| --version | Print the version and exit |
| --debug | Turn on debugging. Use more than once to increase debugging verbosity. |
| --silent | Use silent setup - no user input. By default, setup will prompt for a series of setup values. |
| --file=name | Use the file 'name' in .inf format to supply the default answers. See below for format. |
| --keepcache | Do not delete the temporary .inf file generated by this program. This is very useful if you want to generate a .inf file for use with subsequent setups. |
| --logfile | Log setup messages to this file - otherwise, a temp file will be used. |
| --update | Update (re-register) all of the servers so that they show up correctly in the console with the latest version and date information. |
Migration adds some additional options:
| Name | Description |
|---|---|
| --oldsroot | The old server root directory. This will usually be /opt/fedora-ds |
| --actualsroot | This is the old location of the old server root. If doing cross platform migration, you may have to use this. See below. The default is the value of --oldsroot |
| --cross | Do a cross platform migration. The old databases must have been exported to LDIF first. See below. |
| --instance | By default, migration will migrate all server instances. If you do not want to do this, specify each instance to migrate with a --instance argument. |
For all options, you can also use the short name e.g. -h, -d, etc. For the -d argument, specifying it more than once will increase the debug level e.g. -ddddd. If you want no log file at all, use -l /dev/null.
Command line arguments
You can supply default values for setup parameters in this format:
section.param=value
e.g.
General.FullMachineName=foo.example.com
or
"slapd.Suffix=dc=example, dc=com"
Values passed in this manner will override values in an .inf file given with the -f argument, and will be used as the default values when run in interactive mode. See below for a reference of section and parameter names and values.
Setup .inf files
You can pass values into the programs by the use of a .inf file. The file is formatted like this:
[sectionname] paramname= value name= value .. [sectionname] ....
Example
[General] FullMachineName= foo.example.com SuiteSpotUserID= dirsrv SuiteSpotGroup= dirsrv ConfigDirectoryLdapURL= ldap://foo.example.com:389/o=NetscapeRoot ConfigDirectoryAdminID= admin ConfigDirectoryAdminPwd= thepassword AdminDomain= example.com [slapd] ServerIdentifier= foo ServerPort= 389 Suffix= dc=example, dc=com RootDN= cn=Directory Manager RootDNPwd= thepassword [admin] ServerAdminID= admin ServerAdminPwd= thepassword SysUser= dirsrv
The available section names and parameters are as follows. The only required parameters are the ConfigDirectoryAdminPwd and the RootDNPwd. Setup will use or generate reasonable default values for all other parameters.
General section
| Name | Default | Description |
|---|---|---|
| FullMachineName | gethostname(2) + domain from /etc/resolv.conf | the FQDN that you want the server to listen to. This value has significance for a number of reasons:
|
| SuiteSpotUserID | dirsrv or your user id | the user id you want the server to run as. Note that you do not have to use root in order for the server to listen to the default port 389. As long as the server is started as root, it will drop privileges (seteuid()) after binding to the low ports. In fact, you are strongly encouraged to use a non-privileged user instead of root. If you run setup as a non-root user, you must choose your userid. |
| SuiteSpotGroup | dirsrv or your default group | the group id that you want the server specific files and directories to be owned by. You would use this primarily if you already had some sort of local machine administrative group, or if you want to run the admin server as a different user id but allow it to manage directory server files and directories. The SuiteSpotUserID must already be a member of this group. |
| ConfigDirectoryLdapURL | ldap://FullMachineName:398/o=NetscapeRoot | The LDAP URL of the configuration directory server, the one holding the master copy of the o=NetscapeRoot data used to store admin server and console configuration. |
| ConfigDirectoryAdminID | admin | The console/admin server administrator user ID. |
| ConfigDirectoryAdminPwd | none - must be supplied | The console/admin server administrator password. |
| AdminDomain | domain part of FullMachineName | This should generally just be the same as your domain name. |
| CACertificate | None | If the ConfigDirectoryLdapURL uses LDAPS, you can specify the CA certificate to use. You can specify either the full path and filename of the ASCII/PEM encoded CA certificate (e.g. /path/to/cacert.asc), or you can specify the actual CA certificate ASCII/PEM value (e.g. -----BEGIN CERTIFICATE-----\n.......) |
slapd section
| Name | Default | Description |
|---|---|---|
| ServerPort | 389 or a random high port | the network port number the server will listen to. If using ldapi, you can specify a value of "0" here to tell the server not to listen to a network port. You must run setup as root in order to use the default port 389. |
| ServerIdentifier | hostname part of FullMachineName | This is the server instance identifier used to name filesystem paths associated with this instance of directory server. By default, it is the leftmost component of the FullMachineName. For example, if the value is 'foo', this will be used in /etc/dirsrv/slapd-foo, /var/log/dirsrv/slapd-foo, /var/lib/dirsrv/slapd-foo, etc. This will also be used as the name of this server in the console and admin server. |
| Suffix | domain part of FullMachineName in dc= style | the default suffix used to store your data. The default is the domain part of FullMachineName converted to dc= style - foo.example,com -> dc=example,dc=com. The server will create this suffix, the associated database (userRoot), and a simple DIT to use. |
| RootDN | cn=Directory Manager | the directory manager DN. This is the 'superuser' for your directory server. |
| RootDNPwd | none - must be supplied | the password for the directory manager. This value can be passed in clear text or pre-hashed using the pwdhash command. |
| InstallLdifFile | suggest | You can have setup populate your new directory server with an LDIF file. The default value is "suggest" which means setup will create a simple DIT. Use a value of "none" to create an empty DIT. If you want to use your own LDIF file, you must specify the full path and filename. If the data uses custom schema, see SchemaFile below for how to add your custom schema. |
| ldapifilepath | /var/run/dirsrv/slapd-ServerIdentifier.socket | the full path to the unix domain socket e.g. /var/run/dirsrv/slapi-foo.socket |
| start_server | 1 | By default, setup will start the server. Set this parameter to "0" if you do not want to start the server. |
| install_full_schema | 1 | By default, setup will install the full directory server schema for the new instance. Set this to '0' to install a bare bones minimal schema (which will not be suitable for user/group entries). |
| SchemaFile | none | This is a multi-valued parameter, and can be specified more than once. This is the full path and filename of a Fedora DS schema file with the appropriate name that begins with two digits and is in LDIF format (e.g. /path/to/60myschema.ldif). This file will be copied into the schema directory of the new instance. |
| ConfigFile | none | This s a multi-valued parameter, and can be specified more than once. This is the full path and filename of an LDIF file containing one or more entries to be placed into the new dse.ldif configuration file. This could contain additional suffix/database definitions, replication configuration, etc. |
admin section
| Name | Default | Description |
|---|---|---|
| Port | 9830 | the network port admin server will listen to |
| ServerIpAddress | * - all interfaces | by default the admin server will listen to all interfaces - you can specify a single IP address to listen to |
| ServerAdminID | ConfigDirectoryAdminID | This is used for fallback http auth in case LDAP is down |
| ServerAdminPwd | ConfigDirectoryAdminPwd | the password for ServerAdminID |
| SysUser | SuiteSpotUserID | the admin server user id - the default is the value of SuiteSpotUserID, which means by default the directory server and admin server will run as the same user id |
setup-ds-admin.pl
This is the command to use after a new installation. If you already have installed Fedora DS 1.0.x or earlier and you want to upgrade, use migrate-ds-admin.pl instead (see below). This will create your initial directory server instance, and admin server, and set up both servers to be used with the console. You must use this command if you want to use the admin server and console. The only required parameters are the directory manager password and the configuration administrator (i.e. console user) password. Express mode setup will prompt only for these two values. Typical mode will prompt only for values commonly customized during setup. Custom mode will prompt for almost every value above. The simplest way to run setup-ds-admin.pl and use all default values with no user input is this:
setup-ds-admin.pl -s General.ConfigDirectoryAdminPwd=password slapd.RootDNPwd=password
The other simple way will be to run setup-ds-admin.pl with no arguments. This will run the command in interactive mode and it will display a series of dialog screens. The first couple of dialog screens will be Yes/No dialogs, and you must answer Yes to proceed. The rest are text entry dialogs which will usually prompt with a reasonable default value so that you can just hit Enter/Return to proceed (except for the password fields mentioned above - you must supply a value and confirm that value).
migrate-ds-admin.pl
This is the command to use if you already have installed Fedora DS 1.0.x or earlier and you want to upgrade to 1.1 or later. Do not use setup-ds-admin.pl in this case.
WARNING: Migration does not mean changing the hostname. For example, if you have Fedora DS 1.0.4 running on ldap1.example.com and you want to install Fedora DS 1.1 on ldap2.example.com, migration will not handle this case. If you really want to use the new machine, you should first change the hostname and DNS maps to make the new machine ldap1.example.com and rename the old machine to be oldldap1.example.com, for example. Then you can use one of the migration modes listed below. There are a number of reasons why the hostname should not be changed - see Migration design for more information.
There are two main modes of upgrade/migration:
- same platform - This just means you are migrating/upgrading on the same architecture e.g. you have a Fedora 6 x86 machine running Fedora DS 1.0.4 and you just want to install Fedora DS 1.1 and upgrade your installation. Or, you upgrade the machine to Fedora 7 first, then upgrade Fedora DS.
- cross platform - This generally means changing architectures e.g. from i386 to x86_64. This requires some additional preparation work, to convert your databases to LDIF, and to make the old data available on the new machine.
See Migration design for more information about these modes.
Migration is almost completely automated. You must supply the ConfigDirectoryAdminPwd on the command line e.g.
migrate-ds-admin.pl ...options... General.ConfigDirectoryAdminPwd=thepassword
You can also create a .inf file containing the password e.g.
[General] ConfigDirectoryAdminPwd= thepassword
if you do not want to pass the password on the command line.
Cross Platform Migration Usage
- --actualsroot
This is used when you must migrate from one machine to another. The usual case is that you have mounted the old server root on a different root directory, either via a network mount, or by copying a tarball made using a relative directory on the source machine to the destination machine and untarring it.
For example: machineA is a 32bit machine, and you want to migrate your servers to a new 64bit machine. Lets assume your old server root on machineA was /opt/fedora-ds, and your new machine also wants to use a server root of /opt/fedora-ds. There are a couple of different ways to proceed. Either make a tarball of opt/fedora-ds from machineA using a relative path (i.e. NOT /opt/fedora-ds) or use NFS to mount machineA:/opt/fedora-ds on a different mount point (e.g. machineB:/migration/opt/fedora-ds).
If you do this, you should give the old "real" server root (/opt/fedora-ds) as the --actualsroot argument, and use /migration/opt/fedora-ds for the --oldsroot argument. That is, the oldsroot is the physical location of the files on disk. The actualsroot is the old value of the server root on the source machine e.g.
migrate-ds-admin.pl --oldsroot=/migration/opt/fedora-ds \ --actualsroot=/opt/fedora-ds ...otherargs...
- --crossplatform
Also known as crossplatform, or 'c', or 'x'. This is when the source machine is a different architecture than the destination machine. In this case, only certain data will be available for migration. Changelog information will not be migrated, and replicas will need to be reinitialized (if migrating masters or hubs). This type of migration requires that all of your old databases have been dumped to LDIF format, and the LDIF file must be in the default database directory (usually /opt/fedora-ds/slapd-instance/db), and the LDIF file must have the same name as the database instance directory, with a ".ldif". For example, if you have
/opt/fedora-ds/slapd-instance/db/userRoot/ and /opt/fedora-ds/slapd-instance/db/NetscapeRoot/
you must first use db2ldif to export these databases to LDIF e.g.
cd /opt/fedora-ds/slapd-instance ./db2ldif -n userRoot -a /opt/fedora-ds/slapd-instance/db/userRoot.ldif and ./db2ldif -n NetscapeRoot -a /opt/fedora-ds/slapd-instance/db/NetscapeRoot.ldif
Then you must somehow make your old server root directory available on the destination machine, either by creating a tar archive on the source and copying it to the destination, or by network mounting the source directory on the destination machine. Then run migration like this:
migrate-ds-admin.pl --crossplatform --oldsroot=/migration/opt/fedora-ds \ --actualsroot=/opt/fedora-ds ...otherargs...
setup-ds.pl
If you do not want to use admin server or console, you should use setup-ds.pl to create and configure your initial directory server instance. setup-ds.pl works exactly like setup-ds-admin.pl, except that the admin section is ignored, and the following parameters are ignored:
SuiteSpotGroup, ConfigDirectoryLdapURL, ConfigDirectoryAdminID, ConfigDirectoryAdminPwd, AdminDomain
NOTE: Directory Server instances created with this command cannot be managed with the console or admin server. If you have created directory server instances with this command, and later decide that you want to use them with the console or admin server, you can use the register-ds-admin.pl command to do so.
migrate-ds.pl
If you do not use admin server or console, you should use migrate-ds.pl to migrate your Fedora DS 1.0.x and earlier instances to Fedora DS 1.1 and later. migrate-ds.pl works exactly like migrate-ds-admin.pl, except the console and admin server data and configuration are not migrated, and the General.ConfigDirectoryAdminPwd=thepassword parameter is not required.
register-ds-admin.pl
This command can be used to register instances of directory server created with setup-ds.pl with the console and admin server through the configuration directory server. If a configuration directory server is not defined, it prompts to choose one for the role. You could switch an existing configuration directory server to the other directory server, as well. If there is no admin server instance has not be created, it sets up at the same time. After running the command, the registered servers will be accessible on the Console and Administration Express. This command runs in the interactive mode:
register-ds-admin.pl
ds_removal
This command can be used to remove instances of directory server. To run the command the server instance name to be removed and the admin server password is required:
ds_removal -s server_id -w admin_password
The underlying library is shared with the "Remove Server" on the Console. Using the command line, you can remove the configuration directory server instance, as well, which is not allowed on the Console.
