Update documentation
Wim
8 years ago
parent
7baf386ede
commit
0816e96831
@ -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.
|
||||
@ -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"
|
||||
@ -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"
|
||||
Loading…
Reference in New Issue