Reference › DXtools › DXmodify Tool—Add New or Changed Information to a Directory

DXmodify Tool—Add New or Changed Information to a Directory

Use the DXmodify tool to do any of the following:

• Populate an empty directory
• Add complete new entries to an existing directory
• Add new attributes to existing entries
• Modify, rename, or delete attributes of an entry
• Load a binary file

When you run the DXmodify tool, you can enter the new or changed information from standard input or from an LDIF file.

This command has the following format:

dxmodify [action] [options]

action

Specifies the action the tool will take. The DXmodify tool follows any changetype directives in the LDIF file. If the LDIF file contains entries and no changetype directives, then you can tell DXmodify whether it should add these entries or replace existing entries. DXmodify replaces entries if either of the following conditions are true:

• The entry in the LDIF file is a modify operation and the modify type is specified for an attribute in the LDIF file
• -r is specified

-a

Adds the entries in the LDIF file to the directory.

-r

Replaces the entries or attributes in the directory with those in the LDIF file.

options

Denotes one or more of the following options:

-c

Runs in continuous mode. Errors are reported, but the process is not stopped.

-d level [-d level...]

Sets the LDAP debug levels.

level

Defines the level of debugging as follows:

-1 Enable all debugging

0 No debugging

1 Trace function

2 Debug packet handling

4 Heavy trace debugging

8 Connection management

16 Print out packages sent and received

32 Search filter processing

64 Configuration file processing

128 Access control list processing

256 Stats log connections/operations/results

512 Stats log entries sent

1024 Print communication with shell backends

2048 Print entry parsing debugging

You can add numbers together to specify multiple debug levels at the same time. For example, a debug level of 6 specifies the debugging levels of both 2 and 4.

-D bindDN

Specifies the distinguished name of the user performing the bind.

-f filename

Specifies a source LDIF file. If you do not specify this option, or do not specify a file name, then DXmodify waits for input from standard input.

-h dap-host

Specifies the address or host name of the directory host. If you do not specify this, the tool uses localhost instead.

You can include OSI addressing for transport, session, and presentation SAPs by fully expanding dap-host:

hostname:port/tsel/ssel/psel

You can include binary and ASCII characters in the tsel, ssel, and psel selectors, using the % followed by the two hexadecimal digits that represent the ASCII code for the character, for example:

• / is expressed as %2F
• % is expressed as %25

-l timelimit

Specifies the time limit (in seconds) for each DAP operation.

-n

Shows what would be done, but does not actually do it. This can be useful for debugging purposes, usually you use this with the -v option.

-p dap-port

Specifies the port on directory host computer. If you do not specify this, the tool uses port 102, the OSI port, buy default

You can combine the -h and -p arguments into a single argument, and express them as a dotted IP address or hostname. For example, you can replace the options on the first line with those on the second:

-h 192.168.19.202 -p 19389

-h 192.168.19.202:19389

-q

Runs in quiet mode, in which successful operations are not reported.

-s time

Specifies the time (in milliseconds) to sleep after each operation.

-v

Runs in verbose mode.

-w password

Specifies the bind password, which is used for simple authentication.

-Z [ssld_config_filename]

Specifies that the tool should start a TLS request.

Use -ZZ to require a successful response from the DSA.

ssld_config_filename

Specifies the name of the configuration file used by the -Z option. The default file is:

DXHOME/config/ssld/dxldap.conf

This configuration file is a text file. It must contain a line starting TLS_CACERT, and can optionally contain a second line starting TLS_REQCERT. Its format is as follows:

TLS_CACERT trusted_pem_file
[TLS_REQCERT {allow|demand|hard|never|try}]

In the configuration file, the lines have the following meaning:

TLS_CACERT trusted_pem_file

Specifies the file that contains certificates for all of the Certificate Authorities the client will recognize.

trusted_pem_file

Species the trusted pem file.

This must be an absolute reference to a full path, without environment variables.

Do not enclose trusted_pem_file in quotes.

[TLS_REQCERT {allow|demand|hard|never|try} ]

Specifies what checks to perform on server certificates in a TLS session, if any.

If this line is missing, the system uses TLS_REQCERT demand

The keywords have the following meaning:

• allow - The client will request a server certificate and if no certificate is provided, the session proceeds normally. If a bad certificate is provided, it will be ignored and the session proceeds normally.
• demand - The client will request a server certificate and if no certificate is provided, or a bad certificate is provided, the session is immediately terminated. This is the default setting.
• hard - This is a synonym for demand.
• never - The client will not request or check any server certificate.
• try - The client will request a server certificate and if no certificate is provided, the session proceeds normally. However, if a bad certificate is provided, the session immediately terminates.

Example: dxldap.conf file on a Windows System, Specifying the TLS_REQCERT Setting

TLS_CACERT  c:\program files\CA\Directory\dxserver\config\ssld\trusted.pem
TLS_REQCERT allow

Example: dxldap.conf file on a UNIX System, Using the Default TLS_REQECRT Setting

TLS_CACERT  /opt/CA/Directory/dxserver/config/ssld/trusted.pem

Example: Make Multiple Changes to an Entry

This example uses the Democorp sample directory supplied with CA Directory. You can repeat this example as a training exercise.

You can make multiple changes, such as changing the title and postal address, adding a second telephone number, and deleting the description of an entry.

This example shows that you can replace the values of multiple attributes using one replace statement as long as the replace statement specifies the first attribute name in the series.

1. Create an LDIF file named h-modify.ldif that contains the following:

   dn: cn=Murray HORSFALL, ou=Repair,ou=Operations,o=Democorp,c=AU
   changetype: modify
   replace: title
   title: Chief Information Officer
   -
   add: telephone
   telephone: 797 8888
   -
   delete: description
   -
   replace: postalAddress
   postalAddress: 173 Toorak Rd $ South Yarra
   postalCode: 3066
   

2. Use DXmodify to apply the edited file as follows:

   dxmodify -h localhost:19389 -f h-modify.ldif
   

Example: Add a Binary File

This shows how to add a JPEG file with a personnel record from staff.ldif.

For JPEG files, the object class is cosinePilotObject, the X.500 attribute name is cosineJpegPhoto, and the LDAP attribute name is JpegPhoto.

This example uses the Democorp sample directory supplied with CA Directory. You can repeat this example as a training exercise.

To add a binary file, follow these instructions:

1. Decide on the directory schema object class and attribute to use to hold the binary data.

   For this example, use the cosineJpegPhoto attribute within the cosinePilotObject object class.

2. Create entries in an LDIF file with the following syntax:

   attributeName:< FILE://path
   

   For this example, create staff.ldif with the following form:

   dn: cn=Peter Bell,ou=Infrastructure,ou=Support,o=Democorp,c=AU
   oc: organizationalPerson
   oc: newPilotPerson
   oc: cosinePilotObject
   cn: Peter Bell
   sn: BELL
   cosineJpegPhoto:< FILE://d:\temp\PHOTO\BELPE01.jpg
   title: Design Supervisor
   telephone: 881 9256
   description: Computing
   mail: Peter.BELL@Democorp.com
   postalAddress: 7-11 Fine Street$Penville CA
   postalCode: 32750
   

3. Run the following command:

   dxmodify -a -c -h hostname:19389 -f staff.ldif