IRCBridgeModule
From OpenSimulator
Languages: |
English Français |
Configuring IRCBridgeModule
IRCBridgeModule
allows you to relay chat from your OpenSimulator region to an IRC channel and vice versa. You can use this module to
- make in-world chat available via a text-only interface such as IRC
- control objects from IRC channels
- use in-world objects to control bots attached via IRC
- ...
IRCBridge
can be used in three modes:
- in traditional mode where we relay all in-world chat from all regions to a single IRC channel on a single server, or
- in multi-channel mode where we can relay in-world chat from a specific region to a specific channel (or even to a specific server)
- in object chat relay mode where we only relay chat to and from private in-world channels
In addition, we can send commands to IRCBridge
from in-world objects to re-configure IRCBridge
Traditional IRCBridge mode
In the traditional IRCBridge
mode ("traditional" because
that was the original IRCBridge
modus operandi) all
in-world avatar chat from all regions is relayed to a specific IRC
chat channel on a specific server. Chat from an avatar is reported by
an OpenSimulator powered IRC bot in the IRC channel. Chat originating on the
IRC channel is reported via "voice of god" in all regions (voice of
god meaning that the in-world avatars will "hear" the chat but won't
be able to see the originator anywhere in the region).
To configure IRCBridge
for traditional mode operation use
the following configuration section in your OpenSim.ini
file (modifying as necessary, of course):
[IRC] enabled = true ; you need to set this otherwise it won't connect server = some.irc.server.net nick = OpenSinBot channel = #opensin port = 6667 relay_chat = true report_clients = true commands_enabled = false command_channel = 4711 access_password = WuffWuff relay_private_channels = false relay_private_channel_out = 4712 relay_private_channel_in = 4713 ;fallback_region = name of "default" region ;MSGformat fields : 0=botnick, 1=user, 2=region, 3=message ; must start with "PRIVMSG {0} : " or irc server will get upset ;for <bot>:<user in region> :<message> msgformat = "PRIVMSG {0} :<{1} in {2}>: {3}" ;for <bot>:<message> - <user of region> : ;msgformat = "PRIVMSG {0} : {1} [{2}]: {3}" ;for <bot>:<message> - from <user> : ;msgformat = "PRIVMSG {0} : {3} - from {1}"
Let’s go through the list of configuration options:
configuration variable | explanation |
---|---|
enabled | you need to set this to “true” otherwise IRCBridgeModule will not be enabled
|
server | the hostname of the IRC server that you intend to use |
nick | the nickname which IRCBridge will use to connect to the IRC server
|
channel | the IRC channel to connect to |
port | the port on the IRC server to conect to; this is usually port 6667 |
relay_chat | for traditional mode you need to set this to “true” to relay normal in-world chat |
report_clients | if you set this to “true” then IRCBridge will notify the IRC channel whenever an avatar logs on, enters a region, leaves a region, and logs off
|
msgformat | select whichever message format you want IRCBridge to use for relaying in-world messages to the IRC channel.
|
commands_enabled | leave as is for traditional mode |
command_channel | leave as is for traditional mode |
relay_private_channels | leave as is for traditional mode |
relay_private_channel_in | leave as is for traditional mode |
relay_private_channel_out | leave as is for traditional mode |
access_password | leave as is for traditional mode |
Multi-channel mode
With multi-channel mode we can configure IRCBridge
to
relay chat from different regions into different IRC channels — or
even into different IRC channels on different IRC servers!
The following OpenSim.ini
configuration file extract
configures IRCBridge
to relay chat from region A into
IRC channel #opensin-A-opensim.server.net
channel = "#opensim-[%region]-[%host]"
Let’s take a closer look at what’s going on here:
IRCBridge
allows us to apply run-time variable
substitution (a quite powerful mechanism).
configuration | explanation |
---|---|
channel = “#OS” | will connect all regions to the same channel; multiple opensim
servers, specifying this same name would share the channel |
channel = “#OS[%host]” | will connect all regions of a particular opensim server to the named
channel; multiple hosts specifying this same pattern would each be connected to an unique host-name derived channel |
channel = “#OS[%region]” | will result in each region being connected to a channel derived from
the region's name; in effect, all regions will be connected to a unique channel; If two opensim servers were running an identically named region, then those regions would share the channel |
channel = “#OS[%host]-[%region]” | will result in each server-region combination being connected to an
unique channel; this offers the best guarantee of unique name across the internet as a whole |
channel = “#OS[%region][%k]” | this configuration distinguishes consecutive activations of the same
region by affixing an unique numeric to the end of the name |
In all of these examples, the square brackets are eliminated by the substitution process. The '%' prefix indicates that this is a run-time variable. A value in square-brackets and not preceded by '%' indicates that the value may have been supplied as a value in the IRC ini configuration. For example, the existing mechanism for naming the channel could be made unnecessary complicated by specifying:
channel = “[channelid]” channelid = “#my-irc-channel”
The substitution process is exhaustive, so a configuration variable name may be constructed from run-time values.
To illustrate this, assume that the .ini file contains:
channel = “[#[%region]]” #brief1 = “#chatter-1” #brief2 = “#chatter-2”
Then region brief1 will be connected to channel #chatter-1, brief2 will be connected to #chatter-2, and all other regions will connect to channels with names identical to their region names. This is a trivial example, but becomes more meaningful when we consider all of the other parameters that might need to be unique per region (server, port etc). Using this mechanism we can create an ini file that has unique settings for all aspects of IRC for each region.
The following run-time values are available to this process:
variable | explanation |
---|---|
%host | external host name associated with a region |
%region | region name |
%locX | X coordinate of the region. |
%locY | Y coordinate of the region. |
%master1 | Master Avatar's first name |
%master2 | Master Avatar's last name |
%k | A unique numeric assigned to this region, e.g. “0” |
Finally, a more comprehensive example of a configuration file; we are assuming that we have two regions, Wonky and Borked:
channel = “[%region]” server = “[[%region]-server]” port = “[[%region]-port]” nick = “[[%region]-nick]” Wonky-server = irc1.server.org Wonky-port = 1234 Wonky-nick = WonkyBot Borked-server = irc2.anotherserver.net Borked-port = 1234 Borked-nick = BorkedBot
The Wonky region will connect to IRC channel #Wonky
via port 1234 of IRC server irc1.server.org
and IRCBridge
will appear as WonkyBot. Our Borked region will connect to IRC channel
#Borked
via port 1234 of IRC server
irc2.anotherserver.net
using the nickname BorkedBot.
Object chat relay mode
In object chat relay mode IRCBridge
relays messages from
and to in-world channels.
To configure IRCBridge
for this mode you need to use the
following configuration:
[IRC] enabled = true ; you need to set this otherwise it won't connect server = some.irc.server.net nick = OpenSinBot channel = #opensin port = 6667 relay_chat = false report_clients = false commands_enabled = false command_channel = 4711 relay_private_channels = true relay_private_channel_out = 4712 relay_private_channel_in = 4713 access_password = WuffWuff ;fallback_region = name of "default" region ;MSGformat fields : 0=botnick, 1=user, 2=region, 3=message ; must start with "PRIVMSG {0} : " or irc server will get upset ;for <bot>:<user in region> :<message> msgformat = "PRIVMSG {0} :<{1} in {2}>: {3}" ;for <bot>:<message> - <user of region> : ;msgformat = "PRIVMSG {0} : {1} [{2}]: {3}" ;for <bot>:<message> - from <user> : ;msgformat = "PRIVMSG {0} : {3} - from {1}"
The important configuration variables here are:
configuration variable | explanation |
---|---|
relay_chat | needs to be disabled (well, you can keep it enabled if your in-world
objects are silent and do not repeat what they heard) |
report_clients | doesn’t really make sense if you’ve disabled relay_chat |
relay_private_channels | needs to be set to “true” |
relay_private_channel_in | all traffic from the IRC channel will be send on this private
channel in-world |
relay_private_channel_out | all chat on this private in-world channel is relayed to the IRC
channel |
access_password | set this to a password of your choice |
Your in-world objects then need to use LSL code along the following lines:
llSay(command_channel, “access_password,from,message”);
to send messages to the IRC channel.
In-World configuration
The last feature worth mentioning is that you can control IRCBridge
from in-world by sending commands on a specific command channel.
To enable this feature you need to use the following configuration instructions:
commands_enabled = true command_channel = 4711
configuration variable | explanation |
---|---|
commands_enabled | needs to be “true” |
command_channel | set this to the private in-world channel number that you want to use |
IRCBridge
understands the following commands:
configuration variable | explanation |
---|---|
server hostname | change to the new IRC server “hostname” |
port port-number | change the port used to connect to the IRC server |
channel channel-name | change the channel name used |
nick new-nick | change the nick name used |
false | enable client reporting |
in-channel channel-number | change relay_private_channel_in to channel-number |
out-channel channel-number | change relay_private_channel_out to channel-number |
close | close the IRC connection |
connect | open the IRC connection |
reconnect | close and re-open the IRC connection |
irc_admin XmlRpc method
IRCBridge
supports one XmlRpc method that allows you to obtain the IRCBridge
configuration for a specific region. To enable this method you need to enable the [RemoteAdmin]
module.
irc_admin
expects two parameters:
parameter | explanation |
---|---|
password | the RemoteAdmin password |
region | the region name for which you want to the IRC configuration |
it will return
parameter | explanation |
---|---|
server | the server name |
port | the port name |
user | the IRC user name being used |
channel | the channel name being used |
enabled | whether the IRC relay is enabled or not |
connected | whether the IRC relay is connected or not |
nickname | the current nickname |
here is sample python code showing how to invoke irc_admin
:
import xmlrpclib s = xmlrpclib.Server('http://opensim.zurich.ibm.com:9000/admin') print s.irc_admin(dict(password = 'c00lstuff', region = 'zurela')) {'channel': '#opensim-lotus3d-zurela-opensim.zurich.ibm.com', 'connected': True, 'enabled': True, 'nickname': 'lotus3dbot66', 'port': '', 'server': 'zurich.irc.ibm.com', 'success': True, 'user': "USER OpenSimBot 8 * :I'm an OpenSimulator to IRC bot"}