diff options
| -rw-r--r-- | README-0.6.md | 115 | ||||
| -rw-r--r-- | README.md | 45 | ||||
| -rw-r--r-- | changelog.md | 9 | ||||
| -rw-r--r-- | matterbridge.toml.sample | 308 | ||||
| -rw-r--r-- | matterbridge.toml.simple | 32 |
5 files changed, 490 insertions, 19 deletions
diff --git a/README-0.6.md b/README-0.6.md new file mode 100644 index 00000000..f25f4574 --- /dev/null +++ b/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. @@ -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. diff --git a/changelog.md b/changelog.md index c8e1d84e..e01b8aaf 100644 --- a/changelog.md +++ b/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 diff --git a/matterbridge.toml.sample b/matterbridge.toml.sample new file mode 100644 index 00000000..5315b412 --- /dev/null +++ b/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" diff --git a/matterbridge.toml.simple b/matterbridge.toml.simple new file mode 100644 index 00000000..30104d98 --- /dev/null +++ b/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" |