.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH REGISTER-DS-ADMIN.PL 8 "Jun 8, 2010"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
register\-ds\-admin.pl \- Registers Directory Server instances with an Admin Server
.SH SYNOPSIS
.B register-ds-admin.pl
[\fI\-\-options\fR] \fI-\- \fR[\fIargs\fR]
.SH DESCRIPTION
Registers existing Directory Server instances with an existing Admin Server.
This command does the set up necessary for the use of the Console to manage
the Directory Server instances you are registering.  You can register local
Directory Server instances with a local Configuration Directory Server/Admin
Server.  You can also create an Admin Server and register standalone instances
with it. You can register remote Directory Server instances to the local
Admin Server, as well as register local Directory Server instances with a
remote Admin Server \- this allows a single Console/Admin Server to manage all
the Directory Servers in your network.

Use this command with the \fB-\-update\fR option after an upgrade to refresh
 the server information (version, build number, etc.) in the Console.

Can be run in interactive mode with different levels of verbosity, or
in silent mode with parameters supplied in a .inf format file or
on the command line.
.PP
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics, 
.\" respectively.
.SH OPTIONS
A summary of options is included below:
.TP
.B \fB\-\-help\fR
This message
.TP
.B \fB\-\-version\fR
Print the version and exit
.TP
.B \fB\-\-debug\fR
Turn on debugging
.TP
.B \fB\-\-silent\fR
Use silent setup \- no user input
.TP
.B \fB\-\-file\fR=\fIname\fR
Use the file 'name' in .inf format to supply the default answers
.TP
.B \fB\-\-keepcache\fR
Do not delete the temporary .inf file generated by this program
.TP
.B \fB\-\-logfile\fR
Log setup messages to this file \- otherwise, a temp file will be used
.TP
.B \fB\-\-update\fR
Update an existing installation (e.g. after upgrading packages)
.TP
.B \fB\-\-continue
(update only) keep going despite errors (also \-\-force)
.PP
For all options, you can also use the short name e.g. \fB\-h\fR, \fB\-d\fR, etc.
For the \fB\-d\fR argument, specifying it more than once will increase the debug
level e.g. \fB\-ddddd\fR
.PP
args:
You can supply default .inf data in this format:
.IP
section.param=value
.PP
e.g.
.IP
General.FullMachineName=foo.example.com
.PP
or
.IP
"slapd.Suffix=dc=example,dc=com"
.PP
Values passed in this manner will override values in an .inf file given with
the \fB\-f\fR argument.

.SH Silent Mode (.inf file)
.PP
The .inf file use three directives depending on what you want to do:  [General], [admin], and [register].
The [admin] section is only needed if an Admin Server needs to be installed on the local system.
.br

Here is an example of creating an Admin Server, and turning a standalone Directory Server instance into
a configuration instance.  In this case we need the [General], [admin], and [register] directives
.IP
[General]
.br
FullMachineName= localhost.localdomain
.br
SuiteSpotUserID= dirsrv
.br
SuiteSpotGroup= dirsrv
.br
AdminDomain= redhat.com
.br
ConfigDirectoryAdminID= admin
.br
ConfigDirectoryAdminPwd= admin
.br
ConfigDirectoryLdapURL= ldap://localhost.localdomain:389/o=NetscapeRoot
.br

.br
[admin]
.br
Port= 9830
.br
ServerIpAddress= 127.0.0.1
.br
ServerAdminID= admin
.br
ServerAdminPwd= password
.br

.br
[register]
.br
configinst= slapd-localhost::cn=directory manager::password
.br

.PP
Here is an example of an .inf file that registers two local Directory Server
instances (slapi-replica, slapd-instance2) with the local Configuration
Directory Server (slapd-localhost).
.IP
[General]
.br
FullMachineName= localhost.localdomain
.br
SuiteSpotUserID= dirsrv
.br
SuiteSpotGroup= dirsrv
.br
AdminDomain= redhat.com
.br
ConfigDirectoryAdminID= admin
.br
ConfigDirectoryAdminPwd= admin
.br
ConfigDirectoryLdapURL= ldap://localhost.localdomain:389/o=NetscapeRoot
.br

.br
[register]
.br
configinst= slapd-localhost::cn=directory manager::password
.br
localinst= slapd-instance2::cn=directory manager::password
.br
localinst= slapd-replica::cn=directory manager::password
.br

.PP
This example will add the slapd-replica instance to the local configuration server.  Then this
server's configuration to added to the remote configuration server on ldap.redhat.com
.IP
.br
[General]
.br
FullMachineName= localhost.localdomain
.br
SuiteSpotUserID= dirsrv
.br
SuiteSpotGroup= dirsrv
.br
AdminDomain= redhat.com
.br
ConfigDirectoryAdminID= admin
.br
ConfigDirectoryAdminPwd= admin
.br
ConfigDirectoryLdapURL= ldap://localhost.localdomain:389/o=NetscapeRoot
.br

.br
[register]
.br
configinst= slapd-localhost::cn=directory manager::password
.br
localinst= slapd-replica::cn=directory manager::password
.br
localcertdir= /etc/dirsrv/slapd-localhost
.br
remotehost= ldap.redhat.com
.br
remoteport= 636
.br
remotebinddn= cn=directory manager
.br
remotebindpw= password
.br
admindomain= redhat.com
.br
admindn= uid=admin,ou=Administrators,ou=TopologyManagement,o=NetscapeRoot
.br
adminpw= password
.br
destination= remote
.br
.PP
The \fB[register]\fR directive parameter descriptions:
.TP
.B configinst\fR = INSTANCE::BIND_DN::PASSWORD\fR
.br
.IP
.I INSTANCE\fR = The server where the existing configuration exists, or the server where you want
to add the configuration to. The value takes the form of slapd-INSTANCE.
.br
.I BIND_DN\fR = The root DN, usually \*(lqcn=directory manager\*(rq, for the local configuration server.
.br
.I PASSWORD\fR = the root DN password.
.TP
.B localinst\fR = INSTANCE::BIND_DN::PASSWORD\fR
.br
.IP 
The parameters are the same as 'configinst'.  This argument is required for local registerations.
.br
.TP
.B remotehost\fR = The FQDN of the remote server.  This is either the rmeote server we
registering with, or the remote server that is being registered with the local configuration
server.
.TP
.B remoteport\fR = The port of the remote server.
.TP
.B localcertdir\fR = The directory of the certificate database files (e.g. cert8.db, key3.db). This optional parameter is only used if connecting to the remote server over SSL.
.TP
.B remotebinddn\fR = The bind DN, preferrably the root DN, to connect to the remote server.
.TP
.B remotebinddn\fR = The password for the remotebinddn entry.
.TP
.B admindomain\fR = This is the Admin Domain for the server that is being registered. If registering the local server to the remote server, it would be the domain from the local server. If registering a remote server to the local configuration server, it would be the Admin Domain from the remote server.
.TP
.B admindn\fR = The local administrator DN for o=netscaperoot
.TP 
.B adminpw\fR = The local administrator password.
.TP
.B destination\fR = \fBlocal\fR, or \fBremote\fR
.br
.IP
.I local\fR = Registers the remote server with the local configuration server.
.br
.I remote\fR = Registers the local server with the remote configuration server.
.SH AUTHOR
register-ds-admin.pl was written by the 389 Project.
.SH "REPORTING BUGS"
Report bugs to http://bugzilla.redhat.com.
.SH COPYRIGHT
Copyright \(co 2010 Red Hat, Inc.
.br
This is free software.  You may redistribute copies of it under the terms of
the Directory Server license found in the LICENSE file of this
software distribution.  This license is essentially the GNU General Public
License version 2 with an exception for plug-in distribution.