You can use the ADD, CREATE, DELETE, ENABLE, DISABLE, REMOVE, SET, SHOW and UPDATE directives with the DSA entity. The CREATE and DELETE directives are used to create and delete a DSA. The ENABLE and DISABLE directives are used to enable or disable the DSA for communication with directory applications and other DSAs. The SET, SHOW, ADD and REMOVE directives are used to manage DSA attributes. The UPDATE directive is used to initiate replication between DSAs. To use any directives other than the SHOW directive, you require privileges.
1 – ADD
Use the ADD directive to add additional values to a DSA
multi-valued characteristic attribute. The DSA multi-valued
characteristic attributes are:
- READ ONLY DSA NSAPS
- READ ONLY DSA NAMES
- WRITER NAMES
- WRITER NSAPS
- READER NAMES
- READER NSAPS
- TRUSTED DSA NAMES
- TRUSTED DSA NSAPS
Syntax:
ADD DSA <characteristic> {<value>,...}
where <characteristic> is the name of the Characteristic attribute
and <value> is the value you want to add to the attribute. Note
the use of {} to enclose the values of a multivalued attribute.
These must be used even if only one value is actually specified.
2 – CREATE
Use this directive to create a DSA. On completion of this directive, the state of the DSA is OFF. You can then create subentities of the DSA entity, and manage the attributes of the DSA entity and its subentities. Syntax: CREATE DSA When the DSA is being created, it reads its database into memory. If the DSA does not have a database yet, it creates a new one automatically. DSAs on Tru64 UNIX systems use memory image files instead of the snapshot files since V3.0. The DSA can read and write memory image files much faster, especially for large databases. By default, the DSA always reads a memory image file, if a valid one is available. If not, it reads a snapshot file, if one is available, or creates a new database if not. You can use arguments to the CREATE DSA command to specify which type of database file you want the DSA to read during creation. If you use these arguments, the DSA only attempts to read the specified type of database file, and does not fallback to the other type or create a new database. See the Arguments topic for further details. After you have created the DSA for the first time, using the CREATE DSA command with no arguments, you must set values for the AE Title and Presentation Address attributes of the DSA entity. You cannot enable a DSA that does not have these two attributes set. This version provides a DSA configuration utility that simplifies the setting of these attributes. After creation for the first time you are also advised to set the Volatile Modifications attribute to TRUE. Refer to the help for this characteristic attribute for further details. During subsequent DSA creations, the DSA refers to its own database and configures itself automatically.
2.1 – Arguments
DSAs on Tru64 UNIX systems support arguments to the CREATE DSA
directive. The arguments are as follows:
Syntax:
CREATE DSA [FROM MEMORY IMAGE | FROM SNAPSHOT]
If you use the FROM MEMORY IMAGE argument, the DSA attempts to
read a memory image file, and returns a DSA Information Tree
Corrupt error if none is available. The DSA does not attempt
to read a snapshot file or create a new database. If the DSA
can find a valid memory image file, it returns a message
indicating that is has successfully read the memory image file.
The memory image file contains a copy of the schema. This means
that the DSA does not read the schema during creation. However,
the DSA displays a warning message if its copy of the schema
is not the same as the schema file. If the schema has been
changed, use the following commands to force the DSA to read it:
> DELETE DSA TO SNAPSHOT
> CREATE DSA FROM SNAPSHOT
If you use the FROM SNAPSHOT argument, the DSA attempts to read
a snapshot file, as in previous versions, and returns a DSA
Information Tree Corrupt error if none is available. The DSA does
not attempt to read a memory image file or create a new database.
If the DSA can find a valid snapshot file, it returns a message
indicating that is has successfully read the snapshot file.
Do not use the FROM SNAPSHOT argument unless a management
tasks specifically requires it. A snapshot file is
significantly less efficient than a memory image file, and if
you create a snapshot file that is more recent than a memory
image file, you invalidate the memory image file. The FROM
SNAPSHOT argument is supported for a small number of management
tasks only. Forcing the DSA to read a new schema is one of those
tasks.
2.2 – Responses
The CREATE DSA directive can return one of the following
responses:
New DSA database created. Configure the DSA.
This means that the DSA has been created for the first time.
Use the DSA configuration utility to give the DSA a basic
configuration.
DSA created successfully from memory image file.
This means that the DSA has been created from a valid memory
image file.
DSA created successfully from memory image file.
Schema Warning: The memory image file does not use
the current schema.
This means that the DSA has been created from a valid memory
image file. However, the DSA detected that the copy of the
schema in its memory image file is not the same as the one
in /var/dxd. If the schema has been customized, you should
force the DSA to read the new schema. Use the following
commands:
> DELETE DSA TO SNAPSHOT
> CREATE DSA FROM SNAPSHOT
This forces the DSA to read the schema during creation.
DSA created successfully from snapshot file.
This means that the DSA has been created from a valid
snapshot file. On Tru64 UNIX systems, you should only
use a snapshot file for management tasks that specifically
require it. On the first occasion that you start the DSA
after an upgrade, the DSA reads the existing snapshot file.
After the first DIT check interval, or when you delete the
DSA, the DSA creates a memory image file. It then reads
and writes memory image files unless specifically instructed
to read or write a snapshot file.
2.3 – Errors
The CREATE directive can return one of the following errors:
REASON: Already Exists
DESCRIPTION: The DSA entity already exists.
REASON: Communication Failure
DESCRIPTION: There has been a failure in communication.
This means that communication has not been successful.
The response gives more information about the failure.
REASON: DSA Information Tree Corrupt
DESCRIPTION: The DSA Information Tree is corrupt.
The copy of the DSA database stored on disk
is corrupt and consequently not loaded into memory.
On Tru64 UNIX systems, this error is also used
if you specify the FROM MEMORY IMAGE or FROM
SNAPSHOT argument on the CREATE DSA command, but
there is no memory image or snapshot file available.
If this is the case, repeat the command without
the argument.
REASON: DSA Information Tree Incompatible
DESCRIPTION: The DSA Information Tree is incompatible with
this version of the DSA.
This can only happen after an upgrade of the
Enterprise Directory software.
REASON: DSA Information Tree Schema Incompatible
DESCRIPTION: The DSA Information Tree and Schema are incompatible.
The DSA Information Tree contains information that
is not defined in the schema. The missing definition
is identified in a supplementary message.
REASON: License Check Failed
DESCRIPTION: The license check has failed for this product.
A valid HP X.500 Directory Server license has not
been installed.
REASON: Schema Corrupt
DESCRIPTION: The schema file is unreadable. Recompile the schema.
REASON: Schema Incompatible
DESCRIPTION: The schema file is of a different version from the
DSA. Recompile the schema.
REASON: Database Loading
DESCRIPTION: The DSA is currently being created.
Two CREATE directives have been issued in quick
succession. No action is necessary.
3 – DELETE
Use this directive to delete a DSA. The DSA must be in state OFF when you delete it. For more information on a DSA's state, refer to STATUS attributes. Syntax: DELETE DSA [TO MEMORY IMAGE | TO SNAPSHOT] The DSA writes its directory information to disk when you use the DELETE directive. This means that all DSA information is saved, with the exception of any Accessor entities. When you next create the DSA, it will reconfigure itself automatically by reading its database files. The DELETE DSA options are only available on Tru64 UNIX. On OpenVMS systems, the directive DELETE DSA always produces a snapshot file. DSAs on Tru64 UNIX systems use memory image files instead of the snapshot files, by default. The DSA can read memory image files much faster, especially for large databases. Snapshot files are only supported on Tru64 UNIX systems for a small number of management tasks. These are documented in HP Enterprise Directory - Management. You are advised not to use the TO SNAPSHOT argument unless performing one of the tasks that specifically requires it.
3.1 – Errors
The DELETE directive can return the following error: REASON: Wrong State DESCRIPTION: The DSA entity is not in the correct state. The DSA is not in state OFF. The error indicates what state the DSA is in.
4 – DISABLE
Use this directive to disable a DSA. This means the DSA is unable to accept communications from DUAs or other DSAs. On completion of this directive, the DSA is in state OFF. For more information on the state of a DSA, refer to STATUS attributes. Syntax: DISABLE DSA
4.1 – Errors
The DISABLE directive can return the following error: REASON: Wrong State DESCRIPTION: The DSA entity is not in the correct state. The error indicates what state the DSA is in. The DSA must be in state ON for the ENABLE directive to succeed.
5 – ENABLE
Use this directive to enable the DSA for communication with directory applications and other DSAs. On completion of this directive, the DSA is set to state ON. The DSA listens for DOP, DSP, DAP, and DISP bind requests, depending on your setting for Presentation Address. In addition, if you have set LDAP Port to a non-zero value, the DSA listens for LDAP requests. For more information on a DSA's state, refer to STATUS attributes. Syntax: ENABLE DSA
5.1 – Errors
The ENABLE directive can return one of the following errors:
REASON: Wrong State
DESCRIPTION: The DSA entity is not in the correct state.
If the DSA is in state CREATING, ENABLING or UPDATING, wait for
the DSA to complete the relevant task. The response indicates the
current state of the DSA.
REASON: No AE Title
DESCRIPTION: The DSA's AE Title attribute has not been set.
Use the SET DSA AE TITLE directive to set a valid AE Title.
Refer to DSA Common_Datatypes for details of how to
specify a valid AE Title attribute. Remember that the AE Title
attribute should match the distinguished name of the directory
entry that represents this DSA.
REASON: No Presentation Address
DESCRIPTION: The DSA's Presentation Address attribute has not
been set.
Use the DSA configuration procedure to set a presentation address.
See HP Enterprise Directory - Management for
details of how to use the DSA configuration procedure.
6 – Examples
> CREATE DSA
> SET DSA AE TITLE "/C=US/O=Abacus/CN=DSA"
> SET DSA PRESENTATION ADDRESS -
_> '"DSA"/"DSA"/"DSA"/NS+48909090AA001122,CLNS'
> SHOW DSA ALL ATTRIBUTES
> ENABLE DSA
This command enables the DSA for communication with
directory applications and other DSAs.
> DISABLE DSA
> DELETE DSA
The first command disables the DSA from communication. This
means that it cannot communicate with a DUA or another DSA.
The state of the DSA changes from ON to OFF and it is no
longer available for communication. The DSA can now be
deleted. This is performed by the second command.
> UPDATE DSA SUPPLIER -
_> '"DSA"/"DSA"/"DSA"/NS+48909100aa006712121,CLNS'
This command starts the replication of naming contexts from
the DSA with the specified presentation address to this DSA.
DSAs only require the UPDATE DSA command to be used
once. Subsequent replication should be automatic, if you
follow HP's recommendations, as documented in HP
Enterprise Directory - Management. By default,
DSAs communicate with their shadowing partners every 12 hours
to make sure that shadow copies of information are up to
date.
7 – REMOVE
Use the REMOVE directive to remove a value from a DSA
multi-valued characteristic attribute. The DSA multi-valued
characteristic attributes are:
- READ ONLY DSA NSAPS
- READ ONLY DSA NAMES
- WRITER NAMES
- WRITER NSAPS
- READER NAMES
- READER NSAPS
- TRUSTED DSA NAMES
- TRUSTED DSA NSAPS
Syntax:
REMOVE DSA <characteristic> {<value>,...}
where <characteristic> is the name of the Characteristic attribute
and <value> is the value you want to remove from the attribute.
8 – SET
Use the SET directive to set the value of an attribute. You can set all the characteristic attributes of the DSA entity with the exception of the Version attribute. This attribute is a read-only characteristic attribute. Syntax: SET DSA <attr> <value> where <attr> is the name of the attribute and <value> is the value you want to assign to the attribute. When you use the SET directive, any existing value of the attribute is removed, leaving only the value that you now specify. To specify a new value in addition to any existing values, use the ADD directive.
9 – SHOW
Use the SHOW directive to display the attributes of a DSA entity. You can use the SHOW directive on all Characteristic, Status and Counter attributes of the DSA entity. Syntax: SHOW DSA <attr> where <attr> is the name of the Characteristic, Status or Counter attribute you want to display. You can display the values of multiple attributes using one SHOW directive by separating the attributes with a comma, for example: SHOW DSA <attribute1>, <attribute2> You can also show all attributes, or all attributes of a given type, as follows: SHOW DSA ALL ATTRIBUTES SHOW DSA ALL CHARACTERISTICS SHOW DSA ALL STATUS SHOW DSA ALL COUNTERS
10 – UPDATE
Use the UPDATE directive to initiate replication. On issuing this directive, the DSA specified in the SUPPLIER argument provides copies of one or more naming contexts (see the Naming Context entity) to this DSA. You can only use the UPDATE directive when the DSA is in state ON. Syntax: UPDATE DSA SUPPLIER <supplier> Refer to Arguments for details of <supplier>. You should only need to use the UPDATE DSA directive when you implement replication for the first time. Once replication has been established, the DSAs continue to replicate automatically according to a 12 hour schedule. This assumes you follow HP's recommendations, as documented in HP Enterprise Directory - Management.
10.1 – Arguments
The UPDATE directive has one argument: SUPPLIER. The SUPPLIER
argument specifies either the AE title or the presentation address
of the DSA which will supply copies of naming contexts.
If you use the AE title argument, the directive only succeeds if
a directory entry of the same name is accessible to this DSA and
contains a valid presentation address for the supplier DSA.
Specify the argument as follows:
UPDATE DSA SUPPLIER '<ae title>'
UPDATE DSA SUPPLIER '<presentation address>'
Refer to DSA Common_Datatypes for information on how
to specify an AE title or a presentation address.
10.2 – Errors
The UPDATE directive can return one of the following errors:
REASON: Wrong State
DESCRIPTION: The DSA entity is not in the correct state.
The error indicates what state the DSA is in.
The DSA must be in state ON when you use the
UPDATE DSA directive.
REASON: Invalid Address
DESCRIPTION: The Supplier argument is not a valid presentation
address.
Check the presentation address of the DSA that is
to be the supplier DSA, and specify that address
correctly.
REASON: Invalid Supplier Name
DESCRIPTION: The Supplier argument is not a valid directory name.
Check the AE title of the DSA that is to be the
supplier DSA, and specify that AE title correctly.
REASON: Supplier Unavailable
DESCRIPTION: The Supplier DSA is unavailable.
This error usually means that the supplier DSA
cannot verify the identity of the consumer DSA.
Refer to HP Enterprise Directory
- Management for details of replication, and its
prerequisite tasks.
The error can also mean that the supplier DSA is
unavailable temporarily, and a later attempt to
replicate will succeed.
The error can also mean that the supplier DSA has
insufficient diskspace to write the shadow
information to disk before sending it to the
consumer DSA. Check the events generated on the
supplier DSA to see whether they explain the
failure of replication.
REASON: Schema Incompatible
DESCRIPTION: Supplied update incompatible with the DSA.
The two DSAs have different schema, and the
information in the supplied naming context does not
conform to the schema of this DSA.
The consumer DSA needs schema that supports all of
the attribute types, syntaxes, and structure rules
used in the shadowed naming context. HP
recommends that all of your DSAs have identical
schema files.
REASON: DIT Incompatible
DESCRIPTION Supplied update incompatible with the DSA.
The consumer naming context clashes with the DIT
of the consumer DSA. For example, the consumer
DSA might have a naming context that overlaps
with the consumed naming context.
This indicates that you have a problem with your
DSA configuration, and you should check all DSAs
to ensure that they have a consistent understanding
of the division of your DIT.
REASON: Update Incompatible
DESCRIPTION: Supplied update incompatible with the DSA.
The supplied naming context contains information
that is incompatible with this DSA.
REASON: Insufficient Resources
DESCRIPTION: There are insufficient resources to perform the
update.
This usually means that the consumer DSA has
insufficient diskspace to write the shadow
information to disk before applying it to its
database. It can also mean that the consumer DSA
has insufficient memory to add the shadow
information to whatever information it already
holds.
REASON: Insufficient Resources DSA Deleted
DESCRIPTION: Failed in performing the Update due to insufficient
resources. DSA deleted.
This is similar to the Insufficient Resources
problem, but the DSA has already made changes to
its database. It therefore deletes itself to
prevent corruption of its existing data. When you
recreate the DSA, it recovers the data that it
held prior to the failed update.
REASON: No Address
DESCRIPTION: Cannot read address for specified DSA.
You specified an AE title for the supplier DSA.
The consumer DSA looked the AE title up in the
directory, but found that the entry representing
the supplier DSA does not have a presentation
address attribute, or that it could not read the
presentation address attribute.
Check that the entry representing the supplier DSA
has a presentation address attribute, and that it
is accessible to the consumer DSA. Otherwise
specify the presentation address of the supplier
DSA on the UPDATE command, so that a lookup is not
required.
REASON: Bad Update
DESCRIPTION: Invalid data received from Supplier.
This means that there is a problem with the
protocol passed between the supplier DSA and
consumer DSA. The consumer DSA therefore does not
apply any changes to its database. Try the update
again, to see whether the error recurs. If so,
report this error to HP.
REASON: Bad Update DSA Deleted
DESCRIPTION: Invalid data received from Supplier. DSA deleted.
This is similar to the Bad Update error. However,
the consumer DSA has already started applying
changes to its database before detecting the
error. It therefore deletes itself to prevent
corruption of its data. When you recreate the
consumer DSA, it recovers the database that it
held prior to the failed update.
REASON: Unexpected Failure
DESCRIPTION: Unexpected failure.
Check the events generated by the supplier DSA and
the consumer DSA to see whether they explain the
failure.
REASON: Comms Failure
DESCRIPTION: The update failed due to a communications problem.
See HP Enterprise Directory - Problem Solving for
information about fixing communications problems.