Skip to content

Retrieves and updates server information from the Best Servers API.

Notifications You must be signed in to change notification settings

bestserversio/spy

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

A Go program that retrieves and updates game server information such as user counts, map names, and more from the Best Servers API along with adds/updates game servers using APIs such as the Valve Master Server and more!

Building

You may use git, make, and the build.sh script to build/install this project. The build script results in the spy executable being outputted to the build/ directory.

# Clone repository and change to its directory.
git clone https://github.com/bestserversio/spy

cd spy/

# Build Spy project.
./build.sh

# Install Spy executable to /usr/bin and configuration file to /etc/bestservers/spy.json.
sudo make install

# Run project.
spy

Command Line

The following command line arguments are supported.

  • --list -l => Prints the current configuration and exits.
  • --version -v => Prints the current version and exits.
  • --help -h => Prints the current supported command line arguments and exits.
  • --cfg => The full path to the config file (default /etc/bestservers/spy.json).
Example(s)

Load Spy using the local local.json configuration file.

spy --cfg=./local.json

Print help menu.

spy -h

Print current configuration.

spy -l

Configuration

We use JSON to parse configuration files and the default configuration file is located at /etc/bestservers/spy.json. You may change this path with the --cfg command line argument described above.

Types

The following describes the types used in the configuration documentation below. Please not types that are not used in the configuration are not listed.

Name Size (Bytes) Description
string N/A Characters inside of quotes ("")
int 4 A signed 32-bit integer.
uint 4 An unsigned 32-bit integer.
bool 1 A simple true or false type.

General

Please take a look at the following configuration.

Name Type Default Description
verbose int 0 The verbose level. Values 1 - 6 are supported.
log_directory string ./logs The path to the directory to store logs in. Use NULL to disable logging to files.
api BsApi Object {} The Best Servers API object (read below).
web_api Web API Object {} The web API object (read below).
vms Valve Master Server Array [] An array of scanners for the Valve Master Server (read below).
scanners Scanner Array [] An array of Scanner objects (read below).
platform_maps Platform Maps Array [] An array of platform map objects (read below).
bad_names []string [] An array of strings that represent bad names to be filtered.
bad_ips []string [] An array of strings that represent bad IP ranges to be filtered. CIDR ranges are supported (/24). Examples include 192.168.3.0/24 and 192.168.3.5.
bad_asns []uint [] An array of unsigned integers that represent bad ASNs to be filtered (e.g. AS<uint>).
good_ips []string [] A list of IP range(s) to avoid filtering with.
remove_inactive Remove Inactive Object {} Remove inactive servers settings.
platform_filters Platform Filter Array [] A list of platform-specific filters to apply.
remove_dups Remove Duplicates Object {} A list of settings for removing duplicate servers by IP.
remove_timed_out Remove Timed Out Object {} A list of settings for removing timed out servers.
Example(s)

Using a verbose level of 5.

{
    "verbose": 5,
    "api": {

    },
    "web_api": {

    },
    "vms": [

    ],
    "scanners": [

    ],
    "platform_maps": [

    ],
    "bad_words": [

    ],
    "bad_ips": [

    ],
    "bad_asns": [

    ],
    "good_ips": [

    ],
    "platform_filters": [

    ],
    "remove_inactive": {

    },
    "remove_dups": {

    },
    "remove_timed_out": {

    }
}

Setting a few bad names, IPs, and ASNs.

{
    "bad_words": ["badword1", "badword2", "badword3"],
    "bad_ips": ["10.4.0.0/24", "1.2.3.4", "10.5.0.0/16"],
    "bad_asns": [12345, 43212, 42121]
}

BS API Object

The Best Servers API object includes connection and authorization details to the Best Servers API used for adding/updating servers.

Name Type Default Description
host string "http://localhost" The host and endpoint for the Best Servers API.
authorization string "" The authorization token/string to set in the Authorization request header.
timeout int 5 The request timeout.
Example(s)

Use API at http://myserver.com/api/server/add with the authorization Bearer test and a timeout of 10 seconds.

{
    "host": "http://myserver.com/api/server/add",
    "authorization": "Bearer test",
    "timeout": 10
}

Web API Project

The web API/polling information to retrieve configuration settings for this Spy instance from.

Name Type Default Description
enabled bool false Whether to enable web API polling.
host string "http://localhost" The web API host.
endpoint string "/api/spy/get" The web API endpoint (comes after host in request).
authorization string "" What to set the Authorization request header to.
timeout int 5 The API request timeout.
interval int 120 How often in seconds to polling from the web config (0 = only poll once on Spy startup).
save_to_fs bool true Whether to save the web API to the local config file on the file system.
Example(s)

Use web API at http://myserver.com/api/spy/get with the authorization Bearer test and a timeout of 10 seconds. We want Spy to update every 1200 seconds with information from the web API.

{
    "enabled": true,
    "host": "http://myserver.com",
    "endpoint": "/api/server/add",
    "authorization": "Bearer test",
    "timeout": 10,
    "interval": 1200,
    "save_to_fs": true
}

VMS Object

The Valve Master Server API information.

Name Type Default Description
timeout int 5 The request timeout.
api_token string "" The token/key to use when retrieving game servers from this API.
app_ids []uint [] A list of Steam app IDs to retrieve for. Make sure the platform_maps array object contains a mapping from the app IDs to the platform IDs!
recv_only bool false If enabled, Spy will retrieve game servers from VMS, but not update/add servers to the Best Servers API.
min_wait int 60 The minimum amount of time in seconds to wait between each VMS request.
max_wait int 180 The maximum amount of time in seconds to wait between each VMS request.
limit int 100 The limit of game servers to retrieve per VMS request.
exclude_empty bool true If true, will exclude empty servers from the VMS request directly.
only_empty bool false If true, only empty servers will be returned by the VMS request.
sub_bots bool true If true, subtracts the bot count from the user count when calcaluting the current user count.
add_only bool false If true, game servers from each VMS request will be added to Best Servers only if it doesn't already exist.
random_apps bool false If true, the next app ID is selected randomly instead of in order.
set_offline bool true If true, all servers added by VMS will be set to offline by default.
update_limit int 0 If above 0, will limit the amount of servers to update to this amount.
randomize_res bool false If true, the results from the VMS request will be randomized.
Example(s)

Add a scanner for the Valve Master Server for app IDs 240 (Counter-Strike: Source) and 440 (Team Fortress 2). We want to request the VMS every 1000 - 2000 seconds to avoid rate-limiting. We also want to only add new servers to Best Servers and exclude empty servers from the VMS request.

[
    {
        "api_token": "MY_STEAM_API_TOKEN",
        "min_wait": 1000,
        "max_wait": 2000,
        "exclude_empty": true,
        "add_only": true,
        "random_apps": false,
        "set_offline": true
    }
]

Scanner Object

This is the scanner object. Scanners query existing servers and update their information with different types of query types.

Name Type Default Description
protocol string "A2S" The query protocol to use (supported types are "A2S" so far).
platform_ids []uint [] An array of platform IDs to query with this scanner.
limit int 100 The maximum amount of servers allowed to be query with each batch.
min_wait int 30 The minimum amount of time in seconds to wait between each query batch.
max_wait int 60 The maximum amount of time in seconds to wait between each query batch.
recv_only bool false If true, servers will be scanned/outputted (depending on verbose level), but won' be updated through the Best Servers API.
sub_bots bool false If true, will subtract the bot count from the user count when calculating the user count.
query_timeout int 3 The query timeout in seconds.
a2s_player bool true If the protocol is A2S, will attempt to send an A2S_PLAYER request alongside A2S_INFO to determine if the game server is online/not spoofed.
random_platforms bool false If true, the next platform ID will be selected randomly instead of in order.
visible_skip_count int 0 If over 0, will only scan visible servers up to this value. When met, the counter is reset and the query scans for all servers including invisible.
request_delay int 0 The delay in milliseconds between every server request.
Example(s)

We want to create a scanner that queries existing servers with the A2S protocol and executes every 5 - 10 seconds. The limit will be 1000 servers per execution and we want to also send an A2S_PLAYER request to help prevent spoofed servers. We will be scanning platform IDs 1 (Counter-Strike: Source) and 2 (Team Fortress 2).

[
    {
        "protocol": "A2S",
        "platform_ids": [1, 2],
        "limit": 1000,
        "min_wait": 5,
        "max_wait": 10,
        "a2s_player": true
    }
]

Platform Map Object

The platform maps object is used to map app Ids (from something like the VMS) to platform Ids.

Name Type Default Description
app_id int NULL The app ID to from.
platform_id int NULL The platform ID to map to.
Example(s)

We want to map app ID 240 to platform ID 1 (Counter-Strike: Source) and 440 to platform ID 2 (Team Fortress 2)

[
    {
        "app_id": 240,
        "platform_id": 1
    },
    {
        "app_id": 440,
        "platform_id": 2
    }
]

Remove Inactive Object

The remove inactive object contains settings on automatically removing inactive servers based off of last online.

Name Type Default Description
enabled bool false Whether to enable automatically removing servers.
inactive_time int 2592000 How many seconds since last online to consider a server inactive.
interval int 86400 How often to run the remove inactive functionality in seconds.
timeout int 5 The request timeout.
Example(s)

If we want to remove inactive servers that haven't been online in 500 seconds, we'd use the following. We'll execute the remove inactive functionality every 60 seconds (minute).

{
    "enabled":  true,
    "inactive_time": 500,
    "interval": 60,
    "timeout": 5
}

Platform Filter Object

The platform filters object is used to apply platform-specific filters to servers.

Name Type Default Description
id int 0 The platform ID.
max_cur_users int NULL The maximum current users allowed by servers in this platform.
max_users int NULL The maximum max users allowed by servers in this platform.
allow_user_overflow bool NULL If true, any servers that have more current users than max users will be filtered.
Example(s)

Let's say we want to limit Counter-Strike: Source servers to a maximum of 65 users (both current and max). The CS:S platform ID is 4.

[
    {
        "id": 4,
        "max_cur_users": 65,
        "max_users": 65
    }
]

Remove Duplicates Object

This object contains settings for removing duplicate servers by IP. There are many fake game servers that use every port available on a single IP and these settings mitigate this issue.

Name Type Default Description
enabled bool false Whether to enable remove duplicates checking.
interval int 120 How often to check for duplicates in seconds.
limit int 100 The amount of server IPs to check in one request.
max_servers int 100 The maximum amount of servers allowed on one IP.
timeout int 30 The request timeout.
Example(s)

If we want to check for duplicate servers every 60 seconds (1 minute) with the max servers per IP being set to 1000 and the server limit per request set to 200, we'd use the following.

{
    "enabled": true,
    "interval": 60,
    "limit": 200,
    "max_servers": 1000,
    "timeout": 30
}

Remove Timed Out Object

This object contains settings for removing (setting offline) timed out servers based off of the platform's server timeout.

Name Type Default Description
enabled bool false Whether to enable remove timed out servers checking.
interval int 120 How often to check for timed out servers in seconds.
platform_ids []int [] A list of platform IDs to perform the server timed out check for. If left empty, all platforms are checked.
timed_out_time int 3600 The server's timeout time.
timeout int 30 The request timeout.
Example(s)

If we want to check for timed out servers for Counter-Strike: Source (ID 4) every 120 seconds with a server timeout of 3600 seconds (an hour), we'd use the following.

{
    "enabled": true,
    "interval": 120,
    "platform_ids": [4],
    "timed_out_time": 3600,
    "timeout": 30
}

Credits

About

Retrieves and updates server information from the Best Servers API.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages