Configuration

The botdir

Every Ibid lives in a directory, the botdir. This holds the configuration file, logs, caches, the SQLite database if you are using it, and plugins you’ve written.

The botdir should be your current directory whenever you run an ibid-related script, so it can find the configuration file.

All non-absolute paths in the ibid configuration are relative to the botdir.

Note

The botdir is added to the front of sys.path, so any python package that you put in the botdir will be available to the bot, and take precedence over other versions of the same package.

The configuration file

Ibid’s configuration is stored in ibid.ini, created when you install Ibid. You can edit it at any time and tell the bot to reread config or edit it online with the config feature.

A simple example ibid.ini:

botname = joebot
logging = logging.ini

[auth]
    methods = password,
    timeout = 300
    permissions = +factoid, +karma, +sendmemo, +recvmemo, +feeds, +publicresponse

[sources]
    [[telnet]]
    [[timer]]
    [[http]]
        url = http://joebot.example.com
    [[smtp]]
    [[pb]]
    [[atrum]]
        channels = "#ibid",
        nick = $botname
        type = irc
        auth = hostmask, nickserv
        server = irc.atrum.org

[plugins]
    cachedir = /tmp/ibid
    [[core]]
        names = $botname, bot, ant
        ignore = ,

[databases]
    ibid = sqlite:///ibid.db

This shows the main sections of the file. It is in configobj format, an ini-variant with nested sections. Whitespace is ignored, all values belong to the most recently defined section.

Lines can be commented out by prefixing them with #.

Top Level Options

botname:

String: The name of the bot. It will respond to this name.

logging:

String: The location of the logging configuration file.

Default: logging.ini

mysql_engine:

String: The engine that MySQL tables will be created in.

Default: InnoDB

Auth

This section is for configuring Ibid’s user-authentication. Permissions that are granted …when authed require users to authenticate themselves to the bot before the permission can be invoked. Some sources have special ways of authenticating users (e.g. the nickserv authentication method on IRC) or guarantee that their users are always authenticated via the imlicit authentication method (e.g. jabber).

methods:

List: Authentication methods that can be used on all sources.

timeout:

Number: Time in seconds that authentication should be cached for before requiring re-authentication.

permissions:

List: Permissions that are granted to everyone. Although they can be overridden for specific users, using the online grant function.

The name of the permission can be prefixed with a + to indicate that this permission is granted without requiring authentication. Or a - to revoke a permission granted to all users of a source.

See the list of permissions.

Sources

Sources are the way that Ibid connects to users. Every IRC/SILC/DC server is it’s own source as are connections to other services.

The configuration parameters that applies to all sources are:

disabled:

Boolean: Every source can be disabled from auto-starting by setting this to True in the source`s configuration.

type:

String: The driver that this source should use. This allows you to have more than one IRC source, for example.

Default: The name of the source. If you specify a type, you are free to name the source anything you want to.

permissions:

List: This lets you grant and revoke permissions to all users on the source. They can be overridden for specific users, using the online grant function.

The name of the permission can be prefixed with a + to indicate that this permission is granted without requiring authentication. Or a - to revoke a permission granted to all users of a source.

See the list of permissions.

IRC Source

Some of the IRC functionality (i.e. NickServ authentication and joining/parting channels) is handled by the irc plugin.

server:

Reqired String: The hostname of the IRC server to connect to.

Ibid does not currently support falling back to alternate servers, so you may want to use a round-robin hostname.

port:

Number: The port to connect to.

Default: 6667

ssl:

Boolean: Use SSL-encrypted connection to the network.

Default: False

nick:

String: The nickname for the bot to use on this network.

Default: The botname

modes:

String: The IRC modes to set. Some servers require bots to set mode B.

Default: nothing

channels:

List: Channels to join on connection to the network.

Warning

You must include the leading #, but unless you quote each channel, Ibid will see the rest of the config line as a comment.

So use quotes around each channel name like this: "#ibid", "#fun"

nickserv_password:

String: The password identifying your bot to NickServ. If set, the bot will respond to authentication requests from NickServ.

Default: Nothing

nickserv_mask:

String: The NickServ’s hostmask on this network. You can set this to ensure that you don’t accidentally give your NickServ password to an imposter, should the network’s services module go down.

You can use glob wildcards, i.e. * and ?.

Default: *

nickserv_nick:

String: The NickServ’s nickname on this network. You probably won’t need to change it.

Default: NickServ

ping_interval:

Number: How many seconds in between each keep-alive PING sent to the server.

Default: 60

pong_timeout:

Number: How long to wait for PONGs before giving up and reconnecting.

Default: 300

Jabber Source

jid:

Required String: The jabber ID that the bot will connect with. (This looks like an e-mail address)

password:

Required String: The password for the supplied JID.

rooms:

List: MUC chatrooms to join on connection.

Default: Nothing

accept_domains:

List: Domains that the bot will accept messages from. If this isn’t set, it’ll accept messages from anyone.

Default: Nothing (i.e. no restriction)

server:

String: The hostname of the server to connect to.

Default: Determined automatically from the jabber ID.

port:

Number: The port to connect to.

Default: 5222 or 5223 if ssl is True

ssl:

Boolean: Use old port 5223-style SSL connection instead of opportunistic TLS on port 5222.

Default: False

nick:

String: The nickname for the bot to use on this server when in MUC chatrooms.

Default: The botname

max_public_message_length:

Number: The bot will limit public (i.e. MUC) messages to this length (in bytes) to avoid flooding the channel with long messages.

Default: 512

Permissions

The following permissions are used in Ibid core:

accounts

Alter user’s accounts.

admin

Grant and revoke permissions. Shut down the bot.

config

Alter configuration values online. (Rewrites the configuration file)

core

Reload Ibid core components.

plugins

Load and unload plugins.

sources

Start and stop sources. Join and leave channels.

Other permissions used in plugins:

chairmeeting

Start meeting minute-taking.

eval

Execute arbitrary Python code.

factoid

Set factoids and modify factoids that you have set yourself.

factoidadmin

Delete / modify factoids that you didn’t set in the first place.

feeds

Configure RSS/Atom feeds

karma

Promote or demote karma for things.

karmaadmin

Delete karma items.

recvmemo

Receive memos.

saydo

Use the bot as a puppet.

sendmemo

Send memos.

summon

Summon a user via another source.