wm-bot

From Meta, a Wikimedia project coordination wiki
(Redirected from WM-Bot)
Jump to: navigation, search
wm-bot
WM-Bot being happy

wm-bot is an IRC bot that is being used in several Wikimedia IRC channels, particularly developer channels. This page documents the bot.

The bot is designed to have separate configuration for each channel, so that anyone can get it to their channel having own database. Bot is maintained by user who bring it to channel, so that anyone can configure as they want.

Contents

Support[edit]

In case you need any help with this bot, please contact one of its operators:

Or - fill in a ticket: https://bugzilla.wikimedia.org/enter_bug.cgi?product=Tools&component=WM-Bot

Getting bot to the channel[edit]

In case you are a wikimedia user with wikimedia cloak and you want to use this bot in a wikimedia related channel, you can just join #wm-botconnect, where you can type:

@add #nameofchannelyouwant

This make the bot join your channel and give you admin permissions for that channel.

However there may be some exceptional situations:

Bot will not join[edit]

Bot is probably banned or stuck in some way. For example if you invite a bot and then use freenode's /remove command (which isn't compliant with irc standards anyway so it makes sense the bot doesn't know it) the bot will still think it's in the channel. You can try to make it part the channel from #wm-bot by calling @part #channel

Bot will not give you admin rights[edit]

If the bot was in the channel previously and removed using @part command, it will still have the same ACL so that you won't get admin rights. Instead, the same people as before will have it. You can always contact some of bot operators to help you in this situation.

User access[edit]

Admin[edit]

Admin has access to all commands, the user who bring the bot to channel is always made admin unless the bot was previously parted (in that case the previous access list is preserved). This user level can be granted to anyone else using the @trustadd command (see below).

Trusted[edit]

Trusted users have access to most of commands

If you are a trusted or admin you can use command @trustadd to insert more people to access list

User list[edit]

User list can be controlled using following commands

@trusted[edit]

Display list of users for current channel

@trustadd regex level[edit]

Add regex to defined level, level being one of admin, trusted. Example:

@trustadd .*@wikipedia/John trusted

@trustdel regex[edit]

Delete regex, you can only delete trusted users

Recent changes feed for wmf wikis[edit]

wm-bot supports a relay of recent changes feed directly to any channel, below is a list of commands which you can use in order to setup the bot

Wiki codes

  • language_wikipedia
    • example: fr_wikipedia
  • meta_wiki
  • commons
  • wikidata
  • outreach_wiki
  • wikimania2012
  • wikimania2013
  • incubator_wiki

@recentchanges-off[edit]

Needs admin rights, this command has no parameters

Disables a feed of recent changes of wikimedia wikis in current channel. The database of pages you configured, will be preserved.

@recentchanges-on[edit]

Needs admin rights, this command has no parameters

Enables a feed of recent changes in current channel, you can select certain pages on selected wikis to be watched.

@recentchanges+ wiki[edit]

Require admin rights, this command has 1 parameter and is applied global-wise

Request bot to watch a given wiki (example fr_wikipedia), this is a global setting for all channels and is needed only if the required wiki is not already being watched. This option exist so that server resources can be saved by watching only certain wikis which users are interested in, instead of all wmf wikis, including these that nobody needs to see a feed of. However, the bot is capable of watching any WMF wiki. In case that some wiki isn't in this list, it is necessary to insert it in this list, otherwise you won't be able to use feed for that project (this applies mostly for smaller wiki's because large one's are likely already watched). The bot is only watching projects for which the feed was requested.

Example: @recentchanges+ en_wikipedia

@recentchanges- wiki[edit]

Require admin rights

See @recentchanges+ for explanation. Remove a wiki from a feed. Before you do this, make sure that no one (in all channels where bot is being used) is currently watching the feed. This command should be used only for closed projects and it's basically never needed to execute it. (It exists merely for performance optimization).

Example: @recentchanges- en_wikipedia

@RC- wiki page[edit]

Require trusted rights, this command has 1 parameter

Removes a page from list of recent changes, affects only current channel.

Example: @RC- en_wikipedia User:Test_page

@RC+ wiki page[edit]

Needs trusted rights

Insert a page to a feed, example @RC+ de_wikipedia User:Test_page would make it report changes to de.wikipedia.org/wiki/User:Test_page directly to channel.

Additionally, @RC+ de_wikipedia User:Test_page/* would make it report changes to any subpages (but not the primary page) of de.wikipedia.org/wiki/User:Test_page directly to channel. Note that the * wildcard can only be used on the end of the string.

Infobot[edit]

Infobot can be controlled by trusted users using following commands:

<@petan> !key is some data
<wm-bot> Key was added!
<@petan> !key
<wm-bot> some data
<@petan> !key del
<wm-bot> Deleted key
<@petan> !key is this is $1
<wm-bot> Key was added!
<@petan> !key 1
<wm-bot> this is 1
<@petan> !google is https://www.google.com/search?q=$url_encoded_*
<wm-bot> Key was added
<@petan> !google some special symbols % 6 7#%#$%@
<wm-bot> https://www.google.com/search?q=some+special+symbols+%#25+6+7%#23%#25%#23%#24%#25%#40
<@petan> !google some special symbols % 6 7#%#$%@ | addshore
<wm-bot> addshore: https://www.google.com/search?q=some+special+symbols+%#25+6+7%#23%#25%#23%#24%#25%#40

You can create an alias by typing !key alias key2 so that !key would display value of key2.

The aliases have lower priority than keys so you can overwrite an alias with key (it's possible to create both)

Command !key unalias removes it

Variable Response
$1 - $9 Parameters one at a time
$* All parameters in one shot
$url_encoded_1 - $url_encoded_9 URL encoded parameters one at a time
$url_encoded_* All parameters in one shot and URL encoded
$wiki_encoded_1 - $wiki_encoded_9 Wiki encoded parameters one at a time (same as {{URLENCODE: $1 - $9|WIKI}})
$wiki_encoded_* All parameters in one shot and wiki encoded (same as {{URLENCODE: $1 - $9|WIKI}})

@regsearch <regex>[edit]

Search regular expression in all values

@search <word>[edit]

Search key names and values for given word

Private message commands[edit]

@notify[edit]

This command let you know when specified user becomes active or online. You can use this even on users who aren't registered on server or even on users who are online, but not active currently.

Example: @notify hashar

@seen[edit]

@seen user

Tell you when user was last seen

All labs commands[edit]

See help for @labs-*

Channel commands[edit]

@add[edit]

Require admin rights

Insert a bot to another channel (@add #example)

@info[edit]

Doesn't require any permission

Link to html dump of database and channel info (no parameters)

Statistics[edit]

@statistics-on[edit]

Create a table of channel use statistics to be include in the html dump accessible with @info

@statistics-off[edit]

Stop measuring channel use statistics to be include in the html dump accessible with @info

(off by default)

@notify[edit]

For example if I was waiting for hashar, I could just send a private message

@notify hashar

to wm-bot and he send me a private message when hashar appear somewhere, or talk and such. It works even on users who are already online but idle (so it ping you when the user stop being idle).

Infobot[edit]

@infobot-on[edit]

Require admin rights

Turn on infobot for current channel

@infobot-off[edit]

Require admin rights

Disable infobot on current channel

@infobot-link[edit]

Require admin rights

Create a link to infobot db of different channel, this allows you to share infobot with other channels. If you link channel A to channel B's db, the local db of channel A will be no longer accessible, but will not be deleted. If you unlink the channel db, local db will be accessible again.

Example: @infobot-link #mediawiki will make a bot use db of #mediawiki, instead of local db.

Syntax: @infobot-link #channel

@infobot-share-on[edit]

Require admin right

Enable shared infobot, this is necessary to execute on the channel you want to share the db of with other channels.

@infobot-share-trust-[edit]

Require admin right

Remove a channel from trusted relation. This channel will no longer have access to shared db.

@infobot-share-trust+[edit]

Require admin right

Insert a channel to db, that means this channel will be allowed to access the shared db for reading and writing.

example: @infobot-share-trust+ #test

this allows #test to link to infobot db of channel where you triggered this command and to read and write into it, based on own access list.

@infobot-share-off[edit]

Require admin right

Disable shared infobot

@infobot-ignore+[edit]

Require trusted right

Insert a new string to ignore list of infobot, for example

@infobot-ignore+ seen

makes the bot ignore any commands !seen in a channel

@infobot-ignore-[edit]

Require trusted right

This command remove an ignored key from list, syntax: @infobot-ignore- <item>

@infobot-detail[edit]

Doesn't require any rights

Syntax: @infobot-detail <key>

Display information about key

@infobot-set-raw[edit]

Require trusted right

Make the key "raw" that means, all special words, $1, $2... will be displayed as they are, instead of converting to specific values, the | symbol is ignored in such a key. Only special word that is respected is $url_encoded_* and $*

@infobot-unset-raw[edit]

Require trusted right

Syntax: @infobot-unset-raw <key>

This command undo the @infobot-set-raw

@infobot-recovery[edit]

Require admin right

example: @infobot-recovery previousdb

Recovers a snapshot - be careful as this operation removes the current database without asking, it's useful to create a snapshot before recovering some other so that you can restore the current db in case something go wrong.

@infobot-snapshot[edit]

Require admin right

example: @infobot-snapshot previousdb

Creates a snapshot of current db, it is a bit clone of a database that can be restored anytime to its current status.

@infobot-snapshot-rm[edit]

Require admin right

example: @infobot-snapshot-rm previousdb

Removes a snapshot

@infobot-snapshot-ls[edit]

List all snapshots for current channel

Seen[edit]

@seenrx[edit]

Requires trusted right

Tell you when user matching regex was last seen

Example: @seenrx ^[Pp]etan$

@seen[edit]

Tell you when the specified user was last seen, case insensitive and doesn't support wild cards.

Example: @seen petan

@seen-on[edit]

Require admin right

Turn on the seen for the current channel

@seen-off[edit]

Require admin right

Turn off the seen for the current channel

rss feed[edit]

@rss+[edit]

Require trusted right

Insert a new item, syntax: @rss+ <name> <url>

example: @rss+ bbc http://bbc.co.uk/rss.xml

@rss-[edit]

Require trusted right

Remove an item

syntax: @rss- <name>

@rss-on[edit]

Require admin right

Enable rss feed

@rss-off[edit]

Require admin right

Disable rss feed, doesn't remove the DB

@rss-setstyle[edit]

Require admin right

Direct method of configuring rss feeds also obtainable by using @configure style-rss

Please note, there must be no spaces (wrong: key = value bla bla correct: key=value bla bla)

List of variables for style-rss:

  • $bugzilla_assignee
  • $bugzilla_component
  • $bugzilla_creation
  • $bugzilla_priority
  • $bugzilla_product
  • $bugzilla_reporter
  • $bugzilla_resolution
  • $bugzilla_severity

Examples:

@rss-setstyle Bugzilla [bugzilla] $bugzilla_resolution $title ($bugzilla_severity $bugzilla_priority assignee: $bugzilla_assignee created by: $author) - $link
@rss-setstyle gerrit [gerrit $name] $title - Diff: $link

Channel logs[edit]

@logon[edit]

Require admin right

Start to generate public logs for current channel

By default this feature is disabled, no channels the bot is invited to are logged, unless you enable it

@logoff[edit]

Require admin rights

Disable logs

Configuration and help[edit]

@help[edit]

Display help

You can also type @help <command> to display 1 line help for the command

@language[edit]

Require admin rights

Change the language for the channel - this will change the language bot will speak for all users in the channel

Example: @language en

Languages:

  • cs
  • de
  • en
  • zh
  • ko
  • pt

@configure[edit]

Requires admin rights

Change various keys

Key Type What is it
infobot-auto-complete bool enable autocompletion so that typing !k would display value of !key should there be no other key starting with identical char (default is false)
infobot-help bool Provide a help for infobot in case you type a nonexistent key
infobot-case bool whether keys are case sensitive (default is true) - that allows you to create !key as well as !Key turning it off (by setting false) will hide the keys that were created later
infobot-sorted bool sort the infobot in html
logs-no-write-data bool disable writing of logs to storage, this is obsolete feature and shouldn't be ever used
suppress-warnings bool doesn't send any errors to channel
ignore-unknown bool doesn't parse input from users who aren't in trust list, that disable all bot features from users who aren't trusted
respond-message bool send a message to user who attempt to speak to bot
infobot-trim-white-space-in-name bool remove white space
respond-wait int delay to wait between responses from response message
recent-changes-template string
This is the message template for rc item
variables: contains
$wiki Name of the wiki
$url The URL to the index.php for the language the edit was found on. (doesn't work for "all" wikis bugzilla:49874#c3)
$username Username of the editor
$encoded_username URL encoded username
$encoded_wiki_username Same as $encoded_username only replaces spaces with _ instead of + and preserves :/() characters
$link revision ID of the edit
$page verbose page name
$encoded_page URL encoded page name
$encoded_wiki_page Same as $encoded_page except replaces spaces with _ instead of + and preserves :/() characters
$summary Edit summary
$fullurl Returns $url?title=$encoded_wiki_page for new pages
Returns $url?diff=$link for edited pages
$action returns created or modified depending on if it is a new page or not
$flags marked as minor or bot edit
null <default value>: Change on $wiki a page $page was modified, changed by $username, link: $url?diff=$link edit: $summary
style-rss string message template for rss item (variables: $name $author $title $link $description)
default-link-wiki string The default wiki to use as the base for links created using @link or @linkie-on (default: en") (complete list of known and acceptable wikis can be found on GitHub)

The current value of the content of a key can be retrieved like:

@configure recent-changes-template

Note: Returns Value of recent-changes-template is: <default value> if not set.

Examples:

@configure ignore-unknown=true

Please note, there must be no spaces (wrong: key = value bla bla correct: key=value bla bla)

List of variables for style-rss:

  • $bugzilla_assignee
  • $bugzilla_component
  • $bugzilla_creation
  • $bugzilla_priority
  • $bugzilla_product
  • $bugzilla_reporter
  • $bugzilla_resolution
  • $bugzilla_severity

Examples:

@rss-setstyle Bugzilla [bugzilla] $bugzilla_resolution $title ($bugzilla_severity $bugzilla_priority assignee: $bugzilla_assignee created by: $author) - $link
@rss-setstyle gerrit [gerrit $name] $title - Diff: $link

@part[edit]

Require admin rights

Part current channel preserving the configuration and database

@whoami[edit]

Display your user level

@suppress-on[edit]

Require admin rights

Disable output to a channel

@suppress-off[edit]

Require admin rights

Enable output to a channel

@drop[edit]

Require admin rights

Leave channel and remove the configuration, logs and db. The data can't be recovered once removed, so please don't use this command in case you want to keep logs.

Linkie (wiki link)[edit]

@link[edit]

Turns the last line of wikilinks in the channel to actual links using the default wiki specified in the default-link-wiki parameter of @configure.

@linkie-on[edit]

Requires admin rights

Turns on the automatic linker in the channel using the default wiki specified in the default-link-wiki parameter of @configure.

When linker is on, every wiki link similar to [[page]] will be translated to url

@linkie-off[edit]

Requires admin rights

Turns off the automatic linker in the channel.

Labs[edit]

@labs-resolve[edit]

Resolve instance id / name / fqdn

@labs-info[edit]

Provide info for instance

@labs-project-users[edit]

List users in a project

@labs-project-instances[edit]

List instances in project

@labs-user[edit]

Display info about user

Relay of messages from scripts and other tools[edit]

Useful if you need to send a message to any irc channel from wikimedia labs

@relay-on[edit]

Requires admin rights

This command is useful if you need to send a message to any irc channel from wikimedia labs, but you don't want to create a bot for that. If you enable relay, anyone on labs will be able to send a TCP message to wm-bot:64834 in format of:

#channel message is here

And a bot will relay it to your channel

Simple shell script to relay "hello world" to channel #wm-bot

#!/bin/sh

echo "#wm-bot hello world" | nc wm-bot.eqiad.wmflabs 64834 -w0

@relay-off[edit]

Requires admin rights

Turn off a relay

@token-on[edit]

Requires admin rights

Generate a token for your channel which needs to be provided in a message in order to relay it, example:

#channel TOKEN message is here

@token-off[edit]

Requires admin rights

Disable token

Operator tools - channel maintenance tool[edit]

@optools-on[edit]

Requires admin

Enable optools - that let you execute @kb @jb and @kick in a channel, these commands require channel to be registered and bot needs to have +o in chanserv

@optools-off[edit]

Requires admin

Disable optools

@optools-permanent-on[edit]

Requires admin

Bot will not deop itself after op action

@optools-permanent-off[edit]

Requires admin

Bot will deop itself after op action

@kb[edit]

Requires admin

@kb user <reason>

Kickban a user from the channel

@jb[edit]

Requires admin

@jb user

Set a redirect ban. This is supposed to be used for people who join flood channel because of temporary connection issues

@kq[edit]

Requires admin

@kq user

Quiet a user

@unkb[edit]

Requires admin

@unkb user

Removes a ban of user -- bugzilla:53600 "@unkb can't unban user kicked from channel"

@unq[edit]

Requires admin

@unq user

Removes a quiet from user

@kick[edit]

Requires admin

@kick user <reason>

Kick user from a channel

System admin[edit]

These commands are not useful for regular users

@restart[edit]

Require root rights

Restart the process of bot

@reload[edit]

Require admin rights

Reload configuration of the channel

@system-rm[edit]

Requires root

This is a low-level system command that tell a bot to unload specific module from system

@system-lm[edit]

Requires root

Load a module to system

Files and logs[edit]

Data: http://bots.wmflabs.org/~wm-bot/db - database of infobot

Channel logs: http://bots.wmflabs.org/~wm-bot/logs/ (raw), http://bots.wmflabs.org/~wm-bot/html/ (lightly-formatted HTML)

Languages[edit]

The bot will talk any language you want in specific channel. All you need to do, is ask admin of bot to say @language <code>

You can translate the bot to your language by creating a subpage, example Wm-bot/ru for russian. Then just translate the default english file.

Supported languages are:


For developers[edit]

Source[edit]

Source code is in git type

git clone https://github.com/benapetr/wikimedia-bot.git

to download it

Compiling[edit]

In order to compile the bot, you need a C# compiler like gcs or microsoft's csc. Visual Studio or MonoDevelop are the recommended IDE's: they allow you to just open the project file and hit make.

This is a most simple way to build stuff on debian:

# after you checkout the bot
cd wikimedia-bot
make

Following structure must exist for bot to work where $HOME is a folder where you install a bot

$HOME/wmib.exe $HOME/configuration/wmib $HOME/modules

you start the bot always from $HOME

Setting up[edit]

Installation[edit]

  • When you build the bot for first time, there should be a binary either in bin/Debug or bin/Release (depends if you directly invoke xbuild or use the make script). Pick one of these binaries.
  • Create a folder and optionally a unix user which you will use to run the wm-bot under as a service
  • Copy the binary into root of that path, let's call it $wmibhome
  • Create folder $wmibhome/configuration
  • Create file $wmibhome/configuration/wmib.conf and put there following text
// This is a username for a bot
username=wm-bot;
// This password is optional and bot will use it to auth with nickserv in case you provide it
password=blabla;
// This is a root url that will be used in queries like @info
web=http://bots.wmflabs.org/~wm-bot/;
// Whether bot uses a bouncer or not
serverIO=false;
// Debug channel
debug=#wm-bot;
// Irc server bot will connect to
network=holmes.freenode.net;
// This is css style that will be used for dynamically created html pages
style_html_file=http://bots.wmflabs.org/~wm-bot/wmib/style.css;
// This is interval that bot will send messages to network server to in milliseconds, lower the interval is
// faster the bot will send messages to server. Low interval may result in k-line on some networks.
interval=800;
// Nickname for primary instance
nick=wm-bot;
// Optional mysql username
mysql_user=jimmy_wales;
// Optional mysql host
mysql_host=bots-labs;
// Optional password
mysql_pw=I_own_wikipedia;
// Name of database to store items to (by default bot doesn't use mysql, but some extensions might want to)
mysql_db=wmib;
mysql_port=3306;
  • chown this file to wm-bot user and change chmod to 600, this file is dynamically updated by a bot, never write to it when bot is running
  • create database of bot administrators in $wmibhome/configuration/admins example bellow
.*@wikimedia/Petrb|root|this is a secret password|root

These users will be globally recognized in any channel, first column is regular expression to match irc hostname, second is user level, third is password for system console, fourth is username for system console

  • now you can launch the bot (mono wmib.exe)

Restarting the bot[edit]

See admin guide at wikitech:wm-bot

External links[edit]