| Before you begin: Create and verify a current backup of the DocuShare database, document repository, configuration, and license information before performing a restore, migration, upgrade, or other maintenance operation. Do not proceed without a usable recovery backup. |
Overview
Use this procedure to manually back up or restore IDOL index data in a DocuShare installation that uses IDOL. The procedure applies to supported DocuShare releases that provide the idoltool command. Follow the release-specific documentation supplied with your installation package if it differs from this procedure.
IDOL index data is separate from the DocuShare database and document repository. A usable recovery point requires synchronized backups of all required components, not only the IDOL index.
Before You Begin
- Confirm the installed DocuShare release, patch level, operating system, database type, and search engine.
- Place the site in Read Only mode or stop DocuShare before starting the backup. This prevents database and site changes while the backup is being created.
- Back up the DocuShare database and DocuShare directory files during the same backup cycle.
- Back up the document repository shown in the Document Repository field on the Site Management directory-path page.
- Back up configuration files, customizations, integrations, add-ons, and license information as applicable.
- Use a backup destination with sufficient free space and permissions for the DocuShare service or administrator account running the command.
- Keep the backup until the restore or maintenance operation has been fully validated.
| Recovery warning: If you restore the document repository, do not overwrite or delete the existing guid.txt file in the documents directory. This file identifies the DocuShare site and must be preserved on the target installation. |
Locate the DocuShare bin Directory
Open a command prompt on Windows or a terminal on Linux or Solaris, then change to the bin directory under the DocuShare installation directory.
| cd <dshome>\bin |
Replace <dshome> with the actual DocuShare installation directory. The default Windows installation directory is commonly C:\Xerox\Docushare, but the path may differ in your environment.
Back Up IDOL Index Data
Run the command for your operating system. Replace <path_to_backup_directory> with a backup destination, such as D:\content_backup on Windows or /content_backup on Linux or Solaris.
| Windows: idoltool.bat -s backup <path_to_backup_directory> Linux or Solaris: idoltool.sh -s backup <path_to_backup_directory> |
When one content engine is configured, the server argument is normally omitted. When multiple content engines are configured, run the command once for each content engine and provide that engine name.
| Windows examples: idoltool.bat -s backup C:\idolbackup content0 idoltool.bat -s backup C:\idolbackup content1 idoltool.bat -s backup C:\idolbackup content2 Linux or Solaris examples: idoltool.sh -s backup /idolbackup content0 idoltool.sh -s backup /idolbackup content1 |
| Multiple content engines: Use the content-engine names configured in your installation. If more than one content engine is configured and the server argument is omitted, the command fails immediately with Error: No server parameter specified. |
Verify the IDOL Backup
- Open <dshome>/logs/idoltool.log while the backup runs. For multiple content engines, also monitor the applicable content_application.log and content_index.log files under the configured IDOL content-server directories.
- For a single content engine, confirm that the log contains backup completion text, including backup: Done.
- For multiple content engines, verify completion for every content engine. Applicable logs may include content_application.log and content_index.log under the IDOL installation directories.
- Confirm that the expected files exist in the backup directory and that the backup can be read from the recovery location.
| Do not continue: If the backup command reports an error or completion cannot be confirmed, do not use that backup for a restore. Correct the issue and create a new verified backup. |
Restore IDOL Index Data
Use the restore procedure only after the database and document repository recovery point has been identified and verified. The restored database, documents, and IDOL index should represent the same recovery point whenever possible.
- Stop DocuShare and confirm that the IDOL services are stopped before restoring index data.
- Change to the <dshome>\bin directory.
- Confirm that the backup directory exists, contains files, and is readable by the account running the command.
- Run the restore command for the applicable operating system.
| Windows: idoltool.bat -s restore <path_to_backup_directory> Linux or Solaris: idoltool.sh -s restore <path_to_backup_directory> |
- For multiple content engines, run the restore once for each content engine and provide the matching server name.
| Windows examples: idoltool.bat -s restore C:\idolbackup content0 idoltool.bat -s restore C:\idolbackup content1 Linux or Solaris examples: idoltool.sh -s restore /idolbackup content0 idoltool.sh -s restore /idolbackup content1 |
- Monitor <dshome>/logs/idoltool.log for the restore status. For multiple content engines, also monitor the applicable content_application.log and content_index.log files for the matching content engine. As with backup, omitting the server argument when more than one content engine is configured fails immediately with Error: No server parameter specified.
| Submitted DREINITIAL, jobid = <jobid> waitForJobCompletion: id = <jobid>: Finished; documents processed: <n>... restore: Done. |
- Treat restore: Done. in <dshome>/logs/idoltool.log as the required completion marker for the restore command. For multiple content engines, confirm completion for every engine. Do not start DocuShare or continue migration steps until completion has been confirmed.
| Restore duration: Restore time depends on the size of the IDOL index and the storage system. Large indexes may take 30 minutes or longer. Do not assume that the command has failed only because it does not immediately return to the prompt. Check <dshome>/logs/idoltool.log and wait for the matching Submitted DREINITIAL, waitForJobCompletion ... Finished, and restore: Done. entries. A returned prompt by itself is not a valid completion check. |
Reindex After the Restore
After the IDOL index restore is complete and DocuShare is running, reindex objects changed since shortly before the backup was created. Use a date range that includes all changes that may not be represented in the restored index.
| Windows: dsindex.bat -reindexSince MM/dd/yyyy-MM/dd/yyyy index_all Linux or Solaris: dsindex.sh -reindexSince MM/dd/yyyy-MM/dd/yyyy index_all |
Replace the date values with the appropriate range for your recovery point. The first date should be shortly before the backup was created. Confirm that the reindex completes successfully, then test full-text search.
| Date range is half-open: The start date is inclusive and the end date is exclusive. If you set the end date to today, today's changes are not reindexed. Set the end date to one day past the last day you need covered. |
| Search validation: If IDOL was not backed up and restored, run a full index operation according to the applicable release documentation. A full reindex may take considerable time for a large site. |
When resetserver Is Required
The normal IDOL restore command submits DREINITIAL to restore the index from the backup directory; it does not call resetserver. For a routine restore on an existing DocuShare installation, do not add resetserver unless the applicable release procedure specifically requires it.
resetserver is the correct step for a different situation: the IDOL index is corrupted or unusable and no usable IDOL index backup exists. In that case, reset the server and then run a full reindex. It is not part of restoring a good backup, and adding it to a restore is redundant and destroys the live index before you know whether the backup restores successfully.
Some documented new-server migration procedures do require the sequence below before restoring the IDOL index:
| Windows: idoltool.bat -s resetserver all y Linux or Solaris: idoltool.sh -s resetserver all y |
In that migration scenario, follow the migration procedure exactly. Stop the affected IDOL and DocuShare services first, confirm that the target is the intended new or reset installation, and make sure the database and document repository recovery point is available before proceeding.
| Destructive operation: resetserver initializes IDOL server structures and can remove configured server files and content-index data. With the y option, content data paths such as Main, Status, Dynterm, Nodetable, RefIndex, Numeric, User, and Tag may be deleted or cleared. It can also remove selected logs, lock files, database/status files, license and uid directories, and FileSystemFetch temporary or queue data. Run resetserver all y only when a documented migration procedure requires it. For any other situation, including a corrupted index with no usable backup, contact Xerox DocuShare Support before running it rather than using it as a self-service step. |
| Partial reset risk: When resetserver all is used, each configured server is checked and reset in turn. If a later server is still running, the command stops immediately, leaving the servers already processed reset and the rest untouched. Stop all IDOL services first; if any service is still running when you run this command, you can be left with a partially reset installation that is harder to diagnose. |
Troubleshooting
- If a command reports that the backup directory does not exist or contains no files, confirm the path and permissions, then create or select a verified backup.
- If a multi-content command fails without an obvious reason, confirm that the server argument matches the configured content engine name.
- If restore: Done. does not appear in <dshome>/logs/idoltool.log, preserve that log, the applicable IDOL content logs, the command used, and the backup details before stopping or retrying the operation.
- If database, document, or search behavior is inconsistent after restore, stop further changes and contact Xerox DocuShare Support.
Contact Support
Contact Xerox DocuShare Support when the backup or restore fails after you have verified the command, path, permissions, and release-specific procedure. Include the following information:
- DocuShare version, patch level, operating system, database, and search engine.
- Whether the site was stopped or placed in Read Only mode.
- The exact backup or restore command, including the content-engine name if used.
- Backup location, approximate index size, and the time the operation started.
- idoltool.log and applicable IDOL content logs.
- The exact error message and whether restore: Done. was recorded.
Related Resources
- For snapshot-based or scheduled backups, use the applicable DocuShare backup procedure for your environment.
- For major-version upgrades or new-server migrations, use the release-specific DocuShare upgrade path and migration documentation.
- Apply the latest available DocuShare patches, updates, and security fixes before maintenance when they are supported for your release.