sec_admin(1m)sec_admin(1m)NAMEsec_admin - Registry replica administration tool
SYNOPSISsec_admin [-site name] [-nq]
OPTIONS
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 ran‐
domly 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. 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 verification. If you
invoke sec_admin with the -nq option, the subcommand performs the dele‐
tion 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 mem‐
ory 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, option‐
ally, 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 cre‐
ated. 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
maintained 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 sub‐
sys/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 cur‐
rent 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 dis‐
plays 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 subcom‐
mands.
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. 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 designat‐
ing a different master replica. However, you may find the become -mas‐
ter command useful if the master server is irrevocably damaged and you
are unable to use change_master.
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: Applies all
updates to other_replica Becomes a slave Tells other_replica to become
the master
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: Marks other_replica
as deleted Propagates the deletion to all replicas on its replica list
Delivers the delete request to other_replica 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 propa‐
gate 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.
Lists the sec_admin subcommands and shows their allowed abbreviations.
If command is specified, displays help for the specified command. Dis‐
plays status information about the default replica.
The info subcommand contacts the default replica to obtain the appro‐
priate information. If this information is not available, info prints
the replica name and a message stating the information is not avail‐
able.
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 initial‐
ized 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 Copy‐
ing 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 (applica‐
ble 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-ser‐
vice, copying-database, in-maintenance, master-key-changing and becom‐
ing-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-ser‐
vice 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 net‐
work addresses The unique identifier of the cell's master replica The
network addresses of the cell's master replica The master sequence num‐
ber, 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.
Reinitializes a replica by copying an up-to-date database to
other_replica.
The master replica initiates and guides the operation. If the opera‐
tion is successful The master replica Marks other_replica for reini‐
tialization Tells other_replica to reinitialize itself Gives
other_replica a list of replicas with up-to-date databases 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 cur‐
rent 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.
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 informa‐
tion 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 initialization by the master replica. Initializing—The
replica is in the process of being initialized 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 repli‐
cas 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. Generates a new master key for
the default replica and reencrypts 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.
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 dis‐
played by the info subcommand 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 spec‐
ify. m is a number of minutes between intervals. The default is 15
minutes. Destroy the current default replica. To perform this opera‐
tion, 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. 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 Ser‐
vice 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.
Stops the Security Server (secd) associated with the default replica.
Puts the master replica into maintenance state or takes it out of main‐
tenance 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. The quit and exit subcom‐
mands end the sec_admin session.
EXAMPLES
The following example, invokes sec_admin and uses the lrep subcommand
to list replicas on the replica list and their states: $ /opt/dcelo‐
cal/bin/sec_admin
Default replica: /.../dresden.com/sub‐
sys/dce/sec/rs_server_250_2
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> 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>
sec_admin(1m)