Custom Scripts

From TCAdmin 2.0 Documentation
Jump to: navigation, search

TCAdmin supports the following scripting engines:

  • Iron Python
  • Batch/Shell script Object properties and variables are converted to environment variables.
    • Use Linux environment variables like this: ${Object_Property}
    • Use Windows environment variables like this: %Object_Property%

You can specify if you want to run your script on Windows servers, Linux servers, or both.

Script Events

The following events are supported:

Before created
Occurs before any files and folders have been created.
Available objects: ThisServer, ThisGame, ThisUser, ThisService
After created
Occurs after the service files have been created but before it has been configured as a service. The script is executed in the service's root directory.
Available objects: ThisServer, ThisGame, ThisUser, ThisService
Before deleted
Occurs before the delete process is started. The script is executed in the service's root directory.
Available objects: ThisServer, ThisGame, ThisUser, ThisService
After deleted
Occurs after the service files have been deleted and it has been removed from the database.
Available objects: ThisServer, ThisGame, ThisUser, ThisService
Before reinstall
Occurs before the service files have been deleted. The script is executed in the service's root directory.
Available objects: ThisServer, ThisGame, ThisUser, ThisService, Game Switcher Scripting Variables
After reinstall
Occurs after the service has been reinstalled but before it has been configured as a service. The script is executed in the service's root directory.
Available objects: ThisServer, ThisGame, ThisUser, ThisService, Game Switcher Scripting Variables
Before move
Occurs before the service has been moved. It is executed on the server where the service is currently located. The script is executed in the service's root directory.
Available objects: ThisServer, ThisGame, ThisUser, ThisService
After move
Occurs after the service has been moved. It is executed on the server where the service was moved to. The script is executed in the service's root directory.
Available objects: ThisServer, ThisGame, ThisUser, ThisService
Custom icon
Allows the user to execute the script by clicking on an icon in the service's home page. The script can also be configured as a scheduled task. This requires the "Scheduled Script" feature permission in the game's settings. The script is executed in the service's root directory.
Available objects: ThisServer, ThisGame, ThisUser, ThisService
Custom action
Allows the user to execute the script by clicking on the link in the service's Actions tab. The script can also be configured as a scheduled task. This requires the "Scheduled Script" feature permission in the game's settings. The script is executed in the service's root directory.
Available objects: ThisServer, ThisGame, ThisUser, ThisService
Query monitoring
Occurs after the service has been queried by the game monitor. If there is an error and "Ignore execution errors" is unchecked it will cancel all other query monitoring checks.
Available objects: ThisServer, ThisGame, ThisUser, ThisService, QueryResults
Scripts can also be configured for each detection type in the game's query monitoring configuration. Each detection type has additional variables that are available:
Query Failure: ThisService_TimesNotResponding
Slot Detection: ThisService_MaxSlotsAllowed, ThisService_SlotsDetected
Brand Detection: ThisService_UnbrandedHostname
Rule Detection: Rule, RuleVariable, RuleOperator, RuleValue, DetectedValue
Before started (executed by the Service Manager)
Occurs before the service is started. The script is executed in the service's working directory. After creating or updating a script with this event go to the game's settings and click on Update Existing Services or go to a game server's service settings and click on Save.
Available variables: Service Manager Scripting Variables
After started (executed by the Service Manager)
Occurs after the service is started. The script is executed in the service's working directory. After creating or updating a script with this event go to the game's settings and click on Update Existing Services or go to a game server's service settings and click on Save.
Available variables: Service Manager Scripting Variables
Before stopped (executed by the Service Manager)
Occurs before the service is stopped. The script is executed in the service's working directory. After creating or updating a script with this event go to the game's settings and click on Update Existing Services or go to a game server's service settings and click on Save.
Available variables: Service Manager Scripting Variables
After stopped (executed by the Service Manager)
Occurs after the service is stopped. The script is executed in the service's working directory. After creating or updating a script with this event go to the game's settings and click on Update Existing Services or go to a game server's service settings and click on Save.
Available variables: Service Manager Scripting Variables
External Download Script
This script is executed when a game server has "Enable external download" checked and the local game files don't exist.
Available variables: FilesFolderName, FilesFolderFullName, GameFilesPath, DownloadedFile, DownloadedFileWithoutExtension

Troubleshooting Scripts

  • Enable debug mode on the server.
  • Stop the Monitor or Service Manager service depending on the script's event.
  • Start the Monitor or Service Manager console depending on the script's event.
  • When the script is executed the console will show the output of the batch/shell script or any iron python error.
  • On Linux if the script executes without printing any output make sure you have specified the shell interpreter at the top of the script. For example: #!/bin/bash

How To...

Prevent scripts from hanging

TCAdmin will wait forever until the script completes. To prevent TCAdmin from hanging you need to make sure the commands that you execute never ask for any input from the user. Most commands have a "quiet" mode that disables the user prompts.

For example
rd (Windows) has a /q command line switch to prevent asking to confirm if you want to delete the directory.
rm (Linux) has a -f command to force the command to execute without any prompts.

Print messages from an Iron Python script

Use the "Script.WriteToConsole" function:

Script.WriteToConsole("Hello World");

Throw an exception from an Iron Python script

import clr;
from System import Exception;
raise Exception("CUSTOM ERROR MESSAGE HERE");

Exit from an Iron Python script

Use the "Script.Exit" function:

Script.Exit();

Hide the commands being executed in a Window batch script

Add "@echo off" to the start of your script.

@echo off
echo You should not see the actual command that is being executed.

Get the TCAdmin installation folder

You can use the TCAdminFolder variable.

Windows batch script: %TCAdminFolder%
Linux shell script: ${TCAdminFolder}
Iron Python: TCAdminFolder

Import a .py

Place your custom .py scripts in C:\Program Files\TCAdmin2\Monitor\Shared\Lib or /home/tcadmin/Monitor/Shared/Lib. Python 2.7 is supported.

Use a module that is not included in Iron Python

Install Python 2.7 and add the Lib to the search path.

import sys
sys.path.append("C:\Python27\Lib")
import os
Script.WriteToConsole("Current process id is " + str(os.getpid()))

Capture values before executing the script

  1. Create the variables in the game's custom variables page. In the variable's Options tab check "Script parameter". If you want TCAdmin to save the value entered by the user check "Save script parameter value".
  2. Create a script for the Custom Icon or Custom Action event.
  3. Use the variable in your script and check "Prompt for variable values". TCAdmin will only as for the values of the variables used in the script.
  4. Select the game server. Click on the custom icon or action. It will ask for the variable values.

Secure your script

An invalid value could cause your script to behave in a way that was not intended.

  • Make sure you validate the user's input using the validation options provided by TCAdmin and from your script. You can use the regular expression field to enter an advanced validation. If you don't know how to create regular expressions you can usually find what you want by searching on any search engine. regexlib.com has a large collection of regular expressions: http://regexlib.com/Search.aspx
  • Use numeric textbox, checkbox and combobox instead of textbox whenever possible.
    • A numeric textbox makes sure that the user enters a numeric value.
    • A checkbox allows you to ask for simple yes/no 1/0 values.
    • A combobox makes the user select from a predefined list of values. If the value sent is not in the list it will be rejected.
  • Make sure the variable does not contain back quotes `command here` or any other method of executing a string.
  • Check Execute as the service's user in the script's settings. Even if your script has a vulnerability the damage that can be done will be limited to the guest user's permissions.
    • Note: In some cases it is not possible to run the script as the user that runs the service. For example if you have the game configured to create a user for each service this user does not exist yet when the "before created" scripts are executed.
    • You can confirm the user that is executing a script with the follow commands.
      • Windows: echo %USERNAME%
      • Linux: whoami
For example
You create a backup script for Minecraft. You want your user to enter the name of their world folder. You create a texbox for this.
If you don't validate the input the user could enter "..". This will make your script create a backup of the game server root's parent folder. It could create a backup of all services.
In this case the recommended way to capture a folder name is by using a combobox with Source=File System and FilterType=Directories. This way the user will be shown a list of folders in their game server's root folder. Any value that is not in the list is automatically detected as invalid.