system-config/doc/source/irc.rst

:title: IRC Services

.. _irc:

..

IRC Services
############

The OpenDev team runs a number of IRC bots that are active on
OpenDev and OpenStack related channels.

At a Glance
===========

:Hosts:
  * https://eavesdrop01.opendev.org/irclogs/
  * https://meetings.opendev.org/
  * https://ptg.opendev.org/
  * https://wiki.openstack.org/wiki/Infrastructure_Status
:Configuration:
  * :config:`gerritbot/channels.yaml`
  * :config:`accessbot/channels.yaml`
:Projects:
  * https://github.com/ProgVal/Limnoria
  * https://wiki.debian.org/MeetBot
  * https://opendev.org/opendev/gerritbot
  * https://opendev.org/opendev/statusbot
  * https://opendev.org/openstack/ptgbot
:Bugs:
  * https://storyboard.openstack.org/#!/project/748

Channel Requirements
====================

In general, discussion for OpenStack projects is preferred in #openstack-dev,
but there are many reasons why a team would like to have their own channel.

Access
------

`Register the channel with ChanServ
<https://www.oftc.net/Services/>`_ and give the
infrastructure team account master access to the channel with::

  /msg chanserv register #channel
  /msg chanserv access #channel add opendevaccess master

This is good practice project-wide to make sure we keep channels under
control and is a requirement if you want any of the project bots in
your channel.

Join #opendev and ask for help if you have any trouble with any of these
commands.

NOTE: Channel admin should issue the access commands above BEFORE adding
channel to gerritbot and accessbot, otherwise Zuul will fail tests.

Service overview
================

The OpenDev team runs Limnoria `Limnoria
<https://github.com/ProgVal/Limnoria>`__ on `eavesdrop01.opendev.org`
to provide channel and meeting logs.

Channel logs are provided by Limnoria's inbuilt channel logger.
Meeting logging is provided by the `Meetbot plugin
<https://opendev.org/opendev/meetbot>`__.

Running Meetings
================

Starting a Meeting
------------------

To start a meeting, use the command ``#startmeeting`` followed by the
meeting name.  For instance, if you are having a meeting of the
marketing committee use the command ``#startmeeting Marketing
Committee``.  This will cause logs to automatically be placed in a
meeting-specific directory on the eavesdrop log server.  The output
directory will be automatically lowercased and non-alphanumeric
characters translated to '_', so the above example will record to the
``marketing_committee`` directory.  Be sure to use a consistent
meeting name to ensure logs are recorded to the same location.

This feature is specific to the OpenDev Meetbot fork.

Voting
------

The OpenDev Meetbot fork adds simple voting features. After
a meeting has been started a meeting chair can begin a voting block with the
``#startvote`` command. The command takes two arguments, a question posed to
voters (ending with a ``?``), and the valid voting options. If the second
argument is missing the default options are "Yes" and "No". For example:

``#startvote Should we vote now? Yes, No, Maybe``

Meeting participants vote using the ``#vote`` command. This command takes a
single argument, which should be one of the options listed for voting by the
``#startvote`` command. For example:

``#vote Yes``

Note that you can vote multiple times, but only your last vote will count.

One can check the current vote tallies using the ``#showvote`` command, which
takes no arguments. This will list the number of votes and voters for each item
that has votes.

When the meeting chair(s) are ready to stop the voting process they can issue
the ``#endvote`` command, which takes no arguments. Doing so will report the
voting results and log these results in the meeting minutes.

A somewhat contrived voting example:

::

  foo     | #startvote Should we vote now? Yes, No, Maybe
  meetbot | Begin voting on: Should we vote now? Valid vote options are Yes, No, Maybe.
  meetbot | Vote using '#vote OPTION'. Only your last vote counts.
  foo     | #vote Yes
  bar     | #vote Absolutely
  meetbot | bar: Absolutely is not a valid option. Valid options are Yes, No, Maybe.
  bar     | #vote Yes
  bar     | #showvote
  meetbot | Yes (2): foo, bar
  foo     | #vote No
  foo     | #showvote
  meetbot | Yes (1): bar
  meetbot | No (1): foo
  foo     | #endvote
  meetbot | Voted on "Should we vote now?" Results are
  meetbot | Yes (1): bar
  meetbot | No (1): foo

Logging
-------

Meetings are automatically logged and published at
https://meetings.opendev.org/meetings/

The bot also has the ability to sit in a channel for the sole purpose
of logging channel activity, not just meetings. Standard channel logs
are sent to http://meetings.opendev.org/irclogs/

The configuration for specific channel logging can be found in ,
:git_file:`inventory/service/group_vars/eavesdrop.yaml`.

.. _statusbot:

Statusbot
=========

Statusbot is used to distribute urgent information from the
Infrastructure team to OpenDev and OpenStack channels.  It updates the
`Infrastructure Status wiki page
<https://wiki.openstack.org/wiki/Infrastructure_Status>`_.

It supports the following public message commands when issued by
authenticated and whitelisted users from the channels the bot is
listening to, including #opendev:

#status log MESSAGE
  Log a message to the wiki page.

#status notice MESSAGE
  Broadcast a message to all OpenDev and OpenStack channels, and
  log to the wiki page.

#status alert MESSAGE
  Broadcast a message to all OpenDev and OpenStack channels and
  change their
  topics, log to the wiki page, and set an alert box on the wiki
  page (eventually include this alert box on status.openstack.org
  pages).

#status ok [MESSAGE]
  Remove alert box and restore channel topics, optionally announcing
  and logging an "okay" message.

It supports the following commands when issued by any IRC user from
the channels the bot is listening to:

#success [MESSAGE]
  Log a message of success to the "Successes" wiki page. This is meant
  as a collection mechanism for little celebration of small successes
  in OpenStack development.

A channel can be added to statusbot by editing the public Hiera data
file, :git_file:`hiera/common.yaml`.

The wiki password for the StatusBot account can be (re)set using the
`ChangePassword.php <https://www.mediawiki.org/wiki/Manual:ChangePassword.php>`_
maintenance script.

.. _gerritbot:

Gerritbot
=========

Gerritbot watches the Gerrit event stream (using the "stream-events"
Gerrit command) and announces events (such as patchset-created, or
change-merged) to relevant IRC channels.

Gerritbot's configuration is in :config:`gerritbot/channels.yaml`

Teams can add their channel and go through the standard code review process to
get the bot added to their channel. The configuration is organized by channel,
with each project that a channel is interested in listed under the channel.

.. _accessbot:

Accessbot
=========

Accessbot defines access that should apply to all channels. Teams can add new
channels to accessbot/channels.yaml and optionally set additional channel
admins or ops, or specific mode overrides.

For typical day-to-day actions like updating channel topics or banning
disruptive users, volunteer ops are sufficient. If the team wishes to retain
deeper control over channel settings which aren't handled via accessbot, then
having some volunteer admins can occasionally be useful. In either case, our
global volunteers are also happy to assist with any of these activities, so
feel free to ask for help in the #opendev channel.

Accessbot's configuration is in :config:`accessbot/channels.yaml`

Example::

  - name: foo
    mode: +bar
    admins:
    - baz
    ops:
    - xyzzy
    - plugh

PTG Bot
=======

Bot that `Project Teams Gathering <https://www.openstack.org/ptg>`_
room moderators use to surface what's currently happening at the
event. Usage instructions are provided in its `README.rst file
<https://opendev.org/openstack/ptgbot/src/branch/master/README.rst>`_.
Its container serves content from an embedded HTTPd which we proxy on
eavesdrop01.opendev.org locally with a https://ptg.opendev.org/ Apache
vhost.

Code for the PTG bot lives in the `openstack/ptgbot respository
<https://opendev.org/openstack/ptgbot>`_, while the
Ansible used to deploy it (including the template used for its
configuration) lives in the `opendev/system-config repository
<https://opendev.org/opendev/system-config/src/branch/master/playbooks/roles/ptgbot>`_.

Basic Channel Operator Commands
===============================

This is not a comprehensive overview of commands available to individuals
running IRC channels on OFTC, but a basic overview of some of the common
commands which may be required for channel operators.

Operator status is sometimes required to perform certain commands in your
channel (though most everything can be done through `/msg chanserv` commands
instead if permission flags are set correctly). To give yourself operator
status in a channel, use the following command::

  /msg chanserv op #channel

You don't need to become an operator to change the topic, this can be done
via Chanserv::

  /msg chanserv set #channel topic New topic goes here.

If you are curious as to who has access to a channel, you can issue this
command::

  /msg chanserv access #channel list

Banning Disruptive Users
========================

The easiest and fastest solution to indefinitely ban an abusive user from a
channel is to add them to Chanserv's auto-kick list like so::

  /msg chanserv akick <channel_name> add <nick> [optional reason]

This will immediately and anonymously kick them from the channel, and prevent
them from rejoining until explicitly removed from the akick list again.

Banning of disruptive users is also available with the `/ban` command, see your
client documentation for syntax, though this will require opping yourself in
the channel first.

Renaming an IRC Channel
=======================

First, follow the procedure for creating a new channel, including submitting
the appropriate changes to Gerrit for logging, accessbot, etc and adding the
proper credentials for the opendevaccess account.

Once those changes merge, or using some combination of Depends-On and/or WIP
status to ensure they don't merge before the others, propose changes to remove
the entries for the old channel from the same files. For the accessbot
:config:`channels.yaml` in particular, don't remove the channel but merely
comment it out with the current date so we'll know when it's safe for to
completely unregister::

  channels:
    - name: bar
    - name: baz
    # - name: foo RETIRED 2021-06-02
    - name: plugh
    - name: xyzzy

Once that is complete, a channel operator should set the topic string for the
old channel to indicate that discussions have moved to the new channel::

  /msg chanserv set #foo topic Discussion has moved to #bar, find us there

Optionally an entry message can be added for anyone joining as a reminder::

  /msg chanserv set #foo entrymsg This channel is unused, we're in #bar

Periodically, someone should sweep the accessbot channels for any comments
indicating a channel has been retired for at least 6 months, propose a change
to clean up those comments, and manually unregister each corresponding
channel::

  /msg chanserv drop #foo

Tips
----

* Collect the list of users and send a message in channel to each of them
  explaining that the channel has moved.
* Some folks simply won't leave and join the new channel, you can /kick
  them after a bit of time (a day? a week?) to get their client to join
  the new channel.
* Don't leave the channel until everything is done, it's non-trivial to
  rejoin because you've set up a forward!

Troubleshooting
===============

Bots may stop responding, common steps to troubleshoot the problem are:

1. Check status of the bot, with::

     service xxxbot status

   If the bot is stopped, start it again. Restart the bot if you see
   it's running but not operating properly.

2. On bot restart, it may show problems connecting to irc.oftc.net.
   If bot logs show it's stopped on connection, you can manually try
   with::

     telnet irc.oftc.net 6667

Registering a Nick for a New Bot
================================

First and foremost, we use a separate alias for the ``infra-root@``
E-mail address to distinguish the NickServ registration for each
bot's nick. Presently, these E-mail alias additions must be
requested from the OpenStack Foundation as they control the
corresponding hosting account. This might take some time, so plan
accordingly.

Once you have the E-mail alias assigned, generate a lengthy (16+
character) mixed-case alphanumeric string suitable as a NickServ
registration password and record both of these pieces of information
along with the nick in the secrets list for future reference.

Now, use an IRC client you're comfortable with (possibly easier if
you stick with default configuration rather than trying to do this
from your normal client setup though) to temporarily connect with
your newly chosen nick. For example, an unconfigured *weechat*
client can be invoked as follows::

  weechat -t -r '/set irc.look.temporary_servers on;/connect irc6s://botnick@irc.oftc.net:6697'

With the connection established, after you see the server MOTD echo,
register the nick as follows::

  /msg nickserv register some_strong_password email_alias

You should hopefully get positive feedback from NickServ at this
point, but don't disconnect yet. Moments later, the ``infra-root@``
shared mailbox should contain a new message from OFTC support
urging you to run the following additional command::

  /msg nickserv verify register botnick some_token

This additional step completes the nick registration, though
additional NickServ commands may be desirable to further secure the
account against pranksters and ne'er-do-wells.