IRCBridgeModule

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(adding run-time variables)
m (Fixed a few typos)
 
(21 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 +
__NOTOC__
 +
{{Quicklinks}}
 +
<br />
 +
 
== Configuring IRCBridgeModule ==
 
== Configuring IRCBridgeModule ==
  
<code>IRCBridgeModule</code> allows you to relay chat from your OpenSim region to an IRC channel and vice versa. You can use this module to  
+
<code>IRCBridgeModule</code> 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
 
* make in-world chat available via a text-only interface such as IRC
Line 10: Line 14:
 
<code>IRCBridge</code> can be used in three modes:  
 
<code>IRCBridge</code> 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 [[#Traditional IRCBridge mode|''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 [[#Multi-channel mode|''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 [[#Object chat relay mode|''object chat relay mode'']] where we only relay chat to and from private in-world channels
 +
 
 +
In addition, we can [[#In-World Configuration|send commands]] to <code>IRCBridge</code> from in-world objects to re-configure <code>IRCBridge</code>
  
=== Traditional IRCBridge mode ===
+
== Traditional IRCBridge mode ==
  
 
In the traditional <code>IRCBridge</code> mode ("traditional" because
 
In the traditional <code>IRCBridge</code> mode ("traditional" because
Line 20: Line 26:
 
in-world avatar chat from all regions is relayed to a specific IRC
 
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
 
chat channel on a specific server. Chat from an avatar is reported by
an OpenSim powered ''IRC bot'' in the IRC channel. Chat originating on the
+
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
 
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
 
god meaning that the in-world avatars will "hear" the chat but won't
Line 33: Line 39:
 
enabled = true ; you need to set this otherwise it won't connect
 
enabled = true ; you need to set this otherwise it won't connect
 
server  = some.irc.server.net
 
server  = some.irc.server.net
nick    = OpenSinBot
+
nick    = OpenSimBot
channel = #opensin
+
user    = "USER OpenSimBot 8 * :I'm an OpenSim to IRC bot"
 +
channel = #opensim
 
port = 6667
 
port = 6667
 
relay_chat = true
 
relay_chat = true
Line 41: Line 48:
 
commands_enabled = false
 
commands_enabled = false
 
command_channel = 4711
 
command_channel = 4711
 +
access_password = WuffWuff
 +
 
relay_private_channels = false
 
relay_private_channels = false
 
relay_private_channel_out = 4712
 
relay_private_channel_out = 4712
 
relay_private_channel_in = 4713
 
relay_private_channel_in = 4713
  
access_password = WuffWuff
 
  
 
;fallback_region = name of "default" region
 
;fallback_region = name of "default" region
Line 61: Line 69:
 
Let’s go through the list of configuration options:
 
Let’s go through the list of configuration options:
  
{| class="wikitable" style="background:transparent" border=”1”
+
{| align=”center” border="1" cellpadding="5" cellspacing="0"
 
|-
 
|-
 
! configuration variable
 
! configuration variable
Line 79: Line 87:
 
|-
 
|-
 
| port
 
| port
| the port on the IRC server to conect to; this is usually port 6667
+
| the port on the IRC server to connect to; this is usually port 6667
 
|-
 
|-
 
| relay_chat
 
| relay_chat
Line 110: Line 118:
 
|}
 
|}
  
 
+
== Multi-channel mode ==
=== Multi-channel mode ===
+
  
 
With multi-channel mode we can configure <code>IRCBridge</code> to
 
With multi-channel mode we can configure <code>IRCBridge</code> to
relay chat from different regions into '''different IRC channels''' — or
+
relay chat from different regions into '''different IRC channels''' — or
 
even into '''different IRC channels on different IRC servers'''!
 
even into '''different IRC channels on different IRC servers'''!
  
 
The following <code>OpenSim.ini</code> configuration file extract
 
The following <code>OpenSim.ini</code> configuration file extract
configures <code>IRCBridge</code> to relay chat from ''region A'' into
+
configures <code>IRCBridge</code> to relay chat from ''region A'' into
 
IRC channel <code>#opensin-A-opensim.server.net</code>
 
IRC channel <code>#opensin-A-opensim.server.net</code>
  
 
<pre>
 
<pre>
channel = "#opensin-[%region]-[%host]"
+
channel = "#opensim-[%region]-[%host]"
 
</pre>
 
</pre>
  
Line 129: Line 136:
 
substitution (a quite powerful mechanism).
 
substitution (a quite powerful mechanism).
  
{| class="wikitable" style="background:transparent" border=”1”
+
{| border="1" cellpadding="5" cellspacing="0" align="center"
 
|-
 
|-
 
! align=”left” | configuration
 
! align=”left” | configuration
 
! align=”left” | explanation
 
! align=”left” | explanation
 
|-
 
|-
| channel = “#OS”
+
| width="40%" | channel = “#OS”
 
| will connect all regions to the same channel; multiple opensim
 
| will connect all regions to the same channel; multiple opensim
 
servers, specifying this same name would share the channel
 
servers, specifying this same name would share the channel
Line 178: Line 185:
  
 
<pre>
 
<pre>
channel = “#[%region]”
+
channel = “[#[%region]]”
 
#brief1 = “#chatter-1”
 
#brief1 = “#chatter-1”
 
#brief2 = “#chatter-2”
 
#brief2 = “#chatter-2”
Line 193: Line 200:
 
The following run-time values are available to this process:
 
The following run-time values are available to this process:
  
{| class="wikitable" style="background:transparent" border=”1”
+
{| border="1" cellpadding="5" cellspacing="0" align="center"
 
|-
 
|-
 
! variable
 
! variable
Line 219: Line 226:
 
| A unique numeric assigned to this region, e.g. “0”
 
| 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'':
 +
 +
<pre>
 +
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
 +
 +
</pre>
 +
 +
The ''Wonky'' region will connect to IRC channel <code>#Wonky</code>
 +
via port 1234 of IRC server <code>irc1.server.org</code> and <code>IRCBridge</code>
 +
will appear as ''WonkyBot''. Our ''Borked'' region will connect to IRC channel
 +
<code>#Borked</code> via port 1234 of IRC server
 +
<code>irc2.anotherserver.net</code> using the nickname ''BorkedBot''.
 +
 +
== Object chat relay mode ==
 +
 +
In object chat relay mode <code>IRCBridge</code> relays messages from
 +
and to in-world channels.
 +
 +
To configure <code>IRCBridge</code> for this mode you need to use the
 +
following configuration:
 +
 +
<pre>
 +
[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}"
 +
 +
</pre>
 +
 +
The important configuration variables here are:
 +
 +
{| align="center" border="1" cellpadding="5" cellspacing="0"
 +
|-
 +
! 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:
 +
 +
<pre>
 +
llSay(command_channel, “access_password,from,message”);
 +
</pre>
 +
 +
to send messages to the IRC channel.
 +
 +
== In-World configuration ==
 +
 +
The last feature worth mentioning is that you can control <code>IRCBridge</code> from in-world by sending commands on a specific command channel.
 +
 +
To enable this feature you need to use the following configuration instructions:
 +
 +
<pre>
 +
commands_enabled = true
 +
command_channel = 4711
 +
</pre>
 +
 +
{| align="center" border="1" cellpadding="5" cellspacing="0"
 +
|-
 +
! 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
 +
|}
 +
 +
<code>IRCBridge</code> understands the following commands:
 +
 +
{| align="center" border="1" cellpadding="5" cellspacing="0"
 +
|-
 +
! 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
 +
|-
 +
| client-reporting true|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 ==
 +
 +
<code>IRCBridge</code> supports one XmlRpc method that allows you to obtain the <code>IRCBridge</code>configuration for a specific region. To enable this method you need to enable the <code>[RemoteAdmin]</code> module.
 +
 +
<code>irc_admin</code> expects two parameters:
 +
 +
{| align="center" border="1" cellpadding="5" cellspacing="0"
 +
|-
 +
! parameter
 +
! explanation
 +
|-
 +
| password
 +
| the RemoteAdmin password
 +
|-
 +
| region
 +
| the region name for which you want to the IRC configuration
 +
|-
 +
|}
 +
 +
it will return
 +
 +
{| align="center" border="1" cellpadding="5" cellspacing="0"
 +
|-
 +
! 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 <code>irc_admin</code>:
 +
 +
<pre>
 +
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"}
 +
</pre>
 +
 +
[[Category:Modules]]

Latest revision as of 20:39, 27 November 2017


[edit] 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

[edit] 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    = OpenSimBot
user    = "USER OpenSimBot 8 * :I'm an OpenSim to IRC bot"
channel = #opensim
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 connect 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

[edit] 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.

[edit] 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.

[edit] 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

[edit] irc_admin XmlRpc method

IRCBridge supports one XmlRpc method that allows you to obtain the IRCBridgeconfiguration 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"}
Personal tools
General
About This Wiki