Ventrilo Server Setup Information.
Version 2.3.1
Copyright 1999-2005 Flagship Industries, Inc.
===================================
1) Requirements
The basic requirements and general operational information about the server and what is expected before it can run.
All of the possible options and parameters in the ventrilo_srv.ini file.
How its run and any special options associated with the specific platform version of the server.
How to configure and setup the NT Service.
Server administration commands.
How to use this statusing tool.
Servers come in two flavors: Public and Pro version. The Public version is freely downloadable and can be used without paying a license fee in accordance to the LICENSE file included with each of the server distributions.
Public version.
The Public version of the server is hard coded to 8 slots per instance, one instance per machine and port 3784.
Pro version.
The Pro version of the server is designed to be scalable, in that multiple copies of the server can be started on the same machine. Each instance of the Ventrilo server running on the same machine must be assigned a unique port number in it's corresponding INI file.
CPU utilization by the Ventrilo server is negligible so just about any low end machine can be used. However, servers will require better upload and download bandwidth capacities due to the nature of voice communication. The more concurrent clients connected to a server (and in the same channel) the greater the bandwidth utilization.
The "ventrilo_srv.ini" file has several categories:
Server - General configuration info.
Intf - Accept connections only from specific IP interfaces.
Each category is contained in [ brackets ] and each option is entered using key=value formatting. This document will use the settings included in the example INI file.
[Server]
Name=Server 1
This is the name of the server that appears at the top of the active user list when someone connects. (Required)
Phonetic=
This is the phonetic pronunciation of the server name. If left blank the servers Name will be used in all TTS events that involve the servers name being announced.
Comment=
This option has been removed. It is now controlled via the client by using the Server Properties window.
Port=3784
This option has no meaning on Public versions of the server. The port will default to 3784. If you use a router to forward the connection from the outside internet to your internal private network then the external port must also be 3784.
This is the TCP/IP port number that the server will listen on waiting for clients to connect. If you start multiple instances of the server on the same computer then they must have different INI files with unique TCP port numbers assigned to them.
Auth=0
This is the authentication mode. (Required)
0 = No authentication and anyone can connect.
1 = Global password authentication.
2 = Specific user/password authentication.
Duplicates=1
Enables or disables duplicate login names. (Required)
0 = Disables duplicates.
1 = Allows duplicate login names.If disabled and someone logs in with a user name identical to that of a currently connected user, the server will disconnect the first user. This setting should only be used when Auth=2 for sanity reasons but it can be disabled for any Auth mode. Note: When this option is set to 0 it creates problems for clients that had auto-reconnect enabled, however, starting with version 2.0.0 this is no longer a problem.
AdminPassword=
This is the remote server administration password. Leaving this option blank will disable remote admin logins. This password is used by normal login accounts and they activate a menu option to have admin rights assigned to their login. (Optional)
Password=
This is the global login password for when Auth=1. All users connecting to this server must have this password, otherwise the server will send back an error message saying that they could not be authenticated. (Optional)
MaxClients=8
This option is not available on Public versions of the server. It is hard coded to a maximum of 8 simultaneous clients (also called slots). If you need more then 8 slots then you will need to rent a server from a licensed professional hosting company.
This option specifies the maximum number of clients that can be connected to the server at the same time. Pro servers have a hard coded maximum limit of 400 clients, however, your servers network connection might not be able to handle a large number of simultaneous connections. (Required)
SendBuffer=0
This option specifies the size of the TCP outbound buffers to each client. The value is in bytes.
A value of 0 will force the program to use a default value of 131072 bytes. If you have a smaller value then I recommend setting it to 0 and let the program use its default.
In the servers log file there will be a line starting with "MSG_CONN" when a new client connects. At the end of this line will be two pairs of numbers (A,B) (C,D). The A number is the buffer size as defined by your platform. The B number is the buffer size as reported by the system after the Ventrilo server has changed it. The number could be larger or smaller depending on the platform.
RecvBuffer=0
This option specifies the size of the TCP inbound buffers for each client. The value is in bytes.
A value of 0 will force the program to use it's default settings of 131072 bytes per client connection.
In the servers log file there will be a line starting with "MSG_CONN" when a new client connects. At the end of this line will be two pairs of numbers (A,B) (C,D). The C number is the buffer size as defined by your platform. The D number is the buffer size as reported by the system after the Ventrilo server has changed it. The number could be larger or smaller depending on the platform.
Diag=0
0 = Diagnostics off.
1 = Diagnostics on.This option has no use to end users and is for developer use only.
LogonTimeout=5
This option specifies in seconds how long a client has to logon to the server before it is automatically disconnected. Once logged on the option has no meaning.
CloseStd=1
0 = Don't close standard input, output and error handles.
1 = Close standard input, output and error handles.This option instructs the server to close or leave-intact the standard input, output and error file handles when starting in daemon mode. At the time of this writing the Ventrilo server is compiled on RedHat 7.2 systems but there seems to be an incompatibility with closing these standard file handles on RedHat80 systems thus causing the program to crash. Setting this option to 0 will force the program to leave the file handles open and prevent it from crashing on RH80 systems. The only downside to this will be if the program was started in daemon mode via an SSH terminal session. When you "exit" the terminal session it will hang waiting for all file handles in spawned processes to close, and you will be forced to manually kill the SSH terminal program. This doesn't seem to happen with normal xterm, gnome-terminal or telnet sessions. *shrug*
Note: Starting with version 2.0.0 this doesn't seem to be an issue anymore due to changes made to the build process. However, the option remains available in case it is needed in the future.
FilterWave=0
FilterTTS=0
These options have been removed. They are now controlled via the client by using the Server Properties window.
TimeStamp=0
0 = Disable console timestamp's.
1 = Enable console timestamp's.This option enables or disables timestamp's being displayed in console messages. This includes remote consoles.
PingRate=10
This option allows the administrator to change the interval at which the server pings the clients. The value is specified in seconds and defaults to 10. Setting to a lower value might be useful for diagnosing problem clients especially when the remote console command "pingtrace" is used.
ExtraBuffer=0
This option allows the administrator to give each outbound client data stream additional buffer space but it's allocated and controlled by the server instead of relying on the TCP stack implementation. A value of 0 instructs the server to use it's default value of 128K bytes of extra buffer space. Any attempt to change the value will usually make any existing problems worse. It remains intact for historical purposes.
ChanWidth=0
This option specifies a maximum number of parallel sub-channels that can be created in each channel. It has no effect on root level channels which only server admin's can create. A value of 0 means there is no limit.
ChanDepth=0
This option specifies the maximum number of nested sub-channels (depth) that can be created. A value of 0 means the server will use it's default max value of 8 nested channels.
ChanClients=0
This option specifies the maximum number of clients allowed in any channel. A value of 0 means there is no limit to the number of clients per channel.
DisableMaxClients=1
This option has has been removed .
DisableQuit=1
0=Allow remote consoles to issue the "quit" command.
1=Disable (prevent) remote console from issuing the "quit" command.This option prevents remote console commands (those typed into the chat window when logged in with server admin rights) from issuing the "quit" command which would instruct the server to exit the system. However, if the server was started in a non-daemon mode the local console can still issue the quit command.
VoiceCodec=0
This option tells the server which codec all clients must use. The value is a 0 based index into a list of possible codec's. To see the list of currently supported codec types issue the command "ventrilo_srv -?" and the program will display a table of codec's and their associated formats.
VoiceFormat=1
This option is the second part of VoiceCodec. Each codec can have one or more possible formats that control the quality and bandwidth usage of the specified codec. To see the list of currently supported codec formats issue the command "ventrilo_srv -?" and the program will display a table of codec's and their associated formats.
SilentLobby=0
0 = Allow replication.
1 = Suppress replication, thus making the lobby silent.This option allows or suppresses replication of voice, wave binds and TTS binds when the client is in the main lobby.
SpamChat=1,1000,2
SpamComment=1,1000,2
SpamWave=1,1000,2
SpamTTS=1,1000,2
These options have been removed. They are now controlled via the client by using the Server Properties window.
AutoKick=0
This option enables auto-kicking of a client after it has been connected for X number of seconds. A value of 0 disables the autokick feature, otherwise it specifies the number of seconds that a client is allowed to remain connected before the server will automatically disconnect them. This feature is primarily intended for professional hosting services who setup servers for potential customers to test the quality of the hosters network and machines, while at the same time prevent people from hijacking the server for their own private use.
[Intf]
This feature is not available on Public versions of the server. The Windows versions of the public server will attempt to identify all possible interfaces and attach to them, while the UNIX based versions of the server will attach to the global interface 0.0.0.0 which means to accept connections from all interfaces.
Pro versions of the server should only attach to a single interface.
This section allows for controlling which interface the server will accept client connections from. If you do not specify anything in this section then the server will accept client connections from all available interfaces.
When the server displays the message "Accepting connections from the following interfaces" and the displayed IP address is 0.0.0.0 then this means the server will accept incoming network connections from all interface cards. This is the default behavior unless you specify an interface.
Note: The key names do not need to be unique but we would encourage you to continue using names like the following examples where the key name starts with "Intf" and followed by a unique identifier.
Intf1=192.168.0.31
Intf2=external.mydomain.com
Intf3=internal.mydomain.com
Intf4=127.0.0.1
The interfaces can now be specified as host names or IP numbers.
[Status]
The entire Status section of the INI file has been removed. All servers will accept remote UDP status requests all the time and on the same interfaces that are used for accepting normal client connections, so long as there is no router or firewall blocking the inbound UDP requests. This means the filter and password options are not supported either. However, the type and amount of information that is returned by a status request can be controlled from the client via the Server Properties window.
All servers, no matter which platform, are designed to be run in a console window. However, the UNIX'ish based versions can be started in daemon mode and the Windows NT based versions can be started via a separate Ventrilo Service program.
Starting with version 1.03 there are two different ways to start a server. The original way requires you to change the current working directory before starting the server. A new optional mechanism uses the "-f" command line option to specify the location of the required files without changing the working directory.
General information about starting a server.
When the program starts it will read the contents of the INI file and validate the information for completeness. If any of the configuration information is incorrect the server will automatically terminate. If the server refuses to start after reading the config info you can check the "ventrilo_srv.log" for details.
After starting the server it will record its Process ID, or PID, to a file named "ventrilo_srv.pid" in the current or filename-prefixed directory. This is useful should you need to manually kill a server that is misbehaving, not as if that will ever happen.
To start a server in daemon mode append a "-d" to the command line.
To get command line help and a list of voice codec/format options append the "-?" to the command line.
Method 1: Original and default way.
To start a server you must first change your current working directory to that of the "ventrilo_srv.ini" file that you plan on using.
To start a standalone server, not a service or a daemon, simply execute the appropriate server program for the given platform, assuming the working directory has been set first.
Method 2: Path and filename prefix.
Starting with version 1.03 you can use the "-f" command line option to specify the path and prefix name to be used for all files. This requires that all files use a unique name for each server that is started on the same machine. When used in this mode the server will use the path/prefix immediately following the "-f" parameter and tack on extensions for each of the files to be read or written by the server. At the time of this writing there are 7 different files used by a server.
1) ventrilo_srv.ini
Read before starting up and required
2) ventrilo_srv.ban
Read and written but not required
3) ventrilo_srv.pid
Written once as soon as the server starts. Deleted when server stops.
4) ventrilo_srv.log
Appended to by the server when ever a log message is generated
5) ventrilo_srv.usr
Read each time a client connects, updated when Server Admin adds/deletes a user via the User Editor window
6) ventrilo_srv.chn
Read before program starts, updated when channels are added/deleted
7) ventrilo_srv.prop
Read before program starts, updated when server admin uses Server Properties window in the client
When using the "-f" you don't need to change the working directory but you must provide a path/prefix to be used for reading and writing these files. For example, lets assume you are running the Linux version and have the server installed in the directory "/home/ventrilo" along with all of the necessary files. To start the server with the "-f" option you would simply issue the following command.
/home/ventrilo/ventrilo_srv -f/home/ventrilo/ventrilo_srv
Notice there is no space following the "-f" option. The above line assumes you are using the default file names. Now, lets assume you are running two servers on the same machine. Each server would need to have its own port number assigned to it. Thus, we recommend naming the files by the port numbers. To start both servers using the "-f" option you issue the following commands.
/home/ventrilo/ventrilo_srv -f/home/ventrilo/3784 -d
/home/ventrilo/ventrilo_srv -f/home/ventrilo/4000 -d
The first server would read/write files using the names: 3784.ini, 3784.ban, 3784.pid, 3784.log, 3784.usr and 3784.chn
While the second server would read/write files using the names: 4000.ini, 4000.ban, 4000.pid, 4000.log, 4000.usr and 4000.chn
The "-d" on those examples will start the servers in daemon mode on UNIX'ish systems.
Linux notes:
If you have an automated system for restarting a Linux based Ventrilo server then you will need to wait about 1 to 2 minutes after the server is stopped and before you restart it. There’s a problem with creating the initial network stream shortly after a server is killed and when a new one is started. Waiting for about 2 minutes should make it work correctly. This seems to be less of a problem starting with version 1.03 because of the architectural change, but it probably wouldn't be a bad idea to continue the delay.
Example startup scripts:
The following script is an example of starting Linux based server(s) from the "/etc/rc.d/rc.local" file when a system is booted. Notice that they are started with the specific user account called "ventrilo" and the process priority is bumped to higher then normal.
# Startup ventrilo servers.
VENPATH=/home/ventrilo
VENBIN=$VENPATH/ventrilo_srvsu ventrilo -c "$VENBIN -f$VENPATH/3784 -d"
su ventrilo -c "$VENBIN -f$VENPATH/4000 -d"
renice -5 `cat $VENPATH/3784.pid`
renice -5 `cat $VENPATH/4000.pid`
Note: Those are GRAVE characters around the `cat ... pid` strings. A.K.A backwards apostrophe.
The "renice" command is used to bump the priority of the daemon process thus preventing it from being starved for CPU time if the same machine is used for running other programs like FTP or WEB servers. The Windows version of the server does this automatically. However, in a *NIX environment only the "root" user is allowed to bump process priority.
Example kill script:
This example shows how to stop a server on a UNIX'ish platform that is running in the background as a daemon. Note that it assumes the current working directory is the same as the location of the PID file.
kill `cat ventrilo_srv.pid`
When running the server on a Windows NT/2000/XP platform you also have the option of executing it as an NT Service that will run in the background and can be started up automatically when the computer is started.
The Ventrilo server doesn't actually run as a service, instead there is another program called "ventrilo_svc.exe" that is the real service program. This service program is responsible for starting up the "ventrilo_srv.exe" server program after the service is loaded.
One advantage to doing it this way is that the service program will restart the server if an admin shuts it down or if the program were to crash due to a bug.
Another advantage to this technique is that the service program can launch multiple copies of the server with each one running a different port number and configuration or even different versions.
To register the Service program with the Service Control Manager simply open a command prompt window and change directories to where you installed the files. Now type the following command:
ventrilo_svc -i
This will install the service and mark it for automatic startup the next time you reboot your system. To start the service program after it's registered you can type "net start ventrilo" or simply reboot your machine. That's all you have to do to get the service installed.
If you want to uninstall the service from your system or want to install a new version, simply perform the following commands in this order.
net stop ventrilo
ventrilo_svc -u
The "-u" option will tell the service program to uninstall it self from the systems Service Control Manager.
The following documentation is for more advanced customization of the service but is not required for a basic setup.
In order for the service to function properly you also need to setup a few registry entries that define each of the servers that you want the service program to start. When you issued the "-i" option it also created an example registry entry for a single server under the key:
HKEY_LOCAL_MACHINE\Software\Ventrilo
There should be at least one value and one sub-key created in here. The value is called EXE and points to the full path and filename of the Ventrilo server program. This is the global entry and is used if the individual server sub-key's don't specify one.
The sub-key names can be anything you want them to be. At installation time the "-i" option created a single sub-key called Server1. In side this key will be 3 string values.
The WorkDir value is required (if the Prefix value isn't used) for each sub-key and must be unique for each server if you want the service to start multiple instances of the server.
The Prefix value is required (if WorkDir is not specified) and is only used in the unique sub-keys for each server. When this option is set it activates the "-f" command line parameter discussed in section 4 of this document. Do not include the "-f" in the Prefix's value as the service program will automatically tack that on. All you need to do is create this value and give it a fully qualified path and prefix file name. If the Prefix value exists and contains anything other then a blank string then the WorkDir option will be ignored.
You can also specify an EXE value for defining a specific copy of the server to be started up by the service. This is useful if you are running different versions of the Ventrilo server. If an EXE value exists in the sub-key then it takes precedence over the global EXE value higher up. If they are both missing then the service will not start anything.
It's recommended that you name the sub-key's with the same name that you would assign each server in its "ventrilo_srv.ini" file or possibly by it's port number, however this is not required and you can name the sub-key's what ever you want.
Another feature of the service program is the ability to run in debug mode. This lets you test your registry entries and INI file configurations before starting it as a real service where its harder to diagnose problems. To do this first make sure that the real service is not currently running and then start the "ventrilo_svc.exe" with the following command line.
net stop ventrilo
ventrilo_svc -d
When the service starts in debug mode all of its output will show up in the console window where you typed in the command. It will then start each instance of the servers you have defined in their own console windows. If the service and all servers are happy then they should stay open and running. If not, you can go look at each servers log file for any possible problems. Don't forget, you can also start the servers manually as mentioned earlier in the document.
The following commands can be typed into a servers console window if it was started manually. These same commands can be sent to the server from a remote clients RCon window. But it does require that the remote client be logged in with server admin rights. The following is a list of all of the console commands and brief descriptions on their meaning and use. Some examples show the < and > around the parameters. Do not include these characters when typing the command.
auth < 0 | 1 | 2 >
Allows the authorization mode to be changed dynamically.
banadd <ip[/bits]> <reason>
Adds an IP address, or subnet address, and a reason for the banning to the ban list and ban file. If you specify a subnet like 192.168.0.0/16 then any IP address that starts with 192.168 will be banned, whereas 192.168.67.0/24 would ban anything that starts with 192.168.67.
bandel <ip[/bits]>
Deletes an IP address from the ban list. Starting with version 1.03 this command will automatically update the ban file. Similar to banadd if you want to remove a ban address that is specified by a subnet then you must also specify the same ip and subnet in the bandel command.
banlist
This option will display all of the banned IP addresses, the user name of the IP address, the admin who banned them and a reason why.
clientkick <uid>
Instructs the server to disconnect a user where <uid> is the users connection ID number.
clientstatus <uid>
This option will output more detailed information about a specified client.
comment <text>
This option is no longer supported. Use the client Server Properties window to change the server comment.
diag < 0 | 1 >
Allows the diagnostic mode to be changed dynamically. This feature is only valid to the developer.
filtertts < 0 | 1 >
filterwave < 0 | 1 >
These options are no longer available. Use the client Server Properties window to change the filter options.
help
Displays the list of possible console commands.
kickall
Kicks all clients connected to the server. If issued via the RCon window from an admining client, that client is exempted from the kick.
loggrep <lines> <search text>
Allows the servers log file to be searched for a specific piece of text. If lines is 0 then all matching entries will be displayed, otherwise only the last number of <lines> specified matching the search will be displayed. The search string does NOT support regular expressions and all comparisons are case sensitive.
WARNING: Using this command may cause the server to momentarily interrupt voice communication for all clients depending on the size of the log file. It's also possible that the results will be too long and potentially flood the requesters connection with too much information, thus causing the server to disconnect you. It is probably best that you always specify a number of <lines> to limit the results.
maxclients
This option will display the total number of slots that the server is configured to handle.
monitor < 0 | 1 >
This option is only valid when requested from a remote client using the Rcon window. It instructs the server to send all status and log messages to the client that typed this command. The monitor command is turned on by setting the value to 1, and turned off by a value of 0.
name
This option will display the server's name and current comment.
password <newpassword>
Changes the current login password for the server when Auth=1. The change is only valid while the server is running and it will revert back to the Password specified in the INI file when the server is restarted.
pingrate <1..10>
Allows for changing the interval (specified in seconds) that the server will ping the clients.
pingtrace < -2 | -1 | 0 | 1..n >
Allows for tracing the ping results as they are reported back from the clients. This option is only valid when issued by remote clients and does not work from the server's console window.
-2 = Display the ping results for those clients that are in the same channel.
-1 = Display the ping results for all clients.
0 = Ping tracing disabled.
1..n = Display the ping results for a specific client (specifies the UID)
quit
Forces the server to shutdown. If the server was started by an NT Service control program then it will be automatically restarted in 10 seconds.
serverstatus
Output detailed status information about the server and specified interfaces.
status
Displays the user id, channel id, login name and IP address for all of the connected users.
timestamp < 0 | 1 >
Enables or disables displaying timestamp's on console and remote console server messages.
tts <text>
This option will send out a Text-to-speech message to all users connected to the server, no matter which channel they are currently in. The <text> can be anything you want. This command and the comment command could be very useful if you are hosting a server that is reserved for a specific amount of time and you want to send TTS messages informing the connected users about how much time remains before the server is shutdown.
version
Displays the application version of the server.
A copy of this program is available with each individual server platform.
This tool is used for submitting status information requests to servers. The following example shows how to issue a general status command "-c1" to a server running on the same machine.
ventrilo_status -c1 -t127.0.0.1
The following example is similar to the one above but will request detailed status "-c2" from the same server.
ventrilo_status -c2 -t127.0.0.1
The -c option specifies the type of request (command).
The -t option specifies the target address and can be an IP address or hostname. Unless otherwise specified the request would be issued to the default port of 3784. If the server you want to status is running on a different port number then you must append the port number to the target address and separated by a colon. The following example shows how:
ventrilo_status -c2 -t127.0.0.1:3794
By default the status program will attempt to request the information 3 times with a 1 second delay between each request in order to guarantee delivery of the request and response. You can override the default number of attempts by placing the -a# option on the command line and replace the # sign with the number of attempts. However, 3 attempts should be more then sufficient.
All of the these options, and any not documented, and more examples can be obtained from the program it self by appending a -? to the command line.
The output from the program is pure ascii text. From the ventrilo.com download page there is a section that deals with additional utilities. One of these is a collection of PHP scripts that shows how to call the program and process the results coming back, in addition to basic examples for calling the other PHP scripts and displaying the results in a meaningful format.