This document describes how to configure, administer and interact with errbot.
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:
If you just wish to know more about a specific command you can issue:
You can have your bot display the same list of repos by issuing:
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
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
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.
config-template.py file for more details.
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.
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.
config.py file contains more information about the format of these options.
If you don’t like encoding access controls into the config file, a member of the errbot community has also created a dynamic ACL module which can be administered through chat commands instead.
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.
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.
In some cases, it may be necessary to run other filters before the CommandNotFoundFilter. Since the CommandNotFoundFilter is part of the core plugin list loaded by errbot, it can not be directly overridden from another plugin. Instead, to prevent CommandNotFoundFilter from being called before other filters, exclude the CommandNotFoundFilter plugin in the CORE_PLUGINS setting in config.py and explicitly call the CommandNotFoundFilter function from the overriding filter.