From 07a867c2d0b06376d8d7a33f211a4c4cb66f4c55 Mon Sep 17 00:00:00 2001 From: Pragmatic Software Date: Mon, 27 Jan 2020 19:52:53 -0800 Subject: [PATCH] doc/QuickStart.md: improvements --- doc/QuickStart.md | 256 ++++++++++++++++++++++++++++------------------ 1 file changed, 156 insertions(+), 100 deletions(-) diff --git a/doc/QuickStart.md b/doc/QuickStart.md index d4462d5a..b973f7b6 100644 --- a/doc/QuickStart.md +++ b/doc/QuickStart.md @@ -7,10 +7,9 @@ * [Installing PBot](#installing-pbot) * [git (recommended)](#git-recommended) * [Download zip archive](#download-zip-archive) -* [First-time Configuration](#first-time-configuration) +* [Initial Setup](#initial-setup) * [Clone data-directory](#clone-data-directory) - * [Quick-start command](#quick-start-command) - * [Edit Registry](#edit-registry) + * [Configuration](#configuration) * [Recommended settings for IRC Networks](#recommended-settings-for-irc-networks) * [Freenode](#freenode) * [IRCnet](#ircnet) @@ -19,26 +18,31 @@ * [Usage](#usage) * [Overriding directories](#overriding-directories) * [Overriding registry](#overriding-registry) -* [Additional Configuration](#additional-configuration) - * [Adding Channels](#adding-channels) - * [Adding Admins](#adding-admins) - * [Loading Plugins](#loading-plugins) + * [First-time start-up](#first-time-start-up) + * [Using default Freenode settings](#using-default-freenode-settings) + * [Using custom settings](#using-custom-settings) + * [Custom recommended Freenode settings](#custom-recommended-freenode-settings) + * [Custom recommended IRCnet/other network settings](#custom-recommended-ircnetother-network-settings) + * [Regular start-up](#regular-start-up) +* [Additional configuration](#additional-configuration) + * [Creating your bot owner user account](#creating-your-bot-owner-user-account) + * [Adding channels](#adding-channels) + * [Adding other users and admins](#adding-other-users-and-admins) * [Further Reading](#further-reading) * [Commands](#commands) * [Factoids](#factoids) + * [Plugins](#plugins) * [Modules](#modules) ## Installation ### Installing Perl - PBot uses the [Perl programming language](https://www.perl.org/). Perl is usually part of a base Linux install. If you do not have Perl installed, please see your system's documentation to install it. ### Installing CPAN modules - Some of PBot's features depend on the availability of Perl modules written by third parties. To use such PBot features, the modules listed in the [`MODULES`](../MODULES) file need to be installed. @@ -54,7 +58,6 @@ expected. ### Installing PBot #### git (recommended) - The recommended way to install PBot is with `git`. This will allow you easily update to the latest version of PBot via the git update process by issuing the `git pull` command. Also, if you become interested in contributing improvements to PBot, you will be able to @@ -65,11 +68,9 @@ The command to install with `git` is: $ git clone https://github.com/pragma-/pbot.git #### Download zip archive - Alternatively, you may [download a ZIP archive](https://github.com/pragma-/pbot/archive/master.zip). -## First-time Configuration - +## Initial Setup After git-cloning (or unpacking the ZIP archive) you should have a directory named `pbot/` (or `pbot-master/`). It should contain at least these directories and files: @@ -86,9 +87,12 @@ You may create a symbolic link to the `pbot` executable in `$HOME/bin/` or even in `/usr/local/bin/`. ### Clone data-directory - PBot uses a data-directory to store all its configuration settings and data. You must -clone this data-directory for each instance of PBot you want to run. +clone this data-directory for each instance of PBot you want to run, otherwise they +will become quite confused with each other and things will break horribly. + +Even if you're using just one instance of PBot it is still strongly recommended to clone +the default data-directory, especially if you used `git` to install PBot. Here we clone the data-directory for two PBot instances, naming them after the IRC network they will connect to: @@ -97,31 +101,23 @@ IRC network they will connect to: $ cp -r data freenode $ cp -r data ircnet -Alternatively, you could name it after your bot's nickname: +Alternatively, you could name your new data directory after your bot's nickname: $ cp -r data coolbot -### Quick-start command - -At this point, you may start PBot if you wish. The default settings will connect -to the Freenode IRC network. Or you may read on to the next section for more -advanced configuration. - -At minimum, the registry key `irc.botnick` must be set before PBot will connect -to any IRC servers. Here we will use the cloned data-directory `coolbot` named -after the botnick we'll use. - - $ pbot data_dir=coolbot irc.botnick=coolbot - -### Edit Registry - +### Configuration PBot configuration is stored in a registry of key/value pairs grouped by sections. -For more details, see the [Registry documentation](Registry.md). +For more information, see the [Registry documentation](Registry.md). -Now you may edit the `registry` file in your data-directory to configure PBot settings. Alternatively, -you may [override the registry entries via the command-line](#overriding-registry). +For initial first-time setup, you may configure registry settings via the PBot +command-line options. We'll show you [how to do that](#starting-pbot) soon! First, read on to +see what settings you should configure. -Some settings you may be interested in configuring: +Alternatively, you can edit the `registry` file in your cloned data-directory. +See the [Editing registry file](Registry.md#editing-registry-file) for more +information. + +Here is a table of some basic initial settings you should configure: Registry key | Description | Default value --- | --- | ---: @@ -132,11 +128,11 @@ irc.server | IRC server address to connect. | irc.freenode.net irc.port | IRC server port. | 6667 general.trigger | Bot trigger. Can be a character class containing multiple trigger characters. Can be overridden per-channel. | [!] -For a more comprehensive list see [this table](Registry.md#list-of-known-registry-items). +For a list of other available settings see [this table](Registry.md#list-of-known-registry-items) in the [Registry documentation](Registry.md). #### Recommended settings for IRC Networks -##### Freenode +##### Freenode The default settings are tailored for the Freenode IRC network. It is strongly recommended that you register an account with NickServ and to request a hostmask cloak. Register your channels with ChanServ. These services will protect your nickname, IP address and channels. @@ -151,7 +147,6 @@ general.autojoin_wait_for_nickserv | Wait for NickServ login before auto-joining general.identify_command | Command to send to NickServ to identify. `$nick` will be replaced with `irc.botnick`; `$password` will be replaced with `irc.identify_password`. If you wish to login to a NickServ account different than the `irc.botnick` you may replace the `$nick` text with a literal value. | `identify $nick $password` ##### IRCnet - IRCnet is one of the oldest IRC networks still running. It has no Services like NickServ and ChanServ. Instead, its nicknames and channels are protected by custom bots. @@ -165,7 +160,6 @@ general.op_nick | Who to /msg to request channel OP status. Defaults to ChanServ general.op_command | Command to send to `general.op_nick` to request channel OP status. | `op $channel` | `` ##### Other networks - Other networks are untested. They should be very similiar to either Freenode or IRCnet, and so one or both of those recommended settings should suffice. If you have any issues, please [report them here](https://github.com/pragma-/pbot/issues) or in the `#pbot2` channel on the Freenode network. @@ -173,31 +167,103 @@ or in the `#pbot2` channel on the Freenode network. ## Starting PBot ### Usage - $ pbot [directory overrides...; e.g. data_dir=...] [registry overrides...; e.g. irc.botnick=...] #### Overriding directories - You may override PBot's default directory locations via the command-line. $ pbot data_dir=/path/to/data plugin_dir=/path/to/Plugins modules_dir=/path/to/modules #### Overriding registry - You may override any of your Registry values via the command-line. Any overrides made will be saved to the `registry` file. You do not need to use the override every time you launch PBot. - $ pbot irc.botnick=coolbot irc.server=irc.freenode.net irc.port=6667 + $ pbot irc.botnick=coolbot irc.server=irc.example.com irc.port=6667 [...] -## Additional Configuration +### First-time start-up -Once you have launched PBot, you can type into the STDIN to execute commands within -the bot. Alternatively you can launch your own IRC client and `/msg` PBot. +#### Using default Freenode settings +The default settings will connect to the Freenode IRC network. -Additional configuration can be done by sending the following commands to PBot. +At minimum, the registry key `irc.botnick` must be set before PBot will connect to any IRC servers. -### Adding Channels +The following command will use the `coolbot` data-directory that we cloned in the [initial setup](#initial-setup), +and set the `irc.botnick` registry key to the same name. It will automatically connect to the Freenode IRC network. + $ pbot data_dir=coolbot irc.botnick=coolbot + +#### Using custom settings +To connect to a specific IRC server or to configure additional settings, you may +[override the directory paths](#overriding-directories) and [override the registry values](#overriding-registry). Read on to the next section for examples. + +##### Custom recommended Freenode settings +The following command is based on the [Recommended settings for IRC Networks](#recommended-settings-for-irc-networks) section earlier in this document. +The `irc.server` and `irc.port` settings are omitted because the default values will connect to the Freenode IRC network. + +Replace the placeholders, marked `X`, with values you want to use. Note that this is just for the first-time start-up. Regular subsequent start-up needs only `data_dir` to be overridden. + +If you have registered your botnick with Freenode's NickServ service, use this command: + + pbot data_dir=X irc.botnick=X irc.identify_password=X irc.randomize_nick=1 general.autojoin_wait_for_nickserv=1 + +Otherwise, use this one: + + pbot data_dir=X irc.botnick=X + +##### Custom recommended IRCnet/other network settings +The following command is based on the [Recommended settings for IRC Networks](#recommended-settings-for-irc-networks) section earlier in this document. + +Replace the placeholders, marked `X`, with values you want to use. Note that this is just for the first-time start-up. Regular subsequent start-up needs only `data_dir` to be overridden. + +If you want PBot to identify with a custom bot or service on IRCnet/other networks, use this command: + + pbot data_dir=X irc.botnick=X irc.server=X irc.port=X general.identify_nick=X general.op_nick=X + +Otherwise, use this one: + + pbot data_dir=X irc.botnick=X irc.server=X irc.port=X + +### Regular start-up +After your initial start-up command, you only need to use the `data_dir` +directory override when starting PBot. + + $ pbot data_dir=X + +## Additional configuration +Once you've launched PBot, you can type directly into its terminal to execute +commands as the built-in PBot console admin user account. This will allow you +to use admin commands to create new users or join channels. + +### Creating your bot owner user account +To create your own fully privileged admin user account, use the following +commands in the PBot terminal console. + +Suppose your nick is `Bob` and your hostmask is `Bob!~user@some.domain.com`. + + useradd Bob global Bob!~user@*.domain.com 100 + +This will create a level `100` admin user account named `Bob`. Note the wildcard +replacing `some` in `some.domain.com`. Now as long as your connected hostmask +matches your user account hostmask, you will be recognized. + +In your own IRC client, connected using the hostmask we just added, type the +following command: + + my password + +This will show you the randomly generated password that was assigned to your +user account. You can change it -- if you want to -- with: + + my password + +Then you can login with: + + login + +Now you can use `/msg` in your own IRC client to administrate PBot, instead of +the terminal console. + +### Adding channels To temporarily join channels, use the `join` command. join @@ -221,65 +287,38 @@ permop | If set to true, PBot will not de-OP itself in this channel. | 0 For more information, see the [Channels documentation](Admin.md#channel-management-commands). -### Adding Admins +### Adding other users and admins +To add users to PBot, use the `useradd` command. -To add admins to PBot, use the `adminadd` command. + useradd [[level] [password]] - adminadd +If you omit the `password` argument, a random password will be generated. The user +can use the [`my`](Commands.md#my) command to view or change it. -To change an admin's properties, use the `adminset` command. +If you omit the `level` argument, the user will be a normal unprivileged user. See [admin levels](Admin.md#admin-levels) +for more information about admin levels. - adminset [key [value]] +Users may view and change their own metadata by using the [`my`](Commands.md#my) command. -You may set the follow admin properties: + my [ [value]] -Name | Description ---- | --- -name | A unique name identifying this admin account. -level | The privilege level of this admin. See [this table](Admin.md#admin-levels) for more information. -password | The password for this admin account. -loggedin | If set to 1, the admin is logged in. -stayloggedin | If set to 1, the admin will not be logged out when they part/quit. - -For more information, see the [Admin documentation](Admin.md#admin-management-commands). - -### Loading Plugins - -Plugins provide optional PBot features. The default plugins loaded by PBot is set by -the `plugin_autoload` file in your data-directory. - -You may load plugins using the `plug` command. - - plug - -You may unload plugins using the `unplug` command. - - unplug - -Currently loaded plugins may be listed with the `pluglist` command. - - !pluglist - Loaded plugins: ActionTrigger, AntiAway, AntiKickAutoRejoin, AntiNickSpam, AntiRepeat, AntiTwitter, AutoRejoin, Counter, GoogleSearch, Quotegrabs, RemindMe, UrlTitles - -For more information, see the [Plugins documentation](Plugins.md). +For more information, see the [Admin documentation](Admin.md). ## Further Reading - That should get you started. For further information about PBot, check out these topics. ### Commands - PBot has several core built-in commands. You've seen some of them in this document, for setting up channels and admins. Additional commands can be added to PBot through Plugins and Factoids. +For more information, see the [Commands documentation](Commands.md). + ### Factoids - Factoids are a very special type of command. Anybody interacting with PBot -can create, edit, delete and invoke factoids. Factoids can be locked by the -creator of the factoid to prevent them from being edited by others. +can create, edit, delete and invoke factoids. -At its most simple, a factoid merely displays the text the creator sets. +In their most basic form, a factoid merely displays the text the creator sets. !factadd hello /say Hello, $nick! hello added to global channel. @@ -292,10 +331,35 @@ command-piping, `/code` invocation, and more! For more information, see the [Factoids documentation](Factoids.md). -### Modules +### Plugins +Plugins provide optional PBot features. The default plugins loaded by PBot is set by +the [`plugin_autoload`](../data/plugin_autoload) file in your data-directory. To autoload additional plugins, +add their name to this file. +You may manually load plugins using the `plug` command. + + plug + +You may unload plugins using the `unplug` command. + + unplug + +Plugins can be quickly reloaded by using the `replug` command. + + replug + +Currently loaded plugins may be listed with the `pluglist` command. + + !pluglist + Loaded plugins: ActionTrigger, AntiAway, AntiKickAutoRejoin, AntiNickSpam, AntiRepeat, + AntiTwitter, AutoRejoin, Counter, Date, GoogleSearch, Quotegrabs, RemindMe, UrlTitles, + Weather + +For more information, see the [Plugins documentation](Plugins.md). + +### Modules Modules are external command-line executable programs and scripts that can be -loaded via PBot Factoids. +loaded as PBot commands. Suppose you have the [Qalculate!](https://qalculate.github.io/) command-line program and you want to provide a PBot command for it. You can create a _very_ simple @@ -306,19 +370,11 @@ shell script containing: And let's call it `qalc.sh` and put it in PBot's `modules/` directory. -Then you can add the `qalc` factoid: - - !factadd global qalc qalc.sh - -And then set its `type` to `module`: - - !factset global qalc type module - -Alternatively, you can simply use the [`load`](Admin.md#load) command: +Then you can use the PBot [`load`](Admin.md#load) command to load the `modules/qalc.sh` script as the `qalc` command: !load qalc qalc.sh -Now you have a `qalc` calculator in PBot! +Now you have a [Qalculate!](https://qalculate.github.io/) calculator in PBot! !qalc 2 * 2 2 * 2 = 4