view release on metacpan or  search on metacpan

doc/config/index.rst  view on Meta::CPAN

a ``~/.pgpass`` file for the user under which your |RB| process will run (in
which case you should omit the ``pass`` setting shown below). The choice is
yours, though you should always ensure that other users on the system are not
able to read any file in which the password is stored.

Example
-------

.. code-block:: aconf

    <database>
        <primary>
            driver      Pg
            host        localhost
            port        5432
            database    robobot
            user        yourdbuser
            pass        abc123nobodycancrackme
            schemas     robobot
            schemas     public
        </primary>
    </database>

Please note that, at this time, the two ``schemas`` lines are required and
should not be set to anything else. Future releases of |RB| may hide this
requirement behind the scenes to reduce the possibility of misconfiguration.

Networks
========

Each network to which you want your instance of |RB| to connect will need its
own ``<network NAME>`` configuration section. The contents of these sections
will depend largely on the protocol being used. Each supported protocol is
explained below under :ref:`config-network-protocols`.

In addition to configuring the details of each network's protocol, you may also
disable individual plugins on a per-network basis. This is useful for, among
other things, reducing redundant features. For example, both Slack and
Mattermost automatically fetch website snippets when users mention URLs, so
there's no need to have |RB| doing the same and doubling up the page titles
and such. Configuring these plugin blacklists is shown in
:ref:`config-network-plugin-disable`.

Common Settings
---------------

Every network configuration includes three common elements:

Network Name
    You must provide a unique name to each network you configure. These names
    may contain letters, numbers, and dashes. They are not case-sensitive. The
    network name is part of the section opening tag.

Network Type
    It is required to specify the type of network being configured, using the
    ``type`` setting. Valid values are: ``irc``, ``slack``, and ``mattermost``.

Enabled
    You may include network configuration sections for networks to which you
    don't currently want |RB| to connect. By setting the value of ``enabled``
    to ``0``, |RB| will load and validate the network's configuration, but will
    not actually connect to the service.

The base minimum settings would result in a configuration section like this:

.. code-block:: aconf

    <network my-network-name>
        type    irc
        enabled 0
    </network>

.. _config-network-protocols:

Protocol Configurations
-----------------------

IRC
~~~

IRC networks will connect to any local or remote IRC service over TCP, and
support SSL encryption at your discretion. At a bare minimum, you must supply
a ``host``, a ``port`` and at least one ``channel``. Technically, channels are
optional, but without them nobody will be able to communicate with the bot
instance except by ``/msg`` commands, and some plugins require a real channel
context. Channel names should omit the ``#`` character.

In addition, if you wish to use an encrypted connection you may set ``ssl`` to
a true value.

An example IRC network configuration with SSL and two channels would look like:

.. code-block:: aconf

    <network my-irc-network>
        type    irc
        enabled 1

        host    irc.mydomain.tld
        port    6689
        ssl     1

        channel awesomechat
        channel boringchat
    </network>

Slack
~~~~~

|Slack| network configuration is a bit simpler than IRC, as you need only
specify the username and |Slack| integration token used for your |Slack| team.
Channels will be joined automatically, and users in your team may invite your
bot to channels at will.

To obtain an appropriate token for your |Slack| team, go to *Apps &
integrations* then *Manage* followed by *Custom Integrations*. In the *Bots*
section, click on *Add Configuration* and choose a username for your |RB|
instance. Your new bot configuration will have an API Token generated for it.
While you're at that screen, you may change things like the icon, description,
and display name.