clearinghouse(1m)clearinghouse(1m)NAME
clearinghouse - A dcecp object that manages a clearinghouse in CDS
SYNOPSIS
clearinghouse catalog [cell_name] [-simplename]
clearinghouse create clearinghouse_name_list
clearinghouse delete clearinghouse_name_list
clearinghouse disable clearinghouse_name_list
clearinghouse help [operation | -verbose]
clearinghouse initiate clearinghouse_name_list -checkpoint
clearinghouse operations
clearinghouse repair clearinghouse_name_list -timestamps
clearinghouse show clearinghouse_name_list [-schema | -all | [-coun‐
ters] [-attributes]]
clearinghouse verify clearinghouse_name_list
ARGUMENTS
The name of a single cell. The name must be a fully qualified cell
name as shown in either of the following: /.:
/.../their_cell.goodco.com A list of one or more names of clearing‐
houses you want to operate on. A clearinghouse can be specified in
either of the following forms: /.:/name_ch
/.../cell_name/name_ch The name of the clearinghouse operation for
which to display help information.
DESCRIPTION
The clearinghouse object represents Cell Directory Service (CDS) clear‐
inghouses. Clearinghouses are databases located on CDS server machines
that store data (directories, objects, and links) in CDS. The server
machines hold files that contain the actual clearinghouse data. Clear‐
inghouses are also represented in the CDS namespace by an entry that
contains information about the clearinghouse.
You must run the create operation on the host where you want to create
the new clearinghouse and the delete, disable, initiate, repair, and
verify operations on the host where the clearinghouse to be operated on
resides.
ATTRIBUTES
The following are the CDS-defined attributes that may be present in CDS
clearinghouse objects: Indicates the date and time the clearinghouse
object has been updated to reflect the CDS_CHDirectories attribute.
Specifies the full name and Universal Unique Identifier (UUID) of every
directory that has a replica in this clearinghouse. Specifies the cur‐
rent reported network address of the clearinghouse. Specifies the full
name of the clearinghouse. Specifies the state of the clearinghouse.
The state on indicates the clearinghouse is running and available.
Specifies the creation timestamp (CTS) of the clearinghouse. Specifies
the current version of the directory in the clearinghouse in which the
directory was created. Specifies the name of the cell in which the
clearinghouse resides. Specifies the UUID of the clearinghouse. This
read-only attribute is set by the system when the clearinghouse is cre‐
ated and cannot be modified by the user. Specifies the current version
of the replica in which the directory was created. The default is 3.0.
If an upgrade has taken place, the value will upgrade to 4.0. A sin‐
gle-valued attribute used to control the upgrading of a clearinghouse
from one version of CDS to another. By modifying this attribute, the
process of upgrading a clearinghouse to a newer version of CDS may be
initiated. Specifies the DTS-style, read-only timestamp of the most
recent update to an attribute of the clearinghouse. The value is set
by the system.
Counters
Specifies the number of times that a clearinghouse generated a data
corruption event. Specifies the number of times that the clearinghouse
was disabled since it was last started. Specifies the number of times
that a clearinghouse was enabled since it was last started, not includ‐
ing the initial startup. Specifies the number of times that upgrades
failed when using the CDS-UpgradeTo attribute. Specifies the number of
times the clearinghouse entry missing event was generated. Specifies
the number of read operations directed to this clearinghouse. Speci‐
fies the number of requests directed to this clearinghouse that
resulted in the return of a partial answer instead of satisfying the
client's entire request. Specifies the number of times the root lost
event was generated by the clearinghouse. Specifies the number of
times that a skulk of a directory, initiated from this clearinghouse,
failed to complete (usually because one of the replicas in the replica
set was unreachable). Specifies the number of write operations
directed to this clearinghouse.
See the OSF DCE Administration Guide for more information about clear‐
inghouse attributes and counters.
OPERATIONS
clearinghouse catalog
Returns a list of the names of all clearinghouses in a cell. The syn‐
tax is as follows: clearinghouse catalog [cell_name] [-simplename]
Option Returns a list of clearinghouse names in a cell without prepend‐
ing the cellname.
The catalog operation returns a list of the names of all clearinghouses
in a cell. If you do not specify the optional cell_name argument, the
cell name defaults to the local cell.
Privileges Required
No special privileges are needed to use the clearinghouse catalog com‐
mand.
Examples
dcecp> clearinghouse catalog /.../dcecp.cell.osf.org/frick_ch dcecp>
dcecp> clearinghouse catalog -simplename frick_ch dcecp>
clearinghouse create
Creates a new clearinghouse on the local machine. The syntax is as
follows: clearinghouse create clearinghouse_name_list
The create operation creates a new clearinghouse on the local machine.
The clearinghouse_name_list argument is a list of one or more names of
the clearinghouses you want to create. Clearinghouses should be named
only in the root directory (that is, /.:). This operation also stores
a read-only replica of the root directory in the new clearinghouse.
The process that creates the new clearinghouse initiates a skulk of the
root directory, so all replicas of the root should be reachable when
you enter the clearinghouse create command. To ensure this, perform an
immediate skulk of /.: before invoking the command, using the directory
synchronize /.: command. Standard clearinghouse naming convention
strongly suggests that the clearinghouse name end with the string
"_ch". Many existing scripts expect this naming convention to be fol‐
lowed. This operation returns an empty string on sucess.
Privileges Required
You need w (write) permission to the server on which you intend to cre‐
ate the clearinghouse, and A (Admin) permission to the cell root direc‐
tory. The server principal (hosts/hostname/cds-server) needs r (read),
w (write), and A (Admin) permission to the cell root directory.
Examples
The following command creates a clearinghouse named /.:/Boston_ch on
the local server system: dcecp> clearinghouse create /.:/Boston_ch
dcecp>
clearinghouse delete
Deletes the specified clearinghouse from the local machine. The syntax
is as follows: clearinghouse delete clearinghouse_name_list
The delete operation deletes the specified clearinghouse from the local
server system. The clearinghouse_name_list argument is a list of one
or more names of the clearinghouses you want to delete. Clearinghouses
that contain master replicas of directories are not deleted (and also
return errors). This command also automatically deletes all read-only
replicas from the clearinghouse; however, you should delete all read-
only replicas by hand (see directory delete -replica) before invoking
this command since invoking many skulks causes the command to execute
more slowly. This operation returns an empty string on success.
CDS does not permit you to delete a disabled (cleared) clearinghouse.
Before you can do so, re-create the clearinghouse, using the clearing‐
house create command.
Privileges Required
You must have w (write) and d (delete) permission to the clearinghouse
and A (Admin) permission to all directories that store replicas in the
clearinghouse. The server principal (hosts/hostname/cds-server) must
have d (delete) permission to the associated clearinghouse object entry
and A (Admin) permission to all directories that store replicas in the
clearinghouse.
Examples
The following command deletes a clearinghouse named /.:/Orion_ch from
the local server system: dcecp> clearinghouse delete /.:/Orion_ch
dcecp>
clearinghouse disable
Removes knowledge of the specified clearinghouse from the local
server's memory. The syntax is as follows: clearinghouse disable
clearinghouse_name_list
The disable operation removes knowledge of the specified clearinghouse
from the local server's memory. The clearinghouse_name_list argument
is a list of names of one or more clearinghouses you want to disable.
Use this command when relocating a clearinghouse. This command removes
the name of the prefix of the clearinghouse files from the /opt/dcelo‐
cal/var/directory/cds/cds_files file and notifies the local CDS server
that the clearinghouse is disabled. The clearinghouse entry is not
removed from the namespace, nor are the datafiles associated with the
clearinghouse removed. This operation returns an empty string on suc‐
cess.
Privileges Required
You must have w (write) permission to the CDS server on which the
clearinghouse resides.
Examples
The following command disables the clearinghouse /.:/Paris2_ch so that
it can be moved to another server: dcecp> clearinghouse disable
/.:/Paris2_ch dcecp>
clearinghouse help
Returns help information about the clearinghouse object and its opera‐
tions. The syntax is as follows: clearinghouse help [operation | -ver‐
bose]
Options
Displays information about the clearinghouse object.
Used without an argument or option, the clearinghouse help command
returns brief information about each clearinghouse operation. The
optional operation argument is the name of an operation about which you
want detailed information. Alternatively, you can use the -verbose
option for more detailed information about the clearinghouse object
itself.
Privileges Required
No special privileges are needed to use the clearinghouse help command.
Examples
dcecp> clearinghouse help catalog Returns the names of all
clearinghouses in a cell. create Creates the named clear‐
inghouse. delete Deletes the named clearinghouse. dis‐
able Disables the named clearinghouse. initiate
Initiates an action on the named CDS clearinghouse. repair
Repairs an aspect of the named CDS clearinghouse. show
Returns the attributes of a clearinghouse. verify Veri‐
fies the consistency of the clearinghouse. help Prints
a summary of command-line options. operations Returns a list
of the valid operations for this command. dcecp>
clearinghouse initiate
Initiates a defined action on the specified clearinghouse on the local
machine. The syntax is as follows: clearinghouse initiate clearing‐
house_name_list -checkpoint
Options
Forces the clearinghouse to checkpont to disk.
The initiate operation initiates a defined action on the specified
clearinghouse. The required clearinghouse_name_list argument is a list
of names of clearinghouses you want to initiate actions on. Currently,
only a checkpoint action is available. This operation returns an empty
string on success.
Privileges Required
You need w (write) permission on the clearinghouse server and A (admin)
permission on the cell root directory. The server principal
(hosts/hostname/cds-server) needs r (read), w (write), and A (Admin)
permission on the cell root directory.
Examples
The following command initiates a checkpoint operation on the clearing‐
house named /.:/oddball_ch on the local system.
dcecp> clearinghouse initiate /.:/oddball_ch -checkpoint dcecp>
clearinghouse operations
Returns a list of the operations supported by the clearinghouse object.
The syntax is as follows: clearinghouse operations
The list of available operations is in alphabetical order except for
help and operations, which are listed last.
Privileges Required
No special privileges are needed to use the clearinghouse operations
command.
Examples
dcecp> clearinghouse operations catalog create delete disable initiate
repair show verify help operations dcecp>
clearinghouse repair
Repairs a specific problem on a specified clearinghouse on the local
machine. The syntax is as follows: clearinghouse repair clearing‐
house_name_list -timestamps
Options
Analyzes and repairs invalid timestamps found in a clearinghouse.
Use the repair operation to fix various problems that can occur in a
clearinghouse. The required clearinghouse_name_list argument is a list
of names of clearinghouses you want to initiate repair actions on.
Currently, only invalid timestamps can be repaired. This operation
returns an empty string on success.
Privileges Required
You need w (write) permission to the clearinghouse server and A (Admin)
permission to the cell root directory. The server principal
(hosts/hostname/cds-server) needs r (read), w (write), and A (Admin)
permission to the cell root directory.
Examples
The following command repairs invalid timestamps in a clearinghouse
named /.:/blech_ch on the local system.
dcecp> clearinghouse repair /.:/blech_ch -timestamps dcecp>
clearinghouse show
Returns attribute and counter information associated with the specified
clearinghouses on local or remote machines. The syntax is as follows:
clearinghouse show clearinghouse_name_list [-schema | -all | [-coun‐
ters] [-attributes]]
Options
Indicates whether attributes are single-valued or multi-valued.
Returns the attributes and counters for the clearinghouse. Returns the
attributes for the clearinghouse. Returns the counters for the clear‐
inghouse.
The show operation displays attribute and counter information associ‐
ated with the clearinghouses specified by clearinghouse_name_list,
which is a list of one or more names of the clearinghouses. If more
than one clearinghouse is specified, the attributes of all the clear‐
inghouses are concatenated into one list. The order of the returned
attributes is the lexical order of the object identifiers (OIDs) of
each attribute for each clearinghouse.
If you supply no options, clearinghouse show returns the attributes
associated with the specified clearinghouse.
Privileges Required
You must have r (read) permission to the clearinghouse.
Examples
dcecp> clearinghouse show /.:/drkstr_ch {CDS_CTS
1994-06-18-20:16:22.150-05:00I0.000/00-00-c0-f7-de-56} {CDS_UTS
1994-06-19-17:17:43.911-05:00I0.000/00-00-c0-f7-de-56} {CDS_ObjectUUID
0066ccea-d978-1db3-8259-0000c0f7de56} {CDS_AllUpTo
1994-07-01-21:30:18.948-05:00I0.000/00-00-c0-f7-de-56} {CDS_Directo‐
ryVersion 3.0} {CDS_CHName /.../terrapin/drkstr_ch} {CDS_CHLastAddress
{Tower ncacn_ip_tcp 130.105.5.16}
{Tower ncadg_ip_udp 130.105.5.16}} {CDS_CHState on} {CDS_CHDirectories
{{Dir_UUID 00146037-d97b-1db3-8259-0000c0f7de56}
{Dir_Name /.../terrapin}}
{{Dir_UUID 0043797a-d991-1db3-8259-0000c0f7de56}
{Dir_Name /.../terrapin/subsys}}
{{Dir_UUID 004faa42-d992-1db3-8259-0000c0f7de56}
{Dir_Name /.../terrapin/subsys/HP}}
{{Dir_UUID 004fa65a-d993-1db3-8259-0000c0f7de56}
{Dir_Name /.../terrapin/subsys/HP/sample-apps}}
{{Dir_UUID 004b1130-d994-1db3-8259-0000c0f7de56}
{Dir_Name /.../terrapin/subsys/dce}}
{{Dir_UUID 00498a0e-d995-1db3-8259-0000c0f7de56}
{Dir_Name /.../terrapin/subsys/dce/sec}}
{{Dir_UUID 003ed80c-d996-1db3-8259-0000c0f7de56}
{Dir_Name /.../terrapin/subsys/dce/dfs}}
{{Dir_UUID 003d4d8e-d997-1db3-8259-0000c0f7de56}
{Dir_Name /.../terrapin/hosts}}
{{Dir_UUID 003bc522-d998-1db3-8259-0000c0f7de56}
{Dir_Name /.../terrapin/hosts/drkstr}}
{{Dir_UUID 0089ee8c-44e0-1dbe-929b-0000c0f7de56}
{Dir_Name /.../terrapin/help}}
{{Dir_UUID 001c6cea-00fb-1dc5-929b-0000c0f7de56}
{Dir_Name /.../terrapin/test_1}}
{{Dir_UUID 00440fe8-02a1-1dc5-929b-0000c0f7de56}
{Dir_Name /.../terrapin/dirmod}}} {CDS_ReplicaVersion 3.0}
{CDS_NSCellname /.../terrapin} dcecp>
dcecp> clearinghouse show /.:/chicago1_ch -counters {corruptions 0}
{disables 0} {enables 1} {failedupgrades 0} {missingentries 0} {reads
2336} {returnedrefs 2} {rootunreachables 0} {skulkfailures 0} {writes
68} dcecp>
clearinghouse verify
Verifies the consistency of the specified clearinghouse on the local
machine. The syntax is as follows: clearinghouse verify clearing‐
house_name_list
The verify operation verifies the consistency of the specified clear‐
inghouse by checking internal attributes. The required clearing‐
house_name_list argument is a list of one or more names of clearing‐
houses you want to verify. This operation returns an empty string on
success.
Privileges Required
You need w (write) permission to the clearinghouse server and A (Admin)
permission to the cell root directory. The server principal
(hosts/hostname/cds-server) needs r (read), w (write), and A (Admin)
permission to the cell root directory.
Examples
The following command verifies the consistency of clearinghouses named
/.:/gumby_ch and /.:/pokey_ch.
dcecp> clearinghouse verify {/.:/gumby_ch /.:/pokey_ch} dcecp>
RELATED INFORMATION
Commands: dcecp(1m), dcecp_cdscache(1m), dcecp_directory(1m),
dcecp_link(1m), dcecp_object(1m).
clearinghouse(1m)