mirror of
https://github.com/coturn/coturn.git
synced 2025-10-27 04:51:28 +01:00
458 lines
9.9 KiB
Groff
458 lines
9.9 KiB
Groff
.\" Text automatically generated by txt2man
|
|
.TH TURN 1 "15 July 2014" "" ""
|
|
.SH GENERAL INFORMATION
|
|
|
|
A set of turnutils_* programs provides some utility functionality to be used
|
|
for testing and for setting up the TURN server.
|
|
.TP
|
|
.B
|
|
1.
|
|
\fIturnutils_uclient\fP: emulates multiple UDP,TCP,TLS or DTLS clients.
|
|
(this program is provided for the testing purposes only !)
|
|
The compiled binary image of this program is located in bin/
|
|
sub\-directory.
|
|
.PP
|
|
WARNING: the \fIturnutils_uclient\fP program is a primitive client application.
|
|
It does not implement the re\-transmission pattern that is necessary for
|
|
a correct TURN client implementation. In TURN, the retransmission burden
|
|
is lying almost entirely on the client application. We provide the messaging
|
|
functionality in the client library, but the client must implement
|
|
the correct Networking IO processing in the client program code.
|
|
.TP
|
|
.B
|
|
2.
|
|
\fIturnutils_peer\fP: a simple stateless UDP\-only "echo" server,
|
|
to be used as the final server in relay pattern ("peer"). For every incoming
|
|
UDP packet, it simply echoes it back.
|
|
(this program is provided for the testing purposes only !)
|
|
When the test clients are communicating in the client\-to\-client manner
|
|
(when the "\fIturnutils_uclient\fP" program is used with "\fB\-y\fP" option) then the
|
|
\fIturnutils_peer\fP is not needed.
|
|
.PP
|
|
The compiled binary image of this program is located in bin/ subdirectory.
|
|
.TP
|
|
.B
|
|
3.
|
|
\fIturnutils_stunclient\fP: a simple STUN client example.
|
|
The compiled binary image of this program is located in bin/ subdirectory.
|
|
.TP
|
|
.B
|
|
4.
|
|
\fIturnutils_rfc5769check\fP: a utility that checks the correctness of the
|
|
STUN/TURN protocol implementation. This utility is used only for the compilation
|
|
check procedure, it is not copied to the installation destination.
|
|
.RE
|
|
.PP
|
|
|
|
.RS
|
|
In the "examples/scripts" subdirectory, you will find the examples of command lines to be used
|
|
to run the programs. The scripts are meant to be run from examples/ subdirectory, for example:
|
|
.PP
|
|
$ cd examples
|
|
.PP
|
|
$ ./scripts/secure_relay.sh
|
|
.PP
|
|
=====================================
|
|
.SS NAME
|
|
\fB
|
|
\fBturnutils_uclient \fP\- this client emulation application is supplied for the test purposes only.
|
|
\fB
|
|
.SS SYNOPSIS
|
|
|
|
$ \fIturnutils_uclient\fP [\fB\-tTSvsyhcxg\fP] [options] <TURN\-Server\-IP\-address>
|
|
.SS DESCRIPTION
|
|
|
|
It was designed to simulate multiple clients. It uses asynch IO API in
|
|
libevent to handle multiple clients. A client connects to the relay,
|
|
negotiates the session, and sends multiple (configured number) messages to the server (relay),
|
|
expecting the same number of replies. The length of the messages is configurable.
|
|
The message is an arbitrary octet stream, but it can be configured as a string.
|
|
The number of the messages to send is configurable.
|
|
.TP
|
|
.B
|
|
Flags:
|
|
.TP
|
|
.B
|
|
\fB\-t\fP
|
|
Use TCP for communications between client and TURN server (default is UDP).
|
|
.TP
|
|
.B
|
|
\fB\-T\fP
|
|
Use TCP for the relay transport (default \- UDP). Implies options \fB\-t\fP, \fB\-y\fP, \fB\-c\fP,
|
|
and ignores flags and options \fB\-s\fP, \fB\-e\fP, \fB\-r\fP and \fB\-g\fP.
|
|
.TP
|
|
.B
|
|
\fB\-P\fP
|
|
Passive TCP (RFC6062 with active peer). Implies \fB\-T\fP.
|
|
.TP
|
|
.B
|
|
\fB\-S\fP
|
|
Secure SSL connection: SSL/TLS for TCP, DTLS for UDP.
|
|
.TP
|
|
.B
|
|
\fB\-U\fP
|
|
Secure unencrypted connection (suite eNULL): SSL/TLS for TCP, DTLS for UDP.
|
|
.TP
|
|
.B
|
|
\fB\-v\fP
|
|
Verbose.
|
|
.TP
|
|
.B
|
|
\fB\-s\fP
|
|
Use "Send" method in TURN; by default, it uses TURN Channels.
|
|
.TP
|
|
.B
|
|
\fB\-y\fP
|
|
Use client\-to\-client connections:
|
|
RTP/RTCP pair of channels to another RTP/RTCP pair of channels.
|
|
with this option the \fIturnutils_peer\fP application is not used,
|
|
as the allocated relay endpoints are talking to each other.
|
|
.TP
|
|
.B
|
|
\fB\-h\fP
|
|
Hang on indefinitely after the last sent packet.
|
|
.TP
|
|
.B
|
|
\fB\-c\fP
|
|
Do not create rtcp connections.
|
|
.TP
|
|
.B
|
|
\fB\-x\fP
|
|
Request IPv6 relay address (RFC6156).
|
|
.TP
|
|
.B
|
|
\fB\-X\fP
|
|
IPv4 relay address explicitly requested.
|
|
.TP
|
|
.B
|
|
\fB\-g\fP
|
|
Set DONT_FRAGMENT parameter in TURN requests.
|
|
.TP
|
|
.B
|
|
\fB\-A\fP
|
|
use short\-term credentials mechanism for authentication.
|
|
By default, the program uses the long\-term credentials mechanism
|
|
if authentication is required.
|
|
.TP
|
|
.B
|
|
\fB\-D\fP
|
|
Do mandatory channel padding even for UDP (like pjnath).
|
|
.TP
|
|
.B
|
|
\fB\-N\fP
|
|
do negative tests (some limited cases only).
|
|
.TP
|
|
.B
|
|
\fB\-R\fP
|
|
do negative protocol tests.
|
|
.TP
|
|
.B
|
|
\fB\-O\fP
|
|
DOS attack mode.
|
|
.TP
|
|
.B
|
|
\fB\-H\fP
|
|
SHA256 digest function for message integrity calculation.
|
|
Without this option, by default, SHA1 is used.
|
|
.TP
|
|
.B
|
|
\fB\-M\fP
|
|
Use TURN ICE Mobility.
|
|
.TP
|
|
.B
|
|
\fB\-I\fP
|
|
Do not set permissions on TURN relay endpoints
|
|
(for testing the non\-standard server relay functionality).
|
|
.TP
|
|
.B
|
|
\fB\-G\fP
|
|
Generate extra requests (create permissions, channel bind).
|
|
.TP
|
|
.B
|
|
\fB\-B\fP
|
|
Random disconnect after a few initial packets.
|
|
.TP
|
|
.B
|
|
\fB\-Z\fP
|
|
Dual allocation.
|
|
.TP
|
|
.B
|
|
Options with required values:
|
|
.TP
|
|
.B
|
|
\fB\-l\fP
|
|
Message length (Default: 100 Bytes).
|
|
.TP
|
|
.B
|
|
\fB\-i\fP
|
|
Certificate file (for secure connections only, optional).
|
|
.TP
|
|
.B
|
|
\fB\-k\fP
|
|
Private key file (for secure connections only).
|
|
.TP
|
|
.B
|
|
\fB\-E\fP
|
|
CA file for server certificate verification,
|
|
if the server certificate to be verified.
|
|
.TP
|
|
.B
|
|
\fB\-p\fP
|
|
\fBTURN Server\fP port (Defaults: 3478 unsecure, 5349 secure).
|
|
.TP
|
|
.B
|
|
\fB\-n\fP
|
|
Number of messages to send (Default: 5).
|
|
.TP
|
|
.B
|
|
\fB\-d\fP
|
|
Local interface device (optional, Linux only).
|
|
.TP
|
|
.B
|
|
\fB\-L\fP
|
|
Local IP address (optional).
|
|
.TP
|
|
.B
|
|
\fB\-m\fP
|
|
Number of clients (Default: 1, 2 or 4, depending on options).
|
|
.TP
|
|
.B
|
|
\fB\-e\fP
|
|
Peer address.
|
|
.TP
|
|
.B
|
|
\fB\-r\fP
|
|
Peer port (Default: 3480).
|
|
.TP
|
|
.B
|
|
\fB\-z\fP
|
|
Per\-session packet interval in milliseconds (Default: 20).
|
|
.TP
|
|
.B
|
|
\fB\-u\fP
|
|
STUN/TURN user name.
|
|
.TP
|
|
.B
|
|
\fB\-w\fP
|
|
STUN/TURN user password.
|
|
.TP
|
|
.B
|
|
\fB\-W\fP
|
|
TURN REST API authentication secret. Is not compatible with \fB\-A\fP flag.
|
|
.TP
|
|
.B
|
|
\fB\-C\fP
|
|
This is the timestamp/username separator symbol (character) in
|
|
TURN REST API. The default value is :.
|
|
.TP
|
|
.B
|
|
\fB\-F\fP
|
|
Cipher suite for TLS/DTLS. Default value is DEFAULT.
|
|
.TP
|
|
.B
|
|
\fB\-o\fP
|
|
the ORIGIN STUN attribute value.
|
|
.TP
|
|
.B
|
|
\fB\-a\fP
|
|
Bandwidth for the bandwidth request in ALLOCATE. The default value is zero.
|
|
.PP
|
|
See the examples in the "examples/scripts" directory.
|
|
.PP
|
|
======================================
|
|
.SS NAME
|
|
\fB
|
|
\fBturnutils_peer \fP\- a simple UDP\-only echo backend server.
|
|
\fB
|
|
.SS SYNOPSYS
|
|
|
|
$ \fIturnutils_peer\fP [\fB\-v\fP] [options]
|
|
.SS DESCRIPTION
|
|
|
|
This application is used for the test purposes only, as a peer for the \fIturnutils_uclient\fP application.
|
|
.TP
|
|
.B
|
|
Options with required values:
|
|
.TP
|
|
.B
|
|
\fB\-p\fP
|
|
Listening UDP port (Default: 3480).
|
|
.TP
|
|
.B
|
|
\fB\-d\fP
|
|
Listening interface device (optional)
|
|
.TP
|
|
.B
|
|
\fB\-L\fP
|
|
Listening address of \fIturnutils_peer\fP server. Multiple listening addresses can be used, IPv4 and IPv6.
|
|
If no listener \fBaddress\fP(es) defined, then it listens on all IPv4 and IPv6 addresses.
|
|
.TP
|
|
.B
|
|
\fB\-v\fP
|
|
Verbose
|
|
.PP
|
|
========================================
|
|
.SS NAME
|
|
\fB
|
|
\fBturnutils_stunclient \fP\- a basic STUN client.
|
|
\fB
|
|
.SS SYNOPSIS
|
|
.nf
|
|
.fam C
|
|
|
|
$ \fIturnutils_stunclient\fP [\fIoptions\fP] <STUN\-Server\-IP\-address>
|
|
|
|
.fam T
|
|
.fi
|
|
.fam T
|
|
.fi
|
|
.SS DESCRIPTION
|
|
|
|
It sends a "new" STUN RFC 5389 request (over UDP) and shows the reply information.
|
|
.TP
|
|
.B
|
|
Options with required values:
|
|
.TP
|
|
.B
|
|
\fB\-p\fP
|
|
STUN server port (Default: 3478).
|
|
.TP
|
|
.B
|
|
\fB\-L\fP
|
|
Local address to use (optional).
|
|
.TP
|
|
.B
|
|
\fB\-f\fP
|
|
Force RFC 5780 processing.
|
|
.PP
|
|
The \fIturnutils_stunclient\fP program checks the results of the first request,
|
|
and if it finds that the STUN server supports RFC 5780
|
|
(the binding response reveals that) then the \fIturnutils_stunclient\fP makes a couple more
|
|
requests with different parameters, to demonstrate the NAT discovery capabilities.
|
|
.PP
|
|
This utility does not support the "old" "classic" STUN protocol (RFC 3489).
|
|
.PP
|
|
=====================================
|
|
.SS NAME
|
|
\fB
|
|
\fBturnutils_rfc5769check \fP\- a utility that tests the correctness of STUN protocol implementation.
|
|
\fB
|
|
.SS SYNOPSIS
|
|
.nf
|
|
.fam C
|
|
|
|
$ \fIturnutils_rfc5769check\fP
|
|
|
|
.fam T
|
|
.fi
|
|
.fam T
|
|
.fi
|
|
.SS DESCRIPTION
|
|
|
|
\fIturnutils_rfc5769check\fP tests the correctness of STUN protocol implementation
|
|
against the test vectors predefined in RFC 5769 and prints the results of the
|
|
tests on the screen. This utility is used only for the compilation
|
|
check procedure, it is not copied to the installation destination.
|
|
.TP
|
|
.B
|
|
Usage:
|
|
.PP
|
|
$ \fIturnutils_rfc5769check\fP
|
|
.PP
|
|
===================================
|
|
.SH DOCS
|
|
|
|
After installation, run the command:
|
|
.PP
|
|
$ man \fIturnutils\fP
|
|
.PP
|
|
or in the project root directory:
|
|
.PP
|
|
$ man \fB\-M\fP man \fIturnutils\fP
|
|
.PP
|
|
to see the man page.
|
|
.PP
|
|
=====================================
|
|
.SH FILES
|
|
|
|
/etc/turnserver.conf
|
|
.PP
|
|
/etc/turnuserdb.conf
|
|
.PP
|
|
/usr/local/etc/turnserver.conf
|
|
.PP
|
|
/usr/local/etc/turnuserdb.conf
|
|
.PP
|
|
=================================
|
|
.SH DIRECTORIES
|
|
|
|
/usr/local/share/\fIturnserver\fP
|
|
.PP
|
|
/usr/local/share/doc/\fIturnserver\fP
|
|
.PP
|
|
/usr/local/share/examples/\fIturnserver\fP
|
|
.PP
|
|
===================================
|
|
.SH STANDARDS
|
|
|
|
new STUN RFC 5389
|
|
.PP
|
|
TURN RFC 5766
|
|
.PP
|
|
TURN\-TCP extension RFC 6062
|
|
.PP
|
|
TURN IPv6 extension RFC 6156
|
|
.PP
|
|
STUN/TURN test vectors RFC 5769
|
|
.PP
|
|
STUN NAT behavior discovery RFC 5780
|
|
.PP
|
|
====================================
|
|
.SH SEE ALSO
|
|
|
|
\fIturnserver\fP, \fIturnadmin\fP
|
|
.RE
|
|
.PP
|
|
======================================
|
|
.SS WEB RESOURCES
|
|
|
|
project page:
|
|
.PP
|
|
http://code.google.com/p/coturn/
|
|
.PP
|
|
Wiki page:
|
|
.PP
|
|
http://code.google.com/p/coturn/wiki/Readme
|
|
.PP
|
|
forum:
|
|
.PP
|
|
https://groups.google.com/forum/?fromgroups=#!forum/turn\-server\-project\-rfc5766\-turn\-server/
|
|
.RE
|
|
.PP
|
|
======================================
|
|
.SS AUTHORS
|
|
|
|
Oleg Moskalenko <mom040267@gmail.com>
|
|
.PP
|
|
Gabor Kovesdan http://kovesdan.org/
|
|
.PP
|
|
Daniel Pocock http://danielpocock.com/
|
|
.PP
|
|
John Selbie (jselbie@gmail.com)
|
|
.PP
|
|
Lee Sylvester <lee@designrealm.co.uk>
|
|
.PP
|
|
Erik Johnston <erikj@openmarket.com>
|
|
.PP
|
|
Roman Lisagor <roman@demonware.net>
|
|
.PP
|
|
Vladimir Tsanev <tsachev@gmail.com>
|
|
.PP
|
|
Po\-sheng Lin <personlin118@gmail.com>
|
|
.PP
|
|
Peter Dunkley <peter.dunkley@crocodilertc.net>
|
|
.PP
|
|
Mutsutoshi Yoshimoto <mutsutoshi.yoshimoto@mixi.co.jp>
|
|
.PP
|
|
Federico Pinna <fpinna@vivocha.com>
|