Update documentation

README-0.6.md

@@ -0,0 +1,115 @@
+# matterbridge
+
+Simple bridge between mattermost, IRC, XMPP, Gitter and Slack
+
+* Relays public channel messages between mattermost, IRC, XMPP, Gitter and Slack. Pick and mix.
+* Supports multiple channels.
+* Matterbridge can also work with private groups on your mattermost.
+
+Look at [matterbridge.conf.sample] (https://github.com/42wim/matterbridge/blob/master/matterbridge.conf.sample) for documentation and an example.
+
+## Changelog
+Since v0.6.1 support for XMPP, Gitter and Slack is added. More details in [changelog.md] (https://github.com/42wim/matterbridge/blob/master/changelog.md)
+
+## Requirements:
+Accounts to one of the supported bridges
+* [Mattermost] (https://github.com/mattermost/platform/)
+* [IRC] (http://www.mirc.com/servers.html)
+* [XMPP] (https://jabber.org)
+* [Gitter] (https://gitter.im)
+* [Slack] (https://www.slack.com)
+
+## binaries
+Binaries can be found [here] (https://github.com/42wim/matterbridge/releases/)
+* For use with mattermost 3.3.0+ [v0.6.1](https://github.com/42wim/matterircd/releases/tag/v0.6.1)
+* For use with mattermost 3.0.0-3.2.0 [v0.5.0](https://github.com/42wim/matterircd/releases/tag/v0.5.0)
+
+
+## Docker
+Create your matterbridge.conf file locally eg in ```/tmp/matterbridge.conf```
+
+```
+docker run -ti -v /tmp/matterbridge.conf:/matterbridge.conf 42wim/matterbridge:0.6.1
+```
+
+## Compatibility
+### Mattermost 
+* Matterbridge v0.6.1 works with mattermost 3.3.0 and higher [3.3.0 release](https://github.com/mattermost/platform/releases/tag/v3.3.0)
+* Matterbridge v0.5.0 works with mattermost 3.0.0 - 3.2.0 [3.2.0 release](https://github.com/mattermost/platform/releases/tag/v3.2.0)
+
+
+#### Webhooks version
+* Configured incoming/outgoing [webhooks](https://www.mattermost.org/webhooks/) on your mattermost instance.
+
+#### Plus (API) version
+* A dedicated user(bot) on your mattermost instance.
+
+
+## building
+Go 1.6+ is required. Make sure you have [Go](https://golang.org/doc/install) properly installed, including setting up your [GOPATH] (https://golang.org/doc/code.html#GOPATH)
+
+```
+cd $GOPATH
+go get github.com/42wim/matterbridge
+```
+
+You should now have matterbridge binary in the bin directory:
+
+```
+$ ls bin/
+matterbridge
+```
+
+## running
+1) Copy the matterbridge.conf.sample to matterbridge.conf in the same directory as the matterbridge binary.  
+2) Edit matterbridge.conf with the settings for your environment. See below for more config information.  
+3) Now you can run matterbridge. 
+
+```
+Usage of ./matterbridge:
+  -conf string
+        config file (default "matterbridge.conf")
+  -debug
+        enable debug
+  -plus
+        running using API instead of webhooks (deprecated, set Plus flag in [general] config)
+  -version
+        show version
+```
+
+## config
+### matterbridge
+matterbridge looks for matterbridge.conf in current directory. (use -conf to specify another file)
+
+Look at [matterbridge.conf.sample] (https://github.com/42wim/matterbridge/blob/master/matterbridge.conf.sample) for an example.
+
+### mattermost
+#### webhooks version
+You'll have to configure the incoming and outgoing webhooks. 
+
+* incoming webhooks
+Go to "account settings" - integrations - "incoming webhooks".  
+Choose a channel at "Add a new incoming webhook", this will create a webhook URL right below.  
+This URL should be set in the matterbridge.conf in the [mattermost] section (see above)  
+
+* outgoing webhooks
+Go to "account settings" - integrations - "outgoing webhooks".  
+Choose a channel (the same as the one from incoming webhooks) and fill in the address and port of the server matterbridge will run on.  
+
+e.g. http://192.168.1.1:9999 (192.168.1.1:9999 is the BindAddress specified in [mattermost] section of matterbridge.conf)
+
+#### plus version
+You'll have to create a new dedicated user on your mattermost instance.
+Specify the login and password in [mattermost] section of matterbridge.conf
+
+## FAQ
+Please look at [matterbridge.conf.sample] (https://github.com/42wim/matterbridge/blob/master/matterbridge.conf.sample) for more information first. 
+### Mattermost doesn't show the IRC nicks
+If you're running the webhooks version, this can be fixed by either:
+* enabling "override usernames". See [mattermost documentation](http://docs.mattermost.com/developer/webhooks-incoming.html#enabling-incoming-webhooks)
+* setting ```PrefixMessagesWithNick``` to ```true``` in ```mattermost``` section of your matterbridge.conf.
+
+If you're running the plus version you'll need to:
+* setting ```PrefixMessagesWithNick``` to ```true``` in ```mattermost``` section of your matterbridge.conf.
+
+Also look at the ```RemoteNickFormat``` setting.

README.md

@@ -1,22 +1,35 @@
 # matterbridge
 
-Simple bridge between mattermost, IRC, XMPP and Gitter
+:warning: Look at [README-0.6.md] (https://github.com/42wim/matterbridge/blob/master/README-0.6.md) for the documentation of the current stable. 
+The information below is about the develop version.
 
-* Relays public channel messages between mattermost, IRC, XMPP and Gitter. Pick and mix.
+Simple bridge between mattermost, IRC, XMPP, Gitter and Slack
+
+* Relays public channel messages between multiple mattermost, IRC, XMPP, Gitter and Slack. Pick and mix.
 * Supports multiple channels.
-* Matterbridge -plus also works with private groups on your mattermost.
+* Matterbridge can also work with private groups on your mattermost.
+* Allow for bridging the same bridges, which means you can eg bridge between multiple mattermosts.
+* The bridge is now a gateway which has support multiple in and out bridges. (and supports multiple gateways).
 
-Look at [matterbridge.conf.sample] (https://github.com/42wim/matterbridge/blob/master/matterbridge.conf.sample) for documentation and an example.
+Look at [matterbridge.toml.sample] (https://github.com/42wim/matterbridge/blob/master/matterbridge.toml.sample) for documentation and an example.
+Look at [matterbridge.toml.simple] (https://github.com/42wim/matterbridge/blob/master/matterbridge.toml.simple) for a simple example.
 
 ## Changelog
-Since v0.6.1 support for XMPP, Gitter and Slack is added. More details in [changelog.md] (https://github.com/42wim/matterbridge/blob/master/changelog.md)
+Since v0.7.0-dev the configuration has changed. More details in [changelog.md] (https://github.com/42wim/matterbridge/blob/master/changelog.md)
 
-## Requirements:
+## Requirements
 Accounts to one of the supported bridges
 * [Mattermost] (https://github.com/mattermost/platform/)
 * [IRC] (http://www.mirc.com/servers.html)
 * [XMPP] (https://jabber.org)
 * [Gitter] (https://gitter.im)
+* [Slack] (https://slack.com)
+
+## Docker
+Create your matterbridge.toml file locally eg in ```/tmp/matterbridge.toml```
+```
+docker run -ti -v /tmp/matterbridge.toml:/matterbridge.toml 42wim/matterbridge
+```
 
 ## binaries
 Binaries can be found [here] (https://github.com/42wim/matterbridge/releases/)
@@ -32,7 +45,7 @@ Binaries can be found [here] (https://github.com/42wim/matterbridge/releases/)
 #### Webhooks version
 * Configured incoming/outgoing [webhooks](https://www.mattermost.org/webhooks/) on your mattermost instance.
 
-#### Plus (API) version
+#### API version
 * A dedicated user(bot) on your mattermost instance.
 
 
@@ -59,20 +72,18 @@ matterbridge
 ```
 Usage of ./matterbridge:
   -conf string
-        config file (default "matterbridge.conf")
+        config file (default "matterbridge.toml")
   -debug
         enable debug
-  -plus
-        running using API instead of webhooks (deprecated, set Plus flag in [general] config)
   -version
         show version
 ```
 
 ## config
 ### matterbridge
-matterbridge looks for matterbridge.conf in current directory. (use -conf to specify another file)
+matterbridge looks for matterbridge.toml in current directory. (use -conf to specify another file)
 
-Look at [matterbridge.conf.sample] (https://github.com/42wim/matterbridge/blob/master/matterbridge.conf.sample) for an example.
+Look at [matterbridge.toml.sample] (https://github.com/42wim/matterbridge/blob/master/matterbridge.toml.sample) for an example.
 
 ### mattermost
 #### webhooks version
@@ -89,18 +100,14 @@ Choose a channel (the same as the one from incoming webhooks) and fill in the ad
 
 e.g. http://192.168.1.1:9999 (192.168.1.1:9999 is the BindAddress specified in [mattermost] section of matterbridge.conf)
 
-#### plus version
-You'll have to create a new dedicated user on your mattermost instance.
-Specify the login and password in [mattermost] section of matterbridge.conf
-
 ## FAQ
-Please look at [matterbridge.conf.sample] (https://github.com/42wim/matterbridge/blob/master/matterbridge.conf.sample) for more information first. 
+Please look at [matterbridge.toml.sample] (https://github.com/42wim/matterbridge/blob/master/matterbridge.toml.sample) for more information first. 
 ### Mattermost doesn't show the IRC nicks
 If you're running the webhooks version, this can be fixed by either:
 * enabling "override usernames". See [mattermost documentation](http://docs.mattermost.com/developer/webhooks-incoming.html#enabling-incoming-webhooks)
-* setting ```PrefixMessagesWithNick``` to ```true``` in ```mattermost``` section of your matterbridge.conf.
+* setting ```PrefixMessagesWithNick``` to ```true``` in ```mattermost``` section of your matterbridge.toml.
 
 If you're running the plus version you'll need to:
-* setting ```PrefixMessagesWithNick``` to ```true``` in ```mattermost``` section of your matterbridge.conf.
+* setting ```PrefixMessagesWithNick``` to ```true``` in ```mattermost``` section of your matterbridge.toml.
 
 Also look at the ```RemoteNickFormat``` setting.

changelog.md

@@ -1,3 +1,12 @@
+# v0.7-dev
+## Breaking config changes from 0.6 to 0.7
+Matterbridge now uses TOML configuration (https://github.com/toml-lang/toml)
+See matterbridge.toml.sample for an example
+
+## New features
+* Allow for bridging the same type of bridge, which means you can eg bridge between multiple mattermosts.
+* The bridge is now a gateway which has support multiple in and out bridges. (and supports multiple gateways).
+
 # v0.6.1
 ## New features
 * Slack support added.  See matterbridge.conf.sample for more information

matterbridge.toml.sample

@@ -0,0 +1,308 @@
+#This is configuration for matterbridge.
+###################################################################
+#IRC section
+###################################################################
+#REQUIRED to start IRC section
+[irc]
+
+#You can configure multiple servers "[irc.name]" or "[irc.name2]"
+#In this example we use [irc.freenode]
+#REQUIRED
+[irc.freenode]
+#irc server to connect to. 
+#REQUIRED
+Server="irc.freenode.net:6667"
+
+#Enable to use TLS connection to your irc server. 
+#OPTIONAL (default false)
+UseTLS=false
+
+#Enable SASL (PLAIN) authentication. (freenode requires this from eg AWS hosts)
+#It uses NickServNick and NickServPassword as login and password
+#OPTIONAL (default false)
+UseSASL=false
+
+#Enable to not verify the certificate on your irc server. i
+#e.g. when using selfsigned certificates
+#OPTIONAL (default false)
+SkipTLSVerify=true
+
+#Your nick on irc. 
+#REQUIRED
+Nick="matterbot"
+
+#If you registered your bot with a service like Nickserv on freenode. 
+#Also being used when UseSASL=true
+#OPTIONAL
+NickServNick="nickserv"
+NickServPassword="secret"
+
+#RemoteNickFormat defines how remote users appear on this bridge 
+#The string "{NICK}" (case sensitive) will be replaced by the actual nick / username.
+#The string "{BRIDGE}" (case sensitive) will be replaced by the sending bridge
+#The string "{PROTOCOL}" (case sensitive) will be replaced by the protocol used by the bridge
+#OPTIONAL (default {BRIDGE}-{NICK})
+RemoteNickFormat="[{BRIDGE}] <{NICK}> 
+
+#Nicks you want to ignore. 
+#Messages from those users will not be sent to other bridges.
+#OPTIONAL
+IgnoreNicks="ircspammer1 ircspammer2"
+
+###################################################################
+#XMPP section
+###################################################################
+[xmpp]
+
+#You can configure multiple servers "[xmpp.name]" or "[xmpp.name2]"
+#In this example we use [xmpp.jabber]
+#REQUIRED
+[xmpp.jabber]
+#xmpp server to connect to. 
+#REQUIRED
+Server="jabber.example.com:5222"
+
+#Jid
+#REQUIRED
+Jid="user@example.com"
+
+#Password
+#REQUIRED
+Password="yourpass"
+
+#MUC
+#REQUIRED
+Muc="conference.jabber.example.com"
+
+#Your nick in the rooms
+#REQUIRED
+Nick="xmppbot"
+
+
+###################################################################
+#mattermost section
+###################################################################
+[mattermost]
+#You can configure multiple servers "[mattermost.name]" or "[mattermost.name2]"
+#In this example we use [mattermost.work]
+#REQUIRED
+
+[mattermost.work]
+#### Settings for webhook matterbridge.
+#### These settings will not be used when useAPI is enabled
+
+#Url is your incoming webhook url as specified in mattermost. 
+#See account settings - integrations - incoming webhooks on mattermost.
+#REQUIRED (unless useAPI=true)
+URL="https://yourdomain/hooks/yourhookkey"
+
+#Address to listen on for outgoing webhook requests from mattermost.
+#See account settings - integrations - outgoing webhooks on mattermost.
+#This setting will not be used when using -plus switch which doesn't use 
+#webhooks
+#REQUIRED (unless useAPI=true)
+BindAddress="0.0.0.0:9999"
+
+#Icon that will be showed in mattermost. 
+#OPTIONAL
+IconURL="http://youricon.png"
+
+#### Settings for matterbridge -plus
+#### Thse settings will only be used when using the -plus switch.
+
+#### Settings for using matterbridge API
+#OPTIONAL
+useAPI=false
+
+#The mattermost hostname. 
+#REQUIRED (when useAPI=true)
+Server="yourmattermostserver.domain"
+
+#Your team on mattermost. 
+#REQUIRED (when useAPI=true)
+Team="yourteam"
+
+#login/pass of your bot. 
+#Use a dedicated user for this and not your own! 
+#REQUIRED (when useAPI=true)
+Login="yourlogin"
+Password="yourpass"
+
+#Enable this to make a http connection (instead of https) to your mattermost. 
+#OPTIONAL (default false)
+NoTLS=false
+
+#### Shared settings for matterbridge and -plus
+
+#Enable to not verify the certificate on your mattermost server. 
+#e.g. when using selfsigned certificates
+#OPTIONAL (default false)
+SkipTLSVerify=true
+
+#Enable to show IRC joins/parts in mattermost. 
+#OPTIONAL (default false)
+ShowJoinPart=false
+
+#Whether to prefix messages from other bridges to mattermost with the sender's nick. 
+#Useful if username overrides for incoming webhooks isn't enabled on the 
+#mattermost server. If you set PrefixMessagesWithNick to true, each message 
+#from bridge to Mattermost will by default be prefixed by "bridge-" + nick. You can, 
+#however, modify how the messages appear, by setting (and modifying) RemoteNickFormat 
+#OPTIONAL (default false)
+PrefixMessagesWithNick=false
+
+#RemoteNickFormat defines how remote users appear on this bridge 
+#The string "{NICK}" (case sensitive) will be replaced by the actual nick / username.
+#The string "{BRIDGE}" (case sensitive) will be replaced by the sending bridge
+#The string "{PROTOCOL}" (case sensitive) will be replaced by the protocol used by the bridge
+#OPTIONAL (default {BRIDGE}-{NICK})
+RemoteNickFormat="[{BRIDGE}] <{NICK}> 
+
+#how to format the list of IRC nicks when displayed in mattermost. 
+#Possible options are "table" and "plain"
+#OPTIONAL (default plain)
+NickFormatter=plain
+#How many nicks to list per row for formatters that support this. 
+#OPTIONAL (default 4)
+NicksPerRow=4
+
+#Nicks you want to ignore. Messages from those users will not be bridged.
+#OPTIONAL 
+IgnoreNicks="mmbot spammer2"
+
+###################################################################
+#Gitter section
+#Best to make a dedicated gitter account for the bot.
+###################################################################
+
+[gitter]
+
+#You can configure multiple servers "[gitter.name]" or "[gitter.name2]"
+#In this example we use [gitter.myproject]
+#REQUIRED
+[gitter.myproject]
+#Token to connect with Gitter API
+#You can get your token by going to https://developer.gitter.im/docs/welcome and SIGN IN
+#REQUIRED
+Token="Yourtokenhere"
+
+#Nicks you want to ignore. Messages of those users will not be bridged.
+#OPTIONAL 
+IgnoreNicks="spammer1 spammer2"
+
+#RemoteNickFormat defines how remote users appear on this bridge 
+#The string "{NICK}" (case sensitive) will be replaced by the actual nick / username.
+#The string "{BRIDGE}" (case sensitive) will be replaced by the sending bridge
+#The string "{PROTOCOL}" (case sensitive) will be replaced by the protocol used by the bridge
+#OPTIONAL (default {BRIDGE}-{NICK})
+RemoteNickFormat="[{BRIDGE}] <{NICK}> 
+
+###################################################################
+#slack section
+###################################################################
+[slack]
+
+#You can configure multiple servers "[slack.name]" or "[slack.name2]"
+#In this example we use [slack.hobby]
+#REQUIRED
+[slack.hobby]
+#### Settings for webhook matterbridge.
+#### These settings will not be used when useAPI is enabled
+
+#Url is your incoming webhook url as specified in slack
+#See account settings - integrations - incoming webhooks on slack
+#REQUIRED (unless useAPI=true)
+URL="https://hooks.slack.com/services/yourhook"
+
+#Address to listen on for outgoing webhook requests from slack
+#See account settings - integrations - outgoing webhooks on slack
+#This setting will not be used when useAPI is eanbled
+#webhooks
+#REQUIRED (unless useAPI=true)
+BindAddress="0.0.0.0:9999"
+
+#Icon that will be showed in slack
+#OPTIONAL
+IconURL="http://youricon.png"
+
+#### Settings for using slack API
+#OPTIONAL
+useAPI=false
+
+#Token to connect with the Slack API
+#REQUIRED (when useAPI=true)
+Token="yourslacktoken"
+
+#### Shared settings for webhooks and API
+
+#Whether to prefix messages from other bridges to mattermost with the sender's nick. 
+#Useful if username overrides for incoming webhooks isn't enabled on the 
+#slack server. If you set PrefixMessagesWithNick to true, each message 
+#from bridge to Slack will by default be prefixed by "bridge-" + nick. You can, 
+#however, modify how the messages appear, by setting (and modifying) RemoteNickFormat 
+#OPTIONAL (default false)
+PrefixMessagesWithNick=false
+
+#RemoteNickFormat defines how remote users appear on this bridge 
+#The string "{NICK}" (case sensitive) will be replaced by the actual nick / username.
+#The string "{BRIDGE}" (case sensitive) will be replaced by the sending bridge
+#OPTIONAL (default {BRIDGE}-{NICK})
+#The string "{PROTOCOL}" (case sensitive) will be replaced by the protocol used by the bridge
+RemoteNickFormat="[{BRIDGE}] <{NICK}> 
+
+#how to format the list of IRC nicks when displayed in slack
+#Possible options are "table" and "plain"
+#OPTIONAL (default plain)
+NickFormatter=plain
+#How many nicks to list per row for formatters that support this. 
+#OPTIONAL (default 4)
+NicksPerRow=4
+
+#Nicks you want to ignore. Messages from those users will not be bridged.
+#OPTIONAL 
+IgnoreNicks="mmbot spammer2"
+
+
+###################################################################
+#Gateway configuration
+###################################################################
+
+#You can specify multiple gateways using [[gateway]]
+#Each gateway has a [[gateway.in]] and a [[gateway.out]]
+#[[gateway.in]] specifies the account and channels we will receive messages from.
+#[[gateway.out]] specifies the account and channels we will send the messages
+#from [[gateway.in]] to.
+#
+#Most of the time [[gateway.in]] and [[gateway.out]] are the same if you 
+#want bidirectional bridging.
+
+#REQUIRED
+[[gateway]]
+#OPTIONAL (not used for now)
+name="gateway1"
+#Enable enables this gateway
+##OPTIONAL (default false)
+enable=true
+
+    #[[gateway.in]] specifies the account and channels we will receive messages from.
+    #The following example bridges between mattermost and irc
+    [[gateway.in]]
+
+    #account specified above
+    #REQUIRED
+    account="irc.freenode"
+    #channel to connect on that account
+    #REQUIRED
+    channel="#testing"
+
+    [[gateway.in]]
+    account="mattermost.work"
+    channel="off-topic"
+
+    [[gateway.out]]
+    account="irc.freenode"
+    channel="#testing"
+
+    [[gateway.out]]
+    account="mattermost.work"
+    channel="off-topic"

matterbridge.toml.simple

@@ -0,0 +1,32 @@
+[irc]
+    [irc.freenode]
+    Server="irc.freenode.net:6667"
+    Nick="matterbot"
+
+[mattermost]
+    [mattermost.work]
+    useAPI=true
+    Server="yourmattermostserver.domain"
+    Team="yourteam"
+    Login="yourlogin"
+    Password="yourpass"
+    PrefixMessagesWithNick=true
+
+[[gateway]]
+name="gateway1"
+enable=true
+    [[gateway.in]]
+    account="irc.freenode"
+    channel="#testing"
+
+    [[gateway.in]]
+    account="mattermost.work"
+    channel="off-topic"
+
+    [[gateway.out]]
+    account="irc.freenode"
+    channel="#testing"
+
+    [[gateway.out]]
+    account="mattermost.work"
+    channel="off-topic"