Manual:Grabbers

From MediaWiki.org
Jump to: navigation, search

This page describes a series of grabber scripts designed to get a wiki's content without direct database access. If you don't have a database dump or access to the database and you need to move/back up a wiki, the MediaWiki API provides access to get most all of what you need. These scripts also requires MediaWiki 1.29+ since Gerrit change 376957.

Appropriate access on the target wiki is required to get private or deleted data, but most scripts will just work without such access. This document was originally compiled and scripts assembled in order to move Uncyclopedia; because the overall goal was to just get the damn thing moved, 'pretty' was not exactly in our vocabulary when we were setting this up so some of it/them are still kind of a horrible mess. However, many of them have been revised since then and made more robust, and were used successfully to move several wikis from wikia to a new host.

The way those scripts work is to replicate the database with the same public identifiers (revision ID, log ID, article ID), so most of them must be used on a clean, empty database (with just the table structure) or a database that has the same IDs as the remote wiki being replicated.

Stuff to get[edit]

If you're moving an entire wiki, these are probably what you need to get. More information on the tables can found on Manual:database layout, but the secondary tables can be rebuilt based on these. Otherwise you probably know what you want.

  • Revisions: text, revision, page, page_restrictions, protected_titles, archive (most hosts will provide an xml dump of at least text, revision, and page tables, which add up to the bulk of a wiki)
  • Logs: logging
  • Interwiki: interwiki
  • Files (including deleted) and file data: image, oldimage, filearchive
  • Users: user, user_groups, user_properties, watchlist, ipblocks
  • Other stuff probably (this is just core; extensions often add other tables and stuff).

Scripts[edit]

  • php files should be in the code repository.
  • python files have been added to the repository too.
  • java is MWDumper.
  • No ruby is involved. So far.

PHP scripts[edit]

These are maintenance scripts and output their grab straight into the wiki's database. To "install" them:

  • get MediaWiki core,
  • It needs a working LocalSettings.php with database credentials, and a working MediaWiki database, so be sure you've set up the wiki first
    • You can create it quickly by running php maintenance/install.php --server="http://dummy/" --dbname=grabber --dbserver="localhost" --installdbuser=root --installdbpass=rootpassword --lang=en --pass=aaaaa --dbuser=grabber --dbpass=grabber --scriptpath=/ GrabberWiki Admin
    • Some configuration variables in LocalSettings.php that those scripts support: $wgDBtype, Manual:$wgCompressRevisions, External storage.
  • If you're importing all the contents with grabText.php, be sure to remove all rows from page, revision and text tables prior to running the script.
  • from the same path, download the scripts, e.g. with git clone https://gerrit.wikimedia.org/r/p/mediawiki/tools/grabbers.git.
Those scripts require that you have sufficient privileges to create files on the directory from where you're executing them. That's because curl attempts to write a cookie file on the current directory, and failing to do so will result in a failed login attempt, without any other explanation of what's going on.
Script Target Tables Notes
grabText.php Page content (live).
  • Gets all revisions from all pages, from all or selected namespaces. It supports resuming operation starting from a given page.
  • Has support for External Storage, compression and ContentHandler.
  • It uses the original page, revision and user ID.
    • After doing the import, you will probably need to set the userid autoincrement to after the highest rev_user in the revision table. Otherwise there may be some weird attribution issues with new accounts.
  • It is highly recommended to import a dump first if you can and just fill in the missing stuff with grabNewText.php instead - revisions are huge and take a long time to download - so use MWDumper for that (the importDump maintenance script included with MediaWiki was broken as 1.20, and probably still is). Missing stuff generally includes deleted revisions (archive), protection information (page_restrictions, protected_titles), and obviously anything that changed since the dump was created.
    • On june 2017 it took 6h15m to grab all revisions from the main namespace of a wiki (grabbing 25.800 pages and 1.083.000 revisions, with an average page length of 4KB and an average revision length of 17KB, 18GB of uncompressed text) using a database mounted in a ramdisk, with text compression and external storage enabled on a second database on disk, on a linode with 1GB of RAM and 512MB of swap, and logging in with a bot account (which has higher rate limits to query data).
  • It caches the internal IDs of the text table for inserts, so avoid running this script in parallel (for example, with different namespaces) or you'll get primary key errors.
  • Latest version has been thoroughly tested in MediaWiki 1.25 and 1.29 against a MediaWiki 1.19 remote wiki (09/06/2017).
grabNewText.php New content, for filling in edits from after a dump was created and imported.
  • This script must be used only after filling in the secondary tables from the initial dump import, or after using grabText.php.
  • Supports filtering changes from specific namespaces. Due to how it caches latest revision ID, it may erroneously skip changes if you skip namespaces that have been imported already.
  • Has support for External Storage, compression and ContentHandler.
  • It uses the original page, revision and user ID.
  • Latest version has been thoroughly tested in MediaWiki 1.25 and 1.29 against a MediaWiki 1.19 remote wiki (09/06/2017).
grabDeletedText.php Deleted content.
grabNamespaceInfo.php Namespaces n/a
  • Prints out a list to add to the LocalSettings.php because namespace information is not stored internally.
grabLogs.php Stuff that shows up on Special:Log.
  • Ability to filter by a list of log types.
  • Grabs logs from older to newer, can be used to resume operation in case it fails, or for updating a live site.
grabInterwikiMap.php Supported interwiki links - show up on Special:Interwiki if Extension:Interwiki is installed.
  • Can either import all interwikis or just the interlanguage links, though getting all the interwikis is generally recommended to maintain compatibility.
grabFiles.php Files and file info, including old versions (descriptions are page content).
  • Use this for a full dump - it imports files directly (such that log entries and file descriptions from other scripts are used), and includes old revisions.
  • You should run this script as the user that normally runs php on the webserver (for example, sudo -u wwwrun php grabNewFiles.php ...), or fix file owner afterwards.
  • It does multiple retries in case a file fails to download.
  • It compares the sha of the file against the sha provided by the api of the remote wiki to check for corrupted files and retries in case of failure.
  • It uses the internal MediaWiki classes configured in $wgLocalFileRepo to store the files. It can theoretically support complex storage engines.
  • It has special optimizations for wikia. Use the wikia parameter in that case.
grabNewFiles.php Files and file info to update a site that had used grabFiles.php already.
  • Use this to update a live site or after grabNewFiles.php has been run and you want to get more recent uploads.
  • All features from grabFiles.php apply here as well.
grabImages.php Current file versions, without database info n/a
  • If you only want to download the files off something and don't care about the descriptions or old revisions, use this to only download them without affecting the database (and then use the importImages maintenance script that comes with core to import them into the wiki)
    Otherwise use grabFiles.php as that imports files directly as well as downloading them.
grabDeletedFiles.php Deleted files and file info.
  • Only works if the target wiki uses a known (assumes default) deleted file hashing configuration. If you don't know it you will need a screenscraper due to a lack of API support for actually downloading deleted files. (At least as of when this was written.)
grabUserBlocks.php User blocks.
  • Grabs all blocks from older to newer.
grabUserGroups.php Groups users belong to.
  • Assumes ids are/will be the same on source and target wiki, and not much can be done about this because it generally runs before the accounts are actually created.
  • It can be filtered to fetch only a defined list of user groups.
grabAbuseFilter.php Abuse filters.
  • Grabs current filters from Extension:AbuseFilter. Only grabs the current version of filters, no version history and no abuse logs, because there's no api available for them.
populateUserTable.php Users.
  • It doesn't grab anything from the remote wiki, but populates the user table from information from the revision, logging, image, oldimage, filearchive and archive tables.
  • It only creates stub users that can't login to the wiki, used so the database has consistency and Special:Logs doesn't display strange user names like 127.0.0.1.
  • A special extension can be used to allow those users login using the information from the remote wiki (similar to Extension:MediaWikiAuth, I plan to release it soon)

Python scripts[edit]

  • The python scripts will currently populate the ipblocks, user_groups, page_restrictions, and protected_titles tables.

It's recommended that you use python 2.7.2+. You will need to install oursql, and requests.

You need to edit settings.py and set the site you want to import from, and your database information.

The easiest way to run everything is just $ python python_all.py which executes all four individual scripts. You can also run each script individually if you choose (so you can run them concurrently).

Note: Autoblocks will not be imported since we do not have the data about which IP address is actually being blocked

Extension:MediaWikiAuth[edit]

Imports user accounts on login. Note that this requires the site you are copying from to still be active to use their authentication.

Affects user, user_properties, watchlist tables

  • Uses screenscraping as well as the API due to incomplete functionality.
  • Updates user ids in most other tables to match the imported id, though apparently not userid log_params for user creation entries

Other stuff[edit]

Not grabbers, but things to potentially worry about.

  • Configuration stuff - groups, namespaces, etc
  • Extensions
  • Extension stuff - ajaxpoll, checkuser, socialprofile, and others have their own tables and stuff
  • Secondary tables - the above grabber scripts generally just set the primary tables; secondary tables such as category, redirect, site_stats, etc can be rebuilt using other maintenance scripts included with MediaWiki, usually rebuildall.php.

See also[edit]