ArchiveBot

From Archiveteam
Revision as of 00:50, 19 September 2023 by PaulWise (talk | contribs) (better info for folks w/o AB perms)
Jump to navigation Jump to search
Imagine Motoko Kusanagi as an archivist.

ArchiveBot is an IRC bot designed to automate the archival of smaller websites (e.g. up to a few hundred thousand URLs). You give it a URL to start at, and it grabs all content under that URL, records it in a WARC file, and then uploads that WARC to ArchiveTeam servers for eventual injection into the Internet Archive's Wayback Machine (or other archive sites).

Details

To use ArchiveBot, drop by the IRC channel #archivebot (on hackint). To interact with ArchiveBot, you issue commands by typing them into the channel. Note that you will need channel operator (@) or voice (+) permissions in order to issue archiving jobs; if you don't have permission, please ask for assistance by sending a message describing the website you want to archive and the reason for archiving it. Since the channel has a lot of noise, if you don't get a response quickly, your request may get lost, if that happens you can ask on the #archiveteam-bs (on hackint) IRC channel instead.

The ArchiveBot dashboard publicly shows the sites being currently downloaded. The pipeline monitor station shows the status of deployed instances of crawlers. The viewer assists in browsing and searching archives.

Components

IRC interface

The bot listens for commands in the IRC channel and then reports back status on the IRC channel. You can ask it to archive a whole website or single webpage, check whether the URL has been saved, change the delay time between requests, or add some ignore rules to avoid crawling certain web cruft. This IRC interface is collaborative, meaning anyone with permission can adjust the parameter of jobs. Note that the bot isn't a chat bot so it will ignore you if it doesn't understand a command.

Dashboard

The ArchiveBot dashboard is a web-based front-end displaying the URLs being downloaded by the various web crawls. Each URL line in the dashboard is categorized by its HTTP code into successes, warnings, and errors. It will be highlighted in yellow or red. The dashboard also provides RSS feeds and a list of pending jobs.

Backend

The backend contains the database of all jobs and several maintenance tasks such as trimming logs and posting Tweets on Twitter. The backend is the centralized portion of ArchiveBot.

Crawler

The crawler will download and spider the website into WARC files. The crawler is the distributed portion of ArchiveBot. Volunteers run pipeline nodes connected to the backend. The backend will tell the nodes/pipelines what jobs to run. Once the crawl job has finished, the pipeline reports back to the backend and uploads the WARC files to the staging server. This process is handled by a supervisor script called a pipeline.

Staging server

The staging server, known as Fortress of Solitude (FOS), is the place where all the WARC files are temporarily uploaded. Once the current batch has been approved, the files will be uploaded to the Internet Archive for consumption by the Wayback Machine.

Source Code

ArchiveBot's source code can be found at https://github.com/ArchiveTeam/ArchiveBot. Contributions welcomed! Any issues or feature requests may be filed at the issue tracker.

People

The main server that controls the IRC bot, pipeline manager backend, and web dashboard is operated by yipdw, although a few other ArchiveTeam members were given SSH access in late 2017. The staging server Fortress of Solitude (FOS), where the data sits for final checks before being moved over to the Internet Archive servers, is operated by SketchCow. The pipelines are operated by various volunteers around the world. Each pipeline typically runs two or three web crawl jobs at any given time.

Volunteer to run a Pipeline

As of November 2017, ArchiveBot has again started accepting applications from volunteers who want to set up new pipelines. Note that we only accept pipelines from people who have been active on ArchiveTeam for a while. You'll need to have a machine with:

  • lots of disk space (40 GB minimum / 200 GB recommended / 500 GB atypical)
  • 512 MB RAM (2 GB recommended, 2 GB swap recommended)
  • 10 Mb/s upload/download speeds (100 Mb/s recommended)
  • long-term availability (2 months minimum)
  • always-on unrestricted internet access (absolutely no firewall/proxies/censorship/ISP-injected-ads/DNS-redirection/free-cafe-wifi)

If you have a suitable server available and would like to volunteer, please review the Pipeline Install instructions. Then contact ArchiveTeam members Asparagirl, astrid, JAA, yipdw, or other ArchiveTeam members hanging out in #archivebot, and we can hook you up, adding your machine to the list of approved pipelines, so that it will start processing incoming ArchiveBot jobs.

Caveats

As of August 2018, there are a few things you need to be aware of when operating an ArchiveBot pipeline:

  • Never, ever press ^C on the pipeline. Use touch STOP in the ArchiveBot/pipeline directory instead to stop the pipeline.
  • Please give access to the pipeline for maintenance work when you're away (e.g. holidays, busy IRL) to someone who's around frequently. This is to avoid situations where jobs or pipelines are stuck for weeks or months without anyone being able to intervene.
  • Jobs that crash with an error need to be killed manually using kill -9.
  • The log files of jobs that are aborted or crash are not uploaded to the Internet Archive. Please keep the temporary tmp-wpull-*.log.gz files in the pipeline directory, rename them so the filename follows the same format as the JSON file (with extension .log.gz instead of .json), and upload them to FOS manually.
    • You can find the job ID for these files in the second line.
    • Finding the correct filename can be a bit tricky. You can use the viewer or the archivebot-archives repository. Keep in mind that the timestamp in the filename should approximately match the one at the beginning of the log file, though there is usually a difference between the two of at least a few seconds (the log file timestamps being later than the filename timestamp).
    • Be careful with the filename if there were multiple jobs for the same URL (i.e. the same job ID).
    • Here is a public gist on GitHub explaining step by step how to find the proper log file for your crashed or killed job, how to properly rename it, and how to rsync it up to FOS: [[1]]
    • Contact User:JustAnotherArchivist if you need help with this.
  • Due to a bug somewhere deep in the network stack, connections get stuck from time to time. This causes jobs to slow down or halt entirely.
    • As a workaround, you can use the kill-wpull-connections script; it requires pgrep, lsof, and gdb. Depending on the machine configuration (specifically, the value of kernel.yama.ptrace_scope in /proc/sys/kernel/yama/ptrace_scope), it may also require root/sudo privileges.
    • In very rare cases, you may need to use killcx to close the connections.
    • tcp_closer works even when the two methods above fail. It uses the SOCK_DESTROY kernel operation provided by Linux >= 4.5.
  • Also due to a bug suspected to be in the network stack, wpull processes sometimes use a lot of RAM (and CPU). If a process uses more than 300 MB continuously, that's likely the case. kill-wpull-connections seems to "fix" this issue, though it takes a while (minutes, rarely even an hour or more) from running the script until the usage actually drops down.
    • If wpull paused due to high RAM usage try creating a swap file and forcing RAM pages to swap. wpull only checks RAM usage.
dd if=/dev/zero of=swapfile bs=1024 count=1024000
mkswap swapfile
swapon swapfile
perl -e '$tmp = "a" x 999999999'
swapoff swapfile
rm swapfile
  • Make sure that you don't have any search or domain line in /etc/resolv.conf. We've grabbed a number of copies of the websites of OVH and Online.net as a result of such lines and broken http://www/ links... (Cf this issue on GitHub)

Significant incidents

This section lists incidents with ArchiveBot operations that resulted in large or unknown casualties. It does not include individual job crashes, power outages, etc. that had a well-known impact (e.g. causing a job to be incomplete).

  • December 2017: Due to a typo, rsync uploads from one pipeline kept overwriting themselves, which lead to some unknown amount of data loss.
  • December 2018 to January 2019: 6 weeks worth of jobs on a machine, in total around 6.8 TiB in downloads, were lost due to a broken script overwriting files.
  • January 2022: The RAID controller on a machine started dropping the array randomly, which caused file corruption. Three jobs crashed directly due to corruption of the SQLite database (30m0ryds1amy2zp0a2ka3jn9m 33quxn0oovlli18itkn73sa0h 8eq68xsrr9d65ed81dfsd6k8r). Some WARCs were visibly corrupted and became partially unreadable. It's not certain whether there might have been any silent corruption.
  • May 2022[1]: A machine that had been operational since June 2021 had a probable hardware issue. The visible damage of this were three crashes with impossible errors (3s66zwax98l3tqgv7s2j4s6i2 787ob2zl0ode9zeaqn9zwlzut 4uyikz4xdow0jvtxh7izwyvka) and three segfaults (caystmftz9m6netuzuxt4gk7b 7i2a5s799pl6rgfnxtkxpfs5j ef6sdm60zhqc8qn3ekse4aedx), the first of which occurred on 2022-04-01. It can't be ruled out that and is practically impossible to analyse whether the downloaded data may have been corrupted in some way as well.

Installation

Installing the ArchiveBot can be difficult. The Pipeline Install instructions are online, but are tricky.

But there is a Travis.yml automated install script for Travis-cl that is designed to test the ArchiveBot.

Since it's good enough for testing... it's good enough for installation, right? There must be a way to convert it into an installer script.

Disclaimers

  1. Everything is provided on a best-effort basis; nothing is guaranteed to work. (We're volunteers, not a support team.)
  2. We can decide to stop a job or ban a user if a job is deemed unnecessary. (We don't want to run up operator bandwidth bills and waste Internet Archive donations on costs.)
  3. We're not Internet Archive. (We do what we want.)
  4. We're not the Wayback Machine. Specifically, we are not ia_archiver or archive.org_bot. (We don't run crawlers on behalf of other crawlers.)

Occasionally, we had to ban blocks of IP addresses from the channel. If you think a ban does not apply to you but cannot join the #archivebot channel, please join the main #archiveteam channel instead.

Bad behavior

If you are a website operator and you notice ArchiveBot misbehaving, please contact us on #archivebot or #archiveteam on hackint (see top of page for links).

ArchiveBot understands robots.txt (please read the article) but does not match any directives. It uses it for discovering more links such as sitemaps however.

Also, please remember that we are not the Internet Archive.

Trivia

  • One of the ArchiveBot commands, !yahoo, has been named after Yahoo!. This command makes the bot archive the page in a more aggressive manner to speed up the archival process.

Usage, Dashboards, and Completed Job Viewer

Function URL
ArchiveBot documentation, usage guide, manual http://archivebot.rtfd.io/
ArchiveBot traditional dashboard - shows currently active jobs http://archivebot.com/
ArchiveBot newer-style dashboard - shows currently active jobs http://archivebot.com/3
ArchiveBot dashboard - shows pending jobs http://archivebot.com/pending
ArchiveBot dashboard - shows ignores for a specific job http://archivebot.com/ignores/<JOBID>
Adding the query parameter ?compact=true provides a condensed representation for ignore sets.
ArchiveBot Pipeline Monitor Station - shows the status of the deployed crawler pipeline http://archivebot.com/pipelines or https://control.archiveteam.net/
ArchiveBot finished jobs - shows jobs that have finished recently http://archivebot.com/finished
ArchiveBot status - job statistics, especially for programmatic usage http://archivebot.com/status
ArchiveBot Viewer - explore previously archived items https://archive.fart.website/archivebot/viewer/
ChromeBot dashboard - shows pending, running, and finished jobs http://chromebot.6xq.net/

Usage Caveats a.k.a. Things Not To Do With ArchiveBot a.k.a. How To Lose Your Voice

Do not do these things (unless otherwise approved by #archivebot channel ops):

  • attempt to archive file storage mirrors, whether on HTTP or FTP (original file storage sites might be okay...but ask first. Mirroring every Linux ISO mirror site is not a good use of archive resources.)
  • attempt to archive very large sites, including some forums (jobs with up to a few million URLs are usually okay, but it's difficult to predict the total count in advance, and factors like high latency, large responses (especially HTML), and high cookie counts can also cause issues)
  • attempt to archive anything a channel op has told you not to archive
  • continue to archive stuff after a channel op has asked you a question and has not cleared you to continue

Suggested things to focus on archiving with ArchiveBot

  • Company acquisitions and mergers - companies that are being, or have been, acquired or merged
  • ISP Hosting - user homepages on ISPs that have not previously been saved
  • Web presence/content/social media of people that have newly become notable/famous/infamous/featured in the news media. Renewed focus applies if they make important or outrageous public statements that may later be retracted, and also when they pass away as their online records may change/vanish afterwards.

Alternative dashboard clients

There are ways to interact with the ArchiveBot dashboard WebSocket without using the JavaScript frontends:

  • gs-firehose - written in Rust - doesn't build any more.
  • Pipe the WebSocket output to an existing JSON processor
    • Extract the WebSocket JSON stream with one of:
      • websocat 'ws://archivebot.com:4568/stream'
      • uwsc -q 'ws://archivebot.com:4568/stream' | tr -d '\10'
    • Filter the JSON stream using a JSON processor
      • A simple jq command: env site=https://phillyfunguide.com/ jq -r -c 'select(.job_data.url == env.site) | (.response_code | tostring) + " " + .wget_code + " " + .url'
      • A more complex jq command, wrapped in a shell function:
archivebot-monitor () {
	(
		export key="$1"

		export black="$(tput setaf 0)"
		export red="$(tput setaf 1)"
		export green="$(tput setaf 2)"
		export yellow="$(tput setaf 3)"
		export blue="$(tput setaf 4)"
		export magenta="$(tput setaf 5)"
		export cyan="$(tput setaf 6)"
		export white="$(tput setaf 7)"

		export reset="$(tput sgr0)"
		export reset_colour="$(tput op)$(tput oc)"
		export erase_line="$(tput el)"
		export get_position="$(tput u7)"

		websocat 'ws://archivebot.com:4568/stream' |
		jq -r -c '
			select(
				(.job_data.url | contains(env.key)) or
				(.job_data.ident | contains(env.key)) or
				(.job_data.started_by == env.key)
			) |
			if .is_error then
				env.red
			elif .is_warning then
				env.yellow
			elif .response_code >= 300 and .response_code < 400 then
				env.blue
			else
				""
			end
			+
			if .type=="download" then
				 (.response_code | tostring) + " " + .wget_code + " " + .url
			elif .type=="stdout" then
				.message
			else 
				.
			end
			+
			if .is_error or .is_warning or (.response_code >= 300 and .response_code < 400) then
				env.reset
			else
				""
			end
		'
	)
}

Related Links

  • http://archivebot.com is a DNS alias for the ArchiveBot dashboard
  • Chromebot was an IRC bot parallel to ArchiveBot that used Google Chrome and thus was able to archive JavaScript-heavy and pages with endless scrolling. It was available in the #archivebot channel until April 2021.
  • https://twitter.com/ArchiveBot - dormant current Twitter feed of ArchiveBot activity. Tweets may lag live dashboard. Dormant since 2018-04-12.
  • https://twitter.com/ATArchiveBot - former Twitter feed of ArchiveBot activity. Last used 2014-07-28 as @ATArchiveBot was replaced by @ArchiveBot.
  • https://archive.org/details/archivebot - ArchiveTeam ArchiveBot collection at the Internet Archive

More

Like ArchiveBot? Check out our homepage and other projects!

Notes

  1. Pipeline IDs: pipeline:63b112ff83f123cc934166391f3778fe, pipeline:193cb6a171533c7ede3071c43aa84049, pipeline:0622b20d39f5ca69695103725351dbd3, pipeline:2f7d46fc67f0af886b781f082814bea8, pipeline:9e30671b02e58e5f60418368c53fe6cc, and pipeline:7582468775e2c44eed14b5f32784ec90
v · t · e         ArchiveBot
Corporations

Facebook (people· GitHub · Google (people· IBM (people· Microsoft (people· Reddit · Telegram · Twitter · Yahoo · Oldest companies

GLAM

National Archives (Other· National Film Archives (Other· National Galleries (Other· National Libraries (Other· National Museums (Other)

Governments

Algeria · Antarctica · Brazil · Cape Verde · Greenland · Iran · Malta · Micronesia · North Korea · Oman · Philippines · Sahrawi Arab Democratic Republic · Spain · Syria · Sudan · Yemen

History and culture

Languages · Memoria Histórica

People

Archivists · Cancer patients · Travelers · People with physical disabilities

Politics

Elections · Venezuela politics · Yellow Vests - Related: Alternative media (political left)

Sports

World championships in 2019 (2019 FIFA Women's World Cup)

Topics

Artificial Intelligence · Astronomy · Banned stuff · Futurology · Micronations · Rare stuff

Wikis

WikiLeaks · Wikis · Wikidata lists

Other

Datasheets · Educational institutions · Internet campaigns

Tutorial: ArchiveBot/Bot documentation & ArchiveBot/Test