Restore Your Metric Insights Instance
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.conf
on the machine you run the restore. So before restoring on a machine, make sure its/opt/mi/config/insight.conf
points 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-web
on the host to enter Web) -
Make sure the backup tarball is in
/opt/mi/backup
on the host in order to access it from inside the Web container (/opt/mi/backup
is mounted as a volume inside the Web container).
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_FILE
2. 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_FILE
4. 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_FILE
5. 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 |
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.gz
mi-app-restore -u <S3_ID> -p <S3_KEY> s3://@my.s3.endpoint/my-bucket/dir/my_file.tar.gz
6.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>