How To Install & Configure a TURN server for Zimbra Connect

All around Zimbra Chat, give us your feedback, questions and ideas
User avatar
rleiker
Advanced member
Advanced member
Posts: 149
Joined: Tue Jan 07, 2020 8:23 pm
Location: Kansas City
Contact:

How To Install & Configure a TURN server for Zimbra Connect

Post by rleiker »

If you happen to be working on a installing or configuring Zimbra Connect, and you have found in your testing any of the following:
  • Callers are unable to connect
  • Callers cannot see each other's video/screen shares
  • Callers cannot hear each other's audio
  • Chat messages are not being received
This indicates you may need to setup a TURN server. One option for a TURN server is the reTURN project from https://www.resiprocate.org/Main_Page . A TURN server acts as an intermediary relay allowing callers to connect to each other, when they cannot make a direct connection using the WebRTC protocol.

Zextras has a write-up for installing reTURN on their Wiki, but some of the information appears to be outdated: Here is a summary of what I did to get reTURN server working successfully with Zimbra Connect on CentOS 7. These steps should be easily adaptable to Ubuntu by swapping the "yum" commands for the equivalent "apt" commands.

1.) Install CentOS with the minimal install options, and set the host name, ip address, DNS, gateway options.

2.) Upon first boot, run "yum upgrade" then reboot.

3.) Run "yum install epel-release". This installs the repo where the reTURN server can be installed.

4.) Run "yum install resiprocate-turn-server"

5.) In the /etc/reTurn/reTurnServer.config file, make these changes:

Required Settings
TurnAddress = your server's public IP address (1.2.3.4)
TurnPort = 3478
AuthenticationRealm = any valid domain name (example.com)
UserDatabaseHashedPasswords = true
AllocationPortRangeMin = 49152
AllocationPortRangeMax = 65535

Optional Settings
TlsTurnPort = 443
TlsServerCertificateFilename = server.pem

All other settings not mentioned above can be left at their defaults.

6.) If you set the optional settings noted above, you will need to either setup Let's Encrypt or purchase an SSL certificate. In server.pem, you'll need to include the private key, domain certificate, and CA certificate, in that order, concatenated together in a single file.

7.) You'll need to create a single user account for Zimbra Connect to authenticate with the reTURN server. For example, if you want to create a user name of "zimbra", a password of "long-password" and you set the AuthenticationRealm value in step 5 above to "example.com", run this command:

echo -n zimbra:example.com:long-password | md5sum

This will create an MD5 hash that looks like:
403f476b81442de0bf2df8424bad31b3 -

Next, open the /etc/reTurn/users.txt file, comment out the test user sample and add a new line:

zimbra:403f476b81442de0bf2df8424bad31b3:example.com:authorized

The syntax is: login:password:realm:state.

8.) On your reTURN server you will need to open these firewall ports:
  • Required
    • TCP 3478, UDP 3478
    • UDP 49152 - 65535
  • Optional
    • TCP 443
The optional TCP 443 port is only needed if you set the TlsTurnPort and TlsServerCertificateFilename options in step 5 above.

9.) Start the TURN service: "systemctl restart resiprocate-turn-server", then check the /var/log/messages and /var/log/reTurn/reTurnServer.log log files. If all is working well, you should see log entries similar to:

Mar 19 16:36:47 turn reTurnServer: INFO | 20200319-163647.815 | | RETURN | 140267831281792 | ReTurnConfig.cxx:293 | Processed 1 user(s) from 23 line(s) in /etc/reTurn/users.txt

You can also run "netstat -npl | grep -i turn" to confirm that reTURN is listening to the expected ports:

tcp 0 0 1.2.3.4:3478 0.0.0.0:* LISTEN 1102/reTurnServer
tcp 0 0 1.2.3.4 :443 0.0.0.0:* LISTEN 1102/reTurnServer
tcp6 0 0 :::3478 :::* LISTEN 1102/reTurnServer
tcp6 0 0 :::443 :::* LISTEN 1102/reTurnServer
udp 0 0 1.2.3.4 :3478 0.0.0.0:* 1102/reTurnServer
udp6 0 0 :::3478 :::* 1102/reTurnServer

10.) Finally, from your Zimbra server, where the mailboxd service is installed, as the Zimbra user, run:

zxsuite connect iceServer add turn:1.2.3.4:3478?transport=udp credential long-password username zimbra

Where:
  • "1.2.3.4:3478?transport=udp" is the public IP address, port number, and transport for your reTURN server
  • "long-password" is the password that you setup in step 7
  • "zimbra" is the user name that you setup in step 7
For more information on this command, refer to: https://zimbra.github.io/adminguide/lat ... urn_server . If you need to remove the reTURN server from Zimbra, run:

zxsuite connect iceServer remove turn:1.2.3.4:3478?transport=udp credential long-password username zimbra

To see a list of registered TURN servers in Zimbra, use: "zxsuite connect iceServer get"

Tips
After the installation of a TURN server and configuration of the TURN server in Zimbra, if callers are still having trouble connecting, or chat messages are not being received, you can use this site to test your reTURN server: https://webrtc.github.io/samples/src/co ... ickle-ice/ . If problems continue, next check the WebRTC capabilities of the clients using:
jerds
Posts: 2
Joined: Fri Apr 10, 2020 6:03 am

Re: How To Install & Configure a TURN server for Zimbra Connect

Post by jerds »

What is the recommended for stun/turn server, does it need to be in public? Where is the right place to put my stun/turn server?
User avatar
L. Mark Stone
Ambassador
Ambassador
Posts: 2796
Joined: Wed Oct 09, 2013 11:35 am
Location: Portland, Maine, US
ZCS/ZD Version: 10.0.6 Network Edition
Contact:

Re: How To Install & Configure a TURN server for Zimbra Connect

Post by L. Mark Stone »

reSIProcate is a popular package, bundled with all the major Linux distros.

And yes, the server ports need to be public so end users can connect directly (after Zimbra directs their Connect video streams there).

Mark
___________________________________
L. Mark Stone
Mission Critical Email - Zimbra VAR/BSP/Training Partner https://www.missioncriticalemail.com/
AWS Certified Solutions Architect-Associate
jerds
Posts: 2
Joined: Fri Apr 10, 2020 6:03 am

Re: How To Install & Configure a TURN server for Zimbra Connect

Post by jerds »

what is the recommend for STUN/TURN server? it must be NATed or outside firewall?
User avatar
rleiker
Advanced member
Advanced member
Posts: 149
Joined: Tue Jan 07, 2020 8:23 pm
Location: Kansas City
Contact:

Re: How To Install & Configure a TURN server for Zimbra Connect

Post by rleiker »

jerds wrote:what is the recommend for STUN/TURN server? it must be NATed or outside firewall?
Jerds,

Please refer to my original post in this topic for the recommended STUN/TURN server (the reTURN project from reSIProcate).

The STUN/TURN server cannot be NAT'ed, but you should install a host-based firewall (firewalld, iptables, or similar) on the STUN/TURN server. Refer to my original post in this topic for the specific TCP/UDP ports that will need to be opened. The STUN/TURN server must be on a public IP address, accessible by any other Internet connected host, and preferably on the same network subnet as the Zimbra mailboxd server running Zimbra Connect. This is necessary, as end users need to be able to make a direct connection to the STUN/TURN server for WebRTC streaming. When a client connects to the STUN/TURN server for streaming, they'll connect over a randomly selected high numbered UDP port in the range mentioned in my original post.
User avatar
L. Mark Stone
Ambassador
Ambassador
Posts: 2796
Joined: Wed Oct 09, 2013 11:35 am
Location: Portland, Maine, US
ZCS/ZD Version: 10.0.6 Network Edition
Contact:

Re: How To Install & Configure a TURN server for Zimbra Connect

Post by L. Mark Stone »

Hi Randy,

Your instructions are great, again, thanks! But can you point me to the reference that says the TURN server may not be NAT’d please?

All the best,
Mark
___________________________________
L. Mark Stone
Mission Critical Email - Zimbra VAR/BSP/Training Partner https://www.missioncriticalemail.com/
AWS Certified Solutions Architect-Associate
User avatar
rleiker
Advanced member
Advanced member
Posts: 149
Joined: Tue Jan 07, 2020 8:23 pm
Location: Kansas City
Contact:

Re: How To Install & Configure a TURN server for Zimbra Connect

Post by rleiker »

L. Mark Stone wrote:Hi Randy,

Your instructions are great, again, thanks! But can you point me to the reference that says the TURN server may not be NAT’d please?

All the best,
Mark
Hi Mark,

I have not found a specific reference in the reTURN documentation that says the a STUN/TURN server cannot be NAT'ed, but I think an example may help explain why a STUN/TURN server should not be NAT'ed. Assume someone has setup this topology:

Internet -> (public IP address) Firewall/NAT Router (192.168.0.254) -> NAT'ed hosts

For the NAT'ed hosts, you have two hosts:

Zimbra Mailbox server: 192.168.0.1
STUN/TURN server: 192.168.0.2

In this instance, someone would need to configure the Zimbra mailbox server to connect to the STUN/TURN server using the router's public IP address and port number (UDP 3478). This creates a network hairpin situation where all packets sent from the Zimbra server have to go to the router, than back to the STUN/TURN server. If the network owner were to configure the Zimbra mailbox server to use 192.168.0.2 for reaching the TURN server, then Zimbra would advertise this same 192.168.0.2 IP address to WebRTC clients for streaming, and if a client receives the 192.168.0.2 address, then of course that's not a routable IP address on the pubic Internet, which would make the TURN server unreachable by the client. The correct IP address to use by Zimbra admins for configuring a TURN server in this scenario is likely to be widely misunderstood.

Additionally, many NAT routers have default policies not to allow new sessions through to internal NAT'ed hosts without an existing established network session. It is possible to of course override this by configuring the router to allow any host on the Internet to make an unsolicited (aka "new") connection to a host on the NAT'ed network, but to do so, the router would need to be configured to allow new sessions to be created on any UDP port ranging from 49152 - 65535, which WebRTC clients will rely on for making a connection to the TURN server for streaming. But, this creates a new potential problem for the network owner. Many modern NAT routers use PAT (port address translation), and PAT relies on having a large enough pool of available port numbers available on the router's public IP interface for hosts on the NAT'ed hosts to use for connections out to the Internet. If you have a lot of simultaneous streams to your TURN server, or a busy internal NAT'ed network, you could be looking at a situation where the NAT router exhausts it pool of available port numbers that it can allocate out to new network sessions.

So to be more accurate I should say, you could use NAT with a STUN/TURN server, but it is a bad idea to do so and is asking for trouble.
User avatar
L. Mark Stone
Ambassador
Ambassador
Posts: 2796
Joined: Wed Oct 09, 2013 11:35 am
Location: Portland, Maine, US
ZCS/ZD Version: 10.0.6 Network Edition
Contact:

Re: How To Install & Configure a TURN server for Zimbra Connect

Post by L. Mark Stone »

Hi Randy,

Thanks for the explanation; makes sense when using IP addresses.

Suppose however you have a NAT'd Zimbra system and a NAT'd STUN/TURN server, but that when you instantiated the STUN/TURN server in Zimbra, you used the FQDN of the STUN/TURN server instead of an IP address?

The Zimbra server will find the STUN/TURN server on its RFC 1918 IP address (if it's local to Zimbra), and the end users will find the STUN/TURN server via a public DNS lookup, which will resolve the STUN/TURN server's public IP address. Split DNS effectively.

IOW (some elements changed for security):

Code: Select all

zimbra@mail6:~$ zxsuite connect iceServer get

        global                                              
        values                                  

                attribute                                                   teamChatIceServerList
                value                                   

                        credential                                                          <snip>
                        url                                                                 turn:stun3.missioncriticalemail.com:3478?transport=udp
                        username                                                            turn-user3


zimbra@mail6:~$ 
Do you see any reason that wouldn't work?

All the best,
Mark
___________________________________
L. Mark Stone
Mission Critical Email - Zimbra VAR/BSP/Training Partner https://www.missioncriticalemail.com/
AWS Certified Solutions Architect-Associate
User avatar
rleiker
Advanced member
Advanced member
Posts: 149
Joined: Tue Jan 07, 2020 8:23 pm
Location: Kansas City
Contact:

Re: How To Install & Configure a TURN server for Zimbra Connect

Post by rleiker »

L. Mark Stone wrote: Suppose however you have a NAT'd Zimbra system and a NAT'd STUN/TURN server, but that when you instantiated the STUN/TURN server in Zimbra, you used the FQDN of the STUN/TURN server instead of an IP address?
If split DNS is configured correctly, which many admins seem to struggle with, I think that would solve the network hairpin issue. The part I'm not sure about is if this configuration would create a problem when the Zimbra Connect server registers an ICE session with the TURN server from a private network IP block (RFC 1918), which is then advertised to WebRTC clients on a Zimbra Connect video call. The question becomes, does the Zimbra Connect server first resolve the hostname to an IP, and register with the TURN server using the IP, or does it use the FQDN for the session?
User avatar
L. Mark Stone
Ambassador
Ambassador
Posts: 2796
Joined: Wed Oct 09, 2013 11:35 am
Location: Portland, Maine, US
ZCS/ZD Version: 10.0.6 Network Edition
Contact:

Re: How To Install & Configure a TURN server for Zimbra Connect

Post by L. Mark Stone »

rleiker wrote:
L. Mark Stone wrote: Suppose however you have a NAT'd Zimbra system and a NAT'd STUN/TURN server, but that when you instantiated the STUN/TURN server in Zimbra, you used the FQDN of the STUN/TURN server instead of an IP address?
If split DNS is configured correctly, which many admins seem to struggle with, I think that would solve the network hairpin issue. The part I'm not sure about is if this configuration would create a problem when the Zimbra Connect server registers an ICE session with the TURN server from a private network IP block (RFC 1918), which is then advertised to WebRTC clients on a Zimbra Connect video call. The question becomes, does the Zimbra Connect server first resolve the hostname to an IP, and register with the TURN server using the IP, or does it use the FQDN for the session?
Interesting question; we should ask Cine tomorrow!
___________________________________
L. Mark Stone
Mission Critical Email - Zimbra VAR/BSP/Training Partner https://www.missioncriticalemail.com/
AWS Certified Solutions Architect-Associate
Post Reply