19 Indexing and Search Service Command-Line Utilities

This chapter describes the Oracle Communications Indexing and Search Service command-line utilities.

Common Information

The Indexing and Search Service command-line utilities are located in the IndexSearch_home/bin directory, unless otherwise stated. To run these utilities, you must log in as or become the superuser (root), or the Indexing and Search Service user.

List of Indexing and Search Service Utilities

Table 19-1 describes the command-line utilities that you use to administer Indexing and Search Service.

Table 19-1 Indexing and Search Service Command-line Utilities

Utility Description

checkIndex.sh

Checks individual index directories for consistency, and corrects some errors.

checkIss

Checks and verifies that the Indexing and Search Service services are running and that the log files have been written to recently.

checkStack

Checks the Indexing and Search Service installation by bootstrapping a user then performing a search through the RESTful interface.

csearchmgr.sh

Adds and removes Cluster Search Services for indexing nodes.

factorymgr.sh

Views and manages Java Naming and Directory Interface (JNDI) lookup objects.

issadmin.sh

Administers the Indexing and Search Service store.

isshttpdmgr

Starts and stops the isshttpd service, and configures Directory Server entries for the lookup table.

issrehostuser.sh

Automates the movement of accounts from one Indexing and Search Service store to another.

issversion

Reports the Indexing and Search Service version.

mergeIndex.sh

Merges multiple index files.

search_query_number.sh

Reports the number of search queries that have been run since the last time that searchSvc was restarted.

searchRun.sh

Searches the index interactively, from the command line. Prompts for input and displays the results of the query to standard output.

svc_control.sh

Starts and stops Indexing and Search Service services.

watchermgr.sh

Enables or disables the watcher service directly, instead of doing so by running the Indexing and Search Service setup script.


checkIndex.sh

The checkIndex.sh utility is a Lucene tool that you use to debug problems with the Indexing and Search Service store. You use it to check individual index directories in the Indexing and Search Service store for consistency, and to correct some kinds of errors. If indexing services are running, you might see errors from a running index, because the index can change while the utility is running. In any case, you are warned that the index services are running. checkIndex.sh is sometimes helpful in determining if an index directory has been corrupted, possibly during an "optimize" step. Use the -fix option with discretion, because if anything is wrong with the index, it usually causes data to be lost (perhaps a large amount of data). Before using the checkIndex.sh utility, ensure that you understand Lucene concepts and how data is indexed into documents.

Syntax

checkIndex.sh pathToIndex [-fix] [-segment X] ...

Options

Table 19-2 describes the options for the checkindex.sh utility.

Table 19-2 checkIndex.sh Options

Option Description

pathToIndex

Required. The full directory path to an individual Indexing and Search Service index directory under /var/iss, for example, /var/iss/index/store/dIndex.

-fix

Writes a new segments_N file, removing any problematic segments.

-segment X...

Checks only the specified segments. You can specify this option multiple times to check more than one segment, for example: -segment_2 -segment _a. You cannot use this option with the -fix option.


Caution:

Use the -fix option only on an emergency basis, as it causes documents (perhaps many documents) to be permanently removed from the index. Always make a backup copy of your index first before running the checkindex.sh utility. Do not run this utility on an index with active write activity.

When you run checkIndex.sh without the -fix option, it opens the index, reports version information, and reports any exceptions it encounters and what action it would take if the -fix option were specified. When you run checkIndex.sh with the -fix option, it removes any segments that have issues and writes a new segments_N file. All documents contained in the affected segments are removed.

Exit code 1 indicates either that the index cannot be opened or has been corrupted.

checkIss

The checkIss utility checks the Indexing and Search Service status. checkIss verifies that the Indexing and Search Service services are running and that the log files have been written to recently.

Syntax

checkIss [-t] [-B] [-h]

Options

Table 19-3 describes the options for the checkIss utility.

Table 19-3 checkIss Options

Option Description

-t

Specifies the timeout for send and receive of JMQ messages.

-h

Prints out the usage summary.

-B

Checks dIndex backups for account state corruption.


Exit code 1 indicates a failure status along with information on the failure. Exit code 0 indicates no issues.

Example crontab Entry

You can use a crontab entry to schedule checkIss to run periodically, for example:

0,15,30,45 * * * * /opt/sun/comms/jiss/bin/checkIss 2>&1 > /tmp/checkIss || cat
/tmp/checkIss | mailx -s "checkISS warning" admin@example.com

Example Output from checkIss

In the following example, checkIss verifies that all services but the JMQ Consumer service are running.

checkIss
WARNING: JMQConsumer is not running

checkIss Functions Based on Indexing and Search Service Installation Type

Table 19-4 describes the services, processes, and parameters that the checkIss command verifies based on the Indexing and Search Service installation type. For more information about Indexing and Search Service processes and services, see "Indexing and Search Service Processes".

Table 19-4 checkIss Functions

Value of iss.cluster.install Value of iss.cluster.type What checkIss Performs

standalone

None

  • Checks Service Install for utilSvc, indexSvc, searchSvc, and jmqconsumer.

  • Checks pid files for utilSvc, indexSvc, searchSvc, and jmqconsumer.

  • Checks jps for signature for utilSvc, indexSvc, searchSvc, jmqconsumer, Message Queue, and Oracle GlassFish Server.

  • Checks indexSvc and jmqcomsumer log for activity. If log has been modified in over a hour, checkIss returns 1.

  • Checks JNDI lookup for factories and destinations.

  • Sends isAlive JMQ message to indexSvc.

  • Sends isAlive JMQ message to searchSvc.

  • Checks credentials for mail.server:mail.imap.port by using mail.imap.admin.username and mail.imap.admin.password.

  • Checks for the presence of producers on mail.imq for the destination of mail.imq.name.

  • Checks credentials for mail.imq by using mail.imq.user and mail.imq.password.

multi-machine

index

  • Checks Service Install for utilSvc, indexSvc, searchSvc, and jmqconsumer.

  • Checks pid files for utilSvc, indexSvc, searchSvc, and jmqconsumer.

  • Checks jps for signature for utilSvc, indexSvc, searchSvc, jmqconsumer, and Message Queue.

  • Checks indexSvc and jmqcomsumer log for activity, if log has been modified in over a hour, checkIss returns 1.

  • Checks JNDI lookup for factories and destinations.

  • Sends isAlive JMQ message to indexSvc.

  • Sends isAlive JMQ message to searchSvc.

  • Checks credentials for mail.server:mail.imap.port by using mail.imap.admin.username and mail.imap.admin.password.

  • Checks for the presence of producers on mail.imq for the destination of mail.imq.name.

  • Checks credentials for mail.imq by using mail.imq.user and mail.imq.password.

multi-machine

web

  • Checks jps for signature for GlassFish Server.

multi-machine

ldap

  • None.

multi-machine

jmq

  • None.

cluster

web

  • Checks Service Install for utilSvc and csearchSvc.

  • Checks pid files for utilSvc and csearchSvc.

  • Checks jps for signature for utilSvc, csearchSvc, and GlassFish Server.

  • Checks JNDI lookup for factories and destinations.

cluster

index

  • Checks Service Install for utilSvc, indexSvc, and jmqconsumer

  • Checks pid files for utilSvc, indexSvc, and jmqconsumer

  • Checks jps for signature for utilSvc, indexSvc, jmqconsumer, and Message Queue

  • Checks indexSvc and jmqcomsumer log for activity. If log has been modified in over a hour, checkIss returns 1

  • Checks JNDI lookup for factories and destinations

  • Sends isAlive JMQ message to indexSvc

  • Checks credentials for mail.server:mail.imap.port by using mail.imap.admin.username and mail.imap.admin.password

  • Checks for the presence of producers on mail.imq for the destination of mail.imq.name

  • Checks credentials for mail.imq by using mail.imq.user and mail.imq.password

clusterv2

web

  • Checks jps for signature for GlassFish Server.

  • Checks JNDI lookup for factories and destinations.

clusterv2

csearch

  • Checks Service Install for utilSvc and csearchSvc.

  • Checks pid files for utilSvc and csearchSvc.

  • Checks JNDI lookup for factories and destinations.

  • Checks jps for signature for utilSvc, csearchSvc, and Message Queue.

clusterv2

index

  • Checks Service Install for utilSvc, indexSvc, and jmqconsumer.

  • Checks pid files for utilSvc, indexSvc, and jmqconsumer.

  • Checks jps for signature for utilSvc, indexSvc, jmqconsumer, and Message Queue.

  • Checks indexSvc and jmqcomsumer log for activity If log has been modified in over a hour, checkIss returns 1.

  • Checks JNDI lookup for factories and destinations.

  • Sends isAlive JMQ message to indexSvc.

  • Checks credentials for mail.server:mail.imap.port by using mail.imap.admin.username and mail.imap.admin.password.

  • Checks for the presence of producers on mail.imq for the destination of mail.imq.name.

  • Checks credentials for mail.imq by using mail.imq.user and mail.imq.password.


The check service install verification performs different checks depending on the operating system:

  • Solaris: Verifies the Service Management Facility (SMF) entries and that the service is in an enabled state.

  • Linux: Verifies the chkconfig entries and that the service is in an on state.

checkStack

The checkStack utility checks the Indexing and Search Service installation by bootstrapping a user then performing a search of that user through the RESTful interface.

Syntax

checkStack [-h|--help] [--appserver-host host] [--host host] [--folder folder]
           [--password] [--passwordfile file] [--port port] [--user user] [-h]

Options

Table 19-5 describes the options for the checkStack command.

Table 19-5 checkStack Options

Option Description

--appserver-host host

Specifies the GlassFish Server host name, defaults to localhost. Used for cluster, clusterv2 and multi-machine installations.

--port port

Specifies the GlassFish Server port, defaults to 8080.

--host host

Specifies the mail host for the bootstrapped user.

--password

Prompts for the user password to authenticate to GlassFish Server.

--passwordfile file

Reads the user password from the file name provided.

--user user

Bootstraps and searches this user name.

--folder folder

Only bootstraps and searches this folder, default for search is INBOX.

-h|--help

Prints out the usage summary.


Example

checkStack.sh --user c273 --host mail.example.com --passwordfile /var/tmp/userpass --appserver-host web.example.com --port 8070

Starting bootstrap of user c273
Running command [/opt/sun/comms/jiss/bin/issadmin.sh, --bootstrap, --user, c273, --host, mail.example.com]
Wed Aug  8 15:59:33 GMT 2012
Starting indexing c273                 at Wed Aug 08 15:59:36 GMT 2012
Ending task       c273                 at Wed Aug 08 15:59:46 GMT 2012 after 10 seconds
Wed Aug  8 15:59:46 GMT 2012
Successfully bootstrapped user c273
Successfully searched user c273 returned 592 results

csearchmgr.sh

The csearchmgr.sh utility adds and removes Cluster Search Services for indexing nodes. Use this utility only in a clustered environment where the iss.cluster.enabled parameter is set to true.

Syntax

csearchmgr.sh [-b basedir] [-l] [-A|-D] [-a|-d] [-n instance_name] [-h]

Options

Table 19-6 describes the options for the csearchmgr.sh utility.

Table 19-6 csearchmgr.sh Options

Option Description

-b basedir

Specifies the Indexing and Search Service base installation directory. Optional.

-l

Lists all Cluster Search Service entries. Optional.

-A

Adds all Cluster Search Service configuration found in the iss.cluster.dir parameter. Optional.

-D

Removes all Cluster Search Service configurations. Optional.

-a

Adds a Cluster Search Service entry for name. Optional.

-d

Removes a Cluster Search Service entry for name. Optional.

-n instance_name

Specifies the name of the Cluster Search Service entry on which to perform action. Required if -a or -d is provided.

-h

Prints out the usage summary.


Exit code 0 indicates a success. Exit code 1 indicates a failure.

Options can appear in any order.

Examples

List Cluster Search Services:

csearchmgr.sh -l

Add all Cluster Search Services found in the iss.cluster.dir parameter:

csearchmgr.sh -A

Remove all Cluster Search Services:

csearchmgr.sh -D

Add a single Cluster Search Service:

csearchmgr.sh -a -n instance_name

Remove a single Cluster Search Service:

csearchmgr.sh -d -n instance_name

factorymgr.sh

The factorymgr.sh utility is used to view and manage JNDI lookup objects.

Syntax

factorymgr.sh [-h] [-l] |[-m] [-b basedir] [-p parameter] [-n lookupname] [-v value]

Options

Table 19-7 describes the options for the factorymgr.sh utility.

Table 19-7 factorymgr.sh Options

Option Description

-l

Lists all objects or object provided by -n lookupname. Required if -m is not provided.

-m

Modifies object properties. Requires -n, -p, and -v. Required if -l is not provided.

-n lookupname

Lists or modifies the lookup name of the object. Required if -m is provided.

-b basedir

Optional. Provides installation base directory.

-p parameter

Specifies the parameter to be modified. Required if -m is provided. Optional if -l is provided.

-v value

Sets value of parameter. Required if -m is provided.

-h

Optional. Prints out the usage summary.


Exit code 0 indicates a success. Exit code 1 indicates a failure.

Options can appear in any order.

Examples

List all objects:

factorymgr.sh -l

List parameters for an object:

factorymgr.sh -l -n cn=CommsQueueFactory

Modify a parameter for an object:

factorymgr.sh -m cn=CommsQueueFactory -p imqBrokerHostName -v imq.example.com

issadmin.sh

The issadmin.sh utility displays information about the Indexing and Search Service store instance, and provides options to administer the store, enabling you to modify the accounts and folders of accounts. You can use this utility whether the Indexing and Search Service services are running or not.

The issadmin.sh utility takes list, action, and modifier options. List options print information contained in the Indexing and Search Service store. List options do not modify any Indexing and Search Service store data. Action options make changes to the Indexing and Search Service store data. Modifier options provide specific details required for each action or list option. Options can appear in any order.

Syntax

[-h|--help] [--listaccountlistfile] [--listaccounts]
[--listactiveservices] [--listbacklog] [--listbrief] [--listfolders]
[--listgroups] [--liststats] [--host host] [--user user]
[--folder folder] [--accountinfo] [--accountlist accountfile]
[--altoutput file] [--autobootaccounts] [--backup] [--bootstrap]
[--checkaccount] [--checkconfig] [--checkfolder] [--checkstore]
[--continueonerror] [--converttoformat fmt] [--createaccount]
[--createfolder] [--datapath path] [--deleteaccount]
[--deleteautobootlist] [--deletefolder] [--detail detaillist]
[--eximpath path] [--export] [--group groupnum] [--groupinfo]
[--ignorefolder] [--import] [--importversion version] [indexmode full|IMAPonly]
[--lockmemoryindex] [--loglevel all|config|fine|finer|finest|info|servere|warning]
[--moveaccount] [--password] [--passwordfile file] [--port port]
[--prompt] [--protocol ssl|tls] [--reboot] [--refresh] [--rehost host]
[--renamefolder newfoldername] [--runoptimizer true|false]
[--selectstate statelist] [--selecttime h[:m]]
[--setautobootlist file] [--setdefaulteximpath path]
[--setdefaulthostname host] [--setstate newstate] [--singleton]
[--skipfolder folder] [--stopservice usid] [--storepath path] [--sync]
[--threads n] [--timeout seconds] [--uid uidlist] [--unignorefolder]
[--unlockmemoryindex] [--unsetautobootlist file] [--useramdir]

The --accountinfo, --bootstrap, --checkaccount, --checkfolder, --createaccount, --createfolder, --deleteaccount, --deletefolder, --export, --ignorefolder, --import, --moveaccount, --renamefolder, --setstate, and --unignorefolder options require the --user and --host options.

If you do not specify a value for --host, issadmin.sh uses the default host for the Indexing and Search Service store.

The --deleteautobootlist option can optionally specify the --host and --user options.

The --checkfolder, --createfolder, --deletefolder, --ignorefolder, --renamefolder, and --unignorefolder options require the --folder option.

The --moveaccount option requires the --group option.

The --groupinfo option requires either the --group option or the --host and --user options.

The --password, --passwordfile file, --port, and --protocol options only apply to the --bootstrap, --checkaccount, and --checkfolder options.

The --sync and --detail options apply only to the --checkaccount, --checkfolder, and --checkstore options.

The --detail detaillist option can contain only one or more of the values dindex, store, group, full, ignoreok, flags, status, deepcheck, or verbose in a list separated by commas.

The --uid option applies only to --deletefolder.

The --threads and --continueonerror options apply only to --accountlist.

The --password and --passwordfile options are for non-production use only.

The --password option prompts you for the password.

You can specify the --setautobootlist file1 and --unsetautobootlist file2 options in the same command, but only once each. file1 cannot reference the same file as file2.

You can specify --indexmode with --bootstrap, --createaccount, or --setautobootlist options, to override the value of the iss.indexsvc.attachment.indexmode configuration parameter. The iss.indexsvc.attachment.indexmode configuration parameter specifies to either generate all attachment records along with the "fullcontents" field, or only the "fullcontents" field.

Options

Table 19-8 describes issadmin.sh list options. The --list* options are mutually exclusive. Only the last option appearing on the command line has any effect. These options print after any action specified in the command has been performed, so they show Indexing and Search Service store information after any change has occurred, not before. The --info* options act like actions, so the --list* options can also be used when these options are used. Output goes to stdout unless otherwise noted.

Table 19-8 List Options

Option Description

--accountinfo

Prints out all information for a single account. Requires the --host and --user options.

--checkaccount

Compares the specified account in the Indexing and Search Service store against the information in the corresponding account in the Messaging Server message store for consistency. Requires the --host and --user options. Prints out to stderr any discrepancies detected, including problems detected during the bootstrap process. (Fine-grain details such as message flags or problems detected during the bootstrap process are checked only when you specify the --detail option.) By default, the system values for connecting to the Messaging Server message store by using IMAP are used. You can use the --password, --passwordfile, --port, and --protocol options to override these defaults.

--checkfolder

Conducts consistency checks of the specified folder in the specified account in the Indexing and Search Service store against the information for the corresponding account and folder in the original Messaging Server message store. Requires the --folder, --host, and --user options. Prints out to stderr any discrepancies detected, including problems detected during the bootstrap process. (Fine-grained details such as message flags or problems detected during the bootstrap process are checked only when you specify the --detail option.) By default, the system values for connecting to the Messaging Server message store by using IMAP are used. You can use the --password, --passwordfile, --port, and --protocol options to override these defaults.

--detail detaillist

Specifies that the data in the store or the specific folder or account should be checked in detail. Used only with the --checkfolder, --checkaccount, and --checkstore options. Output reflects the differences found at a more detailed level. detaillist is a list of attributes, delimited by commas, from the following set:

dindex store group full flags ignoreok status deepcheck verbose

If this option is not specified with --checkaccount or --checkfolder options, an account or folder is checked for the correct number of emails in the folder only. If this option is not specified with the --checkstore option, the store is checked for dindex consistency only. Values of flags, ignoreok, and status can only be used with the --checkaccount and --checkfolder options. The dindex, store, group, deepcheck, and verbose values can only be used with the --checkstore option. If status is specified, the status messages from the bootstrap process in the index are also displayed in the command output. (These indicate when the index was incomplete, for example, if an attachment failed to convert.) If flags is specified, the flag values of each message are checked to match the content server values (Message Server message store). If ignoreok is specified, then if the only command output shows folders marked as ignored, the command omits these warnings, and returns success. If store is specified, then all the data in every account group in the entire store is checked for consistency. If group is specified with the --checkstore option, each group meta and content index is opened when store is also specified to verify its integrity. (This is a time consuming operation when the store consists of thousands of group index directories. You should do this only one time while the --sync option is used.) If deepcheck is specified with the --checkstore option, the output includes information about which accounts must be reindexed, such as after upgrading to Java 7. This output is formatted in the form of the --accountlist file to be used with the --setautobootlist file command. If verbose is specified with the --checkstore option, more details of the checking are generated. If full is specified, every level of detailed checking is performed.

Detailed checking can impact system performance. Running detailed checking can be up to four times slower for --checkaccount when using --detail full on larger accounts.

--groupinfo

Prints out all information for a single group. To identify which group, this option requires either the --group option or the --host and --user options for any account in the group.

-h or --help

Prints out the usage summary.

--listaccounts

Prints out summary information for all accounts in all groups in the store instance.

--listaccountlistfile

Prints summary of account information that is formatted suitably for use as a file with the --accountlist option. This command provides a simple way to track new accounts generated during autoprovisioning.

--listactiveservices

Prints out the list of services currently active in the Index Server related to issadmin.sh commands. The unique service identifier (USID) of each service is printed. For more information, see the --stopservice usid option.

--listbrief

Prints out simplified summary information for all accounts in all groups in the store instance. The output contains only basic account information, one account per line, and is faster than the --listaccounts option for large numbers of accounts.

--listfolders

Prints out all information for all folders of all accounts in all groups in the store instance.

--listgroups

Prints out summary information for all groups in the store instance.

--liststats

Prints out internal statistics for debugging purposes.


Table 19-9 describes action options.

Table 19-9 Action Options

Option Description

--autobootaccounts

For use only with the --listaccountlistfile command. Modifies output to contain only the list of accounts waiting for autobootstrap in the standardized --accountlist format. The output includes comments indicating the event error count for each account. You can use the list to select accounts manually based on these counts.

--backup

Creates an immediate backup of the dIndex, triggering the notification of the disk full status to service requestors. After the disk space reaches the limit allowed (by default 95 percent), all index services stop being processed until the disk space available shows this threshold is no longer exceeded. After enough disk space has been freed up, use this command to trigger normal processing of indexing services to continue.

--bootstrap

Creates the initial index for an account, known as bootstrapping the account. Bootstraps the account or folder specified. If the --folder option is used with this action, then only that folder (and any descendants) are bootstrapped. Bootstrapping involves indexing all the content from an account by using several parallel threads when possible. If you do not create the account beforehand, --bootstrap creates the account based on the --group or --singleton options specified. If no such information is specified, then the account is assigned to a group by using the default allocation algorithm. (To provide maximum control over the placement of accounts in groups, create accounts by using the --createaccount command before you bootstrap them.) If you create the account before using --bootstrap, then the account must be in the Inactive (I) or Unknown (X) state for this command to operate. During the bootstrap process, the state of the account is Bootstrap (B), and is changed to Active (A) upon completion. Depending on the amount of information in the account, this command can take several minutes to complete, or even hours for very large accounts. See also the --runoptimizer and --skipfolder options, which can be used with --bootstrap. For more information about bootstrapping many accounts, see "Setting Up Large Deployments".

--checkconfig

Compares the current values in the configuration files against the values currently active in the running services. Services must be running to use this option. Any changes that have occurred in the configuration files that have not been applied to the services either through the --refresh command or restarting the services are directed to standard error.

--checkstore

Compares the index store for consistency. When used alone or with the --detail option, this command reports any problems found in the internal consistency of the dIndex and account index directories. This is useful during recovery from a major failure, such as loss of power which might have corrupted data in the store. When problems with the store are detected, use with the --sync option. The --sync option resolves the problem by using different parts of the store data.

If the issadmin.sh --checkstore --sync command detects problems with a user account and cannot fix the errors, it deletes the account and schedules it for autobootstrap.

You can configure some --checkstore detections that cause little performance impact to run automatically when the IndexService starts. In addition, you can configure Indexing and Search Service to automatically repair some of these problems, resulting in fewer failures overall. For more information, see "Automatically Checking and Repairing dIndex Problems".

--converttoformat fmt

Converts the format of the dIndex implementation. The fmt value determines the format to convert to. Currently this value must be either 1 or 2. No other options may be used with this command. When the format of the dIndex is the same as the fmt value specified, the command causes no change to the dIndex. When the fmt value is different than the format of the dIndex, the current dIndex file is renamed and replaced by the reformatted dIndex. The configuration parameter iss.store.partitions.count is used to determine the number of the resulting dIndex partitions. This command is only allowed when Indexing and Search Service services are not running.

--createaccount

Creates an account in the Indexing and Search Service store. Requires the --host and --user options. You can also specify the --group and --singleton options. If the --group option is not also specified, the default allocation policy selects a group into which to place the account. For more information about default allocation policy, see "Overview of the Indexing and Search Service Store Instance".

--createfolder

Creates a folder in an account in the Indexing and Search Service store. Requires the --folder, --host, and --user options.

--deleteaccount

Deletes an account in the Indexing and Search Service store. Requires the --host and --user options.

--deleteautobootlist

Removes all accounts from the current autobootstrap list. When the --user and --host options are also specified, only the specific account is removed from the autobootstrap list.

--deletefolder

Deletes a folder tree in an account in the Indexing and Search Service store. Requires the --folder, --host, and --user options. Any folders underneath the specified folder are also deleted. If --deletefolder detects nested folders, you are prompted to continue, enabling you to quit the command. See also the --uid option.

--export

Copies data for an account, creating a snapshot directory under the current snapshot repository. Requires the --user and --host options. Use this command to back up accounts, and to create snapshots that can be used with the --import option to move accounts between store instances. The account must not be in the Active state, that is, the account must be Inactive. This command creates the snapshot repository if it does not exist. See the --eximpath modifier and --setdefaulteximpath option for how to alter the snapshot repository. Also, see "Exporting and Importing Accounts Example".

--ignorefolder, --unignorefolder

Marks a folder to be ignored. Requires the --folder option. The --ignorefolder action causes the folder specified by the --folder option to be ignored for all indexing operations, including bootstrap, real-time update events, --checkaccount, and --sync operations. The --unignorefolder action reverses the process, returning the named folder to normal operation. If the account is deleted from the index, any ignored folders are also deleted, and all ignore markings for folders of that account are also removed. The --deletefolder action does not affect any folder marked as ignored. The --unignorefolder action must be performed first. The ignored property applies to all nested folders. Only the highest-level folder must be marked and unmarked.

Folders marked to be ignored are also ignored by any search queries on the account.

--import

Copies data for an account into the index from the current snapshot repository. Requires the --user and --host options. The account must already exist but be empty for this to work: use the --createaccount command to create the account in the desired group. The account must not be in the Active state, that is, it must be in the Inactive state. The snapshot may have been created from any store instance. Use this command to move an account from one store instance to another, and to recover from a backup snapshot. The --importversion version option enables you to select between multiple snapshot directories for the account which may be present in the snapshot repository. To be able to import the account while changing the host, you must use the --rehost host option. See the --eximpath option and the --setdefaulteximpath option for how to alter the snapshot repository. Also, see "Exporting and Importing Accounts Example".

--listbacklog

Lists to standard output the current event backlog for all accounts currently with one or more events queued. The output can be filtered using the --user and --host options, the --accountlist option, the --selectstate statelist option, and the --selecttime h[:m] option.

--lockmemoryindex, --unlockmemoryindex

Forces the directory index (dIndex) to be retained in memory to improve performance across multiple indexing commands (such as when the --accountlist option is used with the --bootstrap command). This property remains in effect until the index is released with the --unlockmemoryindex command, which returns the index to disk. (If the server is shutdown, the current memory index is written back to disk, but it is locked back into memory when the server is restarted.) While locked in memory, information is updated, and can be inspected (using --list* commands for example), but any changes are not available to other parts of the system, such as the search or IMQ services. To enable the system to be fully operational, the --unlockmemoryindex action must be performed. (These commands are intended to be useful during the bootstrap process when many threads may update the dIndex repeatedly in parallel with large amounts of data; use avoids large amounts of disk I/O in the rapidly changing data structures, which can become a bottleneck. It is not recommended to use this feature for general system operation, as updated data is not visible to other processes until the unlock.)

--moveaccount

Moves an account from one group to another. Requires the --group, --host, and --user options. The account must not be in the Active state. If --singleton is specified, the target group must not already contain another account, and the target group is marked as --singleton.

--refresh

Forces values for all refreshable parameters changed in the configuration file since the last --refresh command (or since the services were last restarted) to be applied to all running services. Changes affecting log file locations, count, and size occur after all previous log messages have been written for the modified parameters.

--renamefolder newfoldername

Renames a folder in an account to newfoldername. Requires the --folder, --host, and --user options. --folder specifies the old folder name. Any folders underneath the specified folder are also renamed.

--setdefaulteximpath path

Assigns the value for path to be the default snapshot repository for this store instance. Once set, this directory path name is used as the default value for --import and --export commands whenever --eximpath is not specified. The --eximpath option can be used on the command line to override this default. Like --setdefaulthostname, --setdefaulteximpath establishes the default snapshot repository directory for --export and --import to use. If never specified, the iss.store.dir/snapshots directory is used as the default. Unlike --setdefaulthostname, you can set this option more than once, and the last such setting becomes the default setting.

You can use this option to remove the default so that it behaves as if no --setdefaulteximpath path was ever specified. To return the behavior to the original unspecified state, use this option specifying the empty string ("") as the path value.

--setdefaulthostname host

Assigns the value host to be the default host name for this store instance. This value can be set only once for any single store instance. After it is set, the value permits all commands requiring the --host option to be used without it. The value set as the default host name is automatically used whenever --host is not specified. You can use the --host option at the command line to override this default.

You can use this option more than once. Each subsequent use of this option replaces the default value. To remove the default so that none is applied, use this option specifying the empty string ("") as the host value.

--setstate newstate

Sets the state of the account to newstate. The values for newstate are A, B, C, I, 0, and X, which represent Active, Bootstrapping, Cleared, Inactive, Optimized and Unknown, respectively. Requires the --host and --user options. You must set the state of an Active account to Inactive to bootstrap any folder in the account. Real-time notification events and search queries are only processed for accounts in the Active state. Specifying O causes the group of the account to be Optimized. This setting also affects any other accounts in the group. (Optimization of the index improves search performance and does not usually need to be performed manually in this fashion.) An Optimized (O) state is a transient state. As soon as an account is modified by an event, then the account is no longer in the Optimized state. Specifying C causes the command lock for the account to be cleared. You usually only use C to clean up after catastrophic failures. Each of these states (except C and O) can appear in the output of the list options.

--stopservice usid

Specifies the unique service identifier (usid) for services to stop in the Index Server. Using the output from --listactiveservice, this command option stops threads in the Index Server which might have been left running when various issadmin.sh commands were interrupted. Any single usid from the --listactiveservice output can be stopped. Also, any prefix ending with a colon (:) can be used to stop all threads whose usid begins with such a prefix. When stopping threads, it might be necessary to repeat the --listactiveservice and --stopservice commands because new threads can continue to be created while these commands are executed. (After you finish using --stopservice, check any accounts being modified by the services you stopped, as the interrupted commands have not terminated normally. Interrupted commands that modify accounts might leave index locks in the meta or content index directories. Check for problems using a command such as find basedir/index/store/ -name "write.lock" where basedir is the value of the basedir parameter in the configuration file. Any such write.lock files found should be deleted, and any accounts in such groups should be checked for inconsistencies, and, if corrupted, should be deleted and bootstrapped again.)

All write.lock files are found in the basedir/index/store/locks directory, not the individual group index directories. The name of each file in this directory contains the number of the group to which it belongs.


Table 19-10 describes modifier options.

Table 19-10 Modifier Options

Option Description

--accountlist file

Specifies a file containing account information for one or more accounts used to repeat the command action over multiple accounts. You can execute commands such as --createaccount or --deleteaccount over a list of accounts, all within one executable command. (This is much more efficient than invoking issadmin.sh once for each account at the command line.) Each line of file specifies information for one account, minimally the user name. Any command-line option values found in the file override the corresponding value specified on the command line. The command is executed once for each line in the file, with the appropriate values in the line used instead of any from the command line. file can also contain empty, blank, and comment lines. Any line whose first non-white-space character is "#" or "@", or consists of only white space or carriage return, is ignored. Each line may contain several command option values.

The format of a line in the file can be one of the following:

username

or

groupnum;state;singleton;detail;hostname;username

In the first format, only the user name appears on a line, and all the other attributes are defaulted. In the second format, each of the individual terms can appear. If a term is not specified, the separators are still required, and any missing terms are defaulted. The values for the various terms must be valid values that can appear on the command line. (For singleton, an empty entry means not a singleton and any string starting with the letter 's' means --singleton.)

Consider the following example:

;101;I;;;;user30

It specifies the group, state, and user name to use for any commands for which those fields are meaningful. Likewise, the following example specifies the group, state, singleton, host name, and user name:

;104;A;single;;host4;user25

Thus if these lines appeared in file /tmp/userslist, then the following first command would be equivalent to the last two commands:

issadmin.sh --createaccount --accountlist /tmp/userslist

issadmin.sh --createaccount --group 101 --user user30
issadmin.sh --createaccount --group 104 --singleton --host host4 --user user25

Additionally, the following first command would be equivalent to the last two commands:

issadmin.sh --setstate X --accountlist /tmp/userslist

issadmin.sh --setstate I --user user30
issadmin.sh --setstate A --host host4 --user user25

Similarly, the "detail" field can be specified to override the value in the --detail option used in commands such as the following:

issadmin.sh --checkaccount --detail flags --accountlist /tmp/userslist

The following line is equivalent to a line containing just username:

;;;;;;username

For more information, see "Bootstrapping Examples."

--altoutput file

Specifies a file into which to write command output. The value of file must be the path to a file that either does not exist or is writable. Standard error and output from all commands is appended to file. This appending of standard error and output enables the results of long commands, such as those using --accountlist and --bootstrap, to be viewed before the command completes. If this option is not used, output is generated but does not appear on standard error or output until the command completes.

--continueonerror

Specifies that the --accountlist commands should continue running if one gets an error. By default, without this option, processing of the --accountlist stops if one of the commands produces an error.

--datapath path

Specifies the path of an alternative Indexing and Search Service data (that is, attachment) store to use. The default data store (from the configuration parameter iss.data.dir) is used unless this option is specified. The path specified includes the final directory, in the same fashion as is specified in the iss.data.dir parameter in the jiss.conf file. See also the --storepath option. Be careful when specifying --datapath because you might also need to use --storepath to obtain the results you want.

--detail detaillevel

Specifies that the data in the specific folder or account should be checked in detail. Used only with the --checkstore, --checkfolder, and --checkaccount options. If not specified, the account or folder is checked for the right number of emails in the folder only. Values for this option are full, flags, or status. The --checkfolder and --checkaccount options also take the ignoreok value. When used with these commands, ignoreok causes folders marked as "ignored" to be treated as normal, log messages do not appear, and the return code result is as if such folders did not exist. When used with the --checkstore option, additional values are dindex, store, group deepcheck, and verbose. The "full" option, when used with the --checkstore option, means to include dindex, store, group deepcheck, but not verbose. If status is specified, the status messages from the bootstrap process in the index are also displayed. These messages indicate when the index was incomplete such as if an attachment failed to convert. If flags is specified, the flag values of each message are checked to match the values in the Messaging Server store. If full is specified, every level of detailed checking is performed. Output reflects the differences found at a more detailed level. Detailed checking can be expensive to perform. Preliminary tests indicate performance of up to four times slower for --checkaccount when using --detail full on larger accounts.

--eximpath path

Specifies the path of an alternate snapshot repository for the --export and --import commands. Used only with --export or --import commands. If not specified, the default snapshot repository is used.

--folder foldername

Specifies the folder name of an account as needed by various actions.

--group groupnum

Specifies the integer group number of an account as needed by various actions.

--host host

Specifies the host (or domain) name of an account as needed by various actions.

--importversion version

Specifies which version of an account to use for the --import command from the snapshot repository. The value of version must match one of the valid "Created:" time stamps found in the summary file in the snapshot repository. Used only with --import to specify which version of the account to import from.

--loglevel [all|config|fine|finer|finest|info|severe|warning]

Specifies the log level to use for commands. Only applies when the Index Service is not running. Behavior in this case is similar to and overrides the iss.indexsvc.log.level parameter.

--password

Causes the command to prompt for a password. It is read from the command line as plain text.

--passwordfile file

Specifies the file containing the password of an account needed by --checkfolder and --checkaccount options. The password is read from file. It is treated as plain text.

--port port

Specifies the port of the Messaging Server host needed by --checkfolder and --checkaccount options. The value is a simple integer.

--prompt

Specifies that the --checkstore --sync command prompts interactively at the command line. The individual steps in the --sync command prompt for confirmation, enabling you to skip steps. By default, no prompting is performed.

--protocol protocol

Specifies the protocol to use when accessing the Messaging Server host as needed by --checkfolder and --checkaccount options. Values for this option are ssl and tls.

--reboot

Permits accounts in --setautobootlist file to be bootstrapped even when they already exist. This option causes the account to be deleted and completely bootstrapped again. (Refer to --detail deepcheck for example of use.)

--rehost host

Specifies the host name of a snapshot being imported when it is being changed. Using this option permits the --import command to change the name of the host from what is in the snapshot. When an account is exported using --export, the current host name is used to identify the snapshot. To import such a snapshot into an account in another store with a different host value, specify the host of the account as specified in the snapshot in this option. For example, if the snapshot was created for --user U --host H, and the new account is created for --user U --host NEWH, then the --import command needs to use --user U --host NEWH --rehost H options.

--runoptimizer [true|false]

Specifies if the account in the --bootstrap command should be optimized after indexing. If true is specified, the account is optimized. If false is specified, the account is not optimized. If this option is not specified with the --bootstrap command, the default is not to optimize the account. It takes somewhat longer to optimize an account after the bootstrap, but subsequent searches of the account are generally faster. See also the --setstate O option.

--setautobootlist file

Specifies a file containing information for accounts in --accountlist format. This command adds each entry in file to the autobootstrap list so it is bootstrapped by the periodic bootstrap process. Refer to the --unsetautobootlist file command: this option can be specified in the same command as the --unsetautobootlist file option, but only once and the two file specifiers must not then reference the same file. In this case, the --setautobootlist file changes are applied before the --unsetautobootlist file changes.

--selectstate statelist

Specifies a comma-delimited list of one or more account states from the set A, B, I, and X. When specified with the --listbacklog command with or without any --user/- host or --accountlist options, only those accounts found with more than zero events in the event backlog which match one of the specified states are included in the output. When specified with the --listbrief option, only users in the selected state are displayed.

--selecttime h[:m]

Specifies one or two integer values indicating the number of hours h (or hours h and minutes m) to use to select only those accounts which have had events backlogged for longer than that amount of time (and so would be technically out of sync during this interval). This can be used with the --selectstate option as well to further restrict the results. The hours and minutes values can each be zero, but not negative; the minutes value is optional. If the total time interval is zero, then no selection occurs, and all results from the --listbacklog command are returned.

--singleton

Specifies that the target group of the --createaccount or --moveaccount options must contain only one account.

--skipfolder folder

Specifies the folder name of an account which is skipped during the --bootstrap command. No data from folder and any of its descendants appears in the index for the account. The --skipfolder and --folder options cannot specify the same folder in the --bootstrap command.

--storepath path

Specifies the path of an alternative Indexing and Search Service store to use. The default store (from the configuration parameter iss.store.dir) is used unless this option is specified. The path specified does not include the final "/store", just the full path name up to it (such as /var/iss/index). See also --datapath option. Be careful when specifying --storepath because you might also need to use --datapath to obtain the results you want.

--sync

Specifies that the data in the specific folder or account should be synchronized with the Messaging Server store. Used only with the --checkstore, --checkfolder, and --checkaccount options. See --checkstore, --checkfolder, and --checkaccount descriptions in Table 19-8, "List Options" for more information. If the --detail flags modifier is used, then message flags are also checked, which causes additional synchronization to occur. (Reindexing to correct "incomplete" indexing caused by, for example, attachment conversion failures is not attempted, so such warnings remain a reason for the folder or account to be out of sync.)

--threads n

Specifies the number of threads to use when running with the --accountlist option. If not specified, the commands run sequentially in the order found in the --accountlist file. If specified, then commands are submitted to run concurrently in groups of n threads in the order found in the --accountlist file. However, the order that the commands complete is not fixed, so this feature should only be used when the commands in each line are independent of each other. (If two lines of the file specify actions on the same account, the order in which the actions are run is not deterministic.) The maximum permissible value for n is 100. Any error in any of the commands causes processing to halt unless the --continueonerror option is also specified.

--timeout seconds

This option is not currently implemented. The system recognizes it but the value is ignored.

--uid

Specifies a list of Unique Identifiers (as defined by IMAP) relative to the folder in the --folder modifier. Each value is an integer. Separate multiple values with commas. White space within the UID list is not allowed. This option can only be specified when using the --deletefolder option. This option causes only the records associated with each UID to be deleted.

--unsetautobootlist file

Specifies a file containing information for accounts in --accountlist format. This command removes each entry in file from the autobootstrap list so it is not bootstrapped by the periodic bootstrap process. (Unless other action, such as manual bootstrap, is taken, subsequent error events cause an account to be placed on the list again.) Refer to the --setautobootlist file command: this option can be specified in the same command as the --setautobootlist file option, but only once and the two file specifiers must not then reference the same file. In this case, the --setautobootlist file changes are applied before the --unsetautobootlist file changes.

--user user

Specifies the user name of an account as needed by various actions.

--useramdir

Specifies that the --accountlist option should use in-memory processing of dIndex to improve speed. This modifier causes all changes to the dIndex to be delayed from showing up in the rest of the system until the action using --accountlist completes. Only some actions that allow --accountlist are affected by this option: these are currently --createaccount, --createfolder, --deleteaccount, --deletefolder, --setstate, --ignorefolder, and --unignorefolder. Use caution when using this option. Using this option can cause loss of index data if processing is interrupted before the command completes. Use should be limited to when the --accountlist file is extremely large (tens of thousands of entries in the file) and when load is low on the system. You can also use this option when services other than indexing are not running, such as when performing maintenance on many accounts in the instance (for example, large scale initial account creation, modification of account state, account or folder addition or deletion, and so on).


Examples

  • To list all groups in a store instance:

    issadmin.sh --listgroups
    Thu Aug 27 11:32:44 PDT 2009
     Store ID: ISSID_20090824223352 created: 20090824223352
     default host name:              <none specified>
     default export/import path:     <none specified>
     total size of store instance:   0
     total number of accounts:       54
     total number of account groups: 6
     last known consecutive group:   0
     total search queries performed: 0
     total search query failures:    0
     total index events processed:   434
     last backup performed:          never
     last host number:               0
     last user number:               0
     attachment store enabled:       true
     dIndex memory locked:           false
     Group #   # accounts
        101     10    meta index:  6.4M       content index:   18M
        102     10    meta index:   42M       content index:   94M
        103     10    meta index:   91K       content index:  7.5M
        104     10    meta index:   91K       content index:  299K
        105     10    meta index:   12M       content index:   28M
        106     4    meta index:  382M        content index:  697M
            total space in group indices: meta: 442.5777MB   content: 844.7919MB
     
     Time spent in index du:        107ms
     Time spent searching meta index:    0ms
     Time spent searching content index: 0ms
    Thu Aug 27 11:32:46 PDT 2009
    
  • To show all information about a given account:

    issadmin.sh --accountinfo --user user1 --host mailhost.example.com
    Thu Aug 27 11:35:41 PDT 2009
     Store ID: ISSID_20090824223352 created: 20090824223352
     default host name:              <none specified>
     default export/import path:     <none specified>
     total size of store instance:   0
     total number of accounts:       54
     total number of account groups: 6
     last known consecutive group:   0
     total search queries performed: 0
     total search query failures:    0
     total index events processed:   438
     last backup performed:          never
     last host number:               0
     last user number:               0
     attachment store enabled:       true
     dIndex memory locked:           false
      Group #   # accounts  status username     hostname   foldername
          104     10    meta index:   91K       content index:  299K
                             A      user1        mailhost.example.com
                              last state transition: 20090107125507
                                    Account created: 20090107125451
                                      0                 threeleadingspaces
                                      0              thirdemptyfolder
                                      0              test_cr6735149
                                      0              a16new
                                      0              secondemptyfolder
                                      16 at:7        INBOX
                                           5 emails have 36 attachment files, 8.3M
                                      1              simplename
                                      1              new_folder/a_new_folder
                                      3              simpleName
                                      3              user1_shared_folder
                                      2              abc(def) test folder
                                      3              new_folder/subfolder
                                      2              new_folder
                                      38 at:6        demonov19_2007
                                           1 email has 4 attachment files, 35K
                                      24 at:8        Sent
                                           7 emails have 52 attachment files, 10M
                                      1              Junk
                                      2              Trash
                                      1              Drafts
                                      97 at:21     total in account
                                           13 emails have 92 attachment files, 18.33417MB
              97 at:21       total in group 104
                          13 emails have 92 attachment files, 18.33417MB
              total space in group indices: meta: 0.088867MB   content: 0.291992MB
     
     Time spent in index du:        96ms
     Time spent searching meta index:    0ms
     Time spent searching content index: 4ms
    Thu Aug 27 11:35:43 PDT 2009
    

    The account status is specified in the line:

    A user1 mailhost.example.com
    

    In this case, the A specifies "active."

  • To check that an account matches the content store, run the following two commands:

    issadmin.sh --checkaccount --user user1 --host mailhost.example.com
    Thu Jan  8 02:09:22 GMT 2015
    Account user1 mailhost.example.com is in sync
    Thu Jan  8 02:09:24 GMT 2015
    
    issadmin.sh --checkaccount --user user2 --host mailhost.example.com
    Thu Jan  8 02:10:11 GMT 2015
    NOT SYNCHED folder: MSVisioAttachments number of emails match but found 1
    indexing problem
        uid: 0000000001 incomplete: failed to index attachment content type:
    APPLICATION/OCTET-STREAM attachment type: atdoc filename: assignment_1.vsd
    Exception Message MSWord Attachment : Error Creating WordExtractor Object:
    java.io.FileNotFoundException: no such entry: "WordDocument" NameOfAttachment :
    assignment_1.vsd
            folder: MSVisioAttachments MS shows nMsgs: 1 uidVal: 1205273656
    nextUID: 2 new: 0
     
    Thu Jan  8 02:10:28 GMT 2015
    
  • To bootstrap an account by using the --accountlist option:

    issadmin --bootstrap --accountlist /tmp/users.conf --host mailhost.example.com --threads 10
    
  • To bootstrap an account by using the default allocation policy:

    issadmin --bootstrap --user user2 --host mailhost.example.com --runoptimizer true
    
  • To bootstrap an account by allocating to a specific singleton group:

    issadmin --bootstrap --user user2 --host mailhost.example.com --group group2 --singleton --runoptimizer true
    

isshttpdmgr

The isshttpdmgr utility starts and stops the isshttpd service, and configures Directory Server entries for the lookup table.

Location: IndexSearch_home/isshttpd/scripts/isshttpdmgr

Syntax

isshttpdmgr [-b basedir] [-a|-d] [-v] [-h] [-l] [-u file] [-s] [-S]

Options

Table 19-11 describes the options for the isshttpdmgr utility.

Table 19-11 isshttpdmgr Options

Option Description

-b basedir

Specifies the Indexing and Search Service installation directory. The default is /opt/sun/comms/jiss.

-a

Enables isshttpd.

-d

Disables isshttpd.

-l

Lists current file or LDAP entries.

-u file

Sets the current LDAP to value in file.

-s

Configures but does not start isshttpd services.

-S

Does not update the iss.isshttpd.enabled parameter in the jiss.conf file.

-v

Enables verbose debugging.

-h

Prints out the usage summary.


Examples

  • To list current entries:

    isshttpdmgr -l
    
    ms1.example.com=iss1.example.com,8080
    ms2.example.com=iss2.example.com,8080
    
  • To set LDAP entries:

    cat inputfile
    sunkeyvalue: ms1.example.com=iss1.example.com,8080
    sunkeyvalue: ms2.example.com=iss2.example.com,8080
    
    isshttpdmgr -u inputfile
    
  • To enable the isshttpd service:

    isshttpdmgr -a
    
  • To disable the isshttpd service:

    isshttpdmgr -d
    

issrehostuser.sh

The issreshostuser.sh utility automates the movement of accounts from one Indexing and Search Service instance to another. This command is intended to be invoked by the Messaging Server rehostuser command, not directly from the command line.

Location: IndexSearch_home/store/scripts/issrehostuser.sh

Syntax

issrehostuser.sh -a action -s srchost -d desthost -u username
                 -t destiss -o thisiss -c scpuser -p sshcmd
                 [-r true|false] [-x true|false] [-g groupnum]
                 [-n snapowner] [-e eximpath] [-w destpath]

Options

Table 19-12 describes the options for the issrehostuser.sh utility.

Table 19-12 issrehostuser.sh Options

Option Description

-a action

Required. The action to perform. action can be one of prep, fini, or isscleanup.

-s srchost

Required. The Messaging Server host name from which the account is to be moved. Must match the host name of the account in the source Indexing and Search Service store instance.

-d desthost

Required. The Messaging Server host name to which the account is to be moved. This is the host name of the account in the destination Indexing and Search Service store instance.

-u username

Required. The user name of the account to be moved. Must match the user name of the account in the source Indexing and Search Service store instance.

-t destiss

Required. The Indexing and Search Service instance host name to which the account is to be moved.

-o thisiss

Required. The Indexing and Search Service instance host name from which the account is to be moved. This is the host on which the issrehostuser.sh command runs.

-c scpuser

Required. User name used by the secure copy scp command used to transfer data from the thisiss host to the destiss host.

-p sshcmd

Required. The secure shell command used on thisiss host for running remote commands on destiss host.

-r copy

Optional. copy can be either true or false. If true, the command uses secure copy (scp) to transfer data from the thisiss host to the destiss host. If false, the command assumes the two hosts share an NFS disk instead. Default is true. You should not need to ever specify false; this setting is intended primarily for testing purposes.

-x delete

Optional. delete can be either true or false. If true, the account is removed from the thisiss store after the rehost is complete. If false, the account is left on the thisiss machine after the rehost is complete. Default is true. You should not need to ever specify false; this setting is intended primarily for testing purposes.

-g groupnum

Optional. The number of the group into which the rehosted account is moved on destiss. Default is empty (the system determines what group to use).

-n snapowner

Optional. Used to change owner of data copied from the thisiss host to the destiss host. Default is /bin/chown -R ${iss_group}:${iss_user}. You should not specify an alternate to this command.

-e eximpath

Optional. The export/import directory path used when creating the copy of the account being rehosted. Default is iss.exim.dir or, if that is not defined, iss.tmp.dir. You should not specify an alternate path.

-w destpath

Optional. Path to commands on destpath. The default is the same as the thisiss path (base_dir). If the instance on the destpath host is not installed in the same place as on the thisiss host, use this option to specify the correct path.

-h

Prints out the usage summary.

-v

Generates verbose debugging output.


Rehosting an Account from One Indexing and Search Service Instance to Another

Normally, you do not use the issreshostuser.sh utility directly from the command line. However, you can use it to rehost an account from one Indexing and Search Service instance to another.

To rehost an account from one Indexing and Search Service instance to another:

  1. Run the issreshostuser.sh command on the Indexing and Search Service host containing the account to be rehosted, specifying the -a prep action.

  2. Use the Messaging Server rehostuser command to move the account on the Messaging Server.

  3. To complete the rehost, run the issrehostuser.sh command using the -a fini action.

If the rehost succeeds, issreshostuser.sh returns an exit code of 0 (zero). Otherwise, the return code varies depending on the failure. If either the prep or fini actions fail, run the isscleanup action to restore the account to its original state.

issversion

The issversion utility reports the version of Indexing and Search Service.

Syntax

issversion

Example

issversion
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
Indexing and Search Service for Oracle Communications Unified Communications Suite 1u5-26.13901(1.0.5.26.0) (built 20151221)
SunOS sc11152314 5.11 11.0 sun4v sparc sun4v
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
common.jar reports version: 1u5-26.13901
indexapi.jar reports version: 1u5-26.13901
jmqconsumer.jar reports version: 1u5-26.13901
search.jar reports version: 1u5-26.13901
store.jar reports version: 1u5-26.13901
auth.jar reports version: 1u5-26.13901
shared.jar reports version: 1u5-26.13901
watcher.jar reports version: 1u5-26.13901
isshttpd.jar reports version: 1u5-26.13901
utilsvc.jar reports version: 1u5-26.13901
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
Checking deployed wars:
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
rest reports version: 1u5-26.13901
    common.jar in rest reports version: 1u5-26.13901
    indexapi.jar in rest reports version: 1u5-26.13901
    search.jar in rest reports version: 1u5-26.13901
    store.jar in rest reports version: 1u5-26.13901
    auth.jar in rest reports version: 1u5-26.13901
    shared.jar in rest reports version: 1u5-26.13901
searchui reports version: 1u5-26.13901
storeui reports version: 1u5-26.13901
    common.jar in storeui reports version: 1u5-26.13901
    indexapi.jar in storeui reports version: 1u5-26.13901
    store.jar in storeui reports version: 1u5-26.13901
    auth.jar in storeui reports version: 1u5-26.13901
    shared.jar in storeui reports version: 1u5-26.13901

mergeIndex.sh

The mergeIndex.sh utility merges multiple index files. You must supply at least three directories to mergeIndex.sh. The first directory is the result index, and the rest are input index directories to be merged. This utility implements the --moveaccount option. It is provided as a standalone utility that might be useful for recovering corrupted accounts under special situations. This utility is not generally needed, but is used during the export, import, back up, and recovery of index data. Do not attempt using the mergeIndex.sh utility without a thorough understanding of Lucene concepts and how data is indexed into documents. You can use this utility whether the Indexing and Search Service services are running or not.

Syntax

mergeIndex.sh mergedIndex index1 index2 [index3] ...

Options

Table 19-13 describes the options for the mergeIndex.sh utility.

Table 19-13 mergeIndex.sh Options

Option Description

mergedIndex

Required. The resulting index directory from the merge.

index1 index2 index3...

At least two index directories are required. The index directories are merged in the order presented into the mergedIndex directory.


Exit code 1 indicates a a problem parsing the options. Exit code 0 indicates no issues.

search_query_number.sh

The search_query_number.sh utility reports the number of search queries that have been run since the last time that the searchSvc service was restarted.

Syntax

search_query_number.sh [--timeout int] [-h|--help]

Options

Table 19-14 describes the options for the search_query_number.sh utility.

Table 19-14 search_query_number.sh Options

Option Description

--timeout int

Specifies the timeout for send and receive of JMQ messages.

-h|--help

Prints out the usage summary.


Example

search_query_number.sh
Current search query number is: 560

searchRun.sh

The searchRun.sh utility performs searches on the index from the command line interactively. The utility prompts for input and displays the results of the query to standard output.

Requirements: The search services must be running to use this utility.

Syntax

searchRun.sh [--promptcallback] [--promptcompresssize] [--promptcontentformat]
             [--promptcount] [--promptformat] [--promptsize]
             [--promptsort] [--promptstart]
             [--loglevel all|config|fine|finer|finest|info|severe|warning]
             [--nojmssvc] [--queryfile file] [--storepath path]

Options

Table 19-15 describes the options for the searchRun.sh utility. Each of the following options can appear once in a command, in any order:

Table 19-15 searchRun.sh Options

Option Description

--promptsort

Causes the script to prompt for sort criteria. Form of response to prompt is the same as the SORT= parameter of RESTful search services commands.

--promptcount

Causes the script to prompt for the number of results to return. Form of response to prompt is an integer.

--promptstart

Causes the script to prompt for the start number of the results. Form of response to prompt is an integer.

--promptformat

Causes the script to prompt for the format of the results. Form of response to prompt is one of the choices the prompt presents.

--promptcompresssize

Causes the script to prompt for the compression size of the results. Form of response to prompt is an integer indicating how large the search results should be to cause compression.

--promptcontentformat

Causes the script to prompt for the content format of the results. Form of response to prompt is one of the choices the prompt presents.

--promptsize

Causes the script to prompt for the size of the thumbnail to use when formatting the results. Form of response to prompt is one of the choices the prompt presents.

--promptcallback

Causes the script to prompt for the JavaScript callback to use in the JSON format response. If none is provided, the response is not wrapped in a function.

--loglevel all | config | fine | finer | finest | info | severe | warning

Specifies the level of logging information to be generated by the search process.

--nojmssvc

Required if the command is run on a cluster node or when the services are not running.

--queryfile file

Alternate input for search query requests. Each line in the file file is a single query, terminated with a newline. Enables search queries to exceed the limit of 255 characters on the command line.

--storepath path

Specifies the path of an alternative Indexing and Search Service store to use. The default store (from the configuration parameter iss.store.dir) is used unless this option is specified. The path specified does not include the final "/store", just the full path name up to it (such as /var/iss/index).


svc_control.sh

The svc_control.sh utility starts and stops Indexing and Search Service services.

Syntax

svc_control.sh start|stop

watchermgr.sh

The watchermgr.sh utility enables or disables the watcher service outside of the standard Indexing and Search Service setup script.

Syntax

watchermgr.sh [-a] [-d] [-b basedir] [-S] [-s] [-v] [-h]

Table 19-16 describes the options for the watermgr.sh utility.

Table 19-16 watchermgr.sh Options

Option Description

-a

Configures the watcher service.

-d

Unconfigures the watcher service.

-b

Sets the base directory of the Indexing and Search Service installation (default is /opt/sun/comms/jiss).

-S

Does not update the iss.watcher.enabled parameter in the jiss.conf file.

-s

Configures but does not start the watcher service.

-v

Enables verbose debugging for the watcher service.

-h

Prints out the usage summary.


Examples

  • To configure the watcher service:

    watchermgr.sh -a
    No basedir defined defaulting to /opt/sun/comms/jiss
    Running configure watcher
    Starting watcher
    
  • To unconfigure the watcher service:

    watchermgr.sh -d
    No basedir defined defaulting to /opt/sun/comms/jiss
    Running unconfigure watcher
    Stopping watcher
    

Additional Indexing and Search Service Scripts

Indexing and Search Service provides the following scripts, based on Lucene, for manipulating individual index directories within the store instance. To use these scripts, you need an understanding of Lucene and how the data is indexed into documents.

Table 19-17 describes the additional Indexing and Search Service scripts.

Table 19-17 Additional Indexing and Search Service Scripts

Tool Description

lucli.sh

Command-line Lucene index inspection script. Invoke this script and use the help command to inspect the individual index directories under the store.

luke.sh

GUI version of the Lucene Index Toolbox (Luke). Invoke this script and use the Help menu for commands and features to inspect the individual index directories in a store instance. Requires separate download of various .jar files. The script indicates where to find any missing files.


Deprecated Commands

This section lists the Indexing and Search Service commands that have been deprecated.

indexSvcBootstrap.sh

Beginning with Indexing and Search Service 1 Update 2, the indexSvcBootstrap.sh command is deprecated. Use issadmin.sh --bootstrap instead.

The indexSvcBootstrap.sh utility is used to create the initial index for an account, known as bootstrapping the account. For accounts which exist on Messaging Server prior to installing Indexing and Search Services, the data in each account must be initially indexed before the search can be used. This command is used to extract data from the content server (by using the standard IMAP interface) and create the index for each account. (Depending on how many accounts and how much data (email) each has, this can take considerable time. This command is multithreaded to speed up this process; however, it also might produce significant load on the Messaging Server IMAP service, because it must access every email in each account.)

Requirements: Must be root or the Indexing and Search Service user. The content server must be configured to enable access to each account by using the IMAP interface. An account may or may not exist in the index when you use this command. If the account already exists, then it must not be already in the Active state. The index must not contain any records for any folders to be bootstrapped by this command, or duplicate index records may be created.

Location: IndexSearch_home/indexapi/scripts/indexSvcBootstrap.sh

Indexing and Search Service 1 Update 1: Also in IndexSearch_home/bin/indexSvcBootstrap.sh

Syntax

indexSvcBootstrap.sh --host host --user user [--datapath pathname]
 [--folder folder] [--group groupnum]
 [--loglevel all|config|fine|finer|finest|info|server|warning] [--password]
 [--passwordfile file] [--port port] [--protocol ssl|tls]
 [--runoptimizer true|false] [--singleton] [--skipfolder skipfolder]
 [--storepath pathname]

Options

Table 19-18 describes the options for the indexSvcBootstrap.sh command.

Table 19-18 indexSvcBootstrap.sh Options

Option Description

--host host

Required. Specifies the host or domain of the account to be indexed.

--user user

Required. Specifies the user name of the account to be indexed.

--datapath pathname

Optional. Specifies the path of an alternative Indexing and Search Service data (that is, attachment) store to use. The default data store (from the configuration parameter iss.data.dir) is used unless this option is specified. The path specified includes the final directory, in the same fashion as is specified in the iss.data.dir parameter. See also --storepath option. Be careful when specifying --datapath because you might also need to use --storepath to obtain the results you want.

--folder folder

Optional. Specifies to index only this one folder of the account. This includes any nested folders.

--group groupnum

Optional. Specifies the integer group number into which the account index will be placed. If not specified, the default allocation policy will select a group into which to place the account. For more information on default allocation policy, see "Overview of the Indexing and Search Service Store Instance".

--loglevel all|config|fine|finer|finest|info|severe|warning

Optional. Specifies the level of logging information to be generated by the bootstrapping process.

--password

Optional. For development only. It is not meant for production use because it puts the password in the command-line option, which is not secure.

--passwordfile file

Plaintext. If --password option is provided, you are prompted for the password.

--port port

Optional. Used to specify the port for the IMAP connection to the Messaging Server host. Default is 143.

--protocol sls|tls

Optional. Used to specify the security protocol used by the IMAP connection to the Messaging Server host. By default, no security protocol is assumed to be needed.

--runoptimizer true|false

Optional. Used to indicate whether the index being created should be optimized at the conclusion of the bootstrapping. Optimization makes the process take a little longer, but the additional time is usually not significant relative to that of the rest of the processing. However, search performance of an optimized index may be significantly better than the unoptimized index.

--singleton

Optional. Specifies that the target group of the indexing must contain only the one account being bootstrapped.

--skipfolder skipfolder

Optional. Specifies that the folder named skipfolder in the account is not to be indexed during this bootstrap process. This is sometimes useful if there is some problem with a certain folder or if it contains a huge number of emails such that processing it would take an inordinate amount of time.

--storepath pathname

Optional. Specifies the path of an alternative Indexing and Search Service store to use. The default store (from the configuration parameter iss.store.dir) is used unless this option is specified. The path specified does not include the final "/store", just the full path name up to it (such as /var/iss/index). See also --datapath option. Be careful when specifying --storepath because you might also need to use --datapath to obtain the results you want.


Options can appear in any order.

Example

indexSvcBootstrap.sh --user user1 --host mailhost.example.com --runoptimizer true

indexSvcFork.pl

In Indexing and Search Service 1 Update 1, indexSvcFork.sh replaces indexSvcFork.pl.

The indexSvcFork.pl utility provides a means to bootstrap a list of users in parallel.

Requirements: Must be run as root or the Indexing and Search Service user.

Location: IndexSearch_home/indexapi/scripts/indexSvcFork.pl

Syntax

indexSvcFork.pl [-f filename ] [-m mailhost] [-n max_number_of_spawns]
                [ -p polling_interval] [-t timeout]

Options

Table 19-19 describes the options for the indexSvcFork.pl command.

Table 19-19 indexSvcFork.pl Options

Option Description

-f filename

Required. File name containing list of users to index, single user name per line.

-m mailhost

Optional. Mail host of the users to be indexed. Defaults to mail.server in the jiss.conf file.

-n max_number_of_spawns

Optional. Number of indexSvcBootstrap.sh calls to create simultaneously. Defaults to 5.

-p polling_interval

Optional. How often processes should be polled for completion (seconds). Defaults to 1 second.

-t timeout

Optional. How long an indexSvcBootstrap.sh should run before timing out (seconds). Defaults to 3600 seconds.


Example

indexSvcFork.pl -f users.conf -m mailhost.example.com -n 10

indexSvcFork.sh

Beginning with Indexing and Search Service 1 Update 2, the indexSvcFork.sh command is deprecated. Use issadmin.sh --bootstrap with the -accountlist option instead.

This command was introduced with Indexing and Search Service 1 Update 1.

The indexSvcFork.sh utility provides a means to bootstrap a list of users in parallel.

Requirements: Must be run as root or the Indexing and Search Service user.

Location: IndexSearch_home/indexapi/scripts/indexSvcFork.sh (or IndexSearch_home/bin/indexSvcFork.sh)

Syntax

indexSvcFork.sh  --file file  [--host hostname] [--threads num_threads]
[--runoptimizer true|false] [--timeout num_seconds]
[--port port] [--protocol ssl|tls]

Options

Table 19-20 describes the options for the indexSvcFork.sh command.

Table 19-20 indexSvcFork.sh Options

Option Description

--file filename

Required. File name containing list of users to index. The file format is the same as for the --accountlist option of the issadmin.sh utility.

--host mailhost

Optional. Mail host of the users to be indexed, if not specified in the file.

--threads num_threads

Optional. Number of bootstraps to run in parallel. Defaults to 8.

--runoptimizer true|false

Optional. Whether or not to optimize the account. Defaults to false.

--timeout num_seconds

Optional. How long in seconds a bootstrap should run before timing out. Defaults to 50000 seconds.

--port port

Optional. Used to specify the port for the IMAP connection to the Messaging Server host. Default is mail.imap.port in the jiss.conf file.

--protocol ssl|tls

Optional. Use specified type of encryption for IMAP instead of the default in the jiss.conf file.


Example

indexSvcFork.sh --file /tmp/users.conf --host mailhost.example.com --threads 10