Configuration

Ultros uses YAML files for configuration, plugin information and data storage. We decided to use YAML as it's easy to edit and to read, but also provides direct mappings to Python types, which makes working with it in code much easier.

There are some caveats that most people fall into when editing YAML files, such as the following.

• Tabbing - Never use a tab character for you indents, always use spaces only. If your text editor defaults to using tabs, avoid using the tab key at all or reconfigure the editor. Not doing this will cause lots of errors!
• Quoting - If you need to use a *, ! or # symbol, it's always best to use "double quotes" around the entire value. * and ! are YAML literals, and # denotes a comment, so not quoting them will cause things to break!

The configuration files

All configuration files are stored in the config/ folder. When you first download and set up Ultros, none of these files will be filled out - Example files will exist, but you'll need to copy them and fill them out yourself. We've done this to help out people who use git - If the configuration files are changed, git will modify the example files but not your edited ones. This means that git will never overwrite your configurations, and will never cause conflicts just because you filled out your config files.

There are three "categories" of configuration file - Core, Plugin and Protocol.

Core configuration

The core configuration deals with the Ultros core - no plugin- or protocol-specific configuration will be found here. This is the configuration you should start with when you set up Ultros for the first time.

Ultros' main configuration can be found in the config/settings.yml.example file. Copy this to config/settings.yml and modify it as you require. The options and default values are as follows..

• protocols irc - This is a list of protocols that you'd like to use. Each protocol must have a configuration file with the same name in the config/protocols folder.
• plugins Auth, Bridge, Web - A list of plain-English names, each corresponding with a plugin, in the order you want them loaded. If a plugin depends on another plugin, it will wait for the other plugins to load before attempting to load itself. If a required plugin isn't available, then any plugin that depends on it won't load either.
• reconnections - This section is for specifying what the bot will do when it loses connection or fails to connect.
  • delay 10 - How long (in seconds) to wait between connection attempts
  • attempts 5 - How many times to attempt to reconnect before giving up
  • on-drop yes - Whether to reconnect if we lose connection; should either be yes or no
  • on-failure yes - Whether to try again if a connection attempt fails; should either be yes or no
  • reset-on-success yes - Whether to reset connection attempt counters if a connection succeeds; should either be yes or no

Protocol-specific configuration

Each protocol you use will have its own, rather specific configuration file. You can find details on all of these under the protocols section at the table of contents. There is one section that every protocol config will have:

• main - This section contains generic information used by the bot
  • protocol-type irc - The type of protocol this protocol instance should be. This must exist in system/protocols/
    • This method of configuration allows you to have multiple instances of the same type of protocol - for example, you could have Ultros provide IRC services on multiple networks, and even bridge between them!
  • can-flood false - Whether or not the bot (and its plugins) may be liberal with how many messages they send. For example, if you're running this bot on your own IRC network, bypassing rate-limiting and fakelag, then you may prefer the bot to be able to spew out a bit more information, or in a nicer format over multiple messages. Additionally, some protocol types do not have a limit on how many messages you can send.

Plugin-specific configuration

Some plugins will also require a configuration, though this doesn't apply to every plugin. You can find more information on this in the plugins section.

Previous (Setting up) | Home | Next (Plugins)