Limit the maximum number of client connections, connections per IP address and connection rate.

Syntax

object.Throttle( [MaxClients], [MaxClientsPerAddress], [MaxGuests], [ConnectionRate] )

Parameters

MaxClients

An optional integer value that specifies the maximum number of clients that may connect to the server. If this parameter is omitted, the maximum number of clients allowed will be unchanged. The default value is 100 active client connections.

MaxClientsPerAddress

An optional integer value that specifies the maximum number of clients that may connect to the server from the same IP address. If this parameter is omitted, the maximum number of clients per address will be unchanged. The default value is 4 client connections per address.

MaxGuests

An optional integer value that specifies the maximum number of anonymous (guest) users that may be logged in at any one time. If this parameter is omitted, the maximum number of guest users will be unchanged.

ConnectionRate

An optional integer value that specifies a restriction on the rate of client connections, limiting the number of connections that will be accepted within that period of time. A value of zero specifies that there is no restriction on the rate of client connections. The higher this value, the fewer the number of connections that will be accepted within a specific period of time. By default, there is no limit on the client connection rate.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

Remarks

The Throttle method limits the number of connections and the connection rate to minimize the potential impact of a large number of client connections over a short period of time. This can be used to protect the server from a client application that is malfunctioning or a deliberate denial-of-service attack in which the attacker attempts to flood the server with connection attempts.

If the maximum number of client connections or maximum number of connections per address is exceeded, the server will reject subsequent connection attempts until the number of active client sessions drops below the specified threshold. Note that adjusting these values lower than the current connection limits will not affect clients that have already connected to the server. For example, if the Start method is called with the maximum number of clients set to 100, and then the Throttle method is called lowering that value to 75, no existing client connections will be affected by the change. However, the server will not accept any new connections until the number of active clients drops below 75.

If the value of the MaxGuests parameter is greater than zero, then anonymous logins will be enabled and clients can authenticate with the username "anonymous" and their email address as the password. If the parameter is set to zero, then anonymous logins will be disabled. Note that this will not affect any clients that are currently logged in, it only affects those clients that connect after the Throttle method has been called.

Increasing the ConnectionRate value will force the server to slow down the rate at which it will accept incoming client connection requests. For example, setting this parameter to a value of 1000 would limit the server to accepting one client connection every second, while a value of 250 would allow the server to accept four client connections per second. Note that significantly increasing the amount of time the server must wait to accept client connections can exceed the connection backlog queue, resulting in client connections being rejected.

See Also

MaxClients Property, MaxGuests Property, Resume Method, Start Method, Suspend Method, Stop Method

Copyright © 2024 Catalyst Development Corporation. All rights reserved.