Administration

This document describes how to configure, administer and interact with errbot.

Configuration

There is a split between two types of configuration within errbot. On the one hand there is "setup" information, such as the (chat network) backend to use, storage selection and other settings related to how errbot should run. These settings are all configured through the config.py configuration file as explained in configuration.

The other type of configuration is the "runtime" configuration such as the plugin settings. Plugins can be dynamically configured through chatting with the bot by using the !plugin config <plugin name> command.

There are a few other commands which adjust the runtime configuration, such as the !plugin blacklist <plugin> command to unload and blacklist a specific plugin.

You can view a list of all these commands and their help documentation by using the built-in help function.

The built-in help function

To get a list of all available commands, you can issue:

!help

If you just wish to know more about a specific command you can issue:

!help <command>

Installing plugins

Errbot plugins are typically published to and installed from GitHub. We periodically crawl GitHub for errbot plugin repositories and publish the results for people to browse.

You can have your bot display the same list of repos by issuing:

!repos

Searching can be done by specifying one or more keywords, for example:

!repos search hello

To install a plugin from the list, issue:

!repos install <name of plugin>

You aren't limited to installing public plugins though. You can install plugins from any git repository you have access to, whether public or private, hosted on GitHub, BitBucket or elsewhere. The !repos install command can take any git URI as argument.

If you're unhappy with a plugin and no longer want it, you can always uninstall a plugin again with:

!repos uninstall <plugin>

You will probably also want to update your plugins periodically. This can be done with:

!repos update all

Dependencies

Please pay attention when you install a plugin as it may have additional dependencies. If the plugin contains a requirements.txt file then Errbot will automatically check the requirements listed within and warn you when you are missing any.

Additionally, if you set AUTOINSTALL_DEPS to True in your config.py, Errbot will use pip to install any missing dependencies automatically. If you have installed Errbot in a virtualenv, this will run the equivalent of pip install -r requirements.txt. If no virtualenv is detected, the equivalent of pip install --user -r requirements.txt is used to ensure the package(s) is/are only installed for the user running Err.

Extra plugin directory

Plugins installed via the !repos command are managed by errbot itself and stored inside the BOT_DATA_DIR you set in config.py. If you want to manage your plugins manually for any reason then errbot allows you to load additional plugins from a directory you specify. You can do so by specifying the setting BOT_EXTRA_PLUGIN_DIR in your config.py file. See the config-template.py file for more details.

Disabling plugins

You have a number of options available to you if you need to disable a plugin for any reason. Plugins can be temporarily disabled by using the !plugin deactivate <plugin name> command, which deactivates the plugin until the bot is restarted (or activated again via !plugin activate <plugin name>.

If you want to prevent a plugin from being loaded at all during bot startup, the !plugin blacklist <plugin name> command may be used.

It's also possible to strip errbot down even further by disabling some of its core plugins which are otherwise activated by default. You may for example want to this if you're building a very specialized bot for a specific purpose.

Disabling core plugins can be done by setting the CORE_PLUGINS setting in config.py. For example, setting CORE_PLUGINS = () would disable all of the core plugins which even removes the plugin and repository management commands described above.

Restricting access

Errbot features a number of options to limit and restrict access to commands of your bot. All of these are configured through the config.py file as explained in configuration.

The first of these is BOT_ADMINS, which sets up the administrators for your bot. Some commands are hardcoded to be admin-only so the people listed here will be given access to those commands (the users listed here will also receive warning messages generated by the warn_admins() plugin function).

More advanced access controls can be set up using the ACCESS_CONTROLS and ACCESS_CONTROLS_DEFAULT options which allow you to set up sophisticated rules. The example config.py file contains more information about the format of these options.

Note

Different backends have different formats to identify users. Refer to the backend-specific notes at the end of the configuration chapter to see which format you should use.

Command filters

If our built-in access controls don't fit your needs, you can always create your own easily using command filters. Command filters are functions which are called automatically by errbot whenever a user executes a command. They allow the command to be allowed, blocked or even modified based on logic you implement yourself. In fact, the restrictions enforced by BOT_ADMINS and ACCESS_CONTROLS above are implemented using a command filter themselves so they can serve as a good example (be sure to view the module source).

You can add command filters to your bot by including them as part of any regular errbot plugin, it will find and register them automatically when your plugin is loaded. Any method in your plugin which is decorated by cmdfilter() will then act as a command filter.