mirror of
https://github.com/pragma-/pbot.git
synced 2024-11-22 03:49:29 +01:00
doc: add WIP QuickStart.md *rough* draft for preview
This commit is contained in:
parent
be5122fd06
commit
91817a3c43
132
doc/QuickStart.md
Normal file
132
doc/QuickStart.md
Normal file
@ -0,0 +1,132 @@
|
||||
QuickStart
|
||||
==========
|
||||
PBot is an IRC bot written in Perl. This is a work-in-progress rough draft Quick Start guide.
|
||||
This notification will be removed when this guide is mature.
|
||||
|
||||
|
||||
<!-- md-toc-begin -->
|
||||
* [QuickStart](#quickstart)
|
||||
* [Installing](#installing)
|
||||
* [Prerequisites](#prerequisites)
|
||||
* [Installing CPAN modules](#installing-cpan-modules)
|
||||
* [Caveats](#caveats)
|
||||
* [re::engine::RE2](#reenginere2)
|
||||
* [First-time Configuration](#first-time-configuration)
|
||||
* [Clone data-directory](#clone-data-directory)
|
||||
* [Edit Registry](#edit-registry)
|
||||
* [Notable settings](#notable-settings)
|
||||
* [Recommended settings for IRC Networks](#recommended-settings-for-irc-networks)
|
||||
* [Freenode](#freenode)
|
||||
* [IRCnet](#ircnet)
|
||||
* [Other networks](#other-networks)
|
||||
* [Adding Channels](#adding-channels)
|
||||
* [Adding Admins](#adding-admins)
|
||||
* [Loading Plugins](#loading-plugins)
|
||||
<!-- md-toc-end -->
|
||||
|
||||
Installing
|
||||
----------
|
||||
|
||||
### Prerequisites
|
||||
|
||||
#### Installing CPAN modules
|
||||
|
||||
PBot has many features; some of these depend on Perl modules written by others.
|
||||
This list can be found in the `MODULES` file in the root directory of this source.
|
||||
|
||||
The modules may be installed with a simple command:
|
||||
|
||||
cpan -f -i $(cat MODULES)
|
||||
|
||||
##### Caveats
|
||||
|
||||
Some CPAN modules may fail to pass certain tests due to outdated variables.
|
||||
Despite these test failures, their core functionality should still work as
|
||||
expected.
|
||||
|
||||
###### re::engine::RE2
|
||||
There have been reports that this module may not install. TODO: workaround.
|
||||
|
||||
First-time Configuration
|
||||
------------------------
|
||||
|
||||
### Clone data-directory
|
||||
|
||||
PBot uses a data-directory to store all its configuration settings and data. It
|
||||
is **_strongly_** recommended to clone the default data-directory for each PBot
|
||||
connection.
|
||||
|
||||
Here we clone the data-directory for two PBot instances, naming them after the
|
||||
IRC network they will connect to:
|
||||
|
||||
cp -r data freenode
|
||||
cp -r data ircnet
|
||||
|
||||
Alternatively, you could name it after your bot's nickname:
|
||||
|
||||
cp -r data coolbot
|
||||
|
||||
You get the idea.
|
||||
|
||||
### Edit Registry
|
||||
|
||||
Now you may edit the `registry` file in your data-directories to configure PBot
|
||||
settings.
|
||||
|
||||
#### Notable settings
|
||||
|
||||
Some settings you may be interested in configuring:
|
||||
|
||||
Registry key | Description | Default value
|
||||
--- | --- | ---:
|
||||
irc.botnick | IRC nickname. This is the name people see when you talk. | _undefined_
|
||||
irc.username | IRC username. This is the `USER` field of your hostmask. | pbot3
|
||||
irc.ircname | IRC gecos/realname. This is the `general information` or `real-name` field, as seen in `WHOIS`. | https://github.com/pragma-/pbot
|
||||
irc.ircserver | IRC server to connect | irc.freenode.net
|
||||
irc.port | IRC server port | 6667
|
||||
irc.identify_password | Password to use to identify to NickServ/service bot. | _undefined_
|
||||
irc.randomize_nick | Randomize IRC nickname when connecting to server. PBot will change to irc.botnick when connected or logged-in. | 0
|
||||
general.trigger | Bot trigger | [!]
|
||||
general.autojoin_wait_for_nickserv | Wait for NickServ login before auto-joining channels. | 0
|
||||
general.identify_nick | Who to /msg for login/identify/authentication. Defaults to NickServ, can be overridden to a custom bot. | NickServ
|
||||
general.identify_command | Command to send to `general.identify_nick` to login. | identify $nick $password
|
||||
general.op_nick | Who to /msg to request channel OP status. Defaults to ChanServ, can be overridden to a custom bot. | ChanServ
|
||||
general.op_command | Command to send to `general.op_nick` to request channel OP status. | op $channel
|
||||
googlesearch.api_key | API key for Google Custom Search. | _undefined_
|
||||
googlesearch.context | Google Custom Search context key. | _undefined_
|
||||
|
||||
#### Recommended settings for IRC Networks
|
||||
##### Freenode
|
||||
|
||||
The default settings are tailored for the Freenode IRC network. It is strongly recommended that
|
||||
you register an account with its NickServ service and to request a hostmask cloak. It is strongly
|
||||
recommended to register your channels with its ChanServ service. These services will protect your
|
||||
nick, IP address and channels.
|
||||
|
||||
Once you register your botnick with NickServ, it is recommended to set `irc.randomize_nick` to `1`.
|
||||
This will cause PBot to connect to the network with a randomized nickname, which will prevent users
|
||||
from watching for your connection to attempt to capture your IP address.
|
||||
|
||||
Then set `irc.autojoin_wait_for_nickserv` to `1`. This will cause PBot to wait until logged into NickServ
|
||||
before attempting to auto-join your channels, to ensure your NickServ host cloak is applied beforehand.
|
||||
|
||||
##### 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. You may configure the
|
||||
`general.identify_nick`, `general.identify_command`, `general.op_nick` and `general.op_command` settings
|
||||
to point at custom bots and commands to login/request OP.
|
||||
|
||||
##### Other networks
|
||||
|
||||
Other networks are untested. They should be very similiar to either Freenode or IRCnet, and so one of those
|
||||
recommended settings should work. If you have any issues, please report them at https://github.com/pragma-/pbot/issues.
|
||||
|
||||
### Adding Channels
|
||||
|
||||
### Adding Admins
|
||||
|
||||
### Loading Plugins
|
||||
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user