BackupBuddy: ImportBuddy

(Difference between revisions)
Jump to: navigation, search
(Step 1)
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{#ev:vimeo|22918787|400|right}}
 
{{#ev:vimeo|22918787|400|right}}
 
==Getting Started==
 
==Getting Started==
The following will describe what is needed to start migrating or restoring a backup.
+
===Getting the ImportBuddy tool===
* Download ImportBuddy from within BackupBuddy by navigating to the `Backup & Restore` page and clicking the `ImportBuddy` or `Restore / Migrate` button depending on your version.
+
The ImportBuddy tool can be downloaded in BackupBuddy.
* Decide on the server directory that you would like to migrate or restore the backup to (using an empty directory is best).
+
 
* Upload importbuddy.php and the backup zip file (don't rename the zip file!) to that directory.
+
# Navigate to the `Backup & Restore` page.
 +
# Click on the `ImportBuddy` link or `Restore / Migrate` button depending on your version.
 +
#* Alternatively you may click the `Send` link beneath the `Restore / Migrate` button to directly send the tool to a remote destination.
 +
# Save the script to your computer. (You will next upload this script to your destination server to begin using it)
 +
 
 +
===Uploading ImportBuddy to your destination server===
 +
* Decide on the FTP directory that you would like to migrate or restore the backup to (using an empty directory is best) that corresponds to the web URL you want your destination site to be at.
 +
** For example, if you want your new site's URL to be "http://your.com/mybuddy/" then your server directory MIGHT be something like this "/usr/skyler/public_html/mybuddy/"; this is the directory you will then put importbuddy.php into. The directory structure varies host to host but often follows a similar format.
 +
* Upload importbuddy.php and the backup zip file (don't rename the zip file!) to that FTP directory that corresponds to the URL you want.
 
* Navigate to the importbuddy.php file in your web browser after it has been uploaded.
 
* Navigate to the importbuddy.php file in your web browser after it has been uploaded.
 
** Example: <nowiki>http://newsite.com/importbuddy.php</nowiki>
 
** Example: <nowiki>http://newsite.com/importbuddy.php</nowiki>
Line 10: Line 18:
 
* If you encounter problems note the logging information displayed on the problem step when contacting support.
 
* If you encounter problems note the logging information displayed on the problem step when contacting support.
  
 +
==Accessing the ImportBuddy tool==
  
==Step 0: Password Authentication==
+
In your web browser go to the URL corresponding to the FTP directory you uploaded to. For example, if you uploaded importbuddy.php to /usr/skyler/public_html/undiscoveredcorner/importbuddy.php then your ImportBuddy URL MIGHT be http://your.com/undiscoveredcorner/importbuddy.php
This step asks for the password associated with the importbuddy.php file.
+
Upon going to this URL you will be prompted to log in to begin the import / restore process.  Follow the on-screen directions.
* Is set in BackupBuddy's Settings page and required to continue.
+
 
** The password is attached to the importbuddy.php file when it is made so if you change the password will need to download and upload a new importbuddy.php file
+
==Log In - Password Authentication==
 +
 
 +
This step asks for the password associated with the importbuddy.php file. ImportBuddy requires this to protect unauthorized access to your site and backup files before you have finished restoring. This password was previously set by you (or someone) on BackupBuddy's Settings page.
 +
 
 +
''Typical Usage''
 +
* Enter your password.
 +
* Submit the form to continue. (Click the button to submit / continue to the next step)
 +
 
 +
Misc Notes:
 +
* The password is encoded inside your importbuddy.php file when it is made, so:
 +
** If you share this importbuddy.php file to another for usage with a backup file you will need to provide the corresponding password.
 +
** If you change the password will need to download a new copy of importbuddy.php; changing the password will NOT change it in existing importbuddy.php files.
  
  
 
==Step 1==
 
==Step 1==
On this step there is a dropdown list of the backup zip files that can be restored or use to migrate with. Also has an Upload tab to upload a backup .zip file by browsing for it.
+
NOTE: You DO NOT need to first install WordPress on the target hosting server.
  
This step also allows the user to set advanced troubleshooting options to customize the importbuddy process.
+
On this step a listing of backup files that were found in the same directory as the importbuddy.php script are listed for your selection to restore / migrate. If you have not already uploaded your backup file along with the importbuddy.php file an upload feature is available for convenience. However, ''FTP is the best way to upload your backup archives (.zip files), especially for larger files.''.
* Wipe database on import. Use with caution.
+
 
** This option will blank out the current database at the location, if not the option you needed to use then could lose data
+
''Typical Usage''
* Ignore SQL errors & hide them.  
+
* Select the backup you want to restore or migrate to this destination.
 +
* Select any optional advanced options if needed or directed by technical support.
 +
* Submit the form to continue.
 +
 
 +
===Advanced Troubleshooting Options===
 +
ImportBuddy automatically accounts for many server configurations and troubleshooting settings.  However, when ImportBuddy cannot automatically account for some difficulty or cannot automatically assume to do so safely, you have the option to control server options and features which can aid with working around server problems or troubleshooting possible issues.
 +
 
 +
''Features''
 
* Skip zip file extraction.
 
* Skip zip file extraction.
** This option is mainly used if the files are manually being unzipped instead of using the importbuddy file extraction process.
+
** If enabled then Step 2 of ImportBuddy will skip unzipping / extracting your backup ZIP file. You will need to manually unzip the file somehow, such as on your local system and then uploading all files, or with a server-side tool such as within your host's control panel file manager (if available).
 +
* Wipe all database tables. - Use caution.
 +
** This features wipes (erases / deletes) ALL tables within the database you will later select. Use extreme caution with this feature as it could release in permanent loss of data / sites / content in your database if used improperly. This is typically used to clear out a database and start fresh for this restored site. - Use caution.
 +
* Wipe only database tables matching prefix.
 +
** This feature is like the above EXCEPT it only erases tables with the same prefix you enter.  Ie if you enter wp_ only tables starting with wp_ will be erased. Use caution.  This is typically used to overwrite a single existing site.
 
* Skip import of database.
 
* Skip import of database.
 +
** Useful if you only want to restore files and not import anything into your current database. Note: Your database will still be migrated unless disabled below.
 
* Skip migration of database.
 
* Skip migration of database.
 +
** Useful if you only want to migrate the data in the already imported database (ie: You already imported a database or have an existing one and just need things like URLs and paths migrated.) Note: Your database will still be imported unless disabled above.
 +
* Error Logging to importbuddy.txt
 +
* Ignore SQL errors & hide them. Rarely used option for hiding error messages. This can be used if your server is reporting incorrect errors/warnings caused by misconfiguration and it's preventing you from continuing the restore.
 
* Skip migration of .htaccess file.
 
* Skip migration of .htaccess file.
 +
** Rarely used for technical purposes only.
 
* Force medium speed compatibility mode (ZipArchive).
 
* Force medium speed compatibility mode (ZipArchive).
 +
** Bypass attempting to use command line zip. Rarely needed; troubleshooting.
 
* Force slow speed compatibility mode (PCLZip).
 
* Force slow speed compatibility mode (PCLZip).
 +
** Bypass both high speed mode and medium speed mode, falling back all the way to PCLZip (slow speed). Rarely needed; troubleshooting.
 
* Show detailed PHP warnings.
 
* Show detailed PHP warnings.
 
* PHP Maximum Execution Time
 
* PHP Maximum Execution Time
 
** Setting this a little lower can help force importbuddy to chunk the importing and migration of the database into multiple steps if large
 
** Setting this a little lower can help force importbuddy to chunk the importing and migration of the database into multiple steps if large
* Error Logging to importbuddy.txt
 
 
  
 
==Step 2==
 
==Step 2==
The file extraction process occurs during this step, and the extraction method used is displayed.
+
The file extraction process occurs during this step. ImportBuddy attempts to unzip / extract your backup ZIP archive (.zip file) into the same directory as the importbuddy.php script.
  
 +
ImportBuddy attempts to use the following techniques to unzip on your server:
 +
* Command line zip on both Linux and Windows systems (if zip.exe is provided and properly granted security access to run). (Very fast and reliable) - BEST
 +
* PHP's ZipArchive library. (decent speed; reliable) - MEDIUM LEVEL
 +
* PCLZip (extracts the zip file using a PHP script; very low performance; relies on PHP memory limits which are commonly low) - WORST CASE
 +
 +
'''If you are having difficulties getting past this step it is often simplest to just manually unzip your site locally on your computer and upload the files to the destination directory by FTP (or using cpanel to unzip) and on Step 1 of ImportBuddy, select the 'Advanced troubleshooting option' to `Skip file extraction`.'''  See the frequently seen support questions page if you want to troubleshoot why the unzip is failing.
  
 
==Step 3==
 
==Step 3==
Line 55: Line 97:
 
* Database Prefix
 
* Database Prefix
 
** This is the prefix given to all tables in the database.  If you are cloning the site on the same server AND the same database name then you will want to change this or else the imported database will overwrite the existing tables.
 
** This is the prefix given to all tables in the database.  If you are cloning the site on the same server AND the same database name then you will want to change this or else the imported database will overwrite the existing tables.
After entering the database information there is a button labelled "test database settings" that will test the validity of that connection information.  
+
** The most common prefix is wp_ which is fine to use but if you want to use something else that is fine.
 
+
After entering the database information there is a button labelled "test database settings" that will test the validity of that connection information.
  
 
==Step 4==
 
==Step 4==
The database information is imported straight into the database.
+
The database information is imported straight into the database. Your database with any old URLs / paths from the source server exist temporarily on the destination server. The next step will update this data in the database.
  
  
 
==Step 5==
 
==Step 5==
Importbuddy looks through the database and updates any URLs, paths, settings, etc. The wp-config.php information is set and the links are changed during this step.
+
If your destination URL and/or file paths need to be updating due to using a new site URL or server directory stucture then ImportBuddy will proceed to migrate various data inside your database. Importbuddy searches through the database and updates any URLs, paths, settings, etc. that match your source site's settings (BackupBuddy recorded these settings for you in the backup for this functionality to work). The wp-config.php information (such as any new database settings) is set.
 
* Use the link of the site provided to verify that the site is fully migrated and complete before continuing to step 6.
 
* Use the link of the site provided to verify that the site is fully migrated and complete before continuing to step 6.
 
* Can choose which of the import files get deleted in next step if desired. By default is all of them.
 
* Can choose which of the import files get deleted in next step if desired. By default is all of them.
Line 69: Line 111:
  
 
==Step 6==
 
==Step 6==
Cleanup step. This step attempts to delete
+
Cleanup step. This step attempts to delete any temporary files created by ImportBuddy or uploaded by you. If your restore is fully complete you can delete all of these files (assuming you have your backup zip stored elsewhere). Leaving these files could potentially be a security risk. If ImportBuddy is unable to delete these files please use your FTP client or web host's file management tools to delete them.
* backup zip archive
+
* Backup zip archive (.zip file)
* importbuddy.php
+
* ImportBuddy Tool - importbuddy.php file (the tool you are using right now)
* temporary import files (db_1.sql, backupbuddy_dat.php, etc.)
+
* Any temporary import files (db_1.sql, backupbuddy_dat.php, etc.)
* importbuddy.txt log file
+
* importbuddy-XXXXXXX.txt log file
  
  
 
[[Category:PluginBuddy]]
 
[[Category:PluginBuddy]]

Revision as of 12:30, April 24, 2013


Contents

Getting Started

Getting the ImportBuddy tool

The ImportBuddy tool can be downloaded in BackupBuddy.

  1. Navigate to the `Backup & Restore` page.
  2. Click on the `ImportBuddy` link or `Restore / Migrate` button depending on your version.
    • Alternatively you may click the `Send` link beneath the `Restore / Migrate` button to directly send the tool to a remote destination.
  3. Save the script to your computer. (You will next upload this script to your destination server to begin using it)

Uploading ImportBuddy to your destination server

  • Decide on the FTP directory that you would like to migrate or restore the backup to (using an empty directory is best) that corresponds to the web URL you want your destination site to be at.
    • For example, if you want your new site's URL to be "http://your.com/mybuddy/" then your server directory MIGHT be something like this "/usr/skyler/public_html/mybuddy/"; this is the directory you will then put importbuddy.php into. The directory structure varies host to host but often follows a similar format.
  • Upload importbuddy.php and the backup zip file (don't rename the zip file!) to that FTP directory that corresponds to the URL you want.
  • Navigate to the importbuddy.php file in your web browser after it has been uploaded.
    • Example: http://newsite.com/importbuddy.php
  • Follow the directions provided for each ImportBuddy step.
  • If you encounter problems note the logging information displayed on the problem step when contacting support.

Accessing the ImportBuddy tool

In your web browser go to the URL corresponding to the FTP directory you uploaded to. For example, if you uploaded importbuddy.php to /usr/skyler/public_html/undiscoveredcorner/importbuddy.php then your ImportBuddy URL MIGHT be http://your.com/undiscoveredcorner/importbuddy.php Upon going to this URL you will be prompted to log in to begin the import / restore process. Follow the on-screen directions.

Log In - Password Authentication

This step asks for the password associated with the importbuddy.php file. ImportBuddy requires this to protect unauthorized access to your site and backup files before you have finished restoring. This password was previously set by you (or someone) on BackupBuddy's Settings page.

Typical Usage

  • Enter your password.
  • Submit the form to continue. (Click the button to submit / continue to the next step)

Misc Notes:

  • The password is encoded inside your importbuddy.php file when it is made, so:
    • If you share this importbuddy.php file to another for usage with a backup file you will need to provide the corresponding password.
    • If you change the password will need to download a new copy of importbuddy.php; changing the password will NOT change it in existing importbuddy.php files.


Step 1

NOTE: You DO NOT need to first install WordPress on the target hosting server.

On this step a listing of backup files that were found in the same directory as the importbuddy.php script are listed for your selection to restore / migrate. If you have not already uploaded your backup file along with the importbuddy.php file an upload feature is available for convenience. However, FTP is the best way to upload your backup archives (.zip files), especially for larger files..

Typical Usage

  • Select the backup you want to restore or migrate to this destination.
  • Select any optional advanced options if needed or directed by technical support.
  • Submit the form to continue.

Advanced Troubleshooting Options

ImportBuddy automatically accounts for many server configurations and troubleshooting settings. However, when ImportBuddy cannot automatically account for some difficulty or cannot automatically assume to do so safely, you have the option to control server options and features which can aid with working around server problems or troubleshooting possible issues.

Features

  • Skip zip file extraction.
    • If enabled then Step 2 of ImportBuddy will skip unzipping / extracting your backup ZIP file. You will need to manually unzip the file somehow, such as on your local system and then uploading all files, or with a server-side tool such as within your host's control panel file manager (if available).
  • Wipe all database tables. - Use caution.
    • This features wipes (erases / deletes) ALL tables within the database you will later select. Use extreme caution with this feature as it could release in permanent loss of data / sites / content in your database if used improperly. This is typically used to clear out a database and start fresh for this restored site. - Use caution.
  • Wipe only database tables matching prefix.
    • This feature is like the above EXCEPT it only erases tables with the same prefix you enter. Ie if you enter wp_ only tables starting with wp_ will be erased. Use caution. This is typically used to overwrite a single existing site.
  • Skip import of database.
    • Useful if you only want to restore files and not import anything into your current database. Note: Your database will still be migrated unless disabled below.
  • Skip migration of database.
    • Useful if you only want to migrate the data in the already imported database (ie: You already imported a database or have an existing one and just need things like URLs and paths migrated.) Note: Your database will still be imported unless disabled above.
  • Error Logging to importbuddy.txt
  • Ignore SQL errors & hide them. Rarely used option for hiding error messages. This can be used if your server is reporting incorrect errors/warnings caused by misconfiguration and it's preventing you from continuing the restore.
  • Skip migration of .htaccess file.
    • Rarely used for technical purposes only.
  • Force medium speed compatibility mode (ZipArchive).
    • Bypass attempting to use command line zip. Rarely needed; troubleshooting.
  • Force slow speed compatibility mode (PCLZip).
    • Bypass both high speed mode and medium speed mode, falling back all the way to PCLZip (slow speed). Rarely needed; troubleshooting.
  • Show detailed PHP warnings.
  • PHP Maximum Execution Time
    • Setting this a little lower can help force importbuddy to chunk the importing and migration of the database into multiple steps if large

Step 2

The file extraction process occurs during this step. ImportBuddy attempts to unzip / extract your backup ZIP archive (.zip file) into the same directory as the importbuddy.php script.

ImportBuddy attempts to use the following techniques to unzip on your server:

  • Command line zip on both Linux and Windows systems (if zip.exe is provided and properly granted security access to run). (Very fast and reliable) - BEST
  • PHP's ZipArchive library. (decent speed; reliable) - MEDIUM LEVEL
  • PCLZip (extracts the zip file using a PHP script; very low performance; relies on PHP memory limits which are commonly low) - WORST CASE

If you are having difficulties getting past this step it is often simplest to just manually unzip your site locally on your computer and upload the files to the destination directory by FTP (or using cpanel to unzip) and on Step 1 of ImportBuddy, select the 'Advanced troubleshooting option' to `Skip file extraction`. See the frequently seen support questions page if you want to troubleshoot why the unzip is failing.

Step 3

This step is used to set the URL and database connection information. The information shown in parentheses is what importbuddy sees the values where previously, useful for a restore when most if not all of the information will be the same.

  • WordPress Address
    • This field will be pre-set using the information for the current directory the user is restoring/migrating to.
  • MySQL Server
    • This is the address to the mySQL server where your database will be stored. 99% of the time this is localhost. The location of your mySQL server will be provided to you by your host if it differs.
  • Database Name
    • This is the name of the database you want to import your blog into. The database user must have permissions to be able to access this database. If you are migrating this blog to a new host you will need to create this database (ie using CPanel or phpmyadmin) and create a mysql database user with permissions.
  • Database User
    • This is the database user account that has permission to access the database name in the input above. This user must be given permission to this database for the import to work.
  • Database Pass
    • This is the password for the database user.
  • Database Prefix
    • This is the prefix given to all tables in the database. If you are cloning the site on the same server AND the same database name then you will want to change this or else the imported database will overwrite the existing tables.
    • The most common prefix is wp_ which is fine to use but if you want to use something else that is fine.

After entering the database information there is a button labelled "test database settings" that will test the validity of that connection information.

Step 4

The database information is imported straight into the database. Your database with any old URLs / paths from the source server exist temporarily on the destination server. The next step will update this data in the database.


Step 5

If your destination URL and/or file paths need to be updating due to using a new site URL or server directory stucture then ImportBuddy will proceed to migrate various data inside your database. Importbuddy searches through the database and updates any URLs, paths, settings, etc. that match your source site's settings (BackupBuddy recorded these settings for you in the backup for this functionality to work). The wp-config.php information (such as any new database settings) is set.

  • Use the link of the site provided to verify that the site is fully migrated and complete before continuing to step 6.
  • Can choose which of the import files get deleted in next step if desired. By default is all of them.


Step 6

Cleanup step. This step attempts to delete any temporary files created by ImportBuddy or uploaded by you. If your restore is fully complete you can delete all of these files (assuming you have your backup zip stored elsewhere). Leaving these files could potentially be a security risk. If ImportBuddy is unable to delete these files please use your FTP client or web host's file management tools to delete them.

  • Backup zip archive (.zip file)
  • ImportBuddy Tool - importbuddy.php file (the tool you are using right now)
  • Any temporary import files (db_1.sql, backupbuddy_dat.php, etc.)
  • importbuddy-XXXXXXX.txt log file
Personal tools
Namespaces
Variants
Actions
iThemes Codex
Codex Navigation
Toolbox