From 85c11b69e3af16d8b7ef8749dc97082779e0f6c9 Mon Sep 17 00:00:00 2001 From: Pavel Punsky Date: Thu, 22 Dec 2022 11:13:24 -0800 Subject: [PATCH] Move and split documentation files (#1096) This is not a long term documentation works - this is a temp proposal to modernize existing documentation - Create docs folder - Move existing documentation files into docs - Split one massive INSTALL files into smaller files (no text editing was done except small markdown header formatting) - Rename files to be markdowns for nicer rendering - Bad md rendering is expected in many places --- INSTALL | 1248 +------------------------------- README.turnserver | 10 +- configure | 8 +- docs/Build.md | 452 ++++++++++++ docs/ClientLib.md | 8 + docs/Configuration.md | 6 + docs/Man.md | 11 + docs/Management.md | 30 + docs/Mongo.md | 31 + docs/MySQL.md | 86 +++ docs/OpenSSL.md | 41 ++ docs/Performance.md | 5 + docs/PostInstall.md | 39 + docs/PostgreSQL.md | 131 ++++ docs/Redis.md | 67 ++ docs/SQLite.md | 155 ++++ docs/Testing.md | 82 +++ netarch.txt => docs/netarch.md | 12 +- postinstall.txt | 40 +- 19 files changed, 1161 insertions(+), 1301 deletions(-) create mode 100644 docs/Build.md create mode 100644 docs/ClientLib.md create mode 100644 docs/Configuration.md create mode 100644 docs/Man.md create mode 100644 docs/Management.md create mode 100644 docs/Mongo.md create mode 100644 docs/MySQL.md create mode 100644 docs/OpenSSL.md create mode 100644 docs/Performance.md create mode 100644 docs/PostInstall.md create mode 100644 docs/PostgreSQL.md create mode 100644 docs/Redis.md create mode 100644 docs/SQLite.md create mode 100644 docs/Testing.md rename netarch.txt => docs/netarch.md (97%) diff --git a/INSTALL b/INSTALL index 2245e27..121527d 100644 --- a/INSTALL +++ b/INSTALL @@ -1,1247 +1 @@ -I. TURN Server as a standard OS package - -At the present time, several operation systems have this project pre-packaged: - -1) New Linuxes in Debian family have package "coturn": - -http://packages.qa.debian.org/r/coturn.html - -which can be installed the usual way: apt install coturn - -If instead you are using the Debian package from the project download site, -then follow these instructions: - -Unpack the archive: - - $ tar xvfz turnserver-<...>.tar.gz - -Read the INSTALL file: - - $ cat INSTALL - -Install the *.deb file: - - $ sudo apt-get update - $ sudo apt-get install gdebi-core - $ sudo gdebi coturn*.deb - -(to install the bare package without any dependencies, type: - - $ sudo dpkg -i coturn_*_*.deb) - -After the install, read the documentation in /usr/share/doc/coturn directory. - -All binaries will be installed in /usr/bin/ directory. -The turn*.conf config files are in /etc directory. - -The service start-up control scripts will be in /etc/init.d/coturn and -in /etc/defaults/coturn files. - -2) ArchLinux has this TURN server package: - -https://aur.archlinux.org/packages/coturn/ - -3) FreeBSD and OpenSUSE have the predecessor of this project packaged -(rfc5766-turn-server). - -II. DOWNLOAD - -You have to download the archive file turnserver-*.tar.gz and unpack it: - -$ tar xfz turnserver-*.tgz - -it will create the directory 'turnserver-*' with all sources, build files, -examples and documentation. - -III. BUILD - -1) Use autoconfigure build - -If you are sure that you system is ready for the build (see the section -"Extra libraries and Utilities" below) then you can build the system. -First, you have to run the configure script: - - $ cd turnserver-* - $ ./configure - -It will create a Makefile customized for your system. - -By default, the generated Makefile will install everything to: - - - /usr on Solaris. - - /usr/pkg on NetBSD. - - /usr/local everywhere else. - -The binaries will be copied to the bin subdirectory of the installation -destination, config files copied to etc subdirectory. The default SQLite database -will be created in var/db/turndb. There will be -also documents, examples and some other files, in separate directories. - -You can change the root configured destination directory by -setting PREFIX variable in the -configure command line. For example: - - $ PREFIX=/opt ./configure - -Or: - - $ ./configure --prefix=/opt - - You can change the auxiliary configured destination sub-directories by -setting BINDIR, CONFDIR, MANPREFIX, EXAMPLESDIR, DOCSDIR, LIBDIR, SCHEMADIR, -LOCALSTATEDIR, TURNDBDIR and TURNINCLUDEDIR variables in the -configure command line. For example: - - $ PREFIX=/opt BINDIR=/opt/bin64 CONFDIR=/opt/conf ./configure - -Or: - - $ ./configure --prefix=/opt --bindir=/opt/bin64 --confdir=/opt/conf - - You also can change the compilation and link options by -setting common build variables in the -configure command line. For example: - - $ CC=clang CFLAGS=-D_CAURIB LDFLAGS=-lshanka ./configure --prefix=/opt/shy - -See below a separate INSTALL section for more details. - -The script "configure" is a proprietary script. It will create a Makefile -that you can use to build the project: - - $ make - -The make command without options will do the following: - - compile the code. - - create bin/ sub-directory and put the TURN server, TURN admin and - "utility" programs there. - - create lib/ sub-directory and put the client library there. - - create include/turn/ sub-directory and put include files there. - - create sqlite/turndb default empty database that will be copied to - var/db/ during the installation. - -The TURN programs can be either called directly, or a shell scripts can be used. -The script examples are located in examples/scripts directory. These scripts -are just examples: you can run them successfully for the tests, but -you will have to change the script parameters for your real environment. - -The command: - - $ sudo make install - -will install everything into the system file structure (see below). - -(NOTE: On NetBSD, use "su root -c"). - -The command: - - $ sudo make deinstall - -will remove all installed TURN Server files from your system. - -The command: - - $ make clean - -will clean all results of the build and configuration actions. - -Do not run "make clean" before "make deinstall". The "clean" command will -remove the Makefile and you will not be able to "deinstall" then. If that -has happened, then run ./configure and make again, then deinstall and then -clean. - -NOTE: On most modern systems, the build will produce dynamically linked -executables. If you want statically linked executables, you have to modify, -accordingly, the Makefile.in template file. - -2) Use cmake build - -If you are sure that you system is ready for the build (see the section -"Extra libraries and Utilities" below) and cmake tools then you can build -the system. -First, create build directory. you have to run the follow script: - - $ cd coturn - $ mkdir build - -Then you have to run the configure script: - - $ cmake .. - -It will create a Makefile customized for your system. - -By default, the generated Makefile will install everything to: - - - /usr on Solaris. - - /usr/pkg on NetBSD. - - /usr/local everywhere else. - -The binaries will be copied to the bin subdirectory of the installation -destination, config files copied to etc subdirectory. The default SQLite database -will be created in var/db/turndb. There will be -also documents, examples and some other files, in separate directories. - -You can change the root configured destination directory by -setting CMAKE_INSTALL_PREFIX variable in the -configure command line. For example: - - $ cmake .. -DCMAKE_INSTALL_PREFIX=/opt - -Build the project: - - $ cmake --build . - -Install all files(runtime programmes and develop library): - - $ cmake --build . --target install - -Remove all installed: - - $ cmake --build . --target uninstall - -If you want to only install runtime programmes(programmes, configure files, -script files and database): - - $ cmake --build . --target install-runtime - -Remove all installed: - - $ cmake --build . --target uninstall-runtime - -IV. OPENSSL - -If you are using the OpenSSL that is coming with your system, and you are -OK with it, then you do not have to read this chapter. If your system has -an outdated OpenSSL version, or if you need some very fresh OpenSSL features -that are not present in the current usual stable version, then you may have -to compile (and run) your TURN server with a different OpenSSL version. - -For example, if you need ALPN feature, or DTLS1.2, and your system comes with -OpenSSL 1.0.1, you will not be able to use those features unless you install -OpenSSL 1.0.2 and compile and run the TURN server with the newer version. - -The problem is, it is usually not safe to replace the system's OpenSSL with -a different version. Some systems are "bound" to its "native" OpenSSL -installations, and their behavior may become unpredictable with the newer -versions. - -So you want to preserve your system's OpenSSL but you want to compile and to -run the TURN server with newer OpenSSL version. There are different ways to -do that. We are suggesting the following: - - 1) Download the OpenSSL version from openssl.org. - 2) Let's assume that we want to install the "custom" OpenSSL into /opt. - Configure and build OpenSSL as: - $ ./config --prefix=/opt - $ make - $ make install - Those commands will install OpenSSL into /opt, with static libraries (no - dynamic libraries). - 3) Build the TURN server: - $ ./configure --prefix=/opt - $ make - Those commands will build the TURN server binaries, statically linked - against the newer OpenSSL. - 4) Then you can run the TURN server without setting the dynamic - libraries paths - because it has been linked statically against the newer - OpenSSL libraries. - -One potential problem is that libevent2 is using the OpenSSL, too. So, ideally, -to be 100% safe of all potential discrepancies in the runtime, we'd suggesting -rebuilding libevent2 with the newer OpenSSL, too. - -V. INSTALL - -This step is optional. You can run the turnserver from the original build -directory, successfully, without installing the TURN server into your system. -You have to install the turnserver only if you want to integrate the -turnserver in your system. - -Run the command: - -$ make install - -It will install turnserver in /usr/local/ directory (or to whatever directory -was set in the PREFIX variable). You will have to copy -/usr/local/etc/turnserver.conf.default to /usr/local/etc/turnserver.conf file -and adjust your runtime configuration. - -This command will also: - - - copy the content of examples subdirectory into - PREFIX/share/examples/turnserver/ directory; - - copy the generated default empty SQLite database from sqlite/turndb - to /usr/local/var/db or to /var/db/turndb; - - copy the content of include/turn subdirectory into - PREFIX/include/turn/ directory; - - copy the database schema file turndb/schema.sql into - PREFIX/share/turnserver/ - directory; - - copy all docs into PREFIX/share/doc/turnserver/ directory. - -The installation destination of "make install" can be changed by -using DESTDIR variable, for example: - - $ ./configure --prefix=/usr - $ make - $ make DESTDIR=/opt install - -In this example, the root installation directory will be /opt/usr. - -The "configure" script by default generates a Makefile with "rpath" option -set for the dynamic libraries linking (if your system and your compiler -allow that option). If that is not desirable (like in some OS packaging -procedures), then run the "configure" script with --disable-rpath option. - -If you are not using the rpath linking option, then after the installation, -you may have to adjust the system-wide shared library search path with -"ldconfig -n " (Linux), "ldconfig -m " (BSD) or -"crle -u -l " (Solaris). Your system must be able to find the -libevent2, openssl and (optionally) SQLite and/or PostgreSQL and/or MySQL -(MariaDB) and/or MongoDB and/or Redis shared libraries, either with the -help of the system-wide library search configuration or by using -LD_LIBRARY_PATH. "make install" will make a non-guaranteed effort to add -automatically PREFIX/lib and /usr/local/lib to the libraries search path, -but if you have some libraries in different non-default directories then -you will have to add them manually to the search path, or you will have -to adjust LD_LIBRARY_PATH. - -VI. PLATFORMS - -The TURN Server is using generic *NIX system APIs and is supposed to be -usable on wide range of *NIX systems. - -The following platforms are supported -(both i386 and x86_64 variants when applicable): - - - Linux, - - BSD family (Mac OS X, FreeBSD, NetBSD, OpenBSD), - - Solaris 11, - - Cygwin - -It must work on other *NIXes, as well. The configure script and/or -Makefile may need adjustments for other *NIXes not mentioned above. - -The code of the client messaging library can be compiled and used on -Windows, too, but it is not supported for now. - -VI. COMPILERS - -The TURN Server is written in C programming language, for portability -and for the performance reasons. - -The tested C compilers are: - - - gcc 3.4.4 thru 4.8.x - - clang 3.0 or better - - Solaris Studio 12 C compiler - -It may be compiled with other compilers, too. - -The code is compatible with C++ compiler, and a C++ compiler -(like g++) can be used for the compilation, too: - - $ CC=g++ ./configure - $ make - -VIII. WHICH EXTRA LIBRARIES AND UTILITIES YOU NEED - -In addition to common *NIX OS services and libraries, to compile this code, -OpenSSL (version 1.0.0a or better recommended) and libevent2 (version 2.0.5 -or better) are required, SQLite C development library and header is optional, -the PostgreSQL C client development setup is optional, -the MySQL (MariaDB) C client development setup is optional, -the MongoDB C Driver and the Hiredis development files for Redis database -access are all optional. For development build, the development headers and -the libraries to link with, are to be installed. For the runtime, only the -runtime setup is required. If the build is modified for -static linking, then even runtime installation is not needed. - -OpenSSL, SQLite, libevent2, PostgreSQL, MySQL (or MariaDB) and Hiredis -libraries can be downloaded from their web sites: - - http://www.openssl.org (required); - - http://www.libevent.org (required); - - http://www.sqlite.org (optional); - - http://www.postgresql.org (optional); - - http://www.mysql.org (or http://mariadb.org) (optional); - - https://github.com/mongodb/mongo-c-driver (optional); - - http://redis.io (optional). - -The installations are pretty straightforward - the usual -"./configure" and "make install" commands. Install them into their default -locations - the configure script and the Makefile are assuming that they are -installed in their default locations. If not, then you will have to modify -those. - -Most modern popular systems (FreeBSD, Linux Ubuntu/Debian/Mint, Amazon Linux, Fedora) -have a simpler way of the third party tools installation: - - *) FreeBSD (the FRESH ports database is assumed to be installed, with - the turnserver port included): - - $ cd /usr/ports/net/turnserver - $ sudo make install clear - - That's it - that command will install the TURN server with all necesary - thrid-party tools. - - If you system have no fresh ports repository: - - $ cd /usr/ports/security/openssl/ - $ sudo make install clean - $ cd /usr/ports/databases/sqlite3/ - $ sudo make install clean - $ cd /usr/ports/devel/libevent2/ - $ sudo make install clean - $ cd /usr/ports/databases/postgresql84-client/ (or any other version) - $ sudo make install clean - $ cd /usr/ports/databases/mysql51-client/ (or any other version) - $ sudo make install clean - $ cd /usr/ports/databases/hiredis/ - $ sudo make install clean - - **) Linux Ubuntu, Debian, Mint: - - $ sudo apt-get install libssl-dev - $ sudo apt-get install libsqlite3 (or sqlite3) - $ sudo apt-get install libsqlite3-dev (or sqlite3-dev) - $ sudo apt-get install libevent-dev - $ sudo apt-get install libpq-dev - $ sudo apt-get install mysql-client - $ sudo apt-get install libmysqlclient-dev - $ sudo apt-get install libhiredis-dev - - or you can use Synaptic or other software center. - - ***) Fedora: - - $ sudo yum install openssl-devel - $ sudo yum install sqlite - $ sudo yum install sqlite-devel - $ sudo yum install libevent - $ sudo yum install libevent-devel - $ sudo yum install postgresql-devel - $ sudo yum install postgresql-server - $ sudo yum install mysql-devel - $ sudo yum install mysql-server - $ sudo yum install hiredis - $ sudo yum install hiredis-devel - - ****) Amazon Linux is similar to Fedora, but: - - - you have to install gcc first: - $ sudo yum install gcc - - - mongo-c-driver packages are not available "automatically". - MongoDB support will not be compiled, unless you install it "manually" - before the TURN server compilation. Refer to - https://github.com/mongodb/mongo-c-driver for installation instructions - of the driver. - - - hiredis packages are not available, so do not issue the - hiredis installation commands. Redis support will not be - compiled, unless you install it "manually" before the TURN - server compilation. For Amazon EC2 AMIs, we install the - redis manually in the system. But the TURN server can be - perfectly installed without redis support - if you do not - need it. - - *****) Older Debian family Linuxes are using some packages - with different names. - - ******) On some CentOS / RedHat 6.x systems you have to install - libevent2 "manually", and optionally you have to download and - install Hiredis, but everything else can be found in the software - repository. Also, if you would like to make an RPM for CentOS, - check the directory rpm/ with the instructions. - -NOTE: If your tools are installed in non-standard locations, you will -have to adjust CFLAGS and LDFLAGS environment variables for TURN -server ./configure script. For example, to configure the TURN server -with Solaris 11 PostgreSQL 32-bits setup, you may use a command -like this: - - $ CFLAGS="${CFLAGS} -I/usr/postgres/9.2-pgdg/include/" LDFLAGS="${LDFLAGS} -L/usr/postgres/9.2-pgdg/lib/" ./configure - -Dynamic library paths: - -You may also have to adjust the turn server start script, add all the dynamic runtime -library paths to LD_LIBRARY_PATH. Or you may find that it would be more convenient to adjust the -system-wide shared library search path by using commands: - -on Linux: - - $ ldconfig -n - -or on BSD: - - $ ldconfig -m - -or on Solaris: - - $ crle -u -l - -On Mac OS X, you have three different choices for dynamic libraries handling: - -1) Use DYLD_LIBRARY_PATH environment variable in runtime; OR - -2) Before the compilation, check the dynamic libraries and adjust their identification names, -if necessary, to the absolute library path or to @rpath/. -For example, the MySQL dynamic library may need that adjustment. You will have to use -"adjust_name_tool" with -id option for that; OR - -3) After the compilation, you can use the same tool, "adjust_name_tool", -with option -change, to adjust the library paths values in the binary, -where necessary. All library paths must be absolute paths or @rpath/... . - -See also the next section. - -NOTE: See "SQLite setup" and "PostgreSQL setup" and "MySQL setup" and -"MongoDB setup" and "Redis setup" sections below for more database setup -information. - -NOTE: If you do not install SQLite or PostgreSQL or MySQL or MongoDB or Redis, -then you will be limited to the command-line options for user database. -It will work great for development setup, but for real runtime systems you -will need SQLite or PostgreSQL or MySQL or MongoDB or Redis. - -NOTE: To run PostgreSQL or MySQL or MongoDB or Redis server on the same system, -you will also have to install a corresponding PostgreSQL or MySQL or -MongoDB or Redis server package. The DB C development packages only provide -development libraries, and client libraries only provide client -access utilities and runtime libraries. The server packages may -include everything - client, C development and server runtime. - -NOTE: OpenSSL to be installed before libevent2. When libevent2 is building, -it is checking whether OpenSSL has been already installed, and which version -of OpenSSL. If the OpenSSL is missed, or too old, then libevent_openssl -library is not being created during the build, and you will not be able to -compile the TURN Server with TLS support. - -NOTE: An older libevent version, version 1.x.x, is often included in some *NIX -distributions. That version has its deficiencies and is inferior to the newer -libevent2, especially in the performance department. This is why we are -not providing backward compatibility with the older libevent 1.x version. -If you have a system with older libevent, then you have to install the new -libevent2 from their web site. It was tested with older *NIXes -(like FreeBSD 6.x) and it works just fine. - -NOTE: SQLite must be of version 3.x. - -NOTE: For extra security features (like DTLS) -support, OpenSSL version 1.0.0a or newer is recommended. Older versions do -not support DTLS, reliably, in some cases. For example, the Debian 'Squeeze' -Linux supplies 0.9.8 version of OpenSSL, that does not work correctly with -DTLS over IPv6. If your system already has an older version of OpenSSL -installed (usually in directory /usr) then you may want to install your -newer OpenSSL "over" the old one (because it will most probably will not allow -removal of the old one). When installing the newer OpenSSL, run the OpenSSL's -configure command like this: - - $ ./config --prefix=/usr - -that will set the installation prefix to /usr (without "--prefix=/usr" -by default it would be installed to /usr/local). This is necessary if you -want to overwrite your existing older OpenSSL installation. - -IX. BUILDING WITH NON-DEFAULT PREFIX DIRECTORY - -Say, you have an older system with old openssl and old libevent -library and you do not want to change that, but you still want -to build the turnserver. - -Do the following steps: - -1) Download new openssl from openssl.org. -2) Configure and build new openssl and install it into /opt: - - $ ./config --prefix=/opt - $ make - $ make install - -3) Download the latest libevent2 from libevent.org, configure and install -it into /opt: - - $ ./configure --prefix=/opt - $ make - $ make install - -4) Change directory to coturn and build it: - - $ ./configure --prefix=/opt - $ make - -After that, you can either use it locally, or install it into /opt. -But remember that to run it, you have to adjust your LD_LIBRARY_PATH, -like that: - - $ LD_LIBRARY_PATH=/opt/lib ./bin/turnserver - -An alternative would be adjusting the system-wide shared library search path -by using - $ ldconfig -n (Linux) - $ ldconfig -m (BSD) - $ crle -u -l (Solaris) - -X. TEST SCRIPTS - -First of all, you can use the test vectors from RFC 5769 to double-check that the -STUN/TURN message encoding algorithms work properly. Run the utility: - - $ cd examples - $ ./scripts/rfc5769.sh - -It will perform several protocol checks and print the results on the output. -If anything has compiled wrongly (TURN Server, or OpenSSL libraries) -then you will see some errors. - -Now, you can perform the TURN functionality test (bare minimum TURN example). - -If everything compiled properly, then the following programs must run -together successfully, simulating TURN network routing in local loopback -networking environment: - -Open two shell screens or consoles: - -In shell number 1, run TURN server application: - $ cd examples - $ ./scripts/basic/relay.sh - -In shell number 2, run test client application: - - $ cd examples - $ ./scripts/basic/udp_c2c_client.sh - -If the client application produces output and in approximately 22 seconds -prints the jitter, loss and round-trip-delay statistics, then everything is -fine. - -There is another more complex test: - -In shell number 1, run TURN server application: - $ cd examples - $ ./scripts/basic/relay.sh - -In shell number 2, run "peer" application: - $ cd examples - $ ./scripts/peer.sh - -In shell number 3, run test client application: - - $ cd examples - $ ./scripts/basic/udp_client.sh (or ./scripts/basic/tcp_client.sh) - -There is a similar set of examples/scripts/longtermsecure/* scripts for -TURN environment with long-term authentication mechanism. This set of -scripts is more complex, and checking the scripts options is useful for -understanding how the TURN Server works: - -In shell number 1, run secure TURN server application: - $ cd examples - $ ./scripts/longtermsecure/secure_relay.sh - -In shell number 2, run "peer" application: - $ cd examples - $ ./scripts/peer.sh - -In shell number 3, run secure test client application: - - $ cd examples - $ ./scripts/longtermsecure/secure_udp_client.sh - - (or ./scripts/longtermsecure/secure_tcp_client.sh) - (or ./scripts/longtermsecure/secure_tls_client.sh) - (or ./scripts/longtermsecure/secure_dtls_client.sh) - (or ./scripts/longtermsecure/secure_sctp_client.sh) - (or ./scripts/longtermsecure/secure_udp_c2c.sh for "peerless" -client-to-client communications) - -The provided scripts are set for the local loopback communications, -as an example and as a test environment. Real networking IPs must be -used in real work environments. - -Try wireshark to check the communications between client, turnserver -and the peer. - -Check the README.* files and the comments in the scripts relay.sh and -secure_relay.sh as a guidance how to run the TURN server. - -XI. OS X compilation notes - -OS X usually has an older version of openssl supplied, with some Apple -additions. The the "native" openssl will work, within its limitations, -but the best option is to install a good fresh openssl development -library, from http://www.openssl.org. You will have -to handle the dynamic linking of the generated binaries, or use the -static linking (see the section OPENSSL). - -XII. MS Windows and Cygwin support - -Currently, this project cannot be compiled under MS Windows. - -As the project is using fairly straightforward *NIX API, it is supported -under Cygwin environment in MS Windows. - -One note for Cygwin users: we recommended libevent2 installation from the cygwin -"ports" site: http://sourceware.org/cygwinports/ . You will have to install -libevent2 runtime and libevent-devel packages. "Manual" libevent2 compilation -and installation in Cygwin is not recommended and does not garantee a good -outcome. - -XIII. CLIENT API LIBRARY. - -The compilation process will create lib/ sub-directory with libturnclient.a -library. The header files for this library are located in include/turn/client/ -sub-directory. The C++ wrapper for the messaging functionality is located in -TurnMsgLib.h header. An example of C++ code can be found in stunclient.c file. -This file is compiled as a C++ program if C++ compiler is used, and as a C -program if C compiler is used. - -XIV. DOCS - -After installation, the man page turnserver(1) must be available. The man page -is located in man/man1 subdirectory. If you want to see the man page without -installation, run the command: - - $ man -M man turnserver - -HTML-formatted client library functions reference is located in docs/html -subdirectory of the original archive tree. After the installation, it will -be placed in PREFIX/share/doc/turnserver/html. - -XV. SQLite setup - -The site http://www.sqlite.org site has excellent extensive documentation. - -The default SQLite database location for the TURN Server is -/usr/local/var/db/turndb or /var/db/turndb (depending on the platform). - -The database schema for the TURN server is very minimalistic and is located -in project's turndb/schema.sql file, or in the system's -PREFIX/share/turnserver/schema.sql file after the turnserver installation: - -If you would like to created a new fresh SQLite TURN database: - -$ sqlite3 < turndb/schema.sql - -The schema description: - -# Table for long-term credentials mechanism authorization: -# -CREATE TABLE turnusers_lt ( - realm varchar(127) default '', - name varchar(512), - hmackey char(128), - PRIMARY KEY (realm,name) -); - -The field hmackey contains HEX string representation of the key. -We do not store the user open passwords for long-term credentials, for -security reasons. Storing only the HMAC key has its own implications - -if you change the realm, you will have to update the HMAC keys of all -users, because the realm is used for the HMAC key generation. - -The key must be up to 32 characters (HEX representation of 16 bytes) for SHA1: - -# Table holding shared secrets for secret-based authorization -# (REST API). Shared secret can be stored either in unsecure open -# plain form, or in encrypted form (see turnadmin docs). -# It can only be used together with the long-term -# mechanism: -# -CREATE TABLE turn_secret ( - realm varchar(127) default '', - value varchar(127), - primary key (realm,value) -); - -# Table holding "white" allowed peer IP ranges. -# -CREATE TABLE allowed_peer_ip ( - realm varchar(127) default '', - ip_range varchar(256), - primary key (realm,ip_range) -); - -# Table holding "black" denied peer IP ranges. -# -CREATE TABLE denied_peer_ip ( - realm varchar(127) default '', - ip_range varchar(256), - primary key (realm,ip_range) -); - -# Table to match origin to realm. -# Multiple origins may have the same realm. -# If no realm is found or the origin is absent -# then the default realm is used. -# -CREATE TABLE turn_origin_to_realm ( - origin varchar(127), - realm varchar(127), - primary key (origin,realm) -); - -# Realm options. -# Valid options are 'max-bps', -# 'total-quota' and 'user-quota'. -# Values for them are integers (in text form). -# -CREATE TABLE turn_realm_option ( - realm varchar(127) default '', - opt varchar(32), - value varchar(128), - primary key (realm,opt) -); - -# oAuth key storage table. -# -CREATE TABLE oauth_key ( - kid varchar(128), - ikm_key varchar(256), - timestamp bigint default 0, - lifetime integer default 0, - as_rs_alg varchar(64) default '', - realm varchar(127) default '', - primary key (kid) -); - -The oauth_key table fields meanings are: - - kid: the kid of the key; - - ikm_key - base64-encoded key ("input keying material"); - - timestamp - (optional) the timestamp (in seconds) when the key - lifetime starts; - - lifetime - (optional) the key lifetime in seconds; the default value - is 0 - unlimited lifetime. - - as_rs_alg - oAuth token encryption algorithm; the valid values are - "A256GCM", "A128GCM" (see - http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40#section-5.1). - The default value is "A256GCM"; - - realm - (optional) can be used to set the user realm (if the field is not empty). - -# Https access admin users. -# Leave this table empty if you do not want -# remote https access to the admin functions. -# Web user password can be stored either in unsecure open -# plain form, or in encrypted form (see turnadmin docs). -# -CREATE TABLE admin_user ( - name varchar(32), - realm varchar(127), - password varchar(127), - primary key (name) -); - -You can use turnadmin program to manage the database - you can either use -turnadmin to add/modify/delete users, or you can use turnadmin to produce -the hmac keys and modify the database with your favorite tools. - -When starting the turnserver, the --db parameter will be, for example: - -turnserver ... --db="/var/db/turndb" - -You will have to use the program turnadmin to fill the -database, or you can do that manually with psql. - -Fill in users, for example: - - Shared secret for the TURN REST API (realm north.gov): - - $ bin/turnadmin -s logen -r north.gov -b "/var/db/turndb" - - Long-term credentials mechanism: - - $ bin/turnadmin -a -b "/var/db/turndb" -u gorst -r north.gov -p hero - $ bin/turnadmin -a -b "/var/db/turndb" -u ninefingers -r north.gov -p youhavetoberealistic - - Admin users: - - $ bin/turnadmin -A -b "/var/db/turndb" -u gorst -p hero - $ bin/turnadmin -A -b "/var/db/turndb" -u ninefingers -p youhavetoberealistic -r north.gov - -XVI. PostgreSQL setup - -The site http://www.postgresql.org site has excellent extensive documentation. -For a quick-start guide, you can take a look into this page: -http://www.freebsddiary.org/postgresql.php. That page is written for -FreeBSD users, but it has lots of generic information applicable to other -*NIXes, too. - -For the psql-userdb TURN server parameter, you can either set a PostgreSQL -connection string, or a PostgreSQL URI, see the link: - -For 8.4 PostgreSQL version: -http://www.postgresql.org/docs/8.4/static/libpq-connect.html - -For newer 9.x versions: -http://www.postgresql.org/docs/9.2/static/libpq-connect.html#LIBPQ-CONNSTRING. - -In the PostgreSQL connection string or URI, you can set the host, the -access port, the database name, the user, and the user password -(if the access is secured). Numerous other parameters can be set, -see the links above. The TURN server will blindly use that connection -string without any modifications. You are responsible for the right -connection string format. - -Below are the steps to setup the PostgreSQL database server from scratch: - -1) Install PostgreSQL server. After the installation, do not forget to -initialize the postgres root database directory: - - $ sudo bash - $ su -l pgsql - $ initdb -D /usr/local/pgsql/data - -2) Find and edit Postgres' pg_hba.conf file to set the access options -(see docs). On different systems, it may be located in different places. -Set the lines for local access as "trust" for now (you can change it later), -for TCP/IP access set the value as "md5". -To set TCP/IP access from any host, use "0.0.0.0/0" for IPv4, and "::/0" -for IPv6. - -3) Edit postgresql.conf file to allow TCP/IP access - uncomment and edit -the "listen_addresses" option (see docs). On different systems, this file -may be located in different places. - -4) Restart your system or restart the postgresql server, for example: - - $ sudo /etc/init.d/postgresql stop - $ sudo /etc/init.d/postgresql start - - The scripts may also be in /usr/local/etc/init.d, or in /etc/rc.d/, or - in /usr/local/etc/rc.d/ . - -5) Check /etc/passwd file to find out which user account is used for the -PostgreSQL admin access on your system (it may be "pgsql", or "postgres", -or "postgresql"). Let's assume that this is "postgres" account. - -6) Create a database for the TURN purposes, with name, say, "turn": - - $ createdb -U postgres coturn - -7) Create a user for the TURN with name, say, "turn": - $ psql -U postgres coturn - turn=# create user turn with password 'turn'; - turn=# - Ctrl-D - -8) Create the TURN users database schema. - -The database schema for the TURN server is very minimalistic and is located -in project's turndb/schema.sql file, or in the system's -PREFIX/share/turnserver/schema.sql file after the turnserver installation: - -$ cat turndb/schema.sql | psql -U turn -d coturn - NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index "turnusers_lt_pkey" for table "turnusers_lt" - CREATE TABLE - CREATE TABLE - -See the SQLite section for the detailed database schema explanation. - -To fill the database with test data: - -cat turndb/testsqldbsetup.sql | psql -U turn -d coturn - -You can use turnadmin program to manage the database - you can either use -turnadmin to add/modify/delete users, or you can use turnadmin to produce -the hmac keys and modify the database with your favorite tools. - -More examples of database schema creation: - -psql -h -U -d < turndb/schema.sql -(old style for 8.4) - -psql postgresql://username:password@/databasename < turndb/schema.sql -(newer style for 9.x, UNIX domain local sockets) - -Or: - -psql postgresql://username:password@hostname:port/databasename < turndb/schema.sql -(newer style for 9.x, TCP/IP access) - -Below, the string "postgresql://turn:turn@/turn" is the connection URI. -Of course, the administrators can play with the connection string as they want. - -When starting the turnserver, the psql-userdb parameter will be, for example: - -turnserver ... --psql-userdb="host=localhost dbname=coturn user=turn password=turn connect_timeout=30" - -Or, for 9.x PostgreSQL versions: -turnserver ... --psql-userdb=postgresql://username:password@/databasename ... - -9) You are ready to use the TURN database. The database name is "turn", -the user name is "turn", the user password is "turn". Of course, you can -choose your own names. Now, you will have to use the program turnadmin to fill the -database, or you can do that manually with psql. - -Fill in users, for example: - - Shared secret for the TURN REST API (realm north.gov): - - $ bin/turnadmin -s logen -r north.gov -e "host=localhost dbname=coturn user=turn password=turn" - - Long-term credentials mechanism: - - $ bin/turnadmin -a -e "host=localhost dbname=coturn user=turn password=turn" -u gorst -r north.gov -p hero - $ bin/turnadmin -a -e "host=localhost dbname=coturn user=turn password=turn" -u ninefingers -r north.gov -p youhavetoberealistic - - Admin users: - - $ bin/turnadmin -A -e "host=localhost dbname=coturn user=turn password=turn" -u gorst -p hero - $ bin/turnadmin -A -e "host=localhost dbname=coturn user=turn password=turn" -u ninefingers -p youhavetoberealistic -r north.gov - -XVII. MySQL (MariaDB) setup - -The MySQL setup is similar to PostgreSQL (the same idea), and is well documented -on their site http://www.mysql.org. The TURN Server database schema is the -same as for PostgreSQL and you can find it in turndb/schema.sql file, or -in the system's PREFIX/share/turnserver/schema.sql file after the turnserver -installation. - -The general setup is similar to PostgreSQL setup procedure: - -1) Check that the mysql server access is OK. Immediately after the MySQL server -installation, it must be accessible, at the very minimum, at the localhost with -the root account. - -2) Login into mysql console from root account: - - $ sudo bash - # mysql mysql - -(or mysql -p mysql if mysql account password set) - -3) Add 'turn' user with 'turn' password (for example): - - > create user 'turn'@'localhost' identified by 'turn'; - -4) Create database 'coturn' (for example) and grant privileges to user 'turn': - - > create database coturn character set latin1; - > grant all on coturn.* to 'turn'@'localhost'; - > flush privileges; - Ctrl-D - -5) Create database schema: - - $ mysql -p -u turn coturn < turndb/schema.sql - Enter password: turn - $ - - Fill in test database data, if this is a test database - (not a production database): - - $ mysql -p -u turn coturn < turndb/testsqldbsetup.sql - -6) Fill in users, for example: - - Shared secret for the TURN REST API (realm north.gov): - - $ bin/turnadmin -s logen -r north.gov -M "host=localhost dbname=coturn user=turn password=turn" - - Long-term credentials mechanism: - - $ bin/turnadmin -a -M "host=localhost dbname=coturn user=turn password=turn" -u gorst -r north.gov -p hero - $ bin/turnadmin -a -M "host=localhost dbname=coturn user=turn password=turn" -u ninefingers -r north.gov -p youhavetoberealistic - - Admin users: - - $ bin/turnadmin -A -M "host=localhost dbname=coturn user=turn password=turn" -u gorst -p hero - $ bin/turnadmin -A -M "host=localhost dbname=coturn user=turn password=turn" -u ninefingers -p youhavetoberealistic -r north.gov - -7) Now we can use mysql in the turnserver. - -If the TURN server was compiled with MySQL support, then we can use the -TURN server database parameter --mysql-userdb. The value of this parameter -is a connection string for the MySQL database. As "native" MySQL does not -have such a feature as "connection string", the TURN server parses the -connection string and converts it into MySQL database connection parameter. -The format of the MySQL connection string is: - -"host= dbname= user= password= port= connect_timeout= read_timeout=" - -(all parameters are optional) - -So, an example of the MySQL database parameter in the TURN server command -line would be: - ---mysql-userdb="host=localhost dbname=coturn user=turn password=turn connect_timeout=30 read_timeout=30" - -Or in the turnserver.conf file: - -mysql-userdb="host=localhost dbname=coturn user=turn password=turn connect_timeout=30 read_timeout=30" - -If you have to use a secure MySQL connection (SSL) then you have to use also -the optional connection string parameters for the secure communications: -ca, capath, cert, key, cipher (see -http://dev.mysql.com/doc/refman/5.1/en/ssl-options.html for the -command options description). - -XVIII. MongoDB setup - -The MongoDB setup is well documented on their site http://docs.mongodb.org/manual/. - -Note: if your system has a "standard" plain vanilla UNIX "make" utility -(that is not a GNU make) then you will have to use the GNU make to compile -the Mongo driver, because the Mongo compilation process was written with -the "proprietary" GNU extensions. For example, in FreeBSD in will have to use -"gmake" command. - -If the TURN server was compiled with MongoDB support (mongo-c-driver is the C client -library for MongoDB), then we can use the TURN server database parameter ---mongo-userdb. The value of this parameter is a connection string -for the MongoDB database. The format of the connection string is described at -http://hergert.me/docs/mongo-c-driver/mongoc_uri.html: - -"mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]" - -So, an example of the MongoDB database parameter in the TURN server command -line would be: - ---mongo-userdb="mongodb://localhost:27017/coturn" - -Or in the turnserver.conf file: - -mongo-userdb="mongodb://localhost:27017/coturn" - -The meanings of the MongoDB keys are the same as for the other databases, see the -explanations for the Postgres, for example. - -See the file testmongosetup.sh for the database structure examples. - -XIX. Redis setup - -The Redis setup is well documented on their site http://redis.io. -The TURN Server Redis database schema description can be found -in schema.userdb.redis and schema.stats.redis files. Those files are located -either in the turndb subdirectory of the main source code directory, -or in /usr/local/share/turnserver/ after the installation, or somewhere in /usr/share/ -directory, depending on the OS and on the instalation package. - -If the TURN server was compiled with Hiredis support (Hiredis is the C client -library for Redis), then we can use the TURN server database parameter ---redis-userdb. The value of this parameter is a connection string -for the Redis database. As "native" Redis does not have such a feature as -"connection string", the TURN server parses the connection string and -converts it into Redis database access parameter. The format of the Redis -connection string is: - -"ip= dbname= password= port= connect_timeout=" - -(all parameters are optional) - -So, an example of the Redis database parameter in the TURN server command -line would be: - ---redis-userdb="ip=127.0.0.1 dbname=2 password=turn connect_timeout=30" - -Or in the turnserver.conf file: - -redis-userdb="ip=127.0.0.1 dbname=2 password=turn connect_timeout=30" - -Redis can be also used for the TURN allocation status check and for status and -traffic notifications. - -See the explanation in the turndb/schema.stats.redis file, and an example in -turndb/testredisdbsetup.sh file. One special thing about TURN Redis security -setup is that you can store open passwords for long-term credentials in Redis. -You cannot set open passwords for long-term credentials in SQLite or MySQL or -PostgreSQL - with those DBs, you have to use the keys only. With Redis, you -have a choice - keys or open passwords. - -You also have to take care about Redis connection parameters, the timeout and the -keepalive. The following settings must be in your Redis config file -(/etc/redis.conf or /usr/local/etc/redis.conf): - -.......... -timeout 0 -.......... -tcp-keepalive 60 -.......... - -Redis TURN admin commands: - - Shared secret for the TURN REST API (realm north.gov): - - $ bin/turnadmin -s logen -r north.gov -N "host=localhost dbname=2 user=turn password=turn" - - Long-term credentials mechanism: - - $ bin/turnadmin -a -N "host=localhost dbname=2 user=turn password=turn" -u gorst -r north.gov -p hero - $ bin/turnadmin -a -N "host=localhost dbname=2 user=turn password=turn" -u ninefingers -r north.gov -p youhavetoberealistic - - Admin users: - - $ bin/turnadmin -A -N "host=localhost dbname=2 user=turn password=turn" -u gorst -p hero - $ bin/turnadmin -A -N "host=localhost dbname=2 user=turn password=turn" -u ninefingers -p youhavetoberealistic -r north.gov - -See the file testredisdbsetup.sh for the data structure examples. - -XX. Performance tuning - -This topic is covered in the wiki page: - -https://github.com/coturn/coturn/wiki/TURN-Performance-and-Load-Balance - -XXI. TURN Server setup - -Read the project wiki pages: https://github.com/coturn/coturn/wiki - -Also, check the project from page links to the TURN/WebRTC configuration examples. -It may give you an idea how it can be done. - -XXII. HTTPS Management Interface - -The turnserver process provides an HTTPS Web access as statistics and basic management -interface. The turnserver listens to incoming HTTPS admin connections on the same ports -as the main TURN/STUN listener. The Web admin pages are basic and self-explanatory. - -To make the HTTPS interface active, the database table admin_user must be -populated with the admin user account(s). An admin user can be a superuser -(if not assigned to a particular realm) or a restricted user (if assigned to -a realm). The restricted admin users can perform only limited actions, within -their corresponding realms. - -XXIII. Telnet CLI management interface - -You have a telnet interface (enabled by default) to access the turnserver process, -to view its state, to gather some statistical information, and to make some changes -on-the-fly. - -You can access that CLI interface with telnet or putty program (in telnet mode). -The process by default listens to port 5766 on IP address 127.0.0.1 for the telnet -connections. - -WARNING: all telnet communications are going unencrypted over the network. For -security reasons, we advise using the loopback IP addresses for CLI (127.0.0.1 -or ::1). The CLI may have a password configured, but that password is -transferred over the network unencrypted, too. So sticking to the local system -CLI access, and accessing the turnserver system terminal with ssh only, would -be a wise decision. - -XXIV. ALPN support. - -Starting with version 4.3.2.1, the TURN server supports the ALPN STUN -specifications (http://tools.ietf.org/html/draft-ietf-tram-alpn-08). -If the ALPN functionality is needed, then OpenSSL version 1.0.2 or -newer has to be used. See OPENSSL section for the OpenSSL upgrade hints. - -XXV. SCTP support - -Starting with version 4.4.3.1, the TURN server supports 'native' SCTP. -On the client side, the TURN server, additionally, supports SCTP and -TLS-over-SCTP. - -The relay side is not changing - the relay communications will still be UDP -or TCP. - -XXV. Prometheus support. - -See for source and releases for debian packages: -https://github.com/digitalocean/prometheus-client-c +See docs folder or go to https://github.com/coturn/coturn/docs/PostInstall.md \ No newline at end of file diff --git a/README.turnserver b/README.turnserver index 581f422..fd15765 100644 --- a/README.turnserver +++ b/README.turnserver @@ -4,7 +4,7 @@ The TURN Server project contains the source code of a TURN server and TURN clien messaging library. Also, some extra programs provided, for testing-only purposes. -See the INSTALL file for the building instructions. +See the docs/Build.md file for the building instructions. After the build, you will have the following binary images: @@ -108,7 +108,7 @@ User database settings: "postgresql://username:password@hostname:port/databasename" (for 9.x or newer Postgres). - See the INSTALL file for more explanations and examples. + See the docs/PostgreSQL.md file for more explanations and examples. Also, see http://www.PostgreSQL.org for full PostgreSQL documentation. @@ -120,7 +120,7 @@ User database settings: "host= dbname= user= password= connect_timeout= read_timeout=" - See the INSTALL file for more explanations and examples. + See the docs/MySQL.md file for more explanations and examples. Also, see http://www.mysql.org or http://mariadb.org for full MySQL documentation. @@ -143,7 +143,7 @@ User database settings: "mongodb://username:password@host:port/database?options" - See the INSTALL file for more explanations and examples. + See the docs/Mongo.md file for more explanations and examples. Also, see http://docs.mongodb.org/manual/ for full MongoDB documentation. @@ -156,7 +156,7 @@ User database settings: "ip= dbname= password= connect_timeout=" - See the INSTALL file for more explanations and examples. + See the docs/Redis.md file for more explanations and examples. Also, see http://redis.io for full Redis documentation. diff --git a/configure b/configure index 872635b..fc75021 100755 --- a/configure +++ b/configure @@ -830,7 +830,7 @@ else else ${ECHO_CMD} "ERROR: Libevent2 development libraries are not installed properly in required location." ${ECHO_CMD} "ERROR: may be you have just too old libevent tool - then you have to upgrade it." - ${ECHO_CMD} "See the INSTALL file." + ${ECHO_CMD} "See the docs/Build.md file." ${ECHO_CMD} "Abort." cleanup exit 1 @@ -864,7 +864,7 @@ if [ -z "${TURN_NO_PROMETHEUS}" ] ; then ${ECHO_CMD} ${ECHO_CMD} "Warning: microhttpd development libraries are not installed properly in required location." ${ECHO_CMD} "Prometheus support will be disabled." - ${ECHO_CMD} "See the INSTALL file." + ${ECHO_CMD} "See the docs/Build.md file." ${ECHO_CMD} OSCFLAGS="${OSCFLAGS} -DTURN_NO_PROMETHEUS" fi @@ -872,7 +872,7 @@ if [ -z "${TURN_NO_PROMETHEUS}" ] ; then ${ECHO_CMD} ${ECHO_CMD} "Warning: Libpromhttp development libraries are not installed properly in required location." ${ECHO_CMD} "Prometheus support will be disabled." - ${ECHO_CMD} "See the INSTALL file." + ${ECHO_CMD} "See the docs/Build.md file." ${ECHO_CMD} OSCFLAGS="${OSCFLAGS} -DTURN_NO_PROMETHEUS" fi @@ -880,7 +880,7 @@ if [ -z "${TURN_NO_PROMETHEUS}" ] ; then ${ECHO_CMD} ${ECHO_CMD} "Warning: Libprom development libraries are not installed properly in required location." ${ECHO_CMD} "Prometheus support will be disabled." - ${ECHO_CMD} "See the INSTALL file." + ${ECHO_CMD} "See the docs/Build.md file." ${ECHO_CMD} OSCFLAGS="${OSCFLAGS} -DTURN_NO_PROMETHEUS" fi diff --git a/docs/Build.md b/docs/Build.md new file mode 100644 index 0000000..305c708 --- /dev/null +++ b/docs/Build.md @@ -0,0 +1,452 @@ +# Build + +## Using autoconfigure build + +If you are sure that you system is ready for the build (see the section +"Extra libraries and Utilities" below) then you can build the system. +First, you have to run the configure script: + + $ cd turnserver-* + $ ./configure + +It will create a Makefile customized for your system. + +By default, the generated Makefile will install everything to: + + - /usr on Solaris. + - /usr/pkg on NetBSD. + - /usr/local everywhere else. + +The binaries will be copied to the bin subdirectory of the installation +destination, config files copied to etc subdirectory. The default SQLite database +will be created in var/db/turndb. There will be +also documents, examples and some other files, in separate directories. + +You can change the root configured destination directory by +setting PREFIX variable in the +configure command line. For example: + + $ PREFIX=/opt ./configure + +Or: + + $ ./configure --prefix=/opt + + You can change the auxiliary configured destination sub-directories by +setting BINDIR, CONFDIR, MANPREFIX, EXAMPLESDIR, DOCSDIR, LIBDIR, SCHEMADIR, +LOCALSTATEDIR, TURNDBDIR and TURNINCLUDEDIR variables in the +configure command line. For example: + + $ PREFIX=/opt BINDIR=/opt/bin64 CONFDIR=/opt/conf ./configure + +Or: + + $ ./configure --prefix=/opt --bindir=/opt/bin64 --confdir=/opt/conf + + You also can change the compilation and link options by +setting common build variables in the +configure command line. For example: + + $ CC=clang CFLAGS=-D_CAURIB LDFLAGS=-lshanka ./configure --prefix=/opt/shy + +See below a separate INSTALL section for more details. + +The script "configure" is a proprietary script. It will create a Makefile +that you can use to build the project: + + $ make + +The make command without options will do the following: + - compile the code. + - create bin/ sub-directory and put the TURN server, TURN admin and + "utility" programs there. + - create lib/ sub-directory and put the client library there. + - create include/turn/ sub-directory and put include files there. + - create sqlite/turndb default empty database that will be copied to + var/db/ during the installation. + +The TURN programs can be either called directly, or a shell scripts can be used. +The script examples are located in examples/scripts directory. These scripts +are just examples: you can run them successfully for the tests, but +you will have to change the script parameters for your real environment. + +The command: + + $ sudo make install + +will install everything into the system file structure (see below). + +(NOTE: On NetBSD, use "su root -c"). + +The command: + + $ sudo make deinstall + +will remove all installed TURN Server files from your system. + +The command: + + $ make clean + +will clean all results of the build and configuration actions. + +Do not run "make clean" before "make deinstall". The "clean" command will +remove the Makefile and you will not be able to "deinstall" then. If that +has happened, then run ./configure and make again, then deinstall and then +clean. + +NOTE: On most modern systems, the build will produce dynamically linked +executables. If you want statically linked executables, you have to modify, +accordingly, the Makefile.in template file. + +## Using cmake build + +If you are sure that you system is ready for the build (see the section +"Extra libraries and Utilities" below) and cmake tools then you can build +the system. +First, create build directory. you have to run the follow script: + + $ cd coturn + $ mkdir build + +Then you have to run the configure script: + + $ cmake .. + +It will create a Makefile customized for your system. + +By default, the generated Makefile will install everything to: + + - /usr on Solaris. + - /usr/pkg on NetBSD. + - /usr/local everywhere else. + +The binaries will be copied to the bin subdirectory of the installation +destination, config files copied to etc subdirectory. The default SQLite database +will be created in var/db/turndb. There will be +also documents, examples and some other files, in separate directories. + +You can change the root configured destination directory by +setting CMAKE_INSTALL_PREFIX variable in the +configure command line. For example: + + $ cmake .. -DCMAKE_INSTALL_PREFIX=/opt + +Build the project: + + $ cmake --build . + +Install all files(runtime programmes and develop library): + + $ cmake --build . --target install + +Remove all installed: + + $ cmake --build . --target uninstall + +If you want to only install runtime programmes(programmes, configure files, +script files and database): + + $ cmake --build . --target install-runtime + +Remove all installed: + + $ cmake --build . --target uninstall-runtime + + +# INSTALL + +This step is optional. You can run the turnserver from the original build +directory, successfully, without installing the TURN server into your system. +You have to install the turnserver only if you want to integrate the +turnserver in your system. + +Run the command: + +$ make install + +It will install turnserver in /usr/local/ directory (or to whatever directory +was set in the PREFIX variable). You will have to copy +/usr/local/etc/turnserver.conf.default to /usr/local/etc/turnserver.conf file +and adjust your runtime configuration. + +This command will also: + + - copy the content of examples subdirectory into + PREFIX/share/examples/turnserver/ directory; + - copy the generated default empty SQLite database from sqlite/turndb + to /usr/local/var/db or to /var/db/turndb; + - copy the content of include/turn subdirectory into + PREFIX/include/turn/ directory; + - copy the database schema file turndb/schema.sql into + PREFIX/share/turnserver/ + directory; + - copy all docs into PREFIX/share/doc/turnserver/ directory. + +The installation destination of "make install" can be changed by +using DESTDIR variable, for example: + + $ ./configure --prefix=/usr + $ make + $ make DESTDIR=/opt install + +In this example, the root installation directory will be /opt/usr. + +The "configure" script by default generates a Makefile with "rpath" option +set for the dynamic libraries linking (if your system and your compiler +allow that option). If that is not desirable (like in some OS packaging +procedures), then run the "configure" script with --disable-rpath option. + +If you are not using the rpath linking option, then after the installation, +you may have to adjust the system-wide shared library search path with +"ldconfig -n " (Linux), "ldconfig -m " (BSD) or +"crle -u -l " (Solaris). Your system must be able to find the +libevent2, openssl and (optionally) SQLite and/or PostgreSQL and/or MySQL +(MariaDB) and/or MongoDB and/or Redis shared libraries, either with the +help of the system-wide library search configuration or by using +LD_LIBRARY_PATH. "make install" will make a non-guaranteed effort to add +automatically PREFIX/lib and /usr/local/lib to the libraries search path, +but if you have some libraries in different non-default directories then +you will have to add them manually to the search path, or you will have +to adjust LD_LIBRARY_PATH. + + + +# WHICH EXTRA LIBRARIES AND UTILITIES YOU NEED + +In addition to common *NIX OS services and libraries, to compile this code, +OpenSSL (version 1.0.0a or better recommended) and libevent2 (version 2.0.5 +or better) are required, SQLite C development library and header is optional, +the PostgreSQL C client development setup is optional, +the MySQL (MariaDB) C client development setup is optional, +the MongoDB C Driver and the Hiredis development files for Redis database +access are all optional. For development build, the development headers and +the libraries to link with, are to be installed. For the runtime, only the +runtime setup is required. If the build is modified for +static linking, then even runtime installation is not needed. + +OpenSSL, SQLite, libevent2, PostgreSQL, MySQL (or MariaDB) and Hiredis +libraries can be downloaded from their web sites: + - http://www.openssl.org (required); + - http://www.libevent.org (required); + - http://www.sqlite.org (optional); + - http://www.postgresql.org (optional); + - http://www.mysql.org (or http://mariadb.org) (optional); + - https://github.com/mongodb/mongo-c-driver (optional); + - http://redis.io (optional). + +The installations are pretty straightforward - the usual +"./configure" and "make install" commands. Install them into their default +locations - the configure script and the Makefile are assuming that they are +installed in their default locations. If not, then you will have to modify +those. + +Most modern popular systems (FreeBSD, Linux Ubuntu/Debian/Mint, Amazon Linux, Fedora) +have a simpler way of the third party tools installation: + + *) FreeBSD (the FRESH ports database is assumed to be installed, with + the turnserver port included): + + $ cd /usr/ports/net/turnserver + $ sudo make install clear + + That's it - that command will install the TURN server with all necessary + third-party tools. + + If you system have no fresh ports repository: + + $ cd /usr/ports/security/openssl/ + $ sudo make install clean + $ cd /usr/ports/databases/sqlite3/ + $ sudo make install clean + $ cd /usr/ports/devel/libevent2/ + $ sudo make install clean + $ cd /usr/ports/databases/postgresql84-client/ (or any other version) + $ sudo make install clean + $ cd /usr/ports/databases/mysql51-client/ (or any other version) + $ sudo make install clean + $ cd /usr/ports/databases/hiredis/ + $ sudo make install clean + + **) Linux Ubuntu, Debian, Mint: + + $ sudo apt-get install libssl-dev + $ sudo apt-get install libsqlite3 (or sqlite3) + $ sudo apt-get install libsqlite3-dev (or sqlite3-dev) + $ sudo apt-get install libevent-dev + $ sudo apt-get install libpq-dev + $ sudo apt-get install mysql-client + $ sudo apt-get install libmysqlclient-dev + $ sudo apt-get install libhiredis-dev + + or you can use Synaptic or other software center. + + ***) Fedora: + + $ sudo yum install openssl-devel + $ sudo yum install sqlite + $ sudo yum install sqlite-devel + $ sudo yum install libevent + $ sudo yum install libevent-devel + $ sudo yum install postgresql-devel + $ sudo yum install postgresql-server + $ sudo yum install mysql-devel + $ sudo yum install mysql-server + $ sudo yum install hiredis + $ sudo yum install hiredis-devel + + ****) Amazon Linux is similar to Fedora, but: + + - you have to install gcc first: + $ sudo yum install gcc + + - mongo-c-driver packages are not available "automatically". + MongoDB support will not be compiled, unless you install it "manually" + before the TURN server compilation. Refer to + https://github.com/mongodb/mongo-c-driver for installation instructions + of the driver. + + - hiredis packages are not available, so do not issue the + hiredis installation commands. Redis support will not be + compiled, unless you install it "manually" before the TURN + server compilation. For Amazon EC2 AMIs, we install the + redis manually in the system. But the TURN server can be + perfectly installed without redis support - if you do not + need it. + + *****) Older Debian family Linuxes are using some packages + with different names. + + ******) On some CentOS / RedHat 6.x systems you have to install + libevent2 "manually", and optionally you have to download and + install Hiredis, but everything else can be found in the software + repository. Also, if you would like to make an RPM for CentOS, + check the directory rpm/ with the instructions. + +NOTE: If your tools are installed in non-standard locations, you will +have to adjust CFLAGS and LDFLAGS environment variables for TURN +server ./configure script. For example, to configure the TURN server +with Solaris 11 PostgreSQL 32-bits setup, you may use a command +like this: + + $ CFLAGS="${CFLAGS} -I/usr/postgres/9.2-pgdg/include/" LDFLAGS="${LDFLAGS} -L/usr/postgres/9.2-pgdg/lib/" ./configure + +Dynamic library paths: + +You may also have to adjust the turn server start script, add all the dynamic runtime +library paths to LD_LIBRARY_PATH. Or you may find that it would be more convenient to adjust the +system-wide shared library search path by using commands: + +on Linux: + + $ ldconfig -n + +or on BSD: + + $ ldconfig -m + +or on Solaris: + + $ crle -u -l + +On Mac OS X, you have three different choices for dynamic libraries handling: + +1) Use DYLD_LIBRARY_PATH environment variable in runtime; OR + +2) Before the compilation, check the dynamic libraries and adjust their identification names, +if necessary, to the absolute library path or to @rpath/. +For example, the MySQL dynamic library may need that adjustment. You will have to use +"adjust_name_tool" with -id option for that; OR + +3) After the compilation, you can use the same tool, "adjust_name_tool", +with option -change, to adjust the library paths values in the binary, +where necessary. All library paths must be absolute paths or @rpath/... . + +See also the next section. + +NOTE: See "SQLite setup" and "PostgreSQL setup" and "MySQL setup" and +"MongoDB setup" and "Redis setup" sections below for more database setup +information. + +NOTE: If you do not install SQLite or PostgreSQL or MySQL or MongoDB or Redis, +then you will be limited to the command-line options for user database. +It will work great for development setup, but for real runtime systems you +will need SQLite or PostgreSQL or MySQL or MongoDB or Redis. + +NOTE: To run PostgreSQL or MySQL or MongoDB or Redis server on the same system, +you will also have to install a corresponding PostgreSQL or MySQL or +MongoDB or Redis server package. The DB C development packages only provide +development libraries, and client libraries only provide client +access utilities and runtime libraries. The server packages may +include everything - client, C development and server runtime. + +NOTE: OpenSSL to be installed before libevent2. When libevent2 is building, +it is checking whether OpenSSL has been already installed, and which version +of OpenSSL. If the OpenSSL is missed, or too old, then libevent_openssl +library is not being created during the build, and you will not be able to +compile the TURN Server with TLS support. + +NOTE: An older libevent version, version 1.x.x, is often included in some *NIX +distributions. That version has its deficiencies and is inferior to the newer +libevent2, especially in the performance department. This is why we are +not providing backward compatibility with the older libevent 1.x version. +If you have a system with older libevent, then you have to install the new +libevent2 from their web site. It was tested with older *NIXes +(like FreeBSD 6.x) and it works just fine. + +NOTE: SQLite must be of version 3.x. + +NOTE: For extra security features (like DTLS) +support, OpenSSL version 1.0.0a or newer is recommended. Older versions do +not support DTLS, reliably, in some cases. For example, the Debian 'Squeeze' +Linux supplies 0.9.8 version of OpenSSL, that does not work correctly with +DTLS over IPv6. If your system already has an older version of OpenSSL +installed (usually in directory /usr) then you may want to install your +newer OpenSSL "over" the old one (because it will most probably will not allow +removal of the old one). When installing the newer OpenSSL, run the OpenSSL's +configure command like this: + + $ ./config --prefix=/usr + +that will set the installation prefix to /usr (without "--prefix=/usr" +by default it would be installed to /usr/local). This is necessary if you +want to overwrite your existing older OpenSSL installation. + +IX. BUILDING WITH NON-DEFAULT PREFIX DIRECTORY + +Say, you have an older system with old openssl and old libevent +library and you do not want to change that, but you still want +to build the turnserver. + +Do the following steps: + +1) Download new openssl from openssl.org. +2) Configure and build new openssl and install it into /opt: + + $ ./config --prefix=/opt + $ make + $ make install + +3) Download the latest libevent2 from libevent.org, configure and install +it into /opt: + + $ ./configure --prefix=/opt + $ make + $ make install + +4) Change directory to coturn and build it: + + $ ./configure --prefix=/opt + $ make + +After that, you can either use it locally, or install it into /opt. +But remember that to run it, you have to adjust your LD_LIBRARY_PATH, +like that: + + $ LD_LIBRARY_PATH=/opt/lib ./bin/turnserver + +An alternative would be adjusting the system-wide shared library search path +by using + $ ldconfig -n (Linux) + $ ldconfig -m (BSD) + $ crle -u -l (Solaris) \ No newline at end of file diff --git a/docs/ClientLib.md b/docs/ClientLib.md new file mode 100644 index 0000000..e6ef469 --- /dev/null +++ b/docs/ClientLib.md @@ -0,0 +1,8 @@ +# CLIENT API LIBRARY + +The compilation process will create lib/ sub-directory with libturnclient.a +library. The header files for this library are located in include/turn/client/ +sub-directory. The C++ wrapper for the messaging functionality is located in +TurnMsgLib.h header. An example of C++ code can be found in stunclient.c file. +This file is compiled as a C++ program if C++ compiler is used, and as a C +program if C compiler is used. diff --git a/docs/Configuration.md b/docs/Configuration.md new file mode 100644 index 0000000..073a49e --- /dev/null +++ b/docs/Configuration.md @@ -0,0 +1,6 @@ +# TURN Server setup + +Read the project wiki pages: https://github.com/coturn/coturn/wiki + +Also, check the project from page links to the TURN/WebRTC configuration examples. +It may give you an idea how it can be done. \ No newline at end of file diff --git a/docs/Man.md b/docs/Man.md new file mode 100644 index 0000000..263577c --- /dev/null +++ b/docs/Man.md @@ -0,0 +1,11 @@ +# Man pages + +After installation, the man page turnserver(1) must be available. The man page +is located in man/man1 subdirectory. If you want to see the man page without +installation, run the command: + + $ man -M man turnserver + +HTML-formatted client library functions reference is located in docs/html +subdirectory of the original archive tree. After the installation, it will +be placed in PREFIX/share/doc/turnserver/html. diff --git a/docs/Management.md b/docs/Management.md new file mode 100644 index 0000000..32d47a2 --- /dev/null +++ b/docs/Management.md @@ -0,0 +1,30 @@ +# Management Interfaces + +## HTTPS Management Interface + +The turnserver process provides an HTTPS Web access as statistics and basic management +interface. The turnserver listens to incoming HTTPS admin connections on the same ports +as the main TURN/STUN listener. The Web admin pages are basic and self-explanatory. + +To make the HTTPS interface active, the database table admin_user must be +populated with the admin user account(s). An admin user can be a superuser +(if not assigned to a particular realm) or a restricted user (if assigned to +a realm). The restricted admin users can perform only limited actions, within +their corresponding realms. + +## Telnet CLI management interface + +You have a telnet interface (enabled by default) to access the turnserver process, +to view its state, to gather some statistical information, and to make some changes +on-the-fly. + +You can access that CLI interface with telnet or putty program (in telnet mode). +The process by default listens to port 5766 on IP address 127.0.0.1 for the telnet +connections. + +WARNING: all telnet communications are going unencrypted over the network. For +security reasons, we advise using the loopback IP addresses for CLI (127.0.0.1 +or ::1). The CLI may have a password configured, but that password is +transferred over the network unencrypted, too. So sticking to the local system +CLI access, and accessing the turnserver system terminal with ssh only, would +be a wise decision. diff --git a/docs/Mongo.md b/docs/Mongo.md new file mode 100644 index 0000000..50f06bb --- /dev/null +++ b/docs/Mongo.md @@ -0,0 +1,31 @@ +# MongoDB setup + +The MongoDB setup is well documented on their site http://docs.mongodb.org/manual/. + +Note: if your system has a "standard" plain vanilla UNIX "make" utility +(that is not a GNU make) then you will have to use the GNU make to compile +the Mongo driver, because the Mongo compilation process was written with +the "proprietary" GNU extensions. For example, in FreeBSD in will have to use +"gmake" command. + +If the TURN server was compiled with MongoDB support (mongo-c-driver is the C client +library for MongoDB), then we can use the TURN server database parameter +--mongo-userdb. The value of this parameter is a connection string +for the MongoDB database. The format of the connection string is described at +http://hergert.me/docs/mongo-c-driver/mongoc_uri.html: + +"mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]" + +So, an example of the MongoDB database parameter in the TURN server command +line would be: + +--mongo-userdb="mongodb://localhost:27017/coturn" + +Or in the turnserver.conf file: + +mongo-userdb="mongodb://localhost:27017/coturn" + +The meanings of the MongoDB keys are the same as for the other databases, see the +explanations for the Postgres, for example. + +See the file testmongosetup.sh for the database structure examples. diff --git a/docs/MySQL.md b/docs/MySQL.md new file mode 100644 index 0000000..3cd029a --- /dev/null +++ b/docs/MySQL.md @@ -0,0 +1,86 @@ +# MySQL (MariaDB) setup + +The MySQL setup is similar to PostgreSQL (the same idea), and is well documented +on their site http://www.mysql.org. The TURN Server database schema is the +same as for PostgreSQL and you can find it in turndb/schema.sql file, or +in the system's PREFIX/share/turnserver/schema.sql file after the turnserver +installation. + +The general setup is similar to PostgreSQL setup procedure: + +1) Check that the mysql server access is OK. Immediately after the MySQL server +installation, it must be accessible, at the very minimum, at the localhost with +the root account. + +2) Login into mysql console from root account: + + $ sudo bash + # mysql mysql + +(or mysql -p mysql if mysql account password set) + +3) Add 'turn' user with 'turn' password (for example): + + > create user 'turn'@'localhost' identified by 'turn'; + +4) Create database 'coturn' (for example) and grant privileges to user 'turn': + + > create database coturn character set latin1; + > grant all on coturn.* to 'turn'@'localhost'; + > flush privileges; + Ctrl-D + +5) Create database schema: + + $ mysql -p -u turn coturn < turndb/schema.sql + Enter password: turn + $ + + Fill in test database data, if this is a test database + (not a production database): + + $ mysql -p -u turn coturn < turndb/testsqldbsetup.sql + +6) Fill in users, for example: + + Shared secret for the TURN REST API (realm north.gov): + + $ bin/turnadmin -s logen -r north.gov -M "host=localhost dbname=coturn user=turn password=turn" + + Long-term credentials mechanism: + + $ bin/turnadmin -a -M "host=localhost dbname=coturn user=turn password=turn" -u gorst -r north.gov -p hero + $ bin/turnadmin -a -M "host=localhost dbname=coturn user=turn password=turn" -u ninefingers -r north.gov -p youhavetoberealistic + + Admin users: + + $ bin/turnadmin -A -M "host=localhost dbname=coturn user=turn password=turn" -u gorst -p hero + $ bin/turnadmin -A -M "host=localhost dbname=coturn user=turn password=turn" -u ninefingers -p youhavetoberealistic -r north.gov + +7) Now we can use mysql in the turnserver. + +If the TURN server was compiled with MySQL support, then we can use the +TURN server database parameter --mysql-userdb. The value of this parameter +is a connection string for the MySQL database. As "native" MySQL does not +have such a feature as "connection string", the TURN server parses the +connection string and converts it into MySQL database connection parameter. +The format of the MySQL connection string is: + +"host= dbname= user= password= port= connect_timeout= read_timeout=" + +(all parameters are optional) + +So, an example of the MySQL database parameter in the TURN server command +line would be: + +--mysql-userdb="host=localhost dbname=coturn user=turn password=turn connect_timeout=30 read_timeout=30" + +Or in the turnserver.conf file: + +mysql-userdb="host=localhost dbname=coturn user=turn password=turn connect_timeout=30 read_timeout=30" + +If you have to use a secure MySQL connection (SSL) then you have to use also +the optional connection string parameters for the secure communications: +ca, capath, cert, key, cipher (see +http://dev.mysql.com/doc/refman/5.1/en/ssl-options.html for the +command options description). diff --git a/docs/OpenSSL.md b/docs/OpenSSL.md new file mode 100644 index 0000000..65132cd --- /dev/null +++ b/docs/OpenSSL.md @@ -0,0 +1,41 @@ +# OPENSSL + +If you are using the OpenSSL that is coming with your system, and you are +OK with it, then you do not have to read this chapter. If your system has +an outdated OpenSSL version, or if you need some very fresh OpenSSL features +that are not present in the current usual stable version, then you may have +to compile (and run) your TURN server with a different OpenSSL version. + +For example, if you need ALPN feature, or DTLS1.2, and your system comes with +OpenSSL 1.0.1, you will not be able to use those features unless you install +OpenSSL 1.0.2 and compile and run the TURN server with the newer version. + +The problem is, it is usually not safe to replace the system's OpenSSL with +a different version. Some systems are "bound" to its "native" OpenSSL +installations, and their behavior may become unpredictable with the newer +versions. + +So you want to preserve your system's OpenSSL but you want to compile and to +run the TURN server with newer OpenSSL version. There are different ways to +do that. We are suggesting the following: + + 1) Download the OpenSSL version from openssl.org. + 2) Let's assume that we want to install the "custom" OpenSSL into /opt. + Configure and build OpenSSL as: + $ ./config --prefix=/opt + $ make + $ make install + Those commands will install OpenSSL into /opt, with static libraries (no + dynamic libraries). + 3) Build the TURN server: + $ ./configure --prefix=/opt + $ make + Those commands will build the TURN server binaries, statically linked + against the newer OpenSSL. + 4) Then you can run the TURN server without setting the dynamic + libraries paths - because it has been linked statically against the newer + OpenSSL libraries. + +One potential problem is that libevent2 is using the OpenSSL, too. So, ideally, +to be 100% safe of all potential discrepancies in the runtime, we'd suggesting +rebuilding libevent2 with the newer OpenSSL, too. diff --git a/docs/Performance.md b/docs/Performance.md new file mode 100644 index 0000000..22026da --- /dev/null +++ b/docs/Performance.md @@ -0,0 +1,5 @@ +# Performance tuning + +This topic is covered in the wiki page: + +https://github.com/coturn/coturn/wiki/TURN-Performance-and-Load-Balance \ No newline at end of file diff --git a/docs/PostInstall.md b/docs/PostInstall.md new file mode 100644 index 0000000..4950102 --- /dev/null +++ b/docs/PostInstall.md @@ -0,0 +1,39 @@ +# Post Install + +1) If your system supports automatic start-up system daemon services, +then to enable the turnserver as a system service that is automatically +started, you have to: + + a) Create and edit /etc/turnserver.conf or + /usr/local/etc/turnserver.conf . + Use /usr/local/etc/turnserver.conf.default as an example. + + b) For user accounts settings: set up SQLite or PostgreSQL or + MySQL or MongoDB or Redis database for user accounts. + Use /usr/local/share/turnserver/schema.sql as SQL database schema, + or use /usr/local/share/turnserver/schema.userdb.redis as Redis + database schema description and/or + /usr/local/share/turnserver/schema.stats.redis + as Redis status & statistics database schema description. + + If you are using SQLite, the default database location is in + /var/db/turndb or in /usr/local/var/db/turndb or in /var/lib/turn/turndb. + + c) add whatever is necessary to enable start-up daemon for the + /usr/local/bin/turnserver. + +2) If you do not want the turnserver to be a system service, + then you can start/stop it "manually", using the "turnserver" + executable with appropriate options (see the documentation). + +3) To create database schema, use schema in file +/usr/local/share/turnserver/schema.sql. + +4) For additional information, run: + + $ man turnserver + $ man turnadmin + $ man turnutils + +================================================================== + diff --git a/docs/PostgreSQL.md b/docs/PostgreSQL.md new file mode 100644 index 0000000..15fb33a --- /dev/null +++ b/docs/PostgreSQL.md @@ -0,0 +1,131 @@ +# PostgreSQL setup + +The site http://www.postgresql.org site has excellent extensive documentation. +For a quick-start guide, you can take a look into this page: +http://www.freebsddiary.org/postgresql.php. That page is written for +FreeBSD users, but it has lots of generic information applicable to other +*NIXes, too. + +For the psql-userdb TURN server parameter, you can either set a PostgreSQL +connection string, or a PostgreSQL URI, see the link: + +For 8.4 PostgreSQL version: +http://www.postgresql.org/docs/8.4/static/libpq-connect.html + +For newer 9.x versions: +http://www.postgresql.org/docs/9.2/static/libpq-connect.html#LIBPQ-CONNSTRING. + +In the PostgreSQL connection string or URI, you can set the host, the +access port, the database name, the user, and the user password +(if the access is secured). Numerous other parameters can be set, +see the links above. The TURN server will blindly use that connection +string without any modifications. You are responsible for the right +connection string format. + +Below are the steps to setup the PostgreSQL database server from scratch: + +1) Install PostgreSQL server. After the installation, do not forget to +initialize the postgres root database directory: + + $ sudo bash + $ su -l pgsql + $ initdb -D /usr/local/pgsql/data + +2) Find and edit Postgres' pg_hba.conf file to set the access options +(see docs). On different systems, it may be located in different places. +Set the lines for local access as "trust" for now (you can change it later), +for TCP/IP access set the value as "md5". +To set TCP/IP access from any host, use "0.0.0.0/0" for IPv4, and "::/0" +for IPv6. + +3) Edit postgresql.conf file to allow TCP/IP access - uncomment and edit +the "listen_addresses" option (see docs). On different systems, this file +may be located in different places. + +4) Restart your system or restart the postgresql server, for example: + + $ sudo /etc/init.d/postgresql stop + $ sudo /etc/init.d/postgresql start + + The scripts may also be in /usr/local/etc/init.d, or in /etc/rc.d/, or + in /usr/local/etc/rc.d/ . + +5) Check /etc/passwd file to find out which user account is used for the +PostgreSQL admin access on your system (it may be "pgsql", or "postgres", +or "postgresql"). Let's assume that this is "postgres" account. + +6) Create a database for the TURN purposes, with name, say, "turn": + + $ createdb -U postgres coturn + +7) Create a user for the TURN with name, say, "turn": + $ psql -U postgres coturn + turn=# create user turn with password 'turn'; + turn=# + Ctrl-D + +8) Create the TURN users database schema. + +The database schema for the TURN server is very minimalistic and is located +in project's turndb/schema.sql file, or in the system's +PREFIX/share/turnserver/schema.sql file after the turnserver installation: + +$ cat turndb/schema.sql | psql -U turn -d coturn + NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index "turnusers_lt_pkey" for table "turnusers_lt" + CREATE TABLE + CREATE TABLE + +See the SQLite section for the detailed database schema explanation. + +To fill the database with test data: + +cat turndb/testsqldbsetup.sql | psql -U turn -d coturn + +You can use turnadmin program to manage the database - you can either use +turnadmin to add/modify/delete users, or you can use turnadmin to produce +the hmac keys and modify the database with your favorite tools. + +More examples of database schema creation: + +psql -h -U -d < turndb/schema.sql +(old style for 8.4) + +psql postgresql://username:password@/databasename < turndb/schema.sql +(newer style for 9.x, UNIX domain local sockets) + +Or: + +psql postgresql://username:password@hostname:port/databasename < turndb/schema.sql +(newer style for 9.x, TCP/IP access) + +Below, the string "postgresql://turn:turn@/turn" is the connection URI. +Of course, the administrators can play with the connection string as they want. + +When starting the turnserver, the psql-userdb parameter will be, for example: + +turnserver ... --psql-userdb="host=localhost dbname=coturn user=turn password=turn connect_timeout=30" + +Or, for 9.x PostgreSQL versions: +turnserver ... --psql-userdb=postgresql://username:password@/databasename ... + +9) You are ready to use the TURN database. The database name is "turn", +the user name is "turn", the user password is "turn". Of course, you can +choose your own names. Now, you will have to use the program turnadmin to fill the +database, or you can do that manually with psql. + +Fill in users, for example: + + Shared secret for the TURN REST API (realm north.gov): + + $ bin/turnadmin -s logen -r north.gov -e "host=localhost dbname=coturn user=turn password=turn" + + Long-term credentials mechanism: + + $ bin/turnadmin -a -e "host=localhost dbname=coturn user=turn password=turn" -u gorst -r north.gov -p hero + $ bin/turnadmin -a -e "host=localhost dbname=coturn user=turn password=turn" -u ninefingers -r north.gov -p youhavetoberealistic + + Admin users: + + $ bin/turnadmin -A -e "host=localhost dbname=coturn user=turn password=turn" -u gorst -p hero + $ bin/turnadmin -A -e "host=localhost dbname=coturn user=turn password=turn" -u ninefingers -p youhavetoberealistic -r north.gov + diff --git a/docs/Redis.md b/docs/Redis.md new file mode 100644 index 0000000..df39899 --- /dev/null +++ b/docs/Redis.md @@ -0,0 +1,67 @@ +# Redis setup + +The Redis setup is well documented on their site http://redis.io. +The TURN Server Redis database schema description can be found +in schema.userdb.redis and schema.stats.redis files. Those files are located +either in the turndb subdirectory of the main source code directory, +or in /usr/local/share/turnserver/ after the installation, or somewhere in /usr/share/ +directory, depending on the OS and on the instalation package. + +If the TURN server was compiled with Hiredis support (Hiredis is the C client +library for Redis), then we can use the TURN server database parameter +--redis-userdb. The value of this parameter is a connection string +for the Redis database. As "native" Redis does not have such a feature as +"connection string", the TURN server parses the connection string and +converts it into Redis database access parameter. The format of the Redis +connection string is: + +"ip= dbname= password= port= connect_timeout=" + +(all parameters are optional) + +So, an example of the Redis database parameter in the TURN server command +line would be: + +--redis-userdb="ip=127.0.0.1 dbname=2 password=turn connect_timeout=30" + +Or in the turnserver.conf file: + +redis-userdb="ip=127.0.0.1 dbname=2 password=turn connect_timeout=30" + +Redis can be also used for the TURN allocation status check and for status and +traffic notifications. + +See the explanation in the turndb/schema.stats.redis file, and an example in +turndb/testredisdbsetup.sh file. One special thing about TURN Redis security +setup is that you can store open passwords for long-term credentials in Redis. +You cannot set open passwords for long-term credentials in SQLite or MySQL or +PostgreSQL - with those DBs, you have to use the keys only. With Redis, you +have a choice - keys or open passwords. + +You also have to take care about Redis connection parameters, the timeout and the +keepalive. The following settings must be in your Redis config file +(/etc/redis.conf or /usr/local/etc/redis.conf): + +.......... +timeout 0 +.......... +tcp-keepalive 60 +.......... + +Redis TURN admin commands: + + Shared secret for the TURN REST API (realm north.gov): + + $ bin/turnadmin -s logen -r north.gov -N "host=localhost dbname=2 user=turn password=turn" + + Long-term credentials mechanism: + + $ bin/turnadmin -a -N "host=localhost dbname=2 user=turn password=turn" -u gorst -r north.gov -p hero + $ bin/turnadmin -a -N "host=localhost dbname=2 user=turn password=turn" -u ninefingers -r north.gov -p youhavetoberealistic + + Admin users: + + $ bin/turnadmin -A -N "host=localhost dbname=2 user=turn password=turn" -u gorst -p hero + $ bin/turnadmin -A -N "host=localhost dbname=2 user=turn password=turn" -u ninefingers -p youhavetoberealistic -r north.gov + +See the file testredisdbsetup.sh for the data structure examples. diff --git a/docs/SQLite.md b/docs/SQLite.md new file mode 100644 index 0000000..32f3f59 --- /dev/null +++ b/docs/SQLite.md @@ -0,0 +1,155 @@ +SQLite setup + +The site http://www.sqlite.org site has excellent extensive documentation. + +The default SQLite database location for the TURN Server is +/usr/local/var/db/turndb or /var/db/turndb (depending on the platform). + +The database schema for the TURN server is very minimalistic and is located +in project's turndb/schema.sql file, or in the system's +PREFIX/share/turnserver/schema.sql file after the turnserver installation: + +If you would like to created a new fresh SQLite TURN database: + +$ sqlite3 < turndb/schema.sql + +The schema description: + +# Table for long-term credentials mechanism authorization: +# +CREATE TABLE turnusers_lt ( + realm varchar(127) default '', + name varchar(512), + hmackey char(128), + PRIMARY KEY (realm,name) +); + +The field hmackey contains HEX string representation of the key. +We do not store the user open passwords for long-term credentials, for +security reasons. Storing only the HMAC key has its own implications - +if you change the realm, you will have to update the HMAC keys of all +users, because the realm is used for the HMAC key generation. + +The key must be up to 32 characters (HEX representation of 16 bytes) for SHA1: + +# Table holding shared secrets for secret-based authorization +# (REST API). Shared secret can be stored either in unsecure open +# plain form, or in encrypted form (see turnadmin docs). +# It can only be used together with the long-term +# mechanism: +# +CREATE TABLE turn_secret ( + realm varchar(127) default '', + value varchar(127), + primary key (realm,value) +); + +# Table holding "white" allowed peer IP ranges. +# +CREATE TABLE allowed_peer_ip ( + realm varchar(127) default '', + ip_range varchar(256), + primary key (realm,ip_range) +); + +# Table holding "black" denied peer IP ranges. +# +CREATE TABLE denied_peer_ip ( + realm varchar(127) default '', + ip_range varchar(256), + primary key (realm,ip_range) +); + +# Table to match origin to realm. +# Multiple origins may have the same realm. +# If no realm is found or the origin is absent +# then the default realm is used. +# +CREATE TABLE turn_origin_to_realm ( + origin varchar(127), + realm varchar(127), + primary key (origin,realm) +); + +# Realm options. +# Valid options are 'max-bps', +# 'total-quota' and 'user-quota'. +# Values for them are integers (in text form). +# +CREATE TABLE turn_realm_option ( + realm varchar(127) default '', + opt varchar(32), + value varchar(128), + primary key (realm,opt) +); + +# oAuth key storage table. +# +CREATE TABLE oauth_key ( + kid varchar(128), + ikm_key varchar(256), + timestamp bigint default 0, + lifetime integer default 0, + as_rs_alg varchar(64) default '', + realm varchar(127) default '', + primary key (kid) +); + +The oauth_key table fields meanings are: + + kid: the kid of the key; + + ikm_key - base64-encoded key ("input keying material"); + + timestamp - (optional) the timestamp (in seconds) when the key + lifetime starts; + + lifetime - (optional) the key lifetime in seconds; the default value + is 0 - unlimited lifetime. + + as_rs_alg - oAuth token encryption algorithm; the valid values are + "A256GCM", "A128GCM" (see + http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40#section-5.1). + The default value is "A256GCM"; + + realm - (optional) can be used to set the user realm (if the field is not empty). + +# Https access admin users. +# Leave this table empty if you do not want +# remote https access to the admin functions. +# Web user password can be stored either in unsecure open +# plain form, or in encrypted form (see turnadmin docs). +# +CREATE TABLE admin_user ( + name varchar(32), + realm varchar(127), + password varchar(127), + primary key (name) +); + +You can use turnadmin program to manage the database - you can either use +turnadmin to add/modify/delete users, or you can use turnadmin to produce +the hmac keys and modify the database with your favorite tools. + +When starting the turnserver, the --db parameter will be, for example: + +turnserver ... --db="/var/db/turndb" + +You will have to use the program turnadmin to fill the +database, or you can do that manually with psql. + +Fill in users, for example: + + Shared secret for the TURN REST API (realm north.gov): + + $ bin/turnadmin -s logen -r north.gov -b "/var/db/turndb" + + Long-term credentials mechanism: + + $ bin/turnadmin -a -b "/var/db/turndb" -u gorst -r north.gov -p hero + $ bin/turnadmin -a -b "/var/db/turndb" -u ninefingers -r north.gov -p youhavetoberealistic + + Admin users: + + $ bin/turnadmin -A -b "/var/db/turndb" -u gorst -p hero + $ bin/turnadmin -A -b "/var/db/turndb" -u ninefingers -p youhavetoberealistic -r north.gov diff --git a/docs/Testing.md b/docs/Testing.md new file mode 100644 index 0000000..a006b03 --- /dev/null +++ b/docs/Testing.md @@ -0,0 +1,82 @@ +# TEST SCRIPTS + +First of all, you can use the test vectors from RFC 5769 to double-check that the +STUN/TURN message encoding algorithms work properly. Run the utility: + + $ cd examples + $ ./scripts/rfc5769.sh + +It will perform several protocol checks and print the results on the output. +If anything has compiled wrongly (TURN Server, or OpenSSL libraries) +then you will see some errors. + +Now, you can perform the TURN functionality test (bare minimum TURN example). + +If everything compiled properly, then the following programs must run +together successfully, simulating TURN network routing in local loopback +networking environment: + +Open two shell screens or consoles: + +In shell number 1, run TURN server application: + $ cd examples + $ ./scripts/basic/relay.sh + +In shell number 2, run test client application: + + $ cd examples + $ ./scripts/basic/udp_c2c_client.sh + +If the client application produces output and in approximately 22 seconds +prints the jitter, loss and round-trip-delay statistics, then everything is +fine. + +There is another more complex test: + +In shell number 1, run TURN server application: + $ cd examples + $ ./scripts/basic/relay.sh + +In shell number 2, run "peer" application: + $ cd examples + $ ./scripts/peer.sh + +In shell number 3, run test client application: + + $ cd examples + $ ./scripts/basic/udp_client.sh (or ./scripts/basic/tcp_client.sh) + +There is a similar set of examples/scripts/longtermsecure/* scripts for +TURN environment with long-term authentication mechanism. This set of +scripts is more complex, and checking the scripts options is useful for +understanding how the TURN Server works: + +In shell number 1, run secure TURN server application: + $ cd examples + $ ./scripts/longtermsecure/secure_relay.sh + +In shell number 2, run "peer" application: + $ cd examples + $ ./scripts/peer.sh + +In shell number 3, run secure test client application: + + $ cd examples + $ ./scripts/longtermsecure/secure_udp_client.sh + + (or ./scripts/longtermsecure/secure_tcp_client.sh) + (or ./scripts/longtermsecure/secure_tls_client.sh) + (or ./scripts/longtermsecure/secure_dtls_client.sh) + (or ./scripts/longtermsecure/secure_sctp_client.sh) + (or ./scripts/longtermsecure/secure_udp_c2c.sh for "peerless" +client-to-client communications) + +The provided scripts are set for the local loopback communications, +as an example and as a test environment. Real networking IPs must be +used in real work environments. + +Try wireshark to check the communications between client, turnserver +and the peer. + +Check the README.* files and the comments in the scripts relay.sh and +secure_relay.sh as a guidance how to run the TURN server. diff --git a/netarch.txt b/docs/netarch.md similarity index 97% rename from netarch.txt rename to docs/netarch.md index d0dfd2a..35050fe 100644 --- a/netarch.txt +++ b/docs/netarch.md @@ -1,8 +1,8 @@ - Coturn architecture, part 1 +# Coturn architecture, part 1 - Network architecture +## Network architecture -I. INTRODUCTION +### I. INTRODUCTION This document assumes that the reader is familiar with the various TURN specifications. The goal of this document is to provide general information for the Coturn @@ -30,7 +30,7 @@ how those communicatiuons are organized in the Coturn code. The key to the understanding how Coturn works is the notions of "listeners" and "general relay servers". -II. LISTENERS +### II. LISTENERS In Coturn, a "listener" is the entity that initiates dialog with the new client. When a new client sends its first packet to TURN, then it is initially accepted by the UDP @@ -57,7 +57,7 @@ listeners with the execution threads and with the relay servers. There may be multiple listeners in the server, and they may be running in different threads. -III. RELAY SERVERS +### III. RELAY SERVERS The relay servers take control over the client sessions after the initial contact was established by the listeners. The relay server will be reading the session sockets @@ -81,7 +81,7 @@ the result. The the original relay server will have to pack the session, say will adopt the session and the session will stay with the new relay server - until the next client address change. -IV. NETWORK ENGINES +### IV. NETWORK ENGINES UDP communications are rather under-developed, comparing to the TCP communications, in modern operational systems. Because TURN stresses UDP communications, UDP diff --git a/postinstall.txt b/postinstall.txt index a73dd28..121527d 100644 --- a/postinstall.txt +++ b/postinstall.txt @@ -1,39 +1 @@ -================================================================== - -1) If your system supports automatic start-up system daemon services, -then to enable the turnserver as a system service that is automatically -started, you have to: - - a) Create and edit /etc/turnserver.conf or - /usr/local/etc/turnserver.conf . - Use /usr/local/etc/turnserver.conf.default as an example. - - b) For user accounts settings: set up SQLite or PostgreSQL or - MySQL or MongoDB or Redis database for user accounts. - Use /usr/local/share/turnserver/schema.sql as SQL database schema, - or use /usr/local/share/turnserver/schema.userdb.redis as Redis - database schema description and/or - /usr/local/share/turnserver/schema.stats.redis - as Redis status & statistics database schema description. - - If you are using SQLite, the default database location is in - /var/db/turndb or in /usr/local/var/db/turndb or in /var/lib/turn/turndb. - - c) add whatever is necessary to enable start-up daemon for the - /usr/local/bin/turnserver. - -2) If you do not want the turnserver to be a system service, - then you can start/stop it "manually", using the "turnserver" - executable with appropriate options (see the documentation). - -3) To create database schema, use schema in file -/usr/local/share/turnserver/schema.sql. - -4) For additional information, run: - - $ man turnserver - $ man turnadmin - $ man turnutils - -================================================================== - +See docs folder or go to https://github.com/coturn/coturn/docs/PostInstall.md \ No newline at end of file