| Before you begin: Create and verify a current backup of the DocuShare database, document repository, configuration, and license information before changing IDOL configuration or performing a restore. Do not proceed without a usable recovery backup. |
Scope and Version Applicability
This procedure is intended for DocuShare 7.0 and later installations using the IDOL search engine. The idoltool backup and restore command behavior and the IDOL scheduled-backup configuration described here have not changed since DocuShare 7.0.
Commands, service procedures, and file paths can still vary by operating system and installation layout. Follow the documentation supplied with your installed release when it differs from this article.
This article covers automatic, scheduled backups of the IDOL index that IDOL itself performs on a timer. For file-system snapshots or operating-system-level backup jobs, use the separate snapshot and scheduled operating system backup article. For a manual, on-demand IDOL backup or restore, use the separate manual backup and restore article.
Required Service State
- Editing the IDOL scheduled-backup configuration: DocuShare stopped, so the configuration file is not open or locked by a running IDOL process.
- 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.
Configure IDOL for Scheduled Automatic Backups
- Stop DocuShare.
- Locate the configuration file for the server that will run the scheduled backup. For a single content engine, this is <dshome>\IDOLServer\IDOL\AutonomyIDOLServer.cfg. If you are running more than one content engine, edit each engine's own configuration file instead, such as content0.cfg and content1.cfg.
- Make a copy of the configuration file before editing it, and rename the copy with a .orig extension so you can revert if needed.
- Open the configuration file in a text editor. Add a [Schedule] section if one is not already present, and set the following parameters.
| [Schedule] Backup=true BackupCompression=true BackupTime=00:00 BackupInterval=0 BackupMaintainStructure=true NumberOfBackups=2 BackupDir0=/contentX_Backup0 BackupDir1=/contentX_Backup1 |
- BackupCompression=true creates compressed backup files.
- BackupTime uses 24-hour notation, for example 00:00 for midnight.
- BackupInterval is the elapsed time in hours between backups. A value of 0 means every day.
- NumberOfBackups must match the number of BackupDirN directories configured, since the schedule cycles through each one in turn.
- Each BackupDirN value must be a unique destination for each content engine. Do not point two engines at the same directory.
| Timing behavior: The configured BackupInterval must fully elapse before the first scheduled backup occurs. For example, with BackupInterval=0, one full day must elapse before the first backup runs. The interval timer also resets whenever DocuShare is restarted, so a restart shortly before the scheduled time can delay the next backup by a full interval. |
- Save the configuration file.
- Start DocuShare.
| Disk space: Consider the disk space required for scheduled backups, particularly when BackupCompression is not used or when NumberOfBackups retains multiple backup cycles. |
Verify the Scheduled Backup
After the configured interval has elapsed, confirm that the scheduled backup completed.
- Single content engine: review <dshome>\IDOLServer\IDOL\logs\content_application.log and <dshome>\IDOLServer\IDOL\logs\content_index.log.
- Multiple content engines: review the equivalent application.log and index.log files under each engine's own log directory, such as <dshome>\IDOLServer\content0\logs and <dshome>\IDOLServer\content1\logs. Check every configured engine, not only one.
- Confirm that the expected backup files exist in the configured BackupDirN destination.
The application log records entries similar to the following when a scheduled backup completes:
| Backing up database into existing directory '<BackupDirN>' Backing up "Main" files into directory '<BackupDirN>/main' Backing up "Status" files into directory '<BackupDirN>/status' ... Backup Complete. |
Restore from a Scheduled Backup
Restore using idoltool only after you have identified and verified the scheduled backup cycle you intend to restore, and after the DocuShare database and document repository recovery point has also been identified.
- Place DocuShare in Read Only mode. Do not stop DocuShare or IDOL for this step; idoltool restore sends an HTTP request to IDOL's index port and requires IDOL to be running.
- Open a command prompt or terminal window and change to the <dshome>\bin directory.
- Run the restore command for your operating system, pointing to the backup directory you are restoring from.
| 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 engine and provide the matching server name. Omitting the server argument when more than one content engine is configured fails immediately with Error: No server parameter specified.
| Windows: idoltool.bat -s restore C:\idolbackup content0 idoltool.bat -s restore C:\idolbackup content1 Linux or Solaris: idoltool.sh -s restore /content0_backup0 content0 idoltool.sh -s restore /content1_backup0 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.
| 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 multiple content engines, confirm completion for every engine before returning DocuShare to normal Read/Write mode.
| Restore duration: Restore time depends on the size of the IDOL index. Large indexes may take 30 minutes or longer. A returned command prompt is not a valid completion check by itself; confirm restore: Done. in idoltool.log. |
Reindex After the Restore
After the IDOL restore is complete, 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 before restoring a good scheduled backup. The restore command submits DREINITIAL and replaces the index contents on its own; it does not call resetserver, and adding it first destroys the live index before you know the backup restores successfully.
resetserver is the correct step for a different situation: the IDOL index is corrupted or unusable and no usable backup exists. In that case, reset the server and then run a full reindex. Some documented new-server migration or index-reset procedures also require it. 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, or when the index is unusable with no good backup available. For any other situation, contact Xerox DocuShare Support before running it rather than using it as a routine restore 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 the scheduled backup did not run, confirm that the BackupInterval has fully elapsed, that DocuShare has not been restarted since the interval began, and that NumberOfBackups matches the number of configured BackupDirN entries.
- If a multi-engine backup or restore 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 content logs, the command used, and the backup details before stopping or retrying the operation.
- 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 version and patch level, operating system, database, content-engine names, the [Schedule] configuration in use, the backup directories, commands used, relevant logs, and whether restore: Done. was recorded.
Related Resources
- For file-system snapshots or operating-system-level scheduled backups, use the separate snapshot and scheduled operating system backup article.
- For a manual, on-demand IDOL backup or restore, use the separate manual backup and restore article.