A Contacts Server Command-Line Utilities

This appendix provides information about the Oracle Communications Contacts Server command-line utilities.

Overview of the Command-Line Utilities

You use the davadmin command to administer Contacts Server. The davadmin command is installed in the ContactsServer_home/sbin directory with user or group bin/bin permissions.

The Contacts Server davadmin command is identical to the Calendar Server davadmin command, with a few changes and enhancements described in this appendix. The Contacts Server davadmin command does not include the calendar and calcomponent commands, nor the delcomponent and upgrade actions. It also does not include the -d option for the account command. Finally, the Contacts Server migration command is slightly different, as it does not include the -T or -c options. For complete information about the davadmin command, see Calendar Server System Administrator's Guide.

Note:

The davadmin command-line utilities administer aspects of the server and do not affect any LDAP entries.

davadmin Security

The davadmin command requires you to authenticate with a user name and password to be able to communicate with the server or database. You can use the davadmin passfile operation to store the necessary passwords in an encrypted wallet for use by subsequent davadmin commands. If you do not store passwords in the wallet, then you must enter them by using a no-echo prompt on the command line. See the topic on the passfile operation in Calendar Server System Administrator's Guide for more information.

Environment Variables

Table A-1 describes the environment variables that you can use with the various davadmin commands.

Table A-1 davadmin Environment Variables

Environment Variable	Description
DAVADMIN_CLIFILE	Specifies the path to the bootstrap file. Can be used instead of the -F option.
DAVADMIN_ACCOUNT	Specifies the account. Can be used instead of the -a option.

davadmin account

Use this command to administer Contacts Server user accounts in the database.

Location

ContactsServer_home/sbin

Syntax

davadmin account [ create | delete | list | modify | repair | subscribe |
                   unsubscribe ]
                 [-u id] [-W] [-F clifile] [-H hostname]
                 [-p port] [-s path] [-a account] [-g uniqueid (delete only)]
                 [-y property=value[,property=value...]] [-f file]
                 [-B ldapbaseuri] [-R ldapfilter]
                 [-c collection_path | -C collections_file_path]
                 [-m] [-o] [-v (list only)] [-e] [-r] [-q] [-h]

account Operation

Table A-2 describes the actions for the account operation.

Table A-2 Actions for account Operation

Action	Description
create	Creates an account for user who has been provisioned in the LDAP Directory Server. The user must have an email address.
delete	Deletes an account.
list	Lists properties of an account.
modify	Modifies an account.
repair	Repairs the user's email address in the database entries after an LDAP email change occurs. When used with the -o option, repair updates the owner lists of all accounts.
subscribe	Subscribes to an address book belonging to another user. That other user must grant the requesting user access before this can be done.
unsubscribe	Removes an address book from a user's subscription list.

Options for account Operation

Table A-3 describes the options for the account operation.

Table A-3 Options for account Operation

Short Option	Long Option	Description
-u	--userid	Specifies the application server administrator user name.
-W	--usepasswordfile	Specifies the password file, if available.
-F	--clifile	Specifies the file containing bootstrap information.
-H	--hostname	Specifies the server's host name. The default is localhost.
-p	--port	Specifies the server's administrative port number.
-s	--secure	Specifies the path and name of the trustStore file for a secure connection (HTTPS).
-a	--account	Specifies the account.
-g	--uniqueid	Specifies the account described by uniqueid. Used only for delete, if the -a option fails.
-y	--property	Specifies a comma-separated list of property=value fields. Possible address book properties are: notifemail - Email notification enable flag. 0 = disabled, 1 = enabled notifrecipients - Recipients of email notifications. Multiple values are separated by a space.
-c	--collectionuri	Specifies a collection path in which to subscribe or unsubscribe.
-C	--collectionuris	Specifies a local input file with collection paths, one per line, in which to subscribe or unsubscribe.
-f	--file	Specifies a local input file with one line for each account, for batch operation. Format is account:property_list,where property_list is optional and contains a comma separated list of property=value fields.
-B	--ldapbaseuri	Specifies a base URI in LDAP.
-R	--ldapbaseuri	Specifies a user search filter in LDAP. Default is (objectClass=nabuser).
-m	--email	Used only for the repair action. Updates the email addresses due to an email change for users specified with -a or -f options.
-o	--ownerlists	Used only for the repair action. Updates the owner lists for all accounts.
-v	--verbose	Used for account list command. If true, outputs details of each account found. This option is implied if the -a option is used.
-e	--detail	Prints detailed output.
-r	--force	Forces the operation. Does not prompt for confirmation.
-q	--quiet	Quiet mode.
-h	--help	Displays help.

davadmin addressbook

Use this command to create, modify, list, and delete user address books.

Location

ContactsServer_home/sbin

Syntax

davadmin addressbook [ create | delete | list | modify ]
                     [-u id] [-W] [-F clifile] [-H hostname]
                     [-p port] [-s path] [-a account] [-n name]
                     [-y property=value[,property=value...]] [-f file]
                     [-e] [-r] [-q] [-h]

addressbook Operation

Table A-4 describes the actions for the addressbook operation.

Table A-4 Actions for addressbook Operation

Action	Description
create	Creates an address book for user who has been provisioned in the LDAP Directory Server. The user must have an email address.
delete	Deletes an address book.
list	Lists properties of an address book.
modify	Modifies an address book.

Options for addressbook Operation

Table A-5 describes the options for the addressbook operation.

Table A-5 Options for addressbook Operation

Short Option	Long Option	Description
-u	--userid	Specifies the application server administrator user name.
-W	--usepasswordfile	Specifies the password file, if available.
-F	--clifile	Specifies the file containing bootstrap information.
-H	--hostname	Specifies the server's host name. The default is localhost.
-p	--port	Specifies the server's administrative port number.
-s	--secure	Specifies the path and name of the trustStore file for a secure connection (HTTPS).
-a	--account	Specifies the account.
-n	--name	Specifies the name of the address book collection.
-y	--property	Specifies a comma-separated list of property=value fields. Possible address book properties are: displayname - The name of the address book. Defaults to name given with the `-n` option. description - Description string. No default. acl - The access control string set on the address book. set-ace - Set one or more individual ACEs in the ACL. A semi-colon separated list of ACEs. remove-ace - Remove one or more individual ACEs from the ACL. A semi-colon separated list of ACE principals. For example: @, @domain, group@domain, or user@domain.
-f	--file	Specifies a local input file with account:addressbook_name:property_list, for batch operation, where property_list is optional and contains a comma separated list of property=value fields.
-e	--detail	Prints detailed output.
-r	--force	Forces the operation. Does not prompt for confirmation.
-q	--quiet	Quiet mode.
-h	--help	Displays help.

davadmin contact

Use this command to list, import, and export address book contacts.

Location

ContactsServer_home/sbin

Syntax

davadmin contact [ delete | list | import | export ]
                 [-u id] [-W] [-F clifile] [-H hostname]
                 [-p port] [-s path] [-a account] [-n name]
                 [-c contact] [-f format] [-L lang] [-m path]
                 [-x path] [-l logpath] [-r] [-e] [-q] [-h]

contact Operation

Table A-6 describes the actions for the contact operation.

Table A-6 Actions for contact Operation

Action	Description
delete	Deletes a contact.
list	Lists properties of a contact.
import	Imports a contact.
export	Exports a contact.

Options for contact Operation

Table A-7 describes the options for the contact operation.

Table A-7 Options for contact Operation

Short Option	Long Option	Description
-u	--userid	Specifies the application server administrator user name.
-W	--usepasswordfile	Specifies the password file, if available.
-F	--clifile	Specifies the file containing bootstrap information.
-H	--hostname	Specifies the server's host name. The default is localhost.
-p	--port	Specifies the server's administrative port number.
-s	--secure	Specifies the path and name of the trustStore file for a secure connection (HTTPS).
-a	--account	Specifies the account that owns the address book.
-n	--name	Specifies the name of the address book collection.
-c	--contact	Specifies the contact URI for which to request content.
-f	--format	Specifies the export format (vcard3 or csv). The default is vcard3.
-L	--language	Specifies the export language.
-m	--import-path	Specifies the path to the file on the host that contains data to be imported.
-x	--export-path	Specifies the path to the file on the host to receive the exported data.
-l	--logpath	Specifies the path to the location of the log directory.
-r	--force	Forces the operation. Does not prompt for confirmation.
-e	--detail	Prints detailed output.
-q	--quiet	Quiet mode.
-h	--help	Displays help.

davadmin ctgroup

Use this command to create, modify, list, import, export, and delete contact groups from a user's address book.

Location

ContactsServer_home/sbin

Syntax

davadmin ctgroup [ create | delete | list | modify | import | export ]
                 [-u id] [-W] [-F clifile] [-H hostname]
                 [-p port] [-s path] [-a account] [-n name]
                 [-c contactgroup] [-g groupname] [-M members]
                 [-E email_addresses] [-f format] [-L lang]
                 [-m path] [-x path] [-l logpath] [-r] [-h]

ctgroup Operation

Table A-8 describes the actions for the ctgroup operation.

Table A-8 Actions for ctgroup Operation

Action	Description
create	Creates an address book contact group.
delete	Deletes an address book contact group.
list	Lists properties of an address book contact group.
modify	Modifies the properties of an address book contact group.
import	Imports an address book contact group.
export	Exports an address book contact group.

Options for ctgroup Operation

Table A-9 describes the options for the ctgroup operation.

Table A-9 Options for ctgroup Operation

Short Option	Long Option	Description
-u	--userid	Specifies the application server administrator user name.
-W	--usepasswordfile	Specifies the password file, if available.
-F	--clifile	Specifies the file containing bootstrap information.
-H	--hostname	Specifies the server's host name. The default is localhost.
-p	--port	Specifies the server's administrative port number.
-s	--secure	Specifies the path and name of the trustStore file for a secure connection (HTTPS).
-a	--account	Specifies the account that owns the address book.
-n	--name	Specifies the name of the address book collection.
-c	--contactgroup	Specifies the contact URI for which to request content.
-g	--groupname	Specifies the contact group name.
-M	--members	Specifies a comma-separated list of contact group members.
-E	--email_addresses	Specifies a comma-separated list of contact group members' email addresses.
-f	--format	Specifies the export format (vcard3).
-L	--language	Specifies the export language.
-m	--import_path	Specifies the path to the file on the host that contains data to be imported.
-x	--export_patch	Specifies the path to the file on the host to receive the exported data.
-l	--logpath	Specifies the path to the location of the log directory.
-r	--force	Forces a delete operation.
-h	--help	Displays help.

ctgroup Examples

The following examples show how to use the davadmin ctgroup command.

To create a contact group in the personal address book with the name group1:

davadmin ctgroup create -a john.smith@example.com -g group1 -n personal

To create a contact group in the personal address book with the name group1 plus an email address and two members:

davadmin ctgroup create -a john.smith@example.com -g group1 -n personal -E my.group@example.com -M "urn:uuid:aaaaaaaaa,urn:uuid:bbbbbbbbbb"

To list all the contact groups in the user's default address book:

davadmin ctgroup list -a john.smith@example.com

To list the details of a contact group:

davadmin ctgroup list -a john.smith@example.com -c 1384904616388-1758-GROUP.vcf

To delete a contact group:

davadmin ctgroup delete -a john.smith@example.com -c 1384904616388-1758-GROUP.vcf

To remove all the current members of a group, replace them with one member, and change the group name to newgroup:

davadmin ctgroup modify -a john.smith@example.com -c 1384904616388-1758-GROUP.vcf -M "urn:uuid:cccccccccc" -g newgroup

davadmin db

Use this command to perform database related operations, such as backing up and restoring the database, and upgrading the database schema.

Unlike other davadmin commands that communicate with the application server, the davadmin db commands communicate directly with the back-end database, and thus require that you specify the database host name, port, and password.

Although the davadmin db commands are not related to the application server like the other davadmin commands, davadmin db commands do still use parameter values in the davadmin.properties file if applicable.

Because each database back end is associated with a database host name, port, document store, and so on, in a multiple back-end deployment, use a unique clifile (specified with the -F option) for each back end in the deployment.

In a non-default deployment or multiple back-end deployment, properly define options such as (-d database) and (-u dbuser), which might need to use specific and not default values.

Syntax

davadmin db [ backup | init | list | restore | schema_version |
              schema_fullupgrade | schema_preupgrade ] 
             [-h] [-e] [-W] [-t dbtype] [-H dbhost] [-p dbport] [-F clifile]
             [-u dbuserid]  [-d database] [-s truststore] [-b blockfactor] 
             [-D domain] [-a account_mail] [-T token] [-O] [-i path]
             [-c] [-A docstore] [-z preupgradefunction] [-k backup_file]

db Operation

Table A-10 describes the actions for the davadmin db operation.

Table A-10 Actions for db Operation

Command	Description
backup	Backs up a database.
init	Completely initializes the database. Caution: All data will be lost.
list	List contents of a backup file. This is the default action if not included on the command line.
restore	Restores the contents of a database.
schema_version	Displays version information for the database, connector, and product schema number.
schema_fullupgrade	Provides an optional way to perform a full upgrade of the database schema. For more information about upgrading database schema and upgrading Contacts Server, see "Upgrading Contacts Server" in Contacts Server Installation and Configuration Guide.
schema_preupgrade	Provides an optional way to perform a pre-upgrade on the database schema. For more information about upgrading database schema and upgrading Contacts Server, see "Upgrading Contacts Server" in Contacts Server Installation and Configuration Guide.

Caution:

Do not run either the schema_fullupgrade or schema_preupgrade without fully understanding the impact on your Contacts Server deployment.

The davadmin db backup, list, and restore commands require that you specify the associated document store by using the -A option, or the docstore option in the clifile.

Note:

If you are using a remote document store, you must set the document store password on the Contacts Server host by using the davadmin passfile command and that password must match the one set for the remote document store. This password is used whenever the backup or restore commands access the remote document store.

Options for db Operation

Table A-11 describes the options for the db operation (in addition to the common options).

Table A-11 Options for db Operation

Short Option	Long Option	Description	Available for Following Actions
-d	--database	Specifies the name of the Contacts Server store to be saved or updated. The default is nab. For MySQL Server, this is the database name. For Oracle Database, this is the network service name (not SID nor pdb name).	backup, restore, list
-H	--dbhost	Specifies the database host. The default is localhost.	All
-p	--dbport	Specifies the database port. The default is 3306.	All
-u	--dbuserid	Specifies the database user. For MySQL Server, this is the connecting user name. For Oracle DB, this is the user/schema name.	All
-k	--bkfile	Specifies the path of the file where the database information is to be saved. Required.	backup, restore, list
-b	--bkfactor	Specifies blocking factor used during backup. The default is 20.	backup, restore, list
-T	--token	Specifies the incremental backup token or start time in milliseconds.	backup
-D	--domain	Domain name for per domain backup.	backup
-a	--account	User account email value for per user backup.	backup
-i	--ipath	Specifies the internal path for partial list or restore.	restore, list
-c	--contents	Lists the resources and header.	list
-A	--docstore	Specifies the document store (remote store specified as host:port or local store by fully qualified path to root of document store).	backup, restore, list
-t	--dbtype	Specifies the type of database, either mysql or oracle. The default is mysql.	All
-O	--overwrite	Overwrites existing data.	backup, restore
-s	--dbsecure	Supplies the path to the trustStore file that contains the SSL certificate for secure communications with the remote document store.	backup, restore
-z	--dbupgradefunction	Specifies to run the pre-upgrade function(s) on the database. Caution: Do not run schema_preupgrade without fully understanding the impact on your Contacts Server deployment. For more information, see "Upgrading Contacts Server" in Contacts Server Installation and Configuration Guide. The pre-upgrade functions are: services-up - Processes all pre-upgrade functions that can be run with old services up. (Online DDL) Otherwise and most commonly, pre-upgrade functions must be run with services shut down. services-down - Processes all pre-upgrade functions that cannot be run with services up. all - Processes all available pre-upgrade functions. Services should be shut down. For a list of available functions by release, see "Preupgrade Functions" in Contacts Server Installation and Configuration Guide. Unless otherwise specified, never run pre-upgrade functions with services up. In addition, always back up your database before upgrading. Preupgrade functions are listed for each release. Some function names process multiple preupgrade functions.	schema_preupgrade

davadmin db Examples

To perform a full database backup:
```
davadmin db backup -k backup_file
```

To perform a full backup for a particular user:

davadmin db backup -k backup_file -a john.smith@example.com

To perform an incremental backup:

davadmin db backup -k backup_file -T token obtained from last full backup

To perform a full backup for a particular domain:
```
davadmin db backup -k backup_file -D sesta.com
```
To list the contents of the backup file:
```
davadmin db list -c backup_file
```
When the davadmin db list -c command retrieves backup file content, it goes through the checksums and is thus a way to verify the structure of the backup file itself.
To perform a restore from a backup file:
```
davadmin db restore -k backup_file
```

To restore an entire user from a backup file:

davadmin db restore -O -e -W -k /export-filepath -i "hosted.domain/mail:given.surname@hosted.domain/" -H mysqlcalhost -A  matching_document_store_host:8007 > /log_output_file

To restore only the default 'addressbook:'

davadmin db restore -O -e -W -k /export-filepath -i "hosted.domain/mail:given.surname@hosted.domain/addressbook/" -H mysqlcalhost -A  matching_document_store_host:8007 > /log_output_file

To restore only an addressbook named Soccer:

davadmin db restore -O -e -W -k /export-filepath -i "hosted.domain/mail:given.surname@hosted.domain/Soccer/" -H mysqlcalhost -A  matching_document_store_host:8007 > /log_output_file

To back up using SSL and the trustStore file:

davadmin db backup -k /tmp/backup_file -O -A docstore_host.example.com:8008 -s /my_home/my_truststore -u mysql

To process a database schema preupgrade:
```
davadmin db schema_preupgrade -z preupgrade_function
```
This command processes one preupgrade function. A preupgrade function is an upgrade change to the database, which can be run before the formal upgrade. This command does not change the database schema version.
To process all available preupgrade functions:
```
davadmin db schema_preupgrade -z all
```
Prior to running this command, ensure that all services are shut down.
To process all preupgrade functions that cannot be run with services down:
```
davadmin db schema_preupgrade -z services-down
```

davadmin migration

Use this command to migrate a user's Personal Address Book (PAB) to Contacts Server.

Location

ContactsServer_home/sbin

Syntax

davadmin migration [ migrate | status ]
                   [-u id] [-W] [-F clifile] [-H hostname]
                   [-p port] [-s path] [-a account] [-X migrationadminuser]
                   [-f file] [-L migrationserver] [-S]
                   [-B ldapbaseuri] [-R ldapfilter] [-l logpath] [-G] [-h]

migration Operation

Table A-12 describes the actions for the migration operation.

Table A-12 Actions for migration Operation

Action	Description
migrate	Migrates the address book from the Personal Address Book host to the Contacts Server host.
status	Provides a status on the migration.

Options for migrate Operation

Table A-13 describes the options for the migration operation.

Table A-13 Options for migration Operation

Short Option	Long Option	Description
-u	--userid	Specifies the application server administrator user name.
-W	--usepasswordfile	Specifies the password file, if available.
-F	--clifile	Specifies the file containing bootstrap information.
-H	--hostname	Specifies the server's host name. The default is localhost.
-p	--port	Specifies the server's administrative port number.
-s	--secure	Specifies the path and name of the trustStore file for a secure connection (HTTPS).
-a	--account	Specifies the account.
-X	--migrationadminuser	Specifies the LDAP auth user for the Personal Address Book Directory Server host.
-f	--file	Specifies a local input file with one line for each user to be migrated, for batch operation.
-L	--migrationserver	Specifies the Personal Address Book Directory server host's name and port number as server:port.
-S	--clientssl	Specifies to use SSL when making client connections.
-B	--ldapbaseuri	Specifies a base URI in LDAP.
-R	--ldapbaseuri	Specifies a user search filter in LDAP. Default is (objectClass=nabuser).
-l	--logpath	Specifies the path to use for the migration log file.
-G	--tag	Specifies the tag to use to access the migration status.
-h	--help	Displays help.