[Fedora-directory-commits] adminserver/man/man8 migrate-ds-admin.pl.8, NONE, 1.1 remove-ds-admin.pl.8, NONE, 1.1 setup-ds-admin.pl.8, NONE, 1.1

[Richard Allen Megginson]

Author: rmeggins

Update of /cvs/dirsec/adminserver/man/man8
In directory cvs1.fedora.phx.redhat.com:/tmp/cvs-serv21602/adminserver/man/man8

Added Files:
    migrate-ds-admin.pl.8 remove-ds-admin.pl.8 setup-ds-admin.pl.8 
Log Message:
Resolves: bug 480869
Bug Description: DS console: Can not delete DS instance
Reviewed by: nkinder (Thanks!)
Fix Description: As it turns out, my assumption that ds_remove in CGI mode also did the unregistration was false.  It is the console that does the unregistration, only after the ds_remove CGI returns success.  So, ds_remove needs to run with AdminSDK off, just like the other "special" CGI programs.  In addition, ds_remove needs to be more robust - if there is an error during ds_remove, you should be allowed to try again after fixing something.  However, the way the error handling worked did not differentiate between fatal errors and errors that could be ignored.  In order to do this properly, we need to propagate the errors back up to the top level (oh how I wish perl had real exception handling . . .).  The main type of error we need to ignore is file not found or process not found.  If we attempted to remove before and that attempt failed for some reason, and left a partial instance, we need to be able to run the remove command again, skipping over the things we shutdown or
  removed already, and clean up the stuff we need to remove.  This can also happen if you use the console to create a ds instance, and remove-ds.pl to remove the instance.  The instance will still show up in the console.  We need to be able to use the Remove Server in the console to remove the instance from the console, even through there is no physical instance on disk any more.  Since the console will only do the unregistration if the CGI returns success, we need to make sure the CGI returns success even though there is no instance on disk.  When ds_remove is run via ds_removal, it will do the unregistration.
I also took this opportunity to refactor the remove code, creating a removeDSInstance method in DSCreate.pm, and moving some of the other removal helper functions to Util.pm.  That simplified the code in both ds_remove and remove-ds.pl.
I added a remove-ds-admin.pl script - one of the problems that users have is that they run setup-ds-admin.pl, then hit some error (e.g. bad DNS setup), then find that they cannot restore the system to the state before they ran setup-ds-admin.pl.  remove-ds-admin.pl does this.
Finally, I added some man pages to the admin package for those commonly used commands.
Platforms tested: RHEL4
Flag Day: no
Doc impact: no

--- NEW FILE migrate-ds-admin.pl.8 ---
."                                      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 MIGRATE-DS-ADMIN.PL 8 "May 18, 2008"
." 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
migrate-ds-admin.pl - Admin Server and Directory Server Migration script
.SH SYNOPSIS
.B migrate-ds-admin.pl 
[--options] \fB--\fR [args]
.SH DESCRIPTION
Admin Server and Directory Server migration script - migrates Admin Server and all Directory Server instances from
older releases to the current release.
.PP
This script will copy instances (data and configuration) from the old
server root directory to their new FHS locations.  This script does a
copy only - the data in the old instances will be left untouched.  The
old instances must be shutdown first to ensure that the databases are
copied safely.  During migration your migrated instances will be started.
.PP
.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--oldsroot\fR
The old server root directory to migrate from
.TP
.B \fB--actualsroot\fR This is the old location of the old server root.
.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 migration messages to this file - otherwise, a temp
file will be used
.TP
.B \fB--instance\fR
By default, all directory server instances will be
migrated.  You can use this argument to specify one
or more (e.g. \fB-i\fR slapd-foo \fB-i\fR slapd-bar) if you do
not want to migrate all of them.
.TP
.B \fB--cross\fR
See below.
.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.  The only required argument is the password of the Configuration Directory Administrator, which can be specified on the command line like this:
.IP
migrate-ds-admin.pl General.ConfigDirectoryAdminPwd=thepassword
.PP
All other paramters needed for migration will be read from the old Admin Server configuration.
.PP
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.
.PP
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/myds, and your new machine also wants to use a
server root of /opt/myds.  There are a couple of different ways to
proceed.  Either make a tarball of opt/myds from machineA using a
relative path (i.e. NOT /opt/myds) or use NFS to mount
machineA:/opt/myds on a different mount point
(e.g. machineB:/migration/opt/myds).
.PP
If you do this, you should give the old "real" server root (/opt/myds)
as the \fB--actualsroot\fR argument, and use /migration/opt/myds for the
\fB--oldsroot\fR 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.
.PP
cross:
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
.IP
.ad l
.nf
/opt/fedora-ds/slapd-instance/db/userRoot/
and
/opt/fedora-ds/slapd-instance/db/NetscapeRoot/
.na
.fi
.PP
you must first use db2ldif to export these databases to LDIF e.g.
.IP
.ad l
.nf
cd /opt/fedora-ds/slapd-instance
&./db2ldif \fB-n\fR userRoot \fB-a\fR /opt/fedora-ds/slapd-instance/db/userRoot.ldif and
&./db2ldif \fB-n\fR NetscapeRoot \fB-a\fR /opt/fedora-ds/slapd-instance/db/NetscapeRoot.ldif
.fi
.na
.PP
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.
.br
.SH AUTHOR
migrate-ds-admin.pl was written by the Fedora Directory Server Project.
.SH "REPORTING BUGS"
Report bugs to http://bugzilla.redhat.com.
.SH COPYRIGHT
Copyright (co 2008 Red Hat, Inc.
.br
This manual page was written by Michele Baldessari ,
for the Debian project (but may be used by others).
.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.

--- NEW FILE remove-ds-admin.pl.8 ---
."                                      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 REMOVE-DS-ADMIN.PL 8 "Feb 24, 2009"
." 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
remove-ds-admin.pl - Remove all Directory Servers and Admin Server
.SH SYNOPSIS
.B remove-ds-admin.pl
[-f] [-d -d ... -d] [-y]
.SH DESCRIPTION
Shuts down and removes all Directory Server instances and the Admin Server
from the system.  The directory server instance configuration
directories will have a .removed extension appended to them, which
will contain the retained certificate database files.

\fBWARNING: This command is extremely destructive!\fR
It will remove all of the data and configuration
of all directory servers and admin servers, with
no chance of recovery.  Therefore, in order to actually
do this, you must give the -y option.  \fBPlease use caution and backup your data if you want to keep it!\fR
.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-f\fR
Force removal - continue on error - otherwise, the command will abort at the first error encountered
.TP
.B \fB-d\fR
Enable debugging - adding more -d will make output more verbose
.TP
.B \fB-y\fR
Do the actual processing.  Since the command is very destructive, you must provide the -y argument in order for the operation to proceed.  \fBUse with extreme caution!\fR
.br
.SH AUTHOR
remove-ds-admin.pl was written by the Fedora Directory Server Project.
.SH "REPORTING BUGS"
Report bugs to http://bugzilla.redhat.com.
.SH COPYRIGHT
Copyright (co 2009 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.

--- NEW FILE setup-ds-admin.pl.8 ---
."                                      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 SETUP-DS-ADMIN.PL 8 "May 18, 2008"
." 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
setup-ds-admin.pl - Set up an instance of Directory Server and Admin Server
.SH SYNOPSIS
.B setup-ds-admin.pl
[\fI--options\fR] \fI-- \fR[\fIargs\fR]
.SH DESCRIPTION
Set up a Directory Server and Admin Server.  Creates the configuration
files for an instance of Directory Server based on a few parameters
like the hostname, port number, and directory manager information.  Creates the configuration
files for the Admin Server.  Starts up the servers.  This command does the set up
necessary for the use of the Console and the Admin Express web interface.

If the Admin Server has already been set up, this command will create a new instance
of Directory Server and register it with the Admin Server so that it can be managed with the Console.

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
Refresh the information used by the Console for all servers on this machine.  Use this after an upgrade to make sure the Console reports the correct information.
.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.
.br
.SH AUTHOR
setup-ds-admin.pl was written by the Fedora Directory Server Project.
.SH "REPORTING BUGS"
Report bugs to http://bugzilla.redhat.com.
.SH COPYRIGHT
Copyright (co 2008 Red Hat, Inc.
.br
This manual page was written by Michele Baldessari ,
for the Debian project (but may be used by others).
.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.