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.

At the time of this writing the server is available on four different platforms:

1) Windows 9x/NT4/2000/XP
2) Linux x86
3) BSD x86
4) Sun Solaris x86

The BSD and Solaris versions do not have formal beta test sites at this time so if you chose to use them and have problems be sure to let us know. We would also like to hear from you if you want to become an official beta site for either of these two platforms. However, we will do everything we can to shake out any bugs in the mean time.

The INI file is broken up into four categories:

Server - General configuration info.
Authenticate - Specific user login/password accounts.
Channels - Channel names to be created.
Intf – Accept connections only from specific IP interfaces

Each category is contained in [ brackets ] and each option is entered using option=value formatting. This document will use the settings included in the example INI file.

[Server]

Name=Server

This is the name of the server that appears at the top of the active user list when someone connects. (Required)

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 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 where anyone can connect using the global password.

2 = Specific user authentication where each user is assigned an account name and password. See [Authenticate] for further details about Auth=2.

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 if the clients are configured to automatically reconnect.

AdminPassword=

This is the remote administration password. Leaving this option blank will disable remote admin logins. (Optional)

Password=test

This is the global login password for when Auth mode is set to 1. All users connecting to this server must have this password, otherwise the server will send back an error message stating 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 100 clients (as of version 1.03), 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.

Start 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.

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.

[Authenticate]

UserName=password

If Auth=2 then every person that connects must have their user name and password assigned here. Replace the UserName in this example with the users login name and assign them a password. (Optional)

[Channels]

Control=0

This option must be set to 0. It will be used in future versions of the server once the feature is fully functional and supported. (Required)

Count=2

Specifies the total number of channels that should be created when the server starts. (Optional)

Channel#=Text

If the channels Count option is set to 2 then there should be 2 Channel# names listed in this category and their names will need to be Channel1 and Channel2. The Text portion is what will be displayed in the active users list when a user connects to the server. There is no limit to the number of channels, but you must specify the total number of channels to be created at start up and the Channel1 through Channel(n) entries must exist. (Required if [Channel] Count > 0)

[Intf]

Count=0

Specifies how many network interfaces should be filtered for accepting connections from. If Count is set to 0 then the Ventrilo server will accept a connection from any network interface on a single or multi-homed machine. If this option is set to 1 then the server will only accept connections from the Intf1 option described below.

Starting with version 1.03 more then 1 interface can be specified. A second interface would be named "Intf2", a third would be named "Intf3", etc.

When count is set to 0 the server will automatically add the interface "0.0.0.0" which means to accept connections from all interfaces in the host machine.

Intf1=192.168.0.31

If [Intf] Count is set to 1 then this option specifies which network interface that the server will accept connections from. A DNS name can be used in place of a literal IP address. (Required if [Intf] Count=1)

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.

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. 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.

After starting the server it will record its Process ID, or PID, to a file named ventrilo_srv.pid in the current 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 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.

The server will record all output to a file named ventrilo_srv.log in the current directory in which it was started.

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 4 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).
4) ventrilo_srv.log (Appended to by the server when ever a log message is generated)

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 "/examp" along with all of the necessary files. To start the server with the "-f" option you would simply issue the following command.

/examp/ventrilo_srv -f/examp/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.

/examp/ventrilo_srv -f/examp/3784 -d
/examp/ventrilo_srv -f/examp/4000 -d

The first server would read/write files using the names: 3784.ini, 3784.ban, 3784.pid and 3784.log

While the second server would read/write files using the names: 4000.ini, 4000.ban, 4000.pid and 4000.log

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 the highest possible.

# 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 console 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. After you have completed the following registry configuration options you can issue a “net start ventrilo” in the console window to manually start the Ventrilo service program.

If you want to uninstall the service from your system or want to install a new version, simply perform the following commands in 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.

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 are not defined and 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 3 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 it will take precedence over the WorkDir option.

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, however this is not required.

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 ventrilo_srv.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 ". But it does require that the remote client be logged in with the admin password. The following is a list of all of the console commands and brief descriptions on their meaning and use.

help

Displays the list of possible console commands.

status

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

clientkick <uid>

Instructs the server to disconnect a user where <uid> is the users connection ID number. Do not include the < and >.

clientstatus <uid>

Introduced with version 1.03, this option will output more detailed information about a specified client.

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.

monitor <0|1>

This option is only valid when requested from a remote client using the "/rcon" option in the chat 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. Prior to version 1.03 the monitor command was a toggle.

comment <text>

This option allows the server's comment string to be changed dynamically. The <text> can be anything you want. The < and > are not required.

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. The < and > are not required.

banlist

This option will display all of the banned IP address, the user name of the IP address, the admin who banned them and a reason why.

banadd <ip> <reason>

Adds an IP address and a reason for the banning to the ban list and ban file. Do not include < and >.

bandel <ip>

Deletes an IP address from the ban list. Starting with version 1.03 this command will automatically update the "*.ban" file.

version

Displays the application version of the server.

password <newpassword>

Introduced with version 1.03, allows the global login password to be changed dynamically.

auth <0|1|2>

Introduced with version 1.03, allows the authorization mode to be changed dynamically.

maxclients <#>

Introduced with version 1.03, allows the maxclients value to be changed dynamically.

kickall

Introduced with version 1.03, kicks all clients connected to the server. If issued via an "rcon" command from an admining client, that client is exempted from the kick.

diag <0|1>

Introduced with version 1.03, allows the diagnostic mode to be changed dynamically.

serverstatus

Introduced with version 1.03, output detailed status information about the server and specified interfaces.