diff --git a/generate_plugin_doc.py b/generate_plugin_doc.py index 4cef831..8bdb659 100755 --- a/generate_plugin_doc.py +++ b/generate_plugin_doc.py @@ -31,6 +31,8 @@ with open(os.path.join(OUTPUT_DIR, "index.rst"), "w") as fd: fd.write( textwrap.dedent( """ + .. _builtin-plugins-reference: + Built-in plugins reference ========================== diff --git a/use/getting_started.rst b/use/getting_started.rst index 1e47ceb..1de24cc 100644 --- a/use/getting_started.rst +++ b/use/getting_started.rst @@ -63,147 +63,159 @@ you can prefix your command with the name of the plugin:: Anytime your bot tells you that a given command is defined in several plugins, you'll need to use this "plugin command" syntax to choose which plugin's command you wish to call. For instance, if you wanted to call the -Config plugin's ``list`` command, then you'd need to say:: +Config plugin's ``list`` command, then you'd need to run:: supybot: config list Rather than just ``list``. -Making Limnoria Recognize You -============================= +.. _login-to-bot: -For making the bot to identify to services, please see :ref:`identifying to services. ` +Logging in to Limnoria +====================== -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 -not running (otherwise it could overwrite supybot-adduser's changes to your -user database before you get a chance to reload them). Just follow the -prompts, and when it asks if you want to give the user any capabilities, say -yes and then give yourself the 'owner' capability, restart the bot and you'll -be ready to load some plugins! +.. note:: + For making the bot to identify to services, please see + :ref:`identifying to services. ` -Now, in order for the bot to recognize you as your owner user, you'll have to -identify with the bot. +Most administrative tasks in Limnoria (loading plugins, adding networks) require +you to be logged in to the bot as an ``owner`` user. If you used +``supybot-wizard`` to configure the bot, you have probably added an owner user +already. If not, shut off the bot and run the ``supybot-adduser`` script to +create a user, and give yourself the ``owner`` capability when it prompts you +to do so. -Open up a query window in your irc client ('/query' -should do it; if not, just know that you can't identify in a channel because -it requires sending your password to the bot). Then type this:: +To log in to the bot, use the ``identify`` command. This must be sent in a +private message (i.e. ``/query``) to the bot, to avoid leaking your password +to a channel:: help identify (identify ) -- Identifies the user as . This command (and all other commands that include a password) must be sent to the bot privately, not in a channel. -And follow the instructions; the command you send will probably look like -this, with 'myowneruser' and 'myuserpassword' replaced:: +Replacing "myowneruser" and "myuserpassword" with your login details, you should +run:: identify myowneruser myuserpassword - The operation succeeded + The operation succeeded. -The bot told you 'The operation succeeded', meaning that you got the right name -and password. Now that you're identified, you can do anything that requires -any privilege: that includes all the commands in the Owner and Admin plugins, -which you may want to take a look at (using the list and help commands, of -course). One command in particular that you might want to use (it's from the -User plugin) is the 'hostmask add' command: it lets you add a hostmask to your -user record so the bot recognizes you by your hostmask instead of requiring -you always to identify with it before it recognizes you. Use the 'help' -command to see how this command works. Here's how I often use it:: +Once you are logged in as an owner user, you can run commands that require +privileges. Many such administrative commands are located in the *Owner* and +*Admin* plugins. - hostmask add myuser [hostmask] mypassword - The operation succeeded +Automatic login (optional) +-------------------------- -You may not have seen that '[hostmask]' syntax before. Limnoria allows nested -commands, which means that any command's output can be nested as an argument -to another command. The hostmask command from the User plugin returns the -hostmask of a given nick, but if given no arguments, it returns the hostmask -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. +If you wish to make managing the bot easier, there are a few ways to log in to +the bot automatically. -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. +Automatic login using network services (NickAuth) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You can specify hostmasks in two other forms depending on the situation, -or rely on network services (ie. NickServ). +On IRC networks that provide a modern NickServ implementation, +Limnoria supports associating your bot account with a services account. This is +often the easiest method, as it does not involve configuring hostmasks. -Wildcard nick -^^^^^^^^^^^^^ +To use this, you first need to load the **NickAuth** plugin (see the +:ref:`loading plugins ` section for details on how to do that). -In case your username and host stay the same or there aren't bots on same -server which could get identified as me to other bots, you can use:: - - user hostmask add myuser *!myident@myhost - The operation succeeded - -I only recommend this if there is ident server configured and the IRC -network checks for it. - -Host only -^^^^^^^^^ - -In case you are the only one who has the same host (cloaks/vhosts on many -networks which have account in them, (for example Libera) or server where -no one else has access and no bots share it either), you can use:: - - user hostmask add myuser *!*@mycloak - The operation succeeded - -Mycloak at Libera is usually in format ``user/accountname``. You -can usually request hostmasks using HostServ, ``/msg HostServ help``, or -asking on help channel of your IRC network, in case of Libera that is -#libera. 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. - -Using network services -^^^^^^^^^^^^^^^^^^^^^^ - -This requires you to load the NickAuth plugin (see next section of this -page for loading plugins). - -NickAuth allows you to identify to the bot using your NickServ account. -First I add my NickServ account name which I can see with "/whois Mikaela Mikaela" (because my current nick is Mikaela). It gives me something like:: +To find your NickServ account name, run ``/whois ``, and you should see +some output like this:: [Mikaela] is logged in as Mikaela -Now I tell the bot add my NickServ account Mikaela to my bot user on -Libera. The syntax is [] :: +NickAuth logins are managed using the ``nickauth nick add`` and ``nickauth nick remove`` +commands. For clarity, ```` refers to your bot user, and ```` refers +to your NickServ account name:: - +nickauth nick add Libera Mikaela Mikaela - OK. + @help nickauth nick add + (nick add [] ) -- Add to the list of nicks owned by the on the . You have to register this nick to the network services to be authenticated. defaults to the current network. -Next time when I identify to NickServ I will get identified automatically -if the bot sees that I was identified when I joined. This requires server -to support extended-join and WHOX. Most of modern networks support -them, but if your bot is using some bouncer, it might not support them. +To add the NickServ account "Mikaela" to a bot account of the same name:: -Automatic identification doesn't work always even when it's supported, but -when it fails, I can always use the NickAuth Auth command to identify to -the bot:: + @nickauth nick add Mikaela Mikaela + OK. - +whoami - I don't recognize you. You can messsage me either of these two commands: "user identify " to log in or "user register " to register. - +nickauth auth - You are now authenticated as Mikaela. +On most networks, NickAuth will automatically activate when you log in to your +services account or join a channel the bot is in. Note that this requires the +`extended-join `_ and +`WHOX `_ IRCv3 features to be supported +by the IRC network. + +In places where this does not work, you can manually trigger a login +attempt using the ``nickauth auth`` command:: + + @whoami + I don't recognize you. You can messsage me either of these two commands: "user identify " to log in or "user register " to register. + @nickauth auth + You are now authenticated as Mikaela. + +Automatic login using a hostmask +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +An alternative to NickAuth that works everywhere is automatic login using your +IRC hostmask (``nick!user@host``). This may be more work to set up as there is +no one-size-fits-all hostmask to match someone; the best approach depends +on the network you're on and the type of host you are connecting from. + +Hostmask login is configured using the ``user hostmask add`` and +``user hostmask remove`` commands:: + + @help hostmask add + (hostmask add [] [] []) -- Adds the hostmask to the user specified by . The may only be required if the user is not recognized by hostmask. is also not required if an owner user is giving the command on behalf of some other user. If is not given, it defaults to your current hostmask. If is not given, it defaults to your currently identified name. This message must be sent to the bot privately (not on a channel) since it may contain a password. + +.. warning:: + Before adding a hostmask, double check that it is specific enough to only + match *you*. Giving permissions to wide hostmasks (e.g. ``nick!user@*``) is + a security risk, and could allow others to hijack your bot. + +If you're on a network that provides unique :ref:`cloaks/vhosts ` +based on your username, or have an otherwise dedicated static IP +(e.g. on a server not shared with other people), you can use the "host" part of +your hostmask for logging in:: + + user hostmask add myuser *!*@mycloak + The operation succeeded. + +On shared hosts that implement the `IDENT protocol `_, +you may want to add the username / ident field to the hostmask as well. +Note that this only works well if the network also implements IDENT checking; +otherwise, anyone can connect with anything in the username field:: + + user hostmask add myuser *!myident@myhost + The operation succeeded + +.. _cloak-examples: + +*mycloak* at Libera.chat, for instance, is usually in the format ``user/accountname``. +On other networks, you may be able to request cloaks using HostServ (``/msg HostServ help``) +or by asking a network operator. Note: OFTC is exception, and uses +``/msg NickServ set cloak on`` instead. + +.. _loading-plugins: Loading Plugins =============== -Let's take a look at loading other plugins. If you didn't use supybot-wizard, -though, you might do well to try it before playing around with loading plugins -yourself: each plugin has its own configure function that the wizard uses to -setup the appropriate registry entries if the plugin requires any. +.. note:: + To load plugins, you first need to be :ref:`logged in the the bot `. -If you do want to play around with loading plugins, you're going to need to -have the owner capability. +Loading plugins is done with the ``load`` command:: -Remember earlier when I told you to try ``help load``? That's the very command -you'll be using. Basically, if you want to load, say, the Games plugin, then -``load Games``. Simple, right? If you need a list of the plugins you can load, -you'll have to list the directory the plugins are in (using whatever command -is appropriate for your operating system, either 'ls' or 'dir'). + @help load + user: (load ) -- Loads the plugin from any of the directories in conf.supybot.directories.plugins; usually this includes the main installed directory and 'plugins' in the current directory. + +For example, to load the *Games* plugin, run:: + + @load Games + The operation succeeded. + +To unload a plugin, there is a corresponding ``unload`` command:: + + @unload Games + The operation succeeded. + +To find plugins to load, consult the :ref:`Built-in plugins reference ` +or the Plugins list on `limnoria.net `_. Understanding the help syntax =============================