NAME
sec_admin - Registry replica administration tool
SYNOPSIS
sec_admin [-site name] [-nq]
OPTIONS
-site name
The -site option causes sec_admin to bind to the replica
specified by the name argument. If the option is not
supplied, sec_admin binds randomly to any replica in the
local cell. The name argument can be:
+ A specific cell_name (or /.: for the local cell) to
bind to any replica in the named cell.
+ The global name of a replica to bind to that specific
replica in that specific cell.
+ The name of a replica as it appears on the replica list
to bind to that replica in the local cell.
+ A string binding to a specific replica. An example of a
string binding is ncadg_ip_udp:15.22.144.163. This form
is used primarily for debugging or if the Cell Directory
Service is not available.
-nq The -nq flag turns off queries initiated by certain sec_admin
subcommands before they perform a specified operation. For
example the delrep subcommand deletes a registry replica.
Before sec_admin performs the deletion, it prompts for verifi-
cation. If you invoke sec_admin with the -nq option, the
subcommand performs the deletion without prompting.
NOTES
With the exception of the following subcommands, this command is
replaced at Revision 1.1 by the dcecp command. This command may be
fully replaced by the dcecp command in a future release of DCE, and
may no longer be supported at that time.
+ monitor
+ exit
+ help
+ quit
DESCRIPTION
The registry database is replicated: each instance of a registry server,
secd, maintains a working copy of the database in virtual memory and on
disk. One server, called the master replica, accepts updates and handles
the subsequent propagation of changes to all other replicas. All other
replicas are slave replicas, which accept only queries. Each cell has
one master replica and numerous slave replicas.
Using the sec_admin command you can:
+ View a list of replicas
+ Delete a replica
+ Reinitialize a replica
+ Stop a replica
+ Put the master replica into and out of the maintenance state
+ Generate a new master key used to encrypt principal keys
+ Turn the master registry into a slave registry and a slave registry
into the master registry..
Note that sec_admin cannot add, delete, or modify information in the
database, such as names and accounts. Use rgy_edit to modify registry
database entries.
THE DEFAULT REPLICA AND DEFAULT CELL
Most sec_admin commands are directed to a default replica. When
sec_admin is invoked, it automatically binds to a replica in the local
cell. This replica becomes the default replica.
Identifying the Default Replica and the Default Cell
You use the site subcommand to change the default replica and,
optionally, the default cell. When you use the site command, you can
supply the name of a specific replica, or you can simply supply the
name of a cell. If you supply a cell name, sec_admin binds to a
replica in that cell randomly. If you supply a specific replica name,
sec_admin binds to that replica.
Specifically, you can supply any of the following names to the site
subcommand:
+ A cell name. If you enter a cell name, the named cell becomes the
default cell. The sec_admin command randomly chooses a replica to
bind to in the named cell, and that replica becomes the default
replica.
+ The global name given to the replica when it was created. A global
name identifies a specific replica in a specific cell. That cell
becomes the default cell and that replica the default replica.
+ The replica's name as it appears on the replica list (a list main-
tained by each Security Server containing the network addresses of
each replica in the local cell). That replica becomes the default
replica and the cell in which the replica exists becomes the
default cell.
+ The network address of the host on which the replica is running.
The replica on that host becomes the default replica, and the cell
in which the host exists becomes the default cell.
Naming the Default Replica
As an example, assume a replica named subsys/dce/sec/rs_server_250_2:
+ Exists in the local cell /.../dresden.com
+ Has a global name of /.../dresden.com/subsys/dce/sec/rs_server_250_2
+ Is named subsys/dce/sec/rs_server_250_2 on the replica list
+ Runs on a host whose ip network address is 15.22.144.248
This replica can then be identified to the site subcommand in any of the
following ways:
+ /.../dresden.com/subsys/dce/sec/rs_server_250_2 - The replica's full
global name.
+ subsys/dce/sec/rs_server_250_2 - The replica's cell-relative name on
the replica list.
+ ncadg_ip_udp:15.22.144.248 - The network address of the host on
which the replica runs.
Naming the Default Cell
When a default replica is identified specifically, its cell becomes the
default cell. In the example in "Naming the Default Replica" above, the
default cell is /.../dresden.com.
You can specify simply a cell name to the site subcommand. When this is
done, any replica in that cell is selected as the default replica.
For example, assume
/.../bayreuth.com/subsys/dce/sec/rs_server_300_1
and
/.../bayreuth.com/subsys/dce/sec/rs_server_300_2
are replicas in the cell /.../bayreuth.com.
If you type
site /.../bayreuth.com
then
/.../bayreuth.com
becomes the default cell and either
/.../bayreuth.com/subsys/dce/sec/rs_server_300_1
or
/.../bayreuth.com/subsys/dce/sec/rs_server_300_2
becomes the default replica.
AUTOMATIC BINDING TO THE MASTER
Some of the sec_admin subcommands can act only on the master registry
and thus require binding to the master registry. If you execute a sub-
command that acts only on the master and the master is not the default
replica, sec_admin attempts to bind to the master replica in the
current default cell automatically. If this attempt is successful,
sec_admin displays a warning message informing you that the default
replica has been changed to the master registry. The master registry
will then remain the default replica until you change it with the site
subcommand. If the attempt to bind is not successful, sec_admin
displays an error message, and the subcommand fails.
INVOKING sec_admin
When you invoke sec_admin, it displays the current default replica's
full global name and the cell in which the replica exists. Then it
displays the sec_admin> prompt.
$ sec_admin
Default replica: /.../dresden.com/subsys/dce/sec/music
Default cell: /.../dresden.com
sec_admin>
At the sec_admin> prompt, you can enter any of the sec_admin
subcommands.
SUBCOMMANDS
The subcommand descriptions that follow use default_replica to indicate
the default replica and other_replica to indicate a replica other than
the default. other_replica must identify a replica in the default cell.
It is specified by its name on the cell's replica list (that is, by its
cell-relative name). Use the lrep subcommand to view the default cell's
replica list.
become [ -master ] [ -slave ]
The -master option makes the current default replica (which
must be a slave) the master replica.
The -slave option makes the current default replica (which
must be the master) a slave replica.
This method of changing to master or slave can cause updates
to be lost. The change_master subcommand is the preferred
means of designating a different master replica. However,
you may find the become -master command useful if the master
server is irrevocably damaged and you are unable to use
change_master.
change_master -to other_replica
Make the replica specified by other_replica the master
replica. To perform this operation, other_replica must be
a slave, and the current default replica must be the master.
If the current default replica is not the master, sec_admin
attempts to bind to the master.
If the change operation is successful, the current master:
1. Applies all updates to other_replica
2. Becomes a slave
3. Tells other_replica to become the master
delr[ep] other_replica [-force ]
Delete the registry replica identified by other_replica. To
perform this operation, the current default replica must be
the master. If it is not, sec_admin attempts to bind to the
master.
If the delete operation is successful, the master:
1. Marks other_replica as deleted
2. Propagates the deletion to all replicas on its replica
list
3. Delivers the delete request to other_replica
4. Removes other_replica from its replica list
The -force option causes a more drastic deletion. It causes the master
to first delete other_replica from its replica list and then to
propagate the deletion to the replicas that remain on its list. Since
this operation never communicates with the deleted replica, you should
use -force only when the replica has died irrecoverably. If you use
-force while other_replica is still running, you should then use the
destroy subcommand to eliminate the deleted replica.
h[elp] [command]
Lists the sec_admin subcommands and shows their allowed
abbreviations. If command is specified, displays help for
the specified command.
info [-full]
Displays status information about the default replica.
The info subcommand contacts the default replica to obtain the
appropriate information. If this information is not available,
info prints the replica name and a message stating the
information is not available.
Without the -full option, info displays:
+ The default replica's name and the name of the cell in
which the replica exists
+ Whether the replica is a master or a slave
+ The date and time the replica was last updated and the
update sequence number
+ An indication of the replica's state, as follows:
- Bad State - The state of the replica prohibits the
requested operation.
- Uninitialized - The database is a stub database that
has not been initialized by the master replica or
another up-to-date replica
- Initializing - The replica is in the process of being
initialized by the master replica or another up-to-date
replica
- In Service - The replica is available for queries and
propagation updates if it is a slave replica or queries
and updates if it is the master replica
- Copying Database - The replica is in the process of
initializing (copying its database to) another replica
- Saving Database - The replica is in the process of
saving its database to disk.
- In Maintenance - The replica is unavailable for updates
but will accept queries
- Changing Master Key - The replica is in the process of
having its master key changed
- Becoming Master- The replica is in the process of
becoming the master replica (applicable to slave
replicas only)
- Becoming Slave- The master replica is in the process
of becoming a slave replica (applicable to the master
replicas only)
- Closed - The replica is in the process of stopping
- Deleted - The replica is in the process of deleting
itself
- Duplicate Master - The replica a duplicate master and
should be deleted.
The master replica is available for queries when it is in the
in-service, copying-database, in-maintenance, master-key-
changing and becoming-slave states. It is available for
updates only when it is in the in-service state.
A slave replica is available for queries when it is in the in-
service, copying-database, master-key-changing and becoming-
master states. It accepts updates from the master replica
only when it is in the in-service state. It accepts a request
from the master replica to initialize only when it is in the
uninitialized or in-service state.
The -full option displays all the above information and the following
information:
+ The default replica's unique identifier
+ The replica's network addresses
+ The unique identifier of the cell's master replica
+ The network addresses of the cell's master replica
+ The master sequence number, which is the sequence number
of the event that made the replica the master
+ If the replica is the master replica, the update sequence
numbers that are still in the propagation queue and have
yet to be propagated
+ The DCE software version number.
initr[ep] other_replica
Reinitializes a replica by copying an up-to-date database to
other_replica.
The master replica initiates and guides the operation. If th
operation is successful
1. The master replica
a. Marks other_replica for reinitialization
b. Tells other_replica to reinitialize itself
c. Gives other_replica a list of replicas with
up-to-date databases
2. The other_replica picks a replica from the list and asks
that replica to initialize it (that is, to copy its
database to other_replica)
To perform this operation, other_replica must be a slave, and the
current default replica must be the master. If the current default
replica is not the master, sec_admin attempts to bind to the master.
This subcommand is generally not used under normal conditions.
lr[ep] [-s[tate]] [-u[uid]] [-a[ddr]] [-p[rop]] [-al[l]]
Lists the replicas on the default replica's replica list.
If you enter no options, the display includes the replica name
and whether or not it is the master replica. In addition if
the master replica's list is being displayed, slave replicas
marked for deletion are noted. With options, the display
includes this information and the information described in the
following paragraphs.
The -state option shows each replica's current state, the date
and time the replica was last updated, and the update sequence
number. To obtain this information, lrep contacts each
replica. If this information is not available from the
replica, lrep prints the replica name and a message stating
the information is not available.
The -addr option shows each replica's network addresses.
The -uuid option shows each replica's unique identifier.
The -prop option shows:
+ The date and time of the last update the master sent to
each slave replica
+ The sequence number of the last update to each slave
replica
+ The number of updates not yet applied to each slave replica
+ The status of the master replica's last communication with
each slave replica
+ The propagation state of each slave replica. This state,
illustrates how the master replica views the slave replica,
can be any of the following:
- Bad State-The state of the replica prohibits the
requested operation.
- Marked for Initialization-The replica has been marked
for deletion by the master replica.
- Initialized-The replica has been marked for initializa-
tion by the master replica.
- Initializing-The replica is in the process of being ini-
tialized by the master replica.
- Ready for Updates-The replica has been initialized by
the master replica and in now available for propagation
updates from the master replica.
- Marked for Deletion-The replica has been marked for
deletion by the master replica.
This information is obtained from the master replica; the slave replicas
are not contacted for this information.
The -prop option is valid only for the master.
For slave replicas, the -all option shows all the information above
except that displayed by the -prop option. For the master replica, the
-all option shows all the information.
mas[ter_key]
Generates a new master key for the default replica and re-
encrypts account keys using the new key. The new master key
is randomly generated.
Each replica (master and slaves) maintains its own master key
used to access the data in its copy of the database.
monitor [-r m]
Periodically list the registry replicas stored in the current
default replica's replica list. The list includes each
replica's current state, the date and time the replica was
last updated and the update sequence number. Note that this
is the same information as that displayed by the info sub-
command with no options. The monitor subcommand contacts
each replica to obtain the information it displays. If this
information is not available from the replica, monitor prints
the replica name and a message stating the information is not
available.
The -r option causes the replicas to be listed at intervals
you specify. m is a number of minutes between intervals. The
default is 15 minutes.
destroy default_replica
Destroy the current default replica. To perform this
operation, the current default replica and the default
replica you name as default_replica must be the same. This
is to confirm your desire to perform the deletion.
If the operation is successful, the default replica deletes
its copy of the registry database and stops running. This
subcommand does not delete default_replica from the replica
lists. Use the delrep -force subcommand to delete the replica
from the other replica lists.
The preferred way to delete replicas is to use the delrep
subcommand. However, the destroy subcommand can be used if
delrep is unusable because the master is unreachable or the
replica is not on the master's replica list.
site [name [-u[pdate]]]
Set or display the default cell and the default replica.
The name argument identifies the replica to set as the default
replica and, as a consequence, the default cell. It can be:
+ A specific cell_name (or /.: for the local cell) to make
any replica in the named cell the default.
+ The global name of a replica to make the specified replica
in the specified cell the default.
+ The name of a replica as it appears on the replica list to
make the named replica (which exists in the default cell)
the default replica.
+ A string binding to a specific replica. An example of a
string binding is ncadg_ip_udp:15.22.144.163. This form is
used primarily for debugging or if the Cell Directory
Service is not available.
The -u option specifies that sec_admin should find the master replica.
Normally you specify the name of a cell for name in conjunction with
the -u option. In this case sec_admin finds the master replica in that
cell. If you use a replica name for name, sec_admin queries the named
replica to find the master replica in the named replica's cell.
If you supply no arguments, sec_admin displays the current default
replica and default cell.
stop Stops the Security Server (secd) associated with the default
replica.
sta[te] -maintenance | -service
Puts the master replica into maintenance state or takes it out
of maintenance state. This subcommand is useful for performing
backups of the registry database.
If the current default replica is not the master, sec_admin
attempts to bind to the master.
The -maintenance flag causes the master replica to save its
database to disk and refuse any updates.
The -service flag causes the master replica to return to its
normal "in service" state and start accepting updates.
e[xit] or q[uit]
The quit and exit subcommands end the sec_admin session.
EXAMPLES
1. The following example, invokes sec_admin and uses the lrep sub-
command to list replicas on the replica list and their states:
$ r sys$system:dce$sec_admin
Default replica: /.../dresden.com/subsys/dce/sec/rs_server_250_
Default cell: /.../dresden.com
sec_admin> lrep -st
Replicas in cell /.../dresden.com
(master) subsys/dce/sec/master
state: in service
Last update received at: 1993/11/16.12:46:59
Last update's seqno: 0.3bc
subsys/dce/sec/rs_server_250_2
state: in service
Last update received at: 1993/11/16.12:46:59
Last update's seqno: 0.3bc
subsys/dce/sec/rs_server_250_3
state: in service
Last update received at: 1993/11/16.12:46:59
Last update's seqno: 0.3bc
sec_admin>
2. The following example, sets the default replica to the master in
the local cell:
sec_admin> site /.: -u
Default replica: /.../dresden.com/subsys/dce/sec/master
Default cell: /.../dresden.com
sec_admin>