TeamTalk 5 C-API DLL Version 5.22A

Loading...
Searching...
No Matches
TeamTalk Server Setup Guide

This guide explains how to configure and run the included standalone TeamTalk server on either Windows, Mac OS X or Linux. If you plan to write your own TeamTalk server then check out the TeamTalk Server API and the sample applications TeamTalk Java Server Example (jTeamTalkServer) and TeamTalk C++ Server Example (TeamTalkServer).

# TeamTalk Server Executables

The server executables are located in the 'Server' sub-directory of the SDK. Note, however, that the Android and iOS releases of the SDK do not include servers.

Here's a brief overview of the server binaries in each SDK and for each platform:

- TeamTalk Standard Edition
  - Windows server executables
    - `tt5srv.exe` TeamTalk server as console application.
    - `tt5svc.exe` TeamTalk server as an NT service.
  - Mac OS X and Linux server executables
    - `tt5srv` TeamTalk server which can run as a console application and a daemon.
- TeamTalk Professional Edition
  - Windows server executables
    - `tt5prosrv.exe` TeamTalk server with encryption as console application.
    - `tt5prosvc.exe` TeamTalk server with encryption as an NT service.
  - Mac OS X and Linux server executables
    - `tt5prosrv` TeamTalk server with encryption which can run as a console application and a daemon.
  - To run in encrypted mode the server requires a certificate and private key which can be created using OpenSSL. See section Setup TeamTalk Server Encryption on how to do this.

This section outlines the following:

- Configurating the TeamTalk Server
- Starting a TeamTalk Server
- Installing the TeamTalk Windows NT Service
- Setup TeamTalk Server Encryption
- TeamTalk PHP Admin for remote administration

# Configurating the TeamTalk Server

The recommended way to configure the TeamTalk server is to use the `-wizard` option.

The TeamTalk server reads its configuration from an XML file, typically `tt5srv.xml` in the Standard SDK Edition and `tt5prosrv.xml` in Professional SDK Edition. This file can be edited manually (using an UTF-8 aware editor).

Below is an example a TeamTalk 5 Professional server's configuration file:

    <?xml version="1.0" encoding="UTF-8" ?>
    <teamtalk version="5.1">
        <general>
            <server-name>TeamTalk 5 Professional Server (Encrypted)</server-name>
            <motd>My login message to users</motd>
            <max-users>1000</max-users>
            <auto-save>true</auto-save>
            <bind-ip />
            <tcpport>10443</tcpport>
            <udpport>10443</udpport>
            <certificate-file>ttservercert.pem</certificate-file>
            <privatekey-file>ttserverkey.pem</privatekey-file>
            <upnp>false</upnp>
            <login-attempts>0</login-attempts>
            <max-logins-per-ipaddr>0</max-logins-per-ipaddr>
            <user-timeout>60</user-timeout>
            <login-delay-msec>2000</login-delay-msec>
            <bandwidth-limits>
                <voicetx-limit>0</voicetx-limit>
                <vidcaptx-limit>0</vidcaptx-limit>
                <mediafiletx-limit>0</mediafiletx-limit>
                <desktoptx-limit>0</desktoptx-limit>
                <totaltx-limit>0</totaltx-limit>
            </bandwidth-limits>
        </general>
        <file-storage>
            <files-root>files</files-root>
            <max-diskusage>500000000000</max-diskusage>
            <channel-diskquota>50000000</channel-diskquota>
        </file-storage>
        <logging>
            <server-log-maxsize>-1</server-log-maxsize>
        </logging>
        <users>
            <user>
                <username>admin</username>
                <password>admin</password>
                <user-type>2</user-type>
                <user-rights>0</user-rights>
                <note />
                <userdata>0</userdata>
                <init-channel />
                <audiocodec-bps-limit>0</audiocodec-bps-limit>
                <channel-operator />
            </user>
            <user>
                <username>guest</username>
                <password>guest</password>
                <user-type>1</user-type>
                <user-rights>259591</user-rights>
                <note />
                <userdata>0</userdata>
                <init-channel />
                <audiocodec-bps-limit>0</audiocodec-bps-limit>
                <abuse-prevention>
                    <commands-limit>10</commands-limit>
                    <commands-interval-msec>10000</commands-interval-msec>
                </abuse-prevention>
                <channel-operator>
                    <channel>1</channel>
                </channel-operator>
            </user>
            <user>
                <username>facebook</username>
                <password></password>
                <user-type>1</user-type>
                <user-rights>521735</user-rights>
                <note>Default user rights for Facebook users</note>
                <userdata>0</userdata>
                <init-channel></init-channel>
                <audiocodec-bps-limit>0</audiocodec-bps-limit>
                <channel-operator />
            </user>
            <user>
                <username>bearware</username>
                <password></password>
                <user-type>1</user-type>
                <user-rights>521735</user-rights>
                <note>Default user rights for BearWare.dk weblogin users</note>
                <userdata>0</userdata>
                <init-channel />
                <audiocodec-bps-limit>0</audiocodec-bps-limit>
                <channel-operator />
            </user>
            <user>
                <username>myname@bearware.dk</username>
                <password></password>
                <user-type>2</user-type>
                <user-rights>0</user-rights>
                <note>Administrator account from BearWare.dk weblogin</note>
                <userdata>0</userdata>
                <init-channel />
                <audiocodec-bps-limit>0</audiocodec-bps-limit>
                <channel-operator />
            </user>
        </users>
        <serverbans>
            <serverban address="192.168.11.44">
                <bantime>2009/10/12 12:48</bantime>
                <nickname>Benjamin</nickname>
                <username>ben</username>
                <channel-path>/Conf ABC</channel-path>
            </serverban>
        </serverbans>
        <permanent-channels>
            <channel>
                <!--Channel: /-->
                <channel-id>1</channel-id>
                <password></password>
                <topic></topic>
                <diskquota>51200000000</diskquota>
                <op-password></op-password>
                <max-users>1000</max-users>
                <channel-type>1</channel-type>
                <userdata>0</userdata>
                <audio-codec>
                    <codec-type>1</codec-type>
                    <bandmode>1</bandmode>
                    <quality>4</quality>
                    <fpp>2</fpp>
                    <sim-stereo>false</sim-stereo>
                </audio-codec>
                <audio-config>
                    <enable-agc>false</enable-agc>
                    <gain-level>0</gain-level>
                    <inc-dbsec-max>0</inc-dbsec-max>
                    <dec-dbsec-max>0</dec-dbsec-max>
                    <gain-db-max>0</gain-db-max>
                    <enable-denoise>false</enable-denoise>
                    <denoise-level>0</denoise-level>
                </audio-config>
                <files>
                    <file name="testmux.wav">
                        <internalname>data_1.dat</internalname>
                        <filesize>107564</filesize>
                        <username>admin</username>
                    </file>
                </files>
            </channel>
        </permanent-channels>
    </teamtalk>

Here is an explanation of each of the tags in the server configuration file:

- `<general>` Tags related to server's configuration.
  - `<server-name>` The server's name.
  - `<motd>` The message of the day (MOTD) which will be available to users once they log in. The MOTD supports the following variables:
    - %users% The number of users on the server.
    - %admins% The number of administrators on the server.
    - %uptime% The time the server has been online.
    - %voicetx% The number of KBytes containing audio which has been forwarded through the server to users.
    - %voicerx% The number of KBytes containing audio which has been received by the server.
    - %lastuser% The nickname of the last user to log on to the server.
  - `<max-users>` The maximum number of users on the server.
  - `<auto-save>` If 'true' the server will automatically save changes to it configuration file whenever the server's configuration is changed. When static channels are either created, updated or deleted this will also be automatically saved to the server's configuration.
  - `<bind-ip>` The server should bind to this IP-address. If the computer running the server has multiple IP-address it is advised to specify the IP-address where the server should be running. If the server should run IPv6 the bind-ip MUST be specified. Use "::" to make the server run IPv6 on all interfaces.
  - `<tcpport>` The TCP port the server must use. Ensure it's not taken by another application.
  - `<udpport>` The UDP port the server must use. Ensure it's not taken by another application.
  - `<certificate-file>` If certificate file and private key file are specified then the server is running in encrypted mode. Read section Setup TeamTalk Server Encryption on how to create certificate and private key files.
  - `<privatekey-file>` Read `<certificate-file>` description above.
  - `<upnp>` If 'true' the server will use UPnP to automatically open the TCP and UDP ports on the router when the server starts. The port mappings are removed when the server stops.
  - `<login-attempts>` The maximum number of log in attempt with incorrect password before banning a user's IP-address.
  - `<max-logins-per-ipaddr>` The maximum number of logins allowed from a single IP-address.
  - `<user-timeout>` The number of seconds a client can be unresponsive without being dropped.
  - <login-delay-msec> The number of miliseconds before the same IP-address can make another login attempt.
  - `<bandwidth-limits>` Tags related to bandwidth usage.
    - `<voicetx-limit>` The maximum number of bytes per second of voice allowed by the server to be forwarded to users.
    - `<vidcaptx-limit>` The maximum number of bytes per second of video allowed by the server to be forwarded to users.
    - `<mediafiletx-limit>` The maximum number of bytes per second of media streaming allowed by the server to be forwarded to users.
    - `<desktoptx-limit>` The maximum number of bytes per second of desktop sharing allowed by the server to be forwarded to users.
    - `<totaltx-limit>` The maximum number of bytes per second of all data allowed by the server to be forwarded to users.
  - `<file-storage>` Tags related to storing files.
    - `<files-root>` If file-sharing is enabled uploaded files will be stored at this location.
    - `<max-diskusage>` The maximum number of bytes available for storing files on the server.
    - `<channel-diskquota>` The default number of bytes available for storing files when a user creates a temporary channel.
  - `<logging>` Tags related to logging
    - `<server-log-maxsize>` The maximum size in bytes of the server log file before it creates a new one (log rotation). Specifying -1 means there is no limit. 0 means don't log events.
  - `<users>` Tags related to user accounts
    - `<user>` Tags related to a user account
      - `<username>` The username of the user account (must be unique). Usernames facebook and bearware are reserved usernames for Facebook and BearWare.dk weblogins.
      - `<password>` The password of the user account.
      - `<user-type>` The type of user. 1 = Default user, 2 = Administrator.
      - `<user-rights>` The user rights assigned to the user. This value is a bitmask where each bit specifies a right on the server. For accounts of user-type Administrator this value is ignored since administrator have unrestricted rights.
      - `<note>` A note assigned to the user account.
      - `<userdata>` A user specific value which can be used by applications to e.g. map the user account to a database.
      - `<init-channel>` The channel which the user should initially join.
      - `<audiocodec-bps-limit>` The highest bitrate for audio codec allowed by the user. Admins do not need to obey this limit.
      - `<abuse-prevention>`
        - `<commands-limit>` The number of commands that can be issued within the time frame specified by <commands-interval-msec>.
        - `<commands-interval-msec>` See description of `<commands-limit>`.
      - `<channel-operator>`
        - `<channel>` The ID of the channel where the user will automatically become channel operator.
- `<server-bans>` Tags related to users who have been banned from the server.
  - `<serverban` address="..."> Tags related to a banned user (IP-address). A banned user where the `address` attribute is the IP-address which has been banned. Note that it's the IP-address which is banned and not the user who own the account.
    - `<bantime>` The time of when the ban was issued.
    - `<nickname>` The nickname of the user at the time of the ban.
    - `<username>` If the user has an account on the server it is specified here.
    - `<channel-path>` The channel the user was in a the time of the ban.
- `<permanent-channels>` Tags related to permanent channels on the server.
  - `<channel>` Tags related to a channel.
    - `<channel-id>` The ID of the channel.
    - `<topic>` The topic of the channel.
    - `<diskquota>` The amount of disk space available for storing files. This value should be less than or equal to `<max-diskusage>`.
    - `<op-password>` A password which any user can use to become channel operator.
    - `<max-users>` The maximum number of users allowed in the channel.
    - `<channel-type>` The type of channel, i.e. classroom, single transmission, etc.
    - `<userdata>` A user specific value which can be used by applications to e.g. map the channel to a database.
    - `<audio-codec>` Tags related to audio codec settings
      - `<codec-type>` The type of codec used, in this case Speex. For Opus the sub-tags would be different.
      - `<bandmode>` Bandmode used by Speex
      - `<quality>` Quality setting for Speex
      - `<fpp>` Frames per packet for Speex
      - `<sim-stereo>` Whether to do stereo playback for Speex
    - `<audio-config>` Audio configuration for the channel
      - `<enable-agc>` Whether users who join should enable AGC.
      - `<gain-level>` Gain level for AGC.
      - `<inc-dbsec-max>` AGC setting for
      - `<dec-dbsec-max>`
      - `<gain-db-max>`
      - `<enable-denoise>`
      - `<denoise-level>`
    - `<files>` Tags related to files in the channel.
      - `<file>` Tags related to a file.
        - `<internalname>` The file name on disk in <files-root>.
        - `<filesize>` The size of the file.
        - `<username>` The owner of the file. The owner of the file can delete it, or a channel operator, or an administrator type user.

# Starting a TeamTalk Server

Try running the server executable to get an overview of the possible ways to run the server.

Note that running the NT service will not give any output since an NT service doesn't have a user-interface. Also note the NT service must be run using the Windows Administrator account.

# Installing the TeamTalk Windows NT Service

In addition to the options described in section Starting a TeamTalk Server the NT Service (`tt5svc.exe` or `tt5prosvc.exe`) also accepts the following parameters:

- `-i` Install the NT service.
- `-s` Start the NT service.
- `-e` Stop the NT service.
- `-u` Uninstall the NT service.

Note the above commands must be run using the Windows Administrator account. Right-click `C:\Windows\system32\cmd.exe` and choose "Run as Administrator".

## Installing multiple Windows NT Services

To install multiple TeamTalk NT Services the `sc.exe` command can be used. Here is an example:

    sc.exe create "TeamTalk Server 2" binPath= "C:\MyServer\tt5svc.exe -wd c:\MyServer" start= auto

The service in the above example will be called "TeamTalk Server 2" in the NT service list. Notice the spaces after `binPath` and `start`. For some strange reason these are required. To start the above service run:

    sc.exe start "TeamTalk Server 2"

To stop it type:

    sc.exe stop "TeamTalk Server 2"

To uninstall it type:

    sc.exe delete "TeamTalk Server 2"

# Setup TeamTalk Server Encryption

Setting up an encrypted TeamTalk server requires a TeamTalk Professional server.

A TeamTalk server supports two types of encryptions:

- Encrypted connection from client to server
- Encrypted connection from client to server where the authenticity of both ends are verified.

When running the server setup wizard (`-wizard` option) the server will ask which type of encryption to use.

## Simple client/server encryption

The simplest way to start an encrypted TeamTalk server is to generate a certificate and private key file.

Run the following command line using OpenSSL to generate the certificate and privte key:

    $ openssl req -newkey rsa:4096 -keyout ttserverkey.pem -nodes -x509 -days 3650 -out ttservercert.pem -outform PEM

Now run the server's setup wizard to specify the location of the certificate and private key files. Alternatively fill out tags `<certificate-file>` and `<privatekey-file>` in `tt5prosrv.xml` (see section Configurating the TeamTalk Server).

To test if the server is running in encrypted mode try the following command:

    $ openssl s_client -connect 127.0.0.1:10443

## Verifying client/server connections

Doing peer verification, i.e. verifying the authenticity of the remote end, requires a quite complicated setup.

First the client and server must agree on a Certificate Authority (CA) which creates certificates.

To generate a certificate authority (CA) cert run the following command:

    $ openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer

Now generate the server's private key:

    $ openssl genrsa -out ttserverkey.pem 4096

Now generate the server's certificate request to the CA:

    $ openssl req -new -key ttserverkey.pem -out server.req -sha256

Now use the server's certificate request to generate the server's certificate:

    $ openssl x509 -req -in server.req -CA ca.cer -CAkey ca.key -set_serial 100 -extensions server -days 3600 -outform PEM -out ttservercert.pem -sha256

The procedure for the client's certificate and private key are similar. First generate the client's private key:

    $ openssl genrsa -out ttclientkey.pem 4096

Now generate the client's certificate request to the CA:

    $ openssl req -new -key ttclientkey.pem -out client.req -sha256

Now use the client's certificate request to generate the client's certificate:

    $ openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 3600 -outform PEM -out ttclientcert.pem

To test if the server is running in encrypted mode with peer verification try the following command:

    $ openssl s_client -connect 127.0.0.1:10443 -cert ttclientcert.pem -key ttclientkey.pem

After the above operations the following files have been generated:

- `ca.cer`
  - The Certificate Authority (CA) cert (in this case self-signed).
  - Both client and server must use the same CA cert to be able to verify certificates authenticity.
- `ca.key`
  - The Certificate Authority (CA) private key. Never give this to anyone.
- `ttserverkey.pem`
  - The server's private key required to run the server in encrypted mode. Never give this to anyone.
- `ttservercert.pem`
  - The server's certificate required to run the server in encrypted mode.
- `ttclientkey.pem`
  - The client's private key required for peer verification. Generate a new private key for each client.
- `ttclientcert.pem`
  - The client's certificate required for peer verification. Generate a new certificate for each client.

Now run the TeamTalk server's wizard and specify that the server should verify peer connections. The following files will be need in the process: `ca.cer`, `ttserverkey.pem`, `ttservercert.pem`

The TeamTalk server also supports multiple Certificate Authorities. In this case a directory must be specified where the server can't find all CA certs.

# TeamTalk PHP Admin for remote administration

The 'Server' sub-directory also contains a PHP script named `tt5admin.php` which can be used for remote administation of a TeamTalk server. The TeamTalk PHP Admin must be executed in a console.