The Ventrilo 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 TCP/IP 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:

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=Welcome

The comment that appears next to the server's name in the same way that a user can assign a comment to their login names. (Optional)

Port=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. (Required)

Auth=0

This is the authentication mode. (Required)

0 = No authentication and anyone can connect.
1 = Global password authentication.
2 = Specific user/password authentication. See section #3 for further details.

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 nolonger 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=32

This option specifies the maximum number of clients that can be connected to the server at the same time. The server has a hard coded maximum limit of 200 clients (as of version 2.0.0), however, your servers network connection might not be able to handle a large number of simultaneous connections. (Required)

SendBuffer=0

Introduced with version 1.03, this option specifies the size of the TCP outbound buffers to each client. The value is in bytes.

Starting with version 1.05 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

Introduced with version 1.05, 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.

Introduced with version 1.03, this option turns on more diagnostic information to be used when troubleshooting problems. However, its mostly for developer use. Starting with version 2.0.0 this option has become almost useless for ordinary users. If you turn it on don't expect much.

LogonTimeout=5

Introduced with version 1.05, 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. Prior to version 1.05 the server used a hard coded value of 3 seconds and occasionally clients would be kicked as soon as connected due to latency in TCP setup times.

CloseStd=1

0 = Don't close standard input, output and error handles.
1 = Close standard input, output and error handles.

Introduced with version 1.07, 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

0 = Allow wave file binds to replicate.
1 = Filter out (prevent) wave file binds from replicating.

Introduced with version 1.07, this option enables or disables filtering of wave file binds being replicated to other users.

FilterTTS=0

0 = Allow TTS binds to replicate.
1 = Filter out (prevent) TTS binds from replicating.

Introduced with version 1.07, this option enables or disables filtering of Text-to-speech binds being replicated to other users.

TimeStamp=0

0 = Disable console timestamp's.
1 = Enable console timestamp's.

Introduced with version 1.07, this option enables or disables timestamp's being displayed in console messages. This includes remote consoles.

PingRate=10

Introduced with version 1.07, 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

Introduced with version 2.0.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.

ChanWidth=0

Introduced with version 2.0.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

Introduced with version 2.0.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

Introduced with version 2.0.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

0=Allow remote consoles to change "maxclients" value.
1=Disable (prevent) remote consoles from changing the "maxclients" value.

Introduced with version 2.0.0, this option prevents remote console commands (those type into the chat window when logged in with server admin rights) from dynamically changing the real "maxclients" allowed by the server. However, if the server was started in a non-daemon mode the local console can still change the maxclients.

DisableQuit=1

0=Allow remote consoles to issue the "quit" command.
1=Disable (prevent) remote console from issuing the "quit" command.

Introduced with version 2.0.0, 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

Introduced with version 2.0.0, this option tells the server which codec all clients must use. The value is a 0 based index into a list of possible codecs. To see the list of currently supported codec types issue the command "ventrilo_srv -?" and the program will display a table of codecs and their associated formats.

VoiceFormat=1

Introduced with version 2.0.0, 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 codecs and their associated formats.

SilentLobby=0

0 = Allow replication.
1 = Suppress replication, thus making the lobby silent.

Introduced with version 2.0.0, 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

Introduced with version 2.1.2 these options allow you to control what should happen to a client if they spam any of these types of events. By default all of the spam variables are commented out so that the server will have the same behavior as previous versions. You will need to remove the leading '#' character from each line in order to activate the option.

Each of these Spam variables uses the exact same format: Action, Interval, Times

Action:
0 = Do nothing. Disables the specific spam filter.
1 = Automatically kick the user.
2 = Automatically ban the user.

Interval:
This parameter specifies the shortest amount of time (in milliseconds) that a client can issue a similar event. Thus, 1000 would mean 1 second.

Times:
This parameter specifies how many times a client is allowed to exceed the given event specified interval. A value of 1 would mean that the very first time a client sends two events of the same type within the span of the specified interval then the action will be triggered.

Please note that the effectiveness of these spam options will be limited. If someone wants to spam your server then they will do so but within the bounds of your spam filters. It might be necessary to set the intervals to a higher value and just make sure that your normal users understand it.

[Intf]

If you are a home user or the computer you run the server on has only one network interface card then you should not be modifying anything in this section. It is intended for machines that have more then one interface and only for restricting which interfaces should be used.

This section allows for controlling which interfaces 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: Starting with version 2.0.0 the "Count=" key is nolonger needed.

Note: Starting with version 2.1.2 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 Status topic is new with version 2.1.2. It enables and controls all UDP traffic associated with the server.

Note: We strongly encourage you to leave this section disabled unless you are running a dedicated server. Home users or dynamic IP based systems would have problems making this work properly and could find them selves under attack by script kiddies or spammers.

Note: If you do enable this feature then please be sure to pay close attention to the following documentation regarding the FilterGen and FilterDetail key words.

Before enabling any features in this section you must first enable both TCP and UDP traffic for the servers port number if the server is running behind a firewall or router, assuming that you want anyone on the outside of the router to be able to send UDP messages to this server. If all UDP messages will be coming from the inside network of the router then this would not be necessary.

Each server distribution now comes with an additional binary program called "ventrilo_status" that can be used to issue UDP request messages to the server. Each of these programs can be used to status any other type of server platform. This is useful if you run your ventrilo server on Linux but your web server on Windows. You would simply install the windows version of the ventrilo_status program on the same machine as your web server and instruct it to send requests to the Linux based ventrilo server. The Ventrilo download page also contains example PHP scripts for calling the ventrilo_status program and processing the results.

By default the Ventrilo server does not support any UDP messages. Specifying one or more "Intf" definitions in the [Status] topic will enable reception of UDP messages.

If you want to receive UDP messages from all interfaces then you would specify the following and no other Intf definitions:

Intf=0.0.0.0

If you want to received UDP message from just the same machine that is running the server (useful if you have a web server running on the same machine) then you would specify the following. Unlike the 0.0.0.0 definition this one can be used in conjunction with other Intf definitions:

Intf=127.0.0.1

Or, you can enter a specific interface address (or hostname) to accept UDP messages from. As mentioned, you can specify more then one interface. The following example shows it restricted to two different interfaces.

Intf=ventrilo.mydomain.com
Intf=127.0.0.1

Password=

The Password option allows for restricting the responses to anyone who provides the correct password as part of the incoming UDP request. If the password field is left blank then it will not be checked. Please note that this password entry is different from the Password= entry in the [Server] topic.

ReplyInterval=500

The ReplyInterval option allows you to control how often the server will respond to incoming UDP status requests. The value is entered as milliseconds. The default value of 500 means that the server will only reply twice a second. This is an effort to prevent script kiddies from spamming the server and flooding the outbound traffic. However, it will not prevent them from flooding the server with inbound spam. If you configure the server to process UDP messages from your internal network only or filter who is allowed to send UDP messages then setting this option to a lower number might be viable.

FilterGen=

There are currently two types of status request messages. The first is called General (or Gen for short) and the second is called Detail. The General status request returns basic info about the server like it's name, uptime, maxclients, number of currently connected clients and other miscellaneous info. The Detail status returns the same information but also includes Channel details and Client details, but this will be discussed in the following info for the FilterDetail keyword.

The FilterGen keyword should only be used if you want to restrict the response to a list of specific IP addresses (not be confused with a specific interface). You can also restrict the response to a subnet of the specified IP address. If you do not provide any FilterGen definitions then all UDP requests for the General status info will be answered. However, if you do specify one or more FilterGen statements then you are restricting the responses to these IP's and/or subnet's. FilterGen can be entered multiple times as the following example will show:

FilterGen=127.0.0.1
FilterGen=192.168.0.0/16
FilterGen=66.139.73.0/24

The first entry means to answer any requests from the same machine. The second entry answers anyone who's IP address starts with 192.168 while the third entry answers anyone who's IP address starts with 66.139.73.

FilterDetail=

Please read the above info for the FilterGen keyword as the two have the same basic format and functionality.

The FilterDetail uses the exact same formatting as FilterGen but it allows you to control who the server will respond to when requesting the detailed information. This is important because the response to a detail request will be considerably larger then the response to a general request. This response size is magnified by the total number of users currently connected to a server. If you have 200 clients currently connected then the detail response will be very large. This is why there are two different filter mechanisms for the same basic information. It's possible that you might want everyone to receive general responses (by not specifying any FilterGen= statements) but you want to restrict the detail requests to your local network or just the machine running the server.

We strongly encourage you to think about setting FilterDetail= statements if you enable the UDP status feature. Failure to do so could result in abuse of the server.

If you run a web server on the same machine that runs the ventrilo server and you want to restrict the details request to just that machine then you would enter the following:

FilterDetail=127.0.0.1

As mentioned the format is identical to that of FilterGen and supports subnet filtering and multiple entries of the FilterDetail keyword. Please read the FilterGen section for details on how to compose the IP addresses.

The "ventrilo_srv.usr" file is used for specifying user login names and other associated details unique to each definition. The users login name must be in brackets like this [Flagship]. Similar to the INI file described above each topic will have the following keys for defining details about each specific user. Using the login names of Flagship and Defiant a USR file might look something like the following.

[Flagship]
UserPassword=test1
ServerAdmin=1

[Defiant]
UserPassword=test2
ServerAdmin=0

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.

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 6 different files used by a server. Version 2.0.0 introduced numbers 5 and 6.

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).
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).
6) ventrilo_srv.chn (Read before program starts, updated when channels are added/deleted)

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.

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 costomization 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 chat window by preceding them with the text "/rcon ". For example "/rcon status". But it does require that the remote client be logged in with the 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 parmaters. Do not include these characters when typing the command.

auth < 0 | 1 | 2 >

Displays the list of possible console commands.

kickall

Displays the user id, channel id, login name and IP address for all of the connected users.

timestamp < 0 | 1 >

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.