coturn/README.turnadmin

GENERAL INFORMATION

turnadmin is a TURN administration tool. This tool can be used to manage 
the user accounts (add/remove users, generate 
TURN keys for the users). For security reasons, we do not recommend 
storing passwords openly. The better option is to use pre-processed "keys" 
which are then used for authentication. These keys are generated by turnadmin. 
Turnadmin is a link to turnserver binary, but turnadmin performs different 
functions.

Options note: turnadmin has long and short option names, for most options.
Some options have only long form, some options have only short form. Their syntax 
somewhat different, if an argument is required:

The short form must be used as this (for example):

  $ turnadmin -u <username> ...
  
The long form equivalent must use the "=" character:

  $ turnadmin --user=<username> ...
  
If this is a flag option (no argument required) then their usage are the same, for example:

 $ turnadmin -k ...
 
is equivalent to:

 $ turnadmin --key ...

You have always the use the -r <realm> option with commands for long term credentials - 
because data for multiple realms can be stored in the same database.
 
=====================================

  NAME

turnadmin - a TURN relay administration tool. 
  
  SYNOPSIS  

$ turnadmin [command] [options]

$ turnadmin [ -h | --help]

  DESCRIPTION
  
Commands:  

-k, --key		Generate key for a long-term credentials mechanism user.

-a, --add       	Add or update a long-term user.

-A, --add-st    	Add or update a short-term credentials mechanism user.

-d, --delete		Delete a long-term user.

-D, --delete-st		Delete a short-term user.

-l, --list		List long-term users in the database.

-L, --list-st		List short-term users in the database.

-s, --set-secret=<value> Add shared secret for TURN RESP API

-S, --show-secret	Show stored shared secrets for TURN REST API

-X, --delete-secret=<value> Delete a shared secret.
	--delete-all_secrets	Delete all shared secrets for REST API.
	
-O, --add-origin		Add origin-to-realm relation.

-R, --del-origin		Delete origin-to-realm relation.

-I, --list-origins		List origin-to-realm relations.

-g, --set-realm-option		Set realm params: max-bps, total-quota, user-quota.

-G, --list-realm-options	List realm params.

NOTE: if you are using the flat file for the user database, then you will have 
to use a text editor to set or show the shared secrets.

NOTE: the origin functionality is not supported with flat user db file, 
a "real" database must be used.
  
Options with required values:  

-b, --userdb		File-based user database file name (default - turnuserdb.conf).
			See the --userdb option in the turnserver section.
-e, --psql-userdb	PostgreSQL user database connection string.
			See the --psql-userdb option in the turnserver section.
-M, --mysql-userdb	MySQL user database connection string.
			See the --mysql-userdb option in the turnserver section.
-J, --mongo-userdb	MongoDB user database connection string.
			See the --mysql-mongo option in the turnserver section.
-N, --redis-userdb	Redis user database connection string.
			See the --redis-userdb option in the turnserver section.
-u, --user		User name.
-r, --realm		Realm, for long-term credentials mechanism only.
-p, --password		Password.
-o, --origin		Origin
-H, --sha256	Use SHA256 as the keys hash function (a non-standard feature). 
				By default, MD5 is used for the key storage encryption 
				(as required by the current STUN/TURNstandards).
--max-bps		Set value of realm's max-bps parameter.
--total-quota	Set value of realm's total-quota parameter.
--user-quota	Set value of realm's user-quota parameter. 
-h, --help		Help.
  
Generate a key:  

$ turnadmin -k -u <username> -r <realm> -p <password>
  
Add/update a user in the userdb file or in the database:

$ turnadmin -a [-b <userdb-file> | -e <db-connection-string> | -M <db-connection-string> | -N <db-connection-string> ] -u <username> -r <realm> -p <password>
  
Delete a user from the userdb file or from the database:

$ turnadmin -d [-b <userdb-file> | -e <db-connection-string> | -M <db-connection-string> | -N <db-connection-string> ] -u <username> -r <realm>

List all long-term users in MySQL database:

$ turnadmin -l --mysql-userdb="<db-connection-string>" -r <realm>

List all short-term users in Redis database:

$ turnadmin -L --redis-userdb="<db-connection-string>"

Set secret in MySQL database:

$ turnadmin -s <secret> --mysql-userdb="<db-connection-string>" -r <realm>

Show secret stored in PostgreSQL database:

$ turnadmin -S --psql-userdb="<db-connection-string>" -r <realm>

Set origin-to-realm relation in MySQL database:

$ turnadmin --mysql-userdb="<db-connection-string>" -r <realm> -o <origin>

Delete origin-to-realm relation from Redis DB:

$ turnadmin --redis-userdb="<db-connection-string>" -o <origin>

List all origin-to-realm relations in Redis DB:

$ turnadmin --redis-userdb="<db-connection-string>" -I

List the origin-to-realm relations in PostgreSQL DB for a single realm:

$ turnadmin --psql-userdb="<db-connection-string>" -I -r <realm>
  
Help:  

$ turnadmin -h

=======================================
 
  DOCS

After installation, run the command:

$ man turnadmin

or in the project root directory:

$ man -M man turnadmin

to see the man page.

=====================================

  FILES

/etc/turnserver.conf

/etc/turnuserdb.conf

/usr/local/etc/turnserver.conf

/usr/local/etc/turnuserdb.conf

=====================================

  DIRECTORIES

/usr/local/share/turnserver

/usr/local/share/doc/turnserver

/usr/local/share/examples/turnserver

======================================

  SEE ALSO

	turnserver, turnutils

======================================

  WEB RESOURCES

	project page:

	http://code.google.com/p/coturn/

	Wiki page:

	http://code.google.com/p/coturn/wiki/Readme

	forum:

	https://groups.google.com/forum/?fromgroups=#!forum/turn-server-project-rfc5766-turn-server/

======================================

  AUTHORS

	Oleg Moskalenko <mom040267@gmail.com>

	Gabor Kovesdan http://kovesdan.org/

	Daniel Pocock http://danielpocock.com/

	John Selbie (jselbie@gmail.com)

	Lee Sylvester <lee@designrealm.co.uk>

	Erik Johnston <erikj@openmarket.com>

	Roman Lisagor <roman@demonware.net>
	
	Vladimir Tsanev <tsachev@gmail.com>
	
	Po-sheng Lin <personlin118@gmail.com>
	
	Peter Dunkley <peter.dunkley@crocodilertc.net>
	
	Mutsutoshi Yoshimoto <mutsutoshi.yoshimoto@mixi.co.jp>

	Federico Pinna <fpinna@vivocha.com>