User Guide (v0.5)

PPF configuration is done through an XML file named PPFConfig.xml. This file can be edited with any plain text editor or using the graphical editor supplied.

The PPFConfig.xml file can also be edited with the provided graphical tool by running config. All of the configuration elements are described after the screen shots. Note that the screen shots are taken from a windows platform, this doesn't mean it is windows only. It will run on most of the Java supported platforms.

	Main config screen where some basic details for the bot are set.

	Server list. You can set encoding, retry rates, add, edit, delete, and change the order of the servers.

	Dialog screen for adding and editing a server.

	Nick list. You can add, edit, delete, and change the order of the nicks.

	Dialog screen for adding and editing a nick.

	Channel list. You can add, edit, and delete channels.

	Dialog for adding and editing a channel.

	Plugin list. You can add, edit, and delete plugins. You can also set if the plugin should load when the bot is started.

	Dialog for adding and editing a plugin.

	Web Server. Set if you want an internal web server to start, which document root and the port.

	Admin Password

The password for the ADMIN of the bot to use.

    <!-- bot owner -->
    <adminPassword>admin</adminPassword>

      

	Master Password

The password for any MASTER.

    <!-- bot master -->
    <masterPassword>master</masterPassword>

      

	Trusted Password

The password for any TRUSTED user.

    <!-- a trusted user -->
    <trustedPassword>trusted</trustedPassword>

      

	Language

Language for the bot to use (when possible).

  <!-- Code for the representation of names of languages
      http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt -->
  <language>en</language>

      

	Message Delay

How long to pause (in milliseconds) before sending a message to the IRC server. This helps prevent flooding. If you find the bot floods often, then increase this value.

    <messageDelay>2000</messageDelay>

      

	Join Message

A message to show as a notice to people as they join a channel that the bot is in. This can be empty if you don't want to show any message.

	<onJoinMessage>Type !help for a list of my commands</onJoinMessage>

      

	Rejoin on kick

Attempt to rejoin channels when kicked. Values are true or false.

	<rejoinOnKick>true</rejoinOnKick>

      

	Command Help

The command that will be used to trigger the help.

	  <commandHelp>!help</commandHelp>

      

	Command Set Language

The command that will be used to set a users language preference (where supported).

	  <commandSetLang>!setlang</commandSetLang>

      

	Verbose

Whether to show all of the IRC activity or not. Values are yes or no.

	<verbose>yes</verbose>

      

	Hide Ping Pong

Whether to show the PING PONG messages from server to client. Values are yes or no. This setting is only valid when verbose is yes.

    <hidePingPong>yes</hidePingPong>

      

	DCC Ports

Set which ports (or range of ports) can be used when making a DCC connection.

    <dccPorts>4563,3444-3544</dccPorts>

      

	Encoding

Set which encoding to use when communicating with the server.

    <encoding>ISO-8859-1</encoding>

      

	Servers

This is a list of the IRC servers that the bot will try to join. It will start at the first one in the list and work down the list until it finds one that accepts the connection.

• name - the IRC server
• port - the port of the IRC server (default: 6667)
• password - password if the server has one set (default: none)

retryDelay is for how long, in seconds, to wait before retrying the connection to the server.
maxConnectionAttempts is how many times to attempt reconnecting to a server before giving up.

    <!-- It will only join one server and that will be the first one that 
      it can connect to from the list -->
    <servers retryDelay="15" maxConnectionAttempts="20">
      <server name="de.quakenet.org" port="6667" password=""/>
      <server name="irc.quakenet.org" port="6667" password=""/>
      <server name="sw.de.quakenet.org" port="6667" password=""/>
      <server name="uk.quakenet.org" port="6667" password=""/>
      <server name="mediatraffic.fi.quakenet.org" port="6667" password=""/>
    </servers>

      

	Nicks

The first nick available from the list will be used. If your server has an ident server running, you may need to log onto IRC with the name of the account you use. In this case, set the account name to the ident attribute. Then set the actual nick that you want to use as normal in the nick list.

    <nicks ident="">
      <nick>EddiesBot</nick>
      <nick>Ed</nick>
      <nick>BootEd</nick>
      <nick>BootEddie</nick>
    </nicks>

      

	Channels

List of channels to join at startup.

• name - the name of the channel to join
• name - the password (if any) of the channel

    <channels>
      <channel name="#deaded" password=""/>
      <channel name="#deaded2" password=""/>
    </channels>

      

	Plugins

The plugins that are available to PPF. Setting load to no means that the plugin will not be loaded when PPF starts. Setting it to yes means that the plugin will be loaded when PPF starts.

  <plugins>
    <plugin load="no">
      <name>Advertiser</name>
      <classname>net.sourceforge.ppf.plugin.advertiserplugin.AdvertiserPlugin</classname>
    </plugin>
  </plugin>

      

	Web Server

There is a small built-in web server that allows web based access to a few features in the bot. If start is set to yes then the web server will start up using documentRoot as the public html directory on the configured port. You can then access the web server with the URL http://machine-bot-is-running-on/botControl
You will be asked for a user name and password. Currently the username can be anything, but suggest using you own nick that is in use on IRC as it will notify you when some actions are done via the web interface. The password is the admin password set in the PPFConfig.xml file.

With the web interface you can see which channels the bot is in. If you select a channel, you can then see which users are in that channel. You can also send public messages to the bot, but note that these send response to the user that you are logged in as. The same can be done for private messages/commands as well. You can also see a list of all of the plugin installed with the bot. Next to each plugin is a Load/Unload link which you can use to activate/deactivate the plugin. The Restart menu item will cause the whole bot to quit and restart (assuming you have used the correct, supplied, startup scripts).

Overall, this is a proof of concept to show what could be done and hopefully to encourage ideas.

    <webServer start="yes">
        <documentRoot>public_web</documentRoot>
        <port>80</port>
    </webServer>

      

The bot will respond to these public commands:

	Help

Command: !help [command]
Description: This will show the commands for using the bot and loaded plugins. To get more help on a command, add the command after !help.
Auth Level: none
Where to give command: channel
Outputs to: notice
Example(s):

• !help
• !help !google (if google plugin is loaded)

	Set language

Command: !setlang lang-code
Description: This lets a user set a language for the bot to use when displaying any text to IRC. Plugins may or may not support that language, in which case the default configured language for the bot is used.
Languages currently supported are, English, Finnish, Swedish, Dutch, German, and French.
Auth Level: none
Where to give command: channel
Outputs to: notice
Example(s):

• !setlang en

	Auth / logon to the bot

Command: auth
Description: To auth, you need the AdminPassword set in the config file, and to use the name of the bot as it is when it is on IRC. This will mean that you are authed with the bot for as long as you are both in the same channel. If either you or the bot quits the channel, you will have to auth again.
Auth Level: none
Where to give command: private message
Outputs to: notice
Example(s):

• /msg BotName auth AdminPassword
• auth AdminPassword

	Join a channel

Command: join
Description: This will make the bot join the given channel and if the channel has a password, that can be given after the channel name.
Auth Level: admin
Where to give command: private message
Outputs to: notice
Example(s):

• /msg BotName join #channel
• join #channel
• /msg BotName join #channel password
• join #channel password

	Show available plugins

Command: plugins
Description: This will list all of the plugins available to the bot
Auth Level: admin
Where to give command: private message
Outputs to: private message
Example(s):

• /msg BotName plugins
• plugins

	Load a plugin

Command: loadplugin
Description: This will cause the bot to load the given plugin

Auth Level: admin
Where to give command: private message
Outputs to: notice
Example(s):

• /msg BotName loadplugin PluginName
• loadplugin PluginName

	Reload a plugin

Command: reloadplugin
Description: This will cause the bot to reload the given plugin

Auth Level: admin
Where to give command: private message
Outputs to: notice
Example(s):

• /msg BotName reloadplugin PluginName
• reloadplugin PluginName

	Unload a plugin

Command: unloadplugin
Description: This will cause the bot to unload the given plugin

Auth Level: admin
Where to give command: private message
Outputs to: notice
Example(s):

• /msg BotName unloadplugin PluginName
• unloadplugin PluginName

	Change the nick

Command: nick
Description: This will change the nick of the bot. Note that you can set a name for it to have by default in the config file in the nicks section
Auth Level: admin
Where to give command: private message
Outputs to: nick is changed
Example(s):

• /msg BotName nick newnick
• nick newnick

	Some simple statistics

Command: stats
Description: Shows when the bot was started and how much memory it is using.
Auth Level: admin
Where to give command: private message
Outputs to: private message
Example(s):

• /msg BotName stats
• stats

	Who is authed with the bot

Command: users
Description: Shows the users that are authed with the bot and what level they are authed at.
Auth Level: admin
Where to give command: private message
Outputs to: private message
Example(s):

• /msg BotName users
• users

	Restart the bot

Command: restart
Description: This tells the bot to quit and start again (requires being started by supplied scripts)
Auth Level: admin
Where to give command: private message
Outputs to: bot quits IRC and then restarts and reconnects
Example(s):

• /msg BotName restart
• restart

	Stop / kill the bot

Command: die
Description: This tells the bot to quit and exit the JVM process
Auth Level: admin
Where to give command: private message
Outputs to: bot quits IRC
Example(s):

• /msg BotName die
• die

Plugins help make PPF so flexible. You can manage the plugins from using the bot, even while it is online. You are able to view existing plugins, load, reload, and unload plugins, and even configure new plugins. To be able to manage the plugins you have to be authed as an admin for the bot.

	View available plugins

This shows what plugins are available to PPF, what version of the plugin is being used, and which plugins are currently loaded or not.

  <DeadEd> plugins
  <BotEd> Loaded plugins are: Dict (v1.0) Bash (v1.0) Say (v1.0) BFTracks (v1.0) EDFinder (v1.0) 
          IMDB (v1.0) TriggerMessage (v1.0) Translate1337 (v1.0) Google (v1.0) CBFinder (v1.0) Simple (v1.0) 
          ServerQuery (v1.0) ServerAuth (v1.0) Seen (v1.0) ChannelCentral (v1.0) EightBall (v1.0) 
  <BotEd> Plugins not loaded are: BadWords ServerAdminShouter SHOUTcast MySqlQuery Advertiser ComicBot         

        

	Load a plugin

A plugin can be loaded after it has been added to the config or when you decide that you would like to activate it. Once the plugin has been loaded, it is available for use.

  <DeadEd> loadplugin comicbot
  -BotEd- Loaded plugin: comicbot

        

	Reload a plugin

Plugins can be reloaded. This means that config changes or suchlike can be made and taken into use immediately by reloading the plugin.

  <DeadEd> reloadplugin comicbot
  -BotEd- Reloaded plugin: comicbot

        

	Unload a plugin

Plugins can be unloaded. Once a plugin has been unloaded it is no longer available for use by the bot, but remains available to be loaded at any point.

  <DeadEd> unloadplugin comicbot
  -BotEd- Unloaded plugin: comicbot

        

	Configure a new plugin

To add a new plugin to an already running system, you need to make the bot aware of the plugin. This is done by adding a new plugin to the plugins section to PPFConfig.xml (the main config file). Let's say we want to add a new plugin that is called Simple. This would be the configuration for it:

    <plugin load="yes">
      <name>Simple</name>
      <classname>net.sourceforge.ppf.plugin.simpleplugin.SimplePlugin</classname>
    </plugin>

      

When the new plugin configuration has been added, the plugin is available to the bot (but not yet loaded). Now load the plugin and the new functionality is ready to use.