mirror of
https://github.com/librenms/librenms.git
synced 2024-10-07 16:52:45 +00:00
Paul Gear
80
doc/IRC-Bot-Extensions.md
Normal file
80
doc/IRC-Bot-Extensions.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# Quick Guide
|
||||
|
||||
Okay this is a very quick walk-through in writing own `commands` for the IRC-Bot.
|
||||
|
||||
First of all, create a file in `includes/ircbot`, the file-name should be in this format: `command.inc.php`.
|
||||
|
||||
When editing the file, do not open nor close PHP-tags.
|
||||
Any variable you assign will be discarded as soon as your command returns.
|
||||
Some variables, specially all listed under `$this->`, have special meanings or effects.
|
||||
Before a command is executed, the IRC-Bot ensures that the MySQL-Socket is working, that `$this->user` points to the right user and that the user is authenticated.
|
||||
Below you will find a table with related functions and attributes.
|
||||
You can chain-load any built-in command by calling `$this->_command("My Parameters")`.
|
||||
You cannot chain-load external commands.
|
||||
|
||||
To enable your command, edit your `config.php` and add something like this:
|
||||
```php
|
||||
...
|
||||
$config['irc_external'][] = "mycommand";
|
||||
...
|
||||
```
|
||||
|
||||
See: [Example](#example)
|
||||
|
||||
# Functions and Attributes
|
||||
... that are accessible from within an extension
|
||||
|
||||
### <a name="glob.func">Functions</a>
|
||||
|
||||
Function( (Type) $Variable [= Default] [,...] ) | Returns | Description
|
||||
--- | --- | ---
|
||||
`$this->getChan( )` | `String` | Returns `channel` of current event.
|
||||
`$this->getData( (boolean) $Block = false )` | `String/Boolean` | Returns a `line` from the IRC-Buffer if it's not matched against any other `command`. If `$Block` is `true`, wait until a suitable line is returned.
|
||||
`$this->getUser( )` | `String` | Returns `nick` of current user. Not to confuse with `$this->user`!
|
||||
`$this->get_user( )` | `Array` | See `$this->user` in Attributes.
|
||||
`$this->irc_raw( (string) $Protocol )` | `Boolean` | Sends raw IRC-Protocol.
|
||||
`$this->isAuthd( )` | `Boolean` | `true` if the user is authenticated.
|
||||
`$this->joinChan( (string) $Channel )` | `Boolean` | Joins given `$Channel`.
|
||||
`$this->log( (string) $Message )` | `Boolean` | Logs given `$Message` into `STDOUT`.
|
||||
`$this->read( (string) $Buffer )` | `String/Boolean` | Returns a `line` from given `$Buffer` or `false` if there's nothing suitable inside the Buffer. Please use `$this->getData()` for handler-safe data retrieval.
|
||||
`$this->respond( (string) $Message )` | `Boolean` | Responds to the `request` auto-detecting channel or private message.
|
||||
|
||||
### <a name="glob.attr">Attributes</a>
|
||||
Attribute | Type | Description
|
||||
--- | --- | ---
|
||||
`$params` | `String` | Contains all arguments that are passed to the `.command`.
|
||||
`$this->chan` | `Array` | Channels that are configured.
|
||||
`$this->commands` | `Array` | Contains accessible `commands`.
|
||||
`$this->config` | `Array` | Contains `$config` from `config.php`.
|
||||
`$this->data` | `String` | Contains raw IRC-Protocol.
|
||||
`$this->debug` | `Boolean` | Debug-Flag.
|
||||
`$this->external` | `Array` | Contains loaded extra `commands`.
|
||||
`$this->nick` | `String` | Bot's `nick` on the IRC.
|
||||
`$this->pass` | `String` | IRC-Server's passphrase.
|
||||
`$this->port` | `Int` | IRC-Sever's port-number.
|
||||
`$this->server` | `String` | IRC-Server's hostname.
|
||||
`$this->ssl` | `Boolean` | SSL-Flag.
|
||||
`$this->tick` | `Int` | Interval to check buffers in microseconds.
|
||||
`$this->user` | `Array` | Array containing details about the `user` that sent the `request`.
|
||||
|
||||
# <a name="example">Example!</a>
|
||||
|
||||
`includes/ircbot/join-ng.inc.php`
|
||||
```php
|
||||
if( $this->user['level'] != 10 ) {
|
||||
return $this->respond("Sorry only admins can make me join.");
|
||||
}
|
||||
if( $this->getChan() == "#noc") {
|
||||
$this->respond("Joining $params");
|
||||
$this->joinChan($params);
|
||||
} else {
|
||||
$this->respond("Sorry, only people from #noc can make join.");
|
||||
}
|
||||
```
|
||||
|
||||
`config.php`
|
||||
```php
|
||||
...
|
||||
$config['irc_external'][] = "join-ng";
|
||||
...
|
||||
```
|
||||
130
doc/IRC-Bot.md
Normal file
130
doc/IRC-Bot.md
Normal file
@@ -0,0 +1,130 @@
|
||||
Table of Content:
|
||||
- [About](#about)
|
||||
- [Configuration](#config)
|
||||
- [Commands](#commands)
|
||||
- [Examples](#examples)
|
||||
- [Extensions](#extensions)
|
||||
|
||||
|
||||
# <a name="about">About</a>
|
||||
|
||||
LibreNMS has an easy to use IRC-Interface for basic tasks like viewing last log-entry, current device/port status and such.
|
||||
|
||||
By default the IRC-Bot will not start when executed and will return an error until at least `$config['irc_host']` and `$config['irc_port']` has been specified inside `config.php`.
|
||||
|
||||
If no channel has been specified with `$config['irc_chan']`, `##librenms` will be used.
|
||||
The default Nick for the bot is `LibreNMS`.
|
||||
|
||||
The Bot will reply the same way it's being called. If you send it the commands via Query, it will respond in the Query. If you send the commands via a Channel, then it will respond in the Channel.
|
||||
|
||||
### <a name="config">Configuration & Defaults</a>
|
||||
|
||||
Option | Default-Value | Notes
|
||||
--- | --- | ---
|
||||
`$config['irc_alert']` | `false` | Optional; Enables Alerting-Socket. `EXPERIMENTAL`
|
||||
`$config['irc_authtime']` | `3` | Optional; Defines how long in Hours an auth-session is valid.
|
||||
`$config['irc_chan']` | `##librenms` | Optional; Multiple channels can be defined as Array or delimited with `,`
|
||||
`$config['irc_debug']` | `false` | Optional; Enables debug output (Wall of text)
|
||||
`$config['irc_external']` | | Optional; Array or `,` delimited string with commands to include from `includes/ircbot/*.inc.php`
|
||||
`$config['irc_host']` | | Required; Domain or IP to connect. If it's an IPv6 Address, embed it in `[]`. (Example: `[::1]`)
|
||||
`$config['irc_maxretry]` | `5` | Optional; How many connection attempts should be made before giving up
|
||||
`$config['irc_nick']` | `LibreNMS` | Optional;
|
||||
`$config['irc_pass']` | | Optional; This sends the IRC-PASS Sequence to IRC-Servers that require Password on Connect
|
||||
`$config['irc_port]` | `6667` | Required; To enable SSL append a `+` before the Port. (Example: `+6697`)
|
||||
|
||||
### <a name="commands">IRC-Commands</a>
|
||||
|
||||
Command | Description
|
||||
--- | ---
|
||||
`.auth <User/Token>` | If `<user>`: Request an Auth-Token. If `<token>`: Authenticate session.
|
||||
`.device <hostname>` | Prints basic information about given `hostname`.
|
||||
`.down` | List hostnames that are down, if any.
|
||||
`.help` | List available commands.
|
||||
`.join <channel>` | Joins `<channel>` if user has admin-level.
|
||||
`.listdevices` | Lists the hostnames of all known devices.
|
||||
`.log [<N>]` | Prints `N` lines or last line of the eventlog.
|
||||
`.port <hostname> <ifname>` | Prints Port-related informations from `ifname` on given `hostname`.
|
||||
`.quit` | Disconnect from IRC and exit.
|
||||
`.reload` | Reload configuration.
|
||||
`.status <type>` | Prints status informations for given `type`. Type can be `devices`, `services`, `ports`. Shorthands are: `dev`,`srv`,`prt`
|
||||
`.version` | Prints `$this->config['project_name_version']`.
|
||||
|
||||
( __/!\__ All commands are case-_insensitive_ but their arguments are case-_sensitive_)
|
||||
|
||||
# <a name="examples">Examples</a>
|
||||
|
||||
### Server examples:
|
||||
|
||||
Unencrypted Connection to `irc.freenode.org`:
|
||||
|
||||
```php
|
||||
...
|
||||
$config['irc_host'] = "irc.freenode.org";
|
||||
$config['irc_port'] = 6667;
|
||||
...
|
||||
```
|
||||
|
||||
SSL-Encrypted Connection to `irc.freenode.org`:
|
||||
|
||||
```php
|
||||
...
|
||||
$config['irc_host'] = "irc.freenode.org";
|
||||
$config['irc_port'] = "+6697";
|
||||
...
|
||||
```
|
||||
|
||||
SSL-Encrypted Connection to `irc.localdomain` with Server-Password and odd port:
|
||||
|
||||
```php
|
||||
...
|
||||
$config['irc_host'] = "irc.localdomain";
|
||||
$config['irc_port'] = "+12345";
|
||||
$config['irc_pass'] = "Super Secret Passphrase123";
|
||||
...
|
||||
```
|
||||
|
||||
### Channel notations:
|
||||
|
||||
Channels can be defined using Array-Notation like:
|
||||
```php
|
||||
...
|
||||
$config['irc_chan'][] = "#librenms";
|
||||
$config['irc_chan'][] = "#otherchan";
|
||||
$config['irc_chan'][] = "#noc";
|
||||
...
|
||||
```
|
||||
Or using a single string using `,` as delimiter between various channels:
|
||||
```php
|
||||
...
|
||||
$config['irc_chan'] = "#librenms,#otherchan,#noc";
|
||||
...
|
||||
```
|
||||
|
||||
# <a name="extensions">Extensions?!</a>
|
||||
|
||||
The bot is coded in a unified way.
|
||||
This makes writing extensions by far less painfull.
|
||||
Simply add your `command` to the `$config['irc_external']` directive and create a file called `includes/ircbot/command.inc.php` containing your code.
|
||||
The string behind the call of `.command` is passed as `$params`.
|
||||
The user who requested something is accessable via `$this->user`.
|
||||
Send your reply/ies via `$this->respond($string)`.
|
||||
|
||||
A more detailed documentation of the functions and variables available for extensions can be found at [IRC-Bot Extensions](IRC-Bot-Extensions);
|
||||
|
||||
Confused? Here an Echo-Example:
|
||||
|
||||
File: config.php
|
||||
```php
|
||||
...
|
||||
$config['irc_external'][] = "echo";
|
||||
...
|
||||
```
|
||||
File: includes/ircbot/echo.inc.php
|
||||
```php
|
||||
//Prefix everything with `You said: '...'` and return what was sent.
|
||||
if( $this->user['name'] != "root" ) {
|
||||
return $this->respond("You said: '".$params."'");
|
||||
} else {
|
||||
return $this->respond("root shouldn't be online so late!");
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user