The mi-app-restore tool will read a backup file generated by mi-app-backup and restore the machine to the state contained in the backup file. To restore a backup file, there are many available options. The four common ones are:
- Full restore;
- Restore when database resides on remote server;
- Restore with retained configuration files;
- Restore database only.
Prerequisites:
- You must have previously used mi-app-backup to Backup Your Metric Insights instance.
- The machine on which you run mi-app-restore needs to already have the Metric Insights application installed on it.
- You will need root privileges to do the following commands. So either sign in as root, or do each command prefixed with "sudo".
- The mi-app-restore will restore the database to the location configured in
/opt/mi/config/insight.confon the machine you run the restore. So before restoring on a machine, make sure its/opt/mi/config/insight.confpoints to the location of the database to which you will restore.
IMPORTANT:
- You need to run the restore command inside the Web container ( run
mi-webon the host to enter Web) - Make sure the backup tarball is in
/opt/mi/backupon the host in order to access it from inside the Web container (/opt/mi/backupis mounted as a volume inside the Web container).
RESTORING ONTO A DIFFERENT INSTANCE?
Beginning in v7.1.1, each Metric Insights instance has its own unique AES_PASSWORD, generated at install time. This passphrase makes previously encrypted values readable; e.g., stored passwords, External Resource client secrets, OAuth tokens. The value of AES_PASSWORD is not stored in the backup file itself.
If the new instance was installed with a different AES_PASSWORD than the instance the backup came from, all of that backup's encrypted secrets will be unreadable after restore and must be re-entered manually.
To avoid manual re-entering of secret values, follow these steps before decommissioning the old instance:
- Retrieve its AES_PASSWORD:
- Access the
webcontainer:mi-web - Obtain the value of
AES_PAWWORD:env | grep AES_PASSWORD
- Access the
- When installing the new instance, pass that value to the installer:
--aes-password <AES_PASSWORD_FROM_OLD_INSTANCE>.- See Generate Installer Command with Wizard for installer options.
- This step happens during installation of the new instance, not as a flag on
mi-app-restore.
- Then restore the backup normally. Encrypted values will remain valid.
NOTE: Beginning in v7.1.0, restore to a different hostname will update the External Applications credentials.
1. Execute a Full Restore process
To restore Metric Insights, including overwriting any configuration files you might have on the system on which the restore is executed, use the mi-app-restore command:
mi-app-restore PATH_TO_BACKUP_FILE2. Execute a Restore when the Database Resides on a Remote Server
If the application database resides on a remote server (i.e., not the Metric Insights application server), you can use the following command:
mi-app-restore -U admin_user -P admin_pass PATH_TO_BACKUP_FILE...where admin_user and admin_pass are the admin credentials for the remote database server
3. Execute a Restore While Retaining Configuration Files
If you wish to keep your configuration files and only restore application state, you can use the following command:
mi-app-restore --no-config PATH_TO_BACKUP_FILE4. Restore Only the Database
If you wish to only restore the database, you can use the following command:
mi-app-restore --include 'db' PATH_TO_BACKUP_FILE5. Usage
To see all usage options:
mi-app-restore -h| Parameter | Description |
|---|---|
| Positional Arguments | |
| src_uri | Location of the backup file. This can point to a local file or a remote scp/ftp/s3 backup. |
| Optional Arguments | |
| -h, --help | Show this help message and exit |
| --dry-run, -n | Dry run. Print what would happen |
| --verbose, -v | Be verbose. More v's, more verbose |
| --version, -V | Show program's version number and exit |
| --force, -f | Don't ask for confirmation, just do the restore |
| --no-config | Don't restore the config files in the backup |
| --db-user DB_USER, -U DB_USER | The DB user to use when loading the MI database. Default: root |
--db-pass DB_PASS, -P DB_PASS | The DB password to use when loading the MI database |
| --user USER, -u USER | Optional user for logging into remote host |
--password PASSWORD, -p PASSWORD | Optional password for logging into remote host |
| --ssh-key SSH_KEY, -i SSH_KEY | SSH key file to use for remote server |
| --include TYPE, -I TYPE | What to include from the backup. Choose from 'db', 'files', or 'full'. Default: full |
| --convert, -c | Convert older backup data to be compatible with the newer installed version |
| --skip-compatibility-check | Skip compatibility check, when restoring an old backup copy |
| --force-cancel-da-indexing | Try forcibly stopping the Data Analyzer indexing process before running the restore. No effect if --force option is supplied. |
| --disable-notifications | Disable system-wide notifications |
| --azure-storage-account-name AZURE_STORAGE_ACCOUNT_NAME | Azure storage account name |
| --azure-blob-container-name AZURE_BLOB_CONTAINER_NAME | Azure blob container name |
| --azure-folder AZURE_FOLDER | Azure virtual folder name, optional |
6. Examples
Restore MI from the given backup:
mi-app-restore /some/dir/my_file.tar.gz mi-app-restore file:///some/dir/my_file.tar.gz Read the backup from the remote machine machine.example.com.
- This will use the ~/.ssh/id_rsa ssh key by default if it exists
- Use -i SSH_KEY to modify this
mi-app-restore ssh://machine.example.com/home/cru/backups/my_file.tar.gz Backup from the file from ftp.example.com in the /upload/backups directory.
mi-app-restore -u <user> -p <pass> ftp://ftp.example.com/upload/backups/my_file.tar.gz
Read backup file from Amazon S3 bucket my-bucket. The @endpoint/bucket syntax will work for RIAK-CS and other s3-compatible cloud storage services.
mi-app-restore -u <S3_ID> -p <S3_KEY> s3://my-bucket/dir/my_file.tar.gzmi-app-restore -u <S3_ID> -p <S3_KEY> s3://@my.s3.endpoint/my-bucket/dir/my_file.tar.gz6.1. Example: Restore Amazon EC2 instance with RDS
1. Spin up new Amazon EC2
2. Spin up new Amazon RDS
On new EC2 instance:
3. Move EC2 local db to RDS
mi-db-move <rds host> <rds db admin> <rds db password>(This will also rename the dashboard db to the "hostname/ip address" of the machine.
Note, you must define the mysql parameters appropriately for the remote db server. Please see http://kb.metricinsights.com/m/44498/l/412310-fine-tuning-mysql-parameters for more information.)
4. Optional: Rename db on RDS to be the same as what is in the restore
mi-db-rename -d <dashboard db name> -D <old dashboard db name> -U <rds db admin> -P <rds db password>5. Get the backup file to restore from
scp root@<old EC2 host>:/var/backups/mi-app-backups/<backup file name> /var/backups/mi-app-backups/6. Do the restore (This will upgrade, then restore)
mi-app-restore -U <rds db admin> -P <rds db password> /var/backups/mi-app-backups/<backup file name>