Create and stop virtual servers

A new virtual server can be created within the current server process by calling:

unsigned int ts3server_createVirtualServer(serverPort,  
 serverIp,  
 serverName,  
 serverKeyPair,  
 serverMaxClients,  
 result); 
unsigned int serverPort;
const char* serverIp;
const char* serverName;
const char* serverKeyPair;
unsigned int serverMaxClients;
uint64* result;
 

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h. On success, the created virtual server will be automatically started.

[Caution]Caution

You should not create a virtual server with an empty keypair except than the first time. If the server should crash, license problems might result when using “throw-away” keypairs, as the license systems might consider you are running more virtual servers than you actually do.

Instead query the keypair the first time the virtual server was started, save it to a file and reuse it when creating a new virtual server. This way licensing issues will not occur.

See the server sample which is included in the TeamSpeak 3 SDK for an example on how to save and restore keypairs.

[Caution]Caution

When a virtual server is started, it will register itself at a TeamSpeak licensing server reporting the maximal client count to ensure the server is operating within the license limits. On shutdown, the virtual server will unregister at the licensing server.

This leads to two important things to keep in mind:

1) Don't just kill your server with Ctrl-C, instead ensure it's shutdown properly calling ts3server_stopVirtualServer. If killed too often, the licensing server might reject this server instance because the license seems to be exceeded as client slots are only added but never removed.

2) Don't start a virtual server too frequently. This may raise an error virtualserver started too many times in a certain time period. Contacting the licensing server will be prevented to protect our backend services from getting spammed with frequent server updates for the same server.

The trigger conditions for this error are very specific and are as follows:

  • You start a server instance and then stop the same instance within 5 seconds of it being started.

  • The above happens more than 3 times in a 41 minute window.

After you triggered this error, you will be prevented from starting any server instance using the affected license for a period of 12 minutes.

You should first investigate how you managed to trigger this error and change your scripts to avoid triggering the conditions above. Then you must not start any server instance for the 12 minute grace period mentioned above. After this wait, you should be able to start your instance normally.

[Note]Note

The TeamSpeak 3 server uses UDP. Support for TCP might be added in the future.


To query the keypair of a virtual server, use:

unsigned int ts3server_getVirtualServerKeyPair(serverID,  
 result); 
uint64 serverID;
char** result;
 

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h. If an error has occured, the result string is uninitialized and must not be released.


A virtual server can be stopped with:

unsigned int ts3server_stopVirtualServer(serverID); 
uint64 serverID;
 

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h.