From 17ff754a9bbecf8ba931698625984e2b7b0b320c Mon Sep 17 00:00:00 2001 From: dgw Date: Mon, 28 Jun 2021 00:34:21 -0500 Subject: [PATCH 1/3] docs: clarify relationship between `owner` and `owner_account` (again) We were going to make `core.owner` optional in Sopel 8, but that's not wise. The setting is used to send important notices to the bot's owner, and so it has to be set with a proper value even if `core.owner_account` is being used for verification (e.g. `plugin.require_owner`). --- docs/source/configuration.rst | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 684496e05d..eca4bea898 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -131,17 +131,10 @@ on the IRC server the bot connects to. Owner & Admins -------------- -A Sopel instance must have exactly one owner. This is configured either by -:attr:`~CoreSection.owner_account` if the IRC server supports IRCv3 accounts, -or by :attr:`~CoreSection.owner`. If ``owner_account`` is set, ``owner`` will -be ignored. - -.. important:: - - Even if ``owner_account`` is set, ``owner`` **must** still have a value. - - This is silly, we know. The plan for Sopel 8 is to require only one value - or the other. +A Sopel instance must have exactly one owner. This is configured by the +:attr:`~CoreSection.owner` setting. If the IRC server supports IRCv3 accounts, +Sopel can use :attr:`~CoreSection.owner_account` to increase the security of +ownership verification. The same instance can have multiple admins. Similarly, it can be configured by :attr:`~CoreSection.admin_accounts` or by :attr:`~CoreSection.admins`. If @@ -151,25 +144,30 @@ Example owner & admin configurations:: # Using nickname matching [core] - owner = dgw + owner = dgw # used for alerts and ownership verification admins = Exirel HumorBaby # Using account matching [core] - owner_account = dgw + owner = dgw # used for alerts only + owner_account = dgws_account # used for ownership verification admin_accounts = Exirel HumorBaby - # ignored when owner_account is set, - # but MUST NOT be empty - owner = dgw Both ``owner_account`` and ``admin_accounts`` are safer to use than nick-based matching, but the IRC server must support accounts. (Most, sadly, do not as of late 2019.) +.. important:: + + The :attr:`~CoreSection.owner` setting should **always** contain the bot + owner's nickname, even when using :attr:`~CoreSection.owner_account`. Both + Sopel and plugins may send important messages or notices to the owner + using ``bot.config.core.owner`` as the recipient. + IRC Server ========== From 974f3acc28b89d17e36dfa158394fe1bd011427e Mon Sep 17 00:00:00 2001 From: dgw Date: Mon, 28 Jun 2021 00:36:21 -0500 Subject: [PATCH 2/3] docs: fix typo in `plugin/anatomy.rst` --- docs/source/plugin/anatomy.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/plugin/anatomy.rst b/docs/source/plugin/anatomy.rst index db18031fb4..c1f05e9abd 100644 --- a/docs/source/plugin/anatomy.rst +++ b/docs/source/plugin/anatomy.rst @@ -136,7 +136,7 @@ manipulation. There are two cases to consider: * A :term:`Named rule` is already named (by definition), so it uses its name directly as rule label. This can't be overridden by a decorator. -This label is particulary useful for bot owners who want to disable a rule in +This label is particularly useful for bot owners who want to disable a rule in a specific channel. In the following example, the ``say_hello`` rule from the ``hello`` plugin is disabled in the ``#rude`` channel: From da5267d9a9145f34512ca361ef618fb563b3c04f Mon Sep 17 00:00:00 2001 From: dgw Date: Mon, 28 Jun 2021 11:28:04 -0500 Subject: [PATCH 3/3] docs: rework misleading inline comment style in config examples Our `ConfigParser` invokation does not allow inline comments, so users could copy and paste broken snippets with comments as part of the value. Regardless of whether it's a good idea to enable inline comment support for Sopel 8, we need clean documentation for the 7.1.x stable branch. --- docs/source/configuration.rst | 80 +++++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 31 deletions(-) diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index eca4bea898..5ce1992dfe 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -144,15 +144,18 @@ Example owner & admin configurations:: # Using nickname matching [core] - owner = dgw # used for alerts and ownership verification + # Will be used for alerts and ownership verification + owner = dgw admins = Exirel HumorBaby # Using account matching [core] - owner = dgw # used for alerts only - owner_account = dgws_account # used for ownership verification + # Will be used for alerts only + owner = dgw + # Will be used for ownership verification + owner_account = dgws_account admin_accounts = Exirel HumorBaby @@ -426,23 +429,30 @@ details: Example of nick-based authentication with NickServ service:: [core] - auth_method = nickserv # select nick-based auth + # select nick-based authentication + auth_method = nickserv # auth_username is not required for nickserv - auth_password = SopelIsGreat! # your bot's password - auth_target = NickServ # default value + # your bot's login password + auth_password = SopelIsGreat! + # default value + auth_target = NickServ And here is an example of server-based authentication using SASL:: [core] - auth_method = sasl # select server-based auth - auth_username = BotAccount # your bot's username - auth_password = SopelIsGreat! # your bot's password - auth_target = PLAIN # default sasl mechanism + # select SASL authentication + auth_method = sasl + # your bot's login username and password + auth_username = BotAccount + auth_password = SopelIsGreat! + # default SASL mechanism + auth_target = PLAIN Example of authentication to a ZNC bouncer:: [core] - auth_method = server # select server-based auth + # select server-based authentication + auth_method = server # auth_username is not used with server authentication, so instead # we combine the ZNC username, network name, and password here: auth_password = Sopel/libera:SopelIsGreat! @@ -482,17 +492,21 @@ When :attr:`~CoreSection.server_auth_method` is defined the settings used are: For example, this will use NickServ ``IDENTIFY`` command and SASL mechanism:: [core] - # nick-based auth - auth_method = nickserv # select nick-based auth + # select nick-based authentication + auth_method = nickserv # auth_username is not required for nickserv - auth_password = SopelIsGreat! # your bot's password - auth_target = NickServ # default value - - # server-based auth - server_auth_method = sasl # select server-based auth - server_auth_username = BotAccount # your bot's username - server_auth_password = SopelIsGreat! # your bot's password - server_auth_target = PLAIN # default sasl mechanism + # your bot's login password + auth_password = SopelIsGreat! + # default value + auth_target = NickServ + + # select SASL authentication + server_auth_method = sasl + # your bot's login username and password + server_auth_username = BotAccount + server_auth_password = SopelIsGreat! + # default SASL mechanism + server_auth_target = PLAIN .. important:: @@ -516,17 +530,21 @@ used are: For example, this will use NickServ ``IDENTIFY`` command and SASL mechanism:: [core] - # nick-based auth - nick_auth_method = nickserv # select nick-based auth + # select nick-based authentication + nick_auth_method = nickserv # nick_auth_username is not required for nickserv - nick_auth_password = SopelIsGreat! # your bot's password - nick_auth_target = NickServ # default value - - # server-based auth - server_auth_method = sasl # select server-based auth - server_auth_username = BotAccount # your bot's username - server_auth_password = SopelIsGreat! # your bot's password - server_auth_target = PLAIN # default sasl mechanism + # your bot's login password + nick_auth_password = SopelIsGreat! + # default value + nick_auth_target = NickServ + + # select SASL auth + server_auth_method = sasl + # your bot's login username and password + server_auth_username = BotAccount + server_auth_password = SopelIsGreat! + # default SASL mechanism + server_auth_target = PLAIN .. important::