Create and stop virtual servers

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

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

create a new virtual server. The server is started automatically after being created.

Parameters:

  • serverPort – the UDP port to listen for client connections on

  • serverIp – comma separated list of IP address(es) to listen for client connections on. IPv4 and IPv6 addresses are supported.

  • serverName – display name of the server.

  • serverKeyPair – Key pair for encryption. Must be unique for each virtual server. Pass an empty string when originally creating a new server, query the generated encryption key with ts3server_getVirtualServerKeyPair, store it and use it on subsequent start ups.

  • serverMaxClients – maximum number of clients that can be connected simultaneously at any given time

  • result – address of a variable that will receive the virtual server ID that can be used to specify this server in future calls to server library functions.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

The server name and server slots can later be modified using the ts3server_setServerVariableAsString() and ts3server_setServerVariableAsInt() function calls if need be, without having to recreate the server.

On success, the created virtual server will be automatically started.

Important

You should not create a virtual server with an empty keypair except for the first time. If the server crashes, license problems might occur when using “throw-away” keypairs, as the license systems may deem you to be running more virtual servers than you actually are.

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

When a virtual server is started, it will register itself at a TeamSpeak licensing server reporting the maximum client count to ensure the server is operating within the license limits. On shutdown, the virtual server will deregister with 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.

Query Keypair for future reuse

To query the keypair of a virtual server, use

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

retrieve the encryption keys used by the virtual server.

Store these and use them on subsequent process startup to recreate this server when calling ts3server_createVirtualServer

Parameters:

  • serverID – the server for which to get the key pair.

  • result – address of a variable to receive a utf8 encoded c string containing the key pair. Memory is allocated by the server library and must be freed by caller using ts3server_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Stopping a virtual server

A virtual server can be stopped with

unsigned int ts3server_stopVirtualServer(uint64 serverID)

deletes a virtual server. All clients will be disconnected and no more connections are accepted. You need to recreate the server using ts3server_createVirtualServer or ts3server_createVirtualServer2 to make it available again.

You may want to save the state of the virtual server if you need persistence.

Parameters:

  • serverID – specifies which server to stop

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Warning

Nothing of the virtual server remains after it has stopped. You will need to recreate the virtual server afterwards. If you need to save state (e.g. channels on the server) you need to do so before stopping the virtual server.