diff --git a/use/getting_started.rst b/use/getting_started.rst index ea79bcf..3bc5675 100644 --- a/use/getting_started.rst +++ b/use/getting_started.rst @@ -74,6 +74,8 @@ Rather than just 'list'. Making Supybot Recognize You ============================ +For making the bot to identify to services, please see :ref:`identifying to services. ` + If you ran the wizard, then it is almost certainly the case that you already added an owner user for yourself. If not, however, you can add one via the handy-dandy 'supybot-adduser' script. You'll want to run it while the bot is @@ -117,6 +119,41 @@ of the person giving the command. So the command above adds the hostmask I'm currently using to my user's list of recognized hostmasks. I'm only required to give mypassword if I'm not already identified with the bot. +It might often be better to specify the hostmask by yourself instead of +nesting the hostmask command as the hostmask command gives your exact +hostmask of that moment meaning ``nick!ident@host`` which means that you +will get unidentified if you change your nickname. + +I (Mikaela) often specify hostmasks in two other forms depending on the +situation which I go through in next subtopics. + +Wildcard nick +^^^^^^^^^^^^^ + +In case my username and host stay the same or there aren't bots on same +server which could get identified as me to other bots, I use:: + + user hostmask add myuser *!myident@myhost + +I only recommend this if there is ident server configured and the IRC +network checks for it. + +Host only +^^^^^^^^^ + +In case I am the only one who has the same host (cloaks/vhosts on many +networks which have account in them, (for example freenode) or server where +no one else has access and no bots share it either), I use:: + + user hostmask add myuser *!*@mycloak + +Mycloak at freenode is usually in format ``unaffiliated/accountname``. You +can usually request hostmasks using HostServ, ``/msg HostServ help``, or +asking on help channel of your IRC network, in case of freenode that is +#freenode. OFTC is exception to this and uses +``/msg NickServ set cloak on``, but whatever your network users, you can +ask it on their help channel. + Limnoria -------- @@ -186,133 +223,6 @@ the bot:: +nickauth auth You are now authenticated as Mikaela. -Identifying the bot to services -=============================== - -The different methods are listed in order which I (Mikaela) recommend. You -can use all of these methods or only some of them. I (Mikaela) personally -use SASL, CertFP and Server password. - -Please also note that SASL and CertFP are only supported on Limnoria. - -SASL ----- - -Note that SASL isn't supported on all networks. You can easily test if it's -supported with ``/msg SaslServ help`` and if you get response, SASL is -probably supported, if you don't get reply or get error about no such nick, -SASL isn't supported. - -SASL is widely agreed as the best method to identify to services as it -identifies you before anyone (other than IRC operators) can see that you -are connected. To enable SASL, simply:: - - config networks..sasl.username AccountName - config networks..sasl.password P455w0rd - -where you of course replace AccountName and P455w0rd with your actual -NickServ account name and password. Remember to replace ```` with -the real network name like ``freenode``. - -CertFP ------- - -You can test if CertFP is supported by services simply by doing -``/msg NickServ cert``. If you get an error about "Insufficient parameters -for CERT", CertFP is supported, and if you get an error about unknown -command, it's not supported. - -CertFP identifies you to services using a client (SSL) certificate and -naturally requires an SSL connection. It doesn't identify you as soon as -SASL, but unlike SASL, it identifies you even when services return from a -netsplit, unlike any other mechanism. - -First you must generate a certificate, and the easiest method is probably -using OpenSSL which you should have even on Windows if you installed with pip:: - - openssl req -nodes -newkey rsa:4096 -keyout .pem -x509 -days 3650 -out .pem -subj "/CN=" - -Now you should have a ``.pem`` file in the directory where you ran -the command, presumably your home directory and you only tell your -bot where to find it and tell NickServ that it belongs to you. -Note that you should replace ```` with the account name of your bot. - -You have two choices, using the same certificate on all networks:: - - config protocols.irc.certfile /home//.pem - -or only on one or more network where it's manually configured:: - - config networks..certfile /home//.pem - -And lastly, you must tell the services what is your certificate -fingerprint, which you can find out with:: - - openssl x509 -sha1 -noout -fingerprint -in BOT.pem | tr -d ':' | tr 'A-Z' 'a-z' - -This results in something like -``05dd01fedc1b821b796d0d785160f03e32f53fa8`` which you tell your bot to -tell services:: - - owner ircquote PRIVMSG NickServ :cert add 05dd01fedc1b821b796d0d785160f03e32f53fa8 - -Or if your bot identifies as you, you can do that by yourself with:: - - /msg NickServ cert add 05dd01fedc1b821b796d0d785160f03e32f53fa8 - - -Remember to replace ``05dd01fedc1b821b796d0d785160f03e32f53fa8`` with your -own fingerprint! Next time your bot connects, it should get identified -automatically. - -Server password ---------------- - -Many networks support identifying using ``username:password`` as server -password. If this is the case with your network (anything that uses a -charybdis-like IRCd), this should work for you. Note that this identifies -you after SASL so, your real host might be seen. To do this, simply:: - - config networks..password username:password - -Replace ```` with the name of network, for example ``freenode`` -and username:password with your real username and password. - -ZNC users: since ZNC 1.0, ZNC's identification format has been -``username/network:password``. - -Services plugin ---------------- - -The Services plugin comes with Supybot and should be an easy way to -identify your bot, but SASL and ``username:password`` as server password -are recommended over it. Start by loading Services with:: - - load Services - -and then tell it what NickServ and ChanServ are called:: - - config plugins.services.nickserv NickServ - config plugins.services.chanserv ChanServ - -Remember to replace NickServ/ChanServ with their real names if they have a -different name on any network. Note that they must have the same name on -all networks, and you must have the same password on all networks. - -Now you can set your password:: - - services password Bot P455w0rd - -makes the bot attempt identifying as Bot using password P455w0rd. Replace -them with your real nickname and password. Note that if you have multiple -nicknames, you must run ``services password`` for them all. - -If your bot happens to get a nickname that isn't configured, it won't -know how to identify. You might be able to avoid this issue by loading -NickCapture, (``load NickCapture``) which attempts to regain the primary -nick, when it's possible, and when it regains the primary nick, the -identification should work. - Loading Plugins =============== diff --git a/use/identifying_to_services.rst b/use/identifying_to_services.rst new file mode 100644 index 0000000..ba767de --- /dev/null +++ b/use/identifying_to_services.rst @@ -0,0 +1,130 @@ +.. _identifying-to-services: + +******************************* +Identifying the bot to services +******************************* + +The different methods are listed in order which I (Mikaela) recommend. You +can use all of these methods or only some of them. I (Mikaela) personally +use SASL, CertFP and Server password. + +Please also note that SASL and CertFP are only supported on Limnoria. + +SASL +---- + +Note that SASL isn't supported on all networks. You can easily test if it's +supported with ``/msg SaslServ help`` and if you get response, SASL is +probably supported, if you don't get reply or get error about no such nick, +SASL isn't supported. + +SASL is widely agreed as the best method to identify to services as it +identifies you before anyone (other than IRC operators) can see that you +are connected. To enable SASL, simply:: + + config networks..sasl.username AccountName + config networks..sasl.password P455w0rd + +where you of course replace AccountName and P455w0rd with your actual +NickServ account name and password. Remember to replace ```` with +the real network name like ``freenode``. + +CertFP +------ + +You can test if CertFP is supported by services simply by doing +``/msg NickServ cert``. If you get an error about "Insufficient parameters +for CERT", CertFP is supported, and if you get an error about unknown +command, it's not supported. + +CertFP identifies you to services using a client (SSL) certificate and +naturally requires an SSL connection. It doesn't identify you as soon as +SASL, but unlike SASL, it identifies you even when services return from a +netsplit, unlike any other mechanism. + +First you must generate a certificate, and the easiest method is probably +using OpenSSL which you should have even on Windows if you installed with pip:: + + openssl req -nodes -newkey rsa:4096 -keyout .pem -x509 -days 3650 -out .pem -subj "/CN=" + +Now you should have a ``.pem`` file in the directory where you ran +the command, presumably your home directory and you only tell your +bot where to find it and tell NickServ that it belongs to you. +Note that you should replace ```` with the account name of your bot. + +You have two choices, using the same certificate on all networks:: + + config protocols.irc.certfile /home//.pem + +or only on one or more network where it's manually configured:: + + config networks..certfile /home//.pem + +And lastly, you must tell the services what is your certificate +fingerprint, which you can find out with:: + + openssl x509 -sha1 -noout -fingerprint -in BOT.pem | tr -d ':' | tr 'A-Z' 'a-z' + +This results in something like +``05dd01fedc1b821b796d0d785160f03e32f53fa8`` which you tell your bot to +tell services:: + + owner ircquote PRIVMSG NickServ :cert add 05dd01fedc1b821b796d0d785160f03e32f53fa8 + +Or if your bot identifies as you, you can do that by yourself with:: + + /msg NickServ cert add 05dd01fedc1b821b796d0d785160f03e32f53fa8 + + +Remember to replace ``05dd01fedc1b821b796d0d785160f03e32f53fa8`` with your +own fingerprint! Next time your bot connects, it should get identified +automatically. + +Server password +--------------- + +Many networks support identifying using ``username:password`` as server +password. If this is the case with your network (anything that uses a +charybdis-like IRCd), this should work for you. Note that this identifies +you after SASL so, your real host might be seen. To do this, simply:: + + config networks..password username:password + +Replace ```` with the name of network, for example ``freenode`` +and username:password with your real username and password. + +ZNC users: since ZNC 1.0, ZNC's identification format has been +``username/network:password``. + +Services plugin +--------------- + +The Services plugin comes with Supybot and should be an easy way to +identify your bot, but SASL and ``username:password`` as server password +are recommended over it. Start by loading Services with:: + + load Services + +and then tell it what NickServ and ChanServ are called:: + + config plugins.services.nickserv NickServ + config plugins.services.chanserv ChanServ + +Remember to replace NickServ/ChanServ with their real names if they have a +different name on any network. Note that they must have the same name on +all networks, and you must have the same password on all networks. + +Now you can set your password:: + + services password Bot P455w0rd + +makes the bot attempt identifying as Bot using password P455w0rd. Replace +them with your real nickname and password. Note that if you have multiple +nicknames, you must run ``services password`` for them all. + +If your bot happens to get a nickname that isn't configured, it won't +know how to identify. You might be able to avoid this issue by loading +NickCapture, (``load NickCapture``) which attempts to regain the primary +nick, when it's possible, and when it regains the primary nick, the +identification should work. + diff --git a/use/index.rst b/use/index.rst index 5c9a3cd..8739681 100644 --- a/use/index.rst +++ b/use/index.rst @@ -10,6 +10,7 @@ The Supybot user guide install.rst getting_started.rst configuration.rst + identifying_to_services.rst capabilities.rst faq.rst httpserver.rst