This appendix provides information about the Oracle Communications Contacts Server 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.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.
Table A-1 describes the environment variables that you can use with the various davadmin commands.
Use this command to administer Contacts Server user accounts in the database.
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]
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. |
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:
|
-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 |
|
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. |
Use this command to create, modify, list, and delete user address books.
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]
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. |
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:
|
-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. |
Use this command to list, import, and export address book contacts.
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]
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. |
Use this command to create, modify, list, import, export, and delete contact groups from a user's address book.
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]
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. |
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. |
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
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.
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]
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.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:
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 |
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
Use this command to migrate a user's Personal Address Book (PAB) to Contacts Server.
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]
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. |