NAME

sec_admin - Registry replica administration tool

SYNOPSIS

sec_admin  [-site name] [-nq]

OPTIONS

-site nameCauses 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 one of the following:

       •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 (CDS) is not available. 

-nqTurns off queries initiated by certain sec_admin subcommands before they perform a specified operation.  For example, the delrep subcommand deletes a registry replica; before the deletion, sec_admin prompts for verification.  If you invoke sec_admin with the ­-nq option, the deletion is performed without prompting. 

DESCRIPTION

Note:   With the exception of the following subcommands, this command is replaced at DCE Version 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

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

Use the site subcommand to change the default replica and, optionally, the default cell.  When you use the site subcommand, 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 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 that the following is true of a replica named subsys/dce/sec/rs_server_250_2:

       •It exists in the local cell /.../dresden.com. 

       •It has a global name of /.../dresden.com/subsys/dce/sec/rs_server_250_2. 

       •It is named subsys/dce/sec/rs_server_250_2 on the replica list. 

       •It runs on a host whose ip network address is 15.22.144.248. 

This replica can 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 the previous section, 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 that the following are replicas in the cell /.../bayreuth.com:

/.../bayreuth.com/subsys/dce/sec/rs_server_300_1
/.../bayreuth.com/subsys/dce/sec/rs_server_300_2

If you enter site /.../bayreuth.com, then /.../bayreuth.com becomes the default cell and one of the following becomes the default replica:

/.../bayreuth.com/subsys/dce/sec/rs_server_300_1
/.../bayreuth.com/subsys/dce/sec/rs_server_300_2

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 subcommand 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.  The other_replica argument 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
Makes 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 does the following:

     1.Applies all updates to other_replica. 

     2.Becomes a slave. 

     3.Tells other_replica to become the master. 

delr[ep] other_replica [-force]
Deletes 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 does the following:

     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 that the information is not available.  Without the ­-full option, info displays the following:

       •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 StateThe 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

InitializingThe replica is in the process of being initialized by the master replica or another up-to-date replica

In ServiceThe 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)

ClosedThe replica is in the process of stopping

DeletedThe replica is in the process of deleting itself

Duplicate Master
The replica is 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, Changing Master Key, 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 the In Service, Copying Database, Changing Master Key, 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 as well:

       •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, 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 the operation is successful, the following actions take place:

     1.The master replica does the following:

     1.Marks other_replica for reinitialization. 

     2.Tells other_replica to reinitialize itself. 

     3.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 following:

       •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 StateThe state of the replica prohibits the requested operation. 

Marked for Initialization
The replica has been marked for deletion by the master replica.

InitializedThe replica has been marked for initialization by the master replica. 

InitializingThe 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 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 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.

monitor [-r m]
Periodically lists 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 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 specify.  The m argument is a number of minutes between intervals.  The default is 15 minutes. 

destroy default_replica
Destroys 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]]]
Sets or displays 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 one of the following:

       •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 CDS 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. 

stopStops 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]
Ends the sec_admin session. 

EXAMPLES

     1.The following example invokes sec_admin and uses the lrep subcommand to list replicas on the replica list and their states:

/opt/dcelocal/bin/sec_admin
          Default replica: \
            /.../dresden.com/subsys/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

     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

RELATED INFORMATION

Commands: rgy_edit(8sec), dtscp(8dts).