Skip to main content

How to Back Up and Restore IDOL Using Snapshots or Scheduled Operating System Backups

Updated
Before you begin:  Create and verify a current backup of the DocuShare database, document repository, configuration, and license information before performing a snapshot, restore, migration, or other maintenance operation. Do not proceed without a usable recovery backup.

 

Scope and Version Applicability

This procedure is intended for DocuShare 7.5, 7.6, 7.7, 8.0, and 8.1 (when released) installations using the IDOL search engine. The IDOL backup and restore command workflow and IDOL directory layout are consistent across these releases.

Commands, service procedures, and migration requirements can still vary by operating system, patch level, and installation layout. Follow the documentation supplied with your installed release when it differs from this article.

Required Service State: Snapshot vs. idoltool vs. resetserver

These three operations need IDOL in opposite states. Using the wrong one for the method you are following will fail or produce an inconsistent result.

  • File-system snapshot or scheduled operating system backup or restore of the IDOLServer directory: DocuShare and IDOL fully stopped. IDOL's content engine writes to the index continuously, so a snapshot taken while it is running can capture an inconsistent state.
  • idoltool backup and idoltool restore: DocuShare in Read Only mode with IDOL running. These commands send an HTTP request to IDOL's configured index port and then poll its ACI port for completion; if IDOL is stopped, the command cannot connect.
  • idoltool resetserver: DocuShare and IDOL fully stopped. The command checks whether the target server is running and aborts immediately if it is.
Do not mix these up:  Do not run the optional idoltool backup procedure while DocuShare and IDOL are stopped for a snapshot; it will fail with a connection error. Perform it separately, with DocuShare in Read Only mode and IDOL running.

 

Before Taking a Snapshot or Scheduled Backup

  1. Confirm the backup window and record the DocuShare release, patch level, operating system, database, IDOL configuration, and configured content engines.
  2. Stop DocuShare before beginning the snapshot or backup. Stopping DocuShare also stops IDOL, since IDOL's server processes are managed by the DocuShare Monitor service. Read Only mode alone is not sufficient for a file-system snapshot; the IDOL content engine keeps writing to the index while it is running. If the database is file-based, stop the database service as required by the database backup procedure.
  3. Confirm where the IDOL content data paths actually reside before capturing the backup. On a default installation they are under <dshome>\IDOLServer, but the content paths, including Main, Status, Dynterm, Nodetable, RefIndex, Numeric, User, and Tag, can be relocated to other storage using the idoltool setcontentdir command. Run idoltool -s info (while IDOL is running, before you stop it) or review the content server configuration to confirm the configured paths.
  4. Ensure that database files, the document repository, configuration files, license information, the IDOLServer directory, and any relocated content data paths identified above are captured during the same recovery cycle.
  5. Use a backup destination with sufficient space and permissions, preferably separate from the source storage so the snapshot or backup provides recovery value.
Relocated content paths:  Backing up only <dshome>\IDOLServer captures the full index on a default installation. If any content data path has been relocated outside IDOLServer, a backup that only covers IDOLServer will miss that portion of the index entirely. This is common on larger sites that move index data to dedicated storage, and those are exactly the sites most likely to rely on snapshots.

 

Capture the Snapshot or Scheduled Backup

  1. With DocuShare and IDOL stopped, back up the complete <dshome>\IDOLServer directory, plus any relocated content data paths identified above, using your approved snapshot or operating system backup procedure.
  2. Capture the DocuShare database, document repository, configuration, and license data in the same recovery cycle.
  3. Verify that the backup completed successfully and that the backup contains the expected IDOLServer data and any relocated content paths. Do not rely only on a reported file size; verify the backup job and recovery contents according to your backup product.
  4. After the snapshot or backup completes, start DocuShare using the supported service procedure for your release. Starting DocuShare also starts IDOL through the Monitor service.
  5. Confirm that IDOL has started and is indexing normally. Review the IDOL logs for startup or indexing errors.
If IDOL does not come back up:  idoltool does not provide a pause, resume, or standalone start command; it provides stop and waitforstartup. IDOL is started and stopped along with DocuShare through the Monitor service. If IDOL does not start normally after DocuShare restarts, do not attempt an undocumented workaround. Review the IDOL logs and contact Xerox DocuShare Support.

 

Optional Alternative: Back Up Only the IDOL Index with idoltool

Separate procedure with a different service state:  This optional command-based procedure is not the snapshot or scheduled operating system backup procedure described above and does not replace a complete backup of the database, document repository, configuration, license information, and IDOLServer directory. It also requires the opposite service state: perform it with DocuShare in Read Only mode and IDOL running, not while DocuShare and IDOL are stopped for a snapshot.

 

Use idoltool when you specifically need a command-based backup of IDOL index data. The utility sends an HTTP DREBACKUP request to IDOL's index port and waits for completion, so IDOL must be running. Change to the DocuShare bin directory and run the command for your operating system.

Windows:
idoltool.bat -s backup <path_to_backup_directory>

Linux or Solaris:
idoltool.sh -s backup <path_to_backup_directory>

 

When multiple content engines are configured, run the command once for each engine and provide the matching server name, such as content0 or content1. Omitting the server argument when more than one content engine is configured fails immediately with Error: No server parameter specified.

Windows:
idoltool.bat -s backup C:\idolbackup content0
idoltool.bat -s backup C:\idolbackup content1

Linux or Solaris:
idoltool.sh -s backup /idolbackup content0
idoltool.sh -s backup /idolbackup content1

 

Verify backup: Done. in <dshome>/logs/idoltool.log. For multiple content engines, confirm completion for every engine and review the applicable IDOL content logs. Do not use the idoltool backup directory as a substitute for the complete snapshot or scheduled backup required for site recovery.

Restore from a Snapshot or Scheduled Backup

  1. Confirm that the database, document repository, configuration, license, and IDOL backup represent the recovery point you intend to restore.
  2. Stop DocuShare and confirm that the IDOL services are shut down through the supported service procedure. Do not terminate IDOL processes forcibly unless Xerox DocuShare Support or the release documentation explicitly directs you to do so.
  3. Restore the <dshome>\IDOLServer directory from the snapshot or operating system backup. Restore the document repository separately as required, preserving the target installation's guid.txt file.
  4. Restore the DocuShare database, configuration, and other required site files according to your approved recovery procedure.
  5. Start the IDOL services and DocuShare using the supported service procedure.
  6. Confirm that IDOL starts normally, that the configured content engines are available, and that the IDOL logs do not report startup or index errors.
Restore completion:  For a snapshot or scheduled operating system restore, completion is confirmed by your backup product's successful restore status and by verifying that IDOL and DocuShare start normally. The restore: Done. message applies only when you separately use idoltool to restore an idoltool-created index backup; it is not a required marker for a file-system snapshot restore.

 

Reindex After Restore

After the IDOL restore is complete and DocuShare is running, reindex objects changed since shortly before the backup was created.

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

 

Set the first date shortly before the backup was created. Confirm that the reindex completes and 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 the last day you need covered, that day's changes are not reindexed. Set the end date to one day past the last day you need covered.

 

When resetserver Is Required

Do not run resetserver as a routine step for a snapshot restore. A file-system snapshot restore restores the IDOLServer directory directly; it does not require the idoltool restore command or resetserver.

resetserver is the correct step for a different situation: the IDOL index is corrupted or unusable and no usable index backup exists. In that case, reset the server and then run a full reindex. It is not part of restoring a good backup.

Some documented new-server migration or index-reset procedures require the following command before restoring or rebuilding IDOL. This command requires DocuShare and IDOL to be fully stopped; it aborts if the target server is still running.

Windows:
idoltool.bat -s resetserver all y

Linux or Solaris:
idoltool.sh -s resetserver all y

 

Destructive operation:  resetserver all y can reset IDOL server structures and remove or clear configured content-index data paths, including Main, Status, Dynterm, Nodetable, RefIndex, Numeric, User, and Tag data. It can also remove selected logs, lock files, database/status files, license and uid directories, and FileSystemFetch temporary or queue data. Run it only when a documented migration or recovery procedure requires it, with verified backups available. 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; otherwise you can be left with a partially reset installation that is harder to diagnose.

 

Troubleshooting and Support

  • If IDOL does not start normally after DocuShare restarts, review the IDOL logs. idoltool does not provide a pause or resume operation; IDOL starts and stops along with DocuShare through the Monitor service.
  • If you used the optional idoltool backup and cannot confirm backup: Done. in idoltool.log for every content engine, treat that backup as unverified and rely on your snapshot or scheduled backup instead.
  • If a documented migration or recovery procedure directs you to restore an idoltool-created index backup with idoltool -s restore, that command also requires IDOL to be running, and restore: Done. in idoltool.log is the required completion marker for that command. It is not required for, and does not apply to, a file-system snapshot restore.
  • If the restored site has inconsistent database, document, or search behavior, stop further changes and contact Xerox DocuShare Support.
  • If you have a valid support agreement, apply the latest supported patches and security updates and plan an upgrade to the latest supported DocuShare release where practical.

When contacting support, provide your DocuShare Host ID, version and patch level, operating system, database, IDOL version if known, content-engine names and configured content-path locations, snapshot or backup product, commands used, relevant logs, and the backup product's restore status.

Related articles