Web Launcher Reference

Navigation

• Web launcher is divided into areas of functionality, each area is accessed via an icon/link on the top level navigation bar. From left to right the order is:
  • Clusters: - Shows a drop down list of cluster configurations to pick from, or no entries if a cluster hasn't been created yet.
  • Permissions: - Opens up a popup overlay that allows you to manage permission grants to other users, or switch to another cluster that has granted you permissions.
  • Machines: - Switches to the machine view, which allows you to setup new machines, and manage existing machines.
  • Add Cluster: - Opens up a popup overlay that allows you to create a cluster and as such a cluster configuration. Users are limited to a maximum number of clusters, as these represent actual cluster server installations of one of Citadel's cluster providers, which consume resources. At the moment this is currently limited to a single created cluster.

Cluster Configuration Page

• The cluster configuration page consists of four primary features, and five sub pages of configuration options specific for the given cluster configuration. These pages define essentially everything about your cluster setup of servers, other than the actual shards server software the machines are running, which is controlled under the specific machine entries.

Page Level Features:

• Sync Config: - Used to manually sync the generated ClusterConfig.xml file to all host machines in the cluster. Starting the cluster does this automatically, so this option is rarely needed.
• Start / Shutdown Server: - Attempts to start up the cluster server and all region servers that are configured to auto start. This is how you start up your cluster. Changes to Shutdown Server once started. Important do not attempt to shutdown a server while region servers are still starting up, this will cause an unpredictable state, which will often need to be corrected with Kill server. Shutdown Server performs a graceful shutdown of the cluster as a whole, making sure all regions shutdown cleanly.
• Keep Alive: - Tick this to have the cluster and region servers automatically spin back up in the event of a crash.
• Kill Server: - Attempts to kill all running cluster server and region server processes immediately.

Regions Sub page

• The regions sub page is where you manage your cluster controller, and are presented with a list of region entries for the cluster configuration.

Page Level Features:

• Add Region: - Add a new region entry to your list of region entries.
• Bulk Operation: - Sets a given value on all region entries in the list.

Cluster Controller Entry:

• A single cluster controller entry is composed of the following available features, and information displays.

Features:

• Manage: - Select a cluster server version to install. Updates when available are also shown here.
• Open Cluster Logs: - Opens the external cluster log viewing web site. Login to it using your http://legendsofaria.com login and password. This is a temporary solution until cluster log support can be integrated into web launcher. This also means that only the actual owner of the cluster can view cluster logs at this time, unless they want to share their account details.

Information Displayed:

• Status: - Online / Offline. Cluster Control must be online for regions to connect to it, and always attempts to startup automatically.
• Provider: - The Citadel server where the installed Cluster Server is hosted. This must be set, currently only a single option exists, but in the future there maybe multiple cluster providers in order to handle capacity needs, or serve other geographical regions. E.G. A EU cluster provider that has the clusters hosted in an EU data center, instead of a USA data center.
• Current Version: - Shows the currently installed cluster server software version if any.

Region Entry:

• Each region entry is composed of the following available features, and information displays.

Features:

• Delete: - Remove a region entry.
• Start Region: - Start a single region entry.

Information Displayed:

• Maximum Users: - How many users are allowed in a given region? Currently if any region has reached its max capacity, players attempting to login to the server will enter a login queue until the region is no longer at max users.
• Index: - Represents the port/server index the particular region will be bound to. This is port 3000 plus the assigned index.
• Machine: - The machine entry assigned to this particular region entry or nil if no machine entry is assigned. A machine entry must be assigned for a region to be able to start. Split up regions to run over multiple physical hosts by using multiple machine entries that represent each physical host.
• Required: - True/False, if set to true, a cluster won't be listed as visible or accept regular non-admin level players until all regions marked as Required have the status of accepting users.
• Autostart: - True/False, if set to true, the region will attempt to automatically start when 'Start Server' is pushed. Currently starting regions after initial cluster startup is not supported, so all regions you wish to run must be set to autostart.
• Obj Threads: - Number of object threads to use for this region.
• Address: - Arbitrary name that maps to a given port/server index and World + Subregion combination. Also is used as the label shown in client when connecting/transferring to a given world.
• World: - This is the name of your map and must match the map filename.
• Subregion: - The Subregion name as defined in WorldData.xml for the map.
• Created: - Timestamp of when this particular region entry was created.
• Updated: - Timestamp of when this particular region entry was last updated.
• Status: - Only shown when the region is running, shows the current status of the region server. This is either starting up, or accepting users.

Configuration Sub Page

• A single cluster controller entry is composed of the following available features, and information displays.

Information Displayed:

Configuration:

• Server Name: - Server name, is displayed in community server list on client.
• Server Description: - Server description, is displayed in the community server list on client.
• Access Restriction: - Set to prevent users from connecting to the cluster that lack the required access level.
• Server Visibility: - True / False, if set to true the server will appear on the community servers list that is displayed inside the client. Note that white listed servers will not show publicly.
• White List Required: - True / False, if set to true only user ids that have an access list entry will be able to connect and login to the server.
• Auto Restart: - Auto restart time for the server. This can be specified as either an interval in minutes (e.g 120 would be an automatic reboot every 2 hours) or as a specific reboot time (e.g "14:00") this time is specified in 24 hour notation and is UTC timezone.
• Backup Frequency: - Server backup frequency in minutes. A setting of 0 here will cause accumulating memory usage, as the backup data grows but is never flushed.
• Log Level: - Default logging level for all servers in the cluster.
• Contact E-mail: - Displayed when a cluster banned user account attempts to connect to your server. (e.g. You have been banned. If this was in error, please email [email protected]);

Network:

• Sending Queue Size: - Not currently used.
• Send Timeout: - Not currently used.
• Send Buffer Size: - Not currently used.
• Connection Timeout: - Not currently used.

Client Flood Protection:

• Window Size MS: - Window size to evaluate message maximum setting.
• Message Maximum: - Maximum amount of network messages the client can send within the Window Size MS before being kicked from the server.

Hack Protection:

• Player Position Tolerance: - Range in units the client is allowed to be ahead of the server movement wise before their position is corrected. Too aggressive of a setting will result in additional client rubber banding, due to factors of network latency, and server load/frame time. Too permissive of a setting will allow for speed hacking by hacked clients.

• Created: - Timestamp of when this configuration was created.
• Updated: - Timestamp of when this configuration was last updated.

Event Tracking:

• Redis Host: - URL address of optional redis database server. Used for Event system logging.
• Redis Database Index: - Redis database index to use for the above.

Access List Sub Page

• The access list sub page is where you can add, manage and remove access list entries for users on your server. Use access list entries to grant Access Levels greater than Mortal to select users, and to control access to a non-public server.

Page Level Features:

• Add Access - Creates a new default access list entry.

Access List Entry:

• Each access list entry is composed of the following available features, and information displays.

Features:

• Remove: - Remove this entire access list entry from the access list.

Information Displayed:

• Name: - Friendly name for the access list entry. No function other than organization.
• Access Level: - Specify the access level granted to the user.
• User Id: - Specify the user-id this access list entry applies to. User id is written in the xx-xxxx format.
• Region Admin: - Does the specified user have the right to connect a region server to the cluster? Make sure your user id is listed as a Region Admin or you will be unable to connect regions to the cluster.
• Created: - Timestamp of when this particular region entry was created.
• Updated: - Timestamp of when this particular region entry was last updated.

Mods Sub Page

• The mods sub page is where you can add, manage and remove mod list entries for your cluster of servers as a whole.

Page Level Features:

• Add a Mod: - Creates a new mod entry, at current region servers only support a single global wide mod. Support for multiple mods will be coming in the future.

Mod List Entry:

• Each mod list entry is composed of the following available features, and information displays.

Features:

• Add Client Bundle: - Allows you to add a client bundle to be associated with your mod. Client bundles are Unity asset bundles which download to a connecting client to allow for the use of custom maps and custom assets. Each Client Bundle creates its own Client Bundle Entry, see below for details on client bundle entries and their configuration.
• Remove Mod Entry: - Removes the mod entry from the list of mod list entries.

Information Displayed:

• Name: - The name of your mod. This needs to match the folder name that your mod uses.
• Created: - Timestamp of when this particular mod entry was created.
• Updated: - Timestamp of when this particular mod entry was last updated.

Features:

• Remove Client Bundle Entry: - Removes the specified client bundle entry from the list of client bundles associated with the mod.

Information Displayed:

• Name: - The name of your client bundle, for Scene types this needs to match the name of your map.
• Type: - Client bundles are currently split into two types, Scene and ClientObjects. Scene types are used for custom maps, ClientObject types are used for Custom Object Libraries.
• Value: - The path or URL where this particular asset bundle is hosted. This can be a local system path which is useful during development such as file:/D:/ZenMod/ZenMapTest/Assets/AssetBundles/zmap or a URL for public access such as http://zenshard.com/bundles/zmap

Starting Templates Sub Page

• The starting templates sub page is where you can add, manage and remove starting template list entries for your cluster of servers as a whole. Starting templates define options to pick from during character creation and as such act as presets of a sort.

Page Level Features:

• Add Starting Template: - Adds a new starting template entry to the list.

Starting Template Entry:

• Each staring template list entry is composed of the following available features, and information displays.

Features:

• Remove Starting Template Entry: - Removes the starting template entry from the list.

Information Displayed:

• Name: - Name of the entry to display as a choice during character creation.
• Template: - Name of the xml template file that corresponds to this entry. E.G playertemplate_male (do not include the .xml extension)
• Access Level: - Sets the access level requirement of the connecting user in order to be able to use the starting template entry. If the connecting user's access level is less than the required access level the option will not be shown in the client.
• Created: - Timestamp of when this particular starting template entry was created.
• Updated: - Timestamp of when this particular starting template entry was last updated.

Permissions Overlay

• The permissions overlay is divided into two pages, Granted and Grant.

Granted

• Shows a list of cluster-ids that you have been granted access to from other cluster administrators. Click on a cluster-id to switch to that cluster, and perform any tasks that you have permissions to do.
• To return to your own cluster, visit http://legendsofaria.com/admin-launcher

Grant

• A list of any user-ids that you have granted permissions to administrate your cluster will appear here. Each user-id entry allows for specific administration permissions to be granted or removed at anytime. Likewise each entry features an 'X' option to remove the entry completely, or commit changed permission grants.
• Grant New Permissions button, allows you to create a new user-id entry to grant administration permissions to, you'll need to know their user-id.

Machines Page

• The machine page provides two tasks, the first creation of new machines, the second management of existing machines. These for organization purposes are referred to as machine entries.

Page Level Features:

• Add Machine: - Creates a new machine entry, which than needs setup on a host machine. Instructions are provided in the popup, follow these carefully. Machine entries are used to deploy Shards Server software, optional plug-ins, and for the assignment of regions across machines to form a cluster.
• Manage Machine Entries: - Below Add Machine is presented a list of machine entries, each with their own information displayed and common features as described below.

Machine Entry:

• Each machine entry is composed of the following available features, and information displays. These are unique per machine entry.

Features:

• Manage Plugins: - Optional plug-ins that maybe installed or uninstalled upon a given machine. Custom plug-ins maybe created.
• Update/Restart Launcher: - Update to latest client side launcher software if a new version is available, otherwise allows for restarting of the client side launcher software.
• Update Available!/Manage Shards Server: - Shows when an update is available, allows you to pick any version to install from drop down list.
• Delete: - A machine that is offline can be deleted from the machine entry list.
• Open Local Logs: - Present if the log browser plug-in is installed on the machine. When clicked opens a web browser on the host machine that allows selecting of individual log files to view.

Information Displayed:

• Status: - Online or Offline, shows if the installed machine is actively connected to the web launcher server.
• Server Address: - IP Address of the host that the machine is installed on.
• Name: - User assigned name for the machine. Used for internal management of machines, and assignment of regions to machines by machine name.
• ID: - Unique alpha-numeric identifier of the installed machine. Important for troubleshooting via pm2 status and other commands.
• Hostname: - Name assigned to the host system that the machine is installed upon.
• CPUS: - Number of detected Cores/Virtual cores on the host machine.
• RAM: - Amount of ram detected on the host machine.
• Launcher Version - Version of the client side launcher software installed on the current machine.
• Shards Server Version - Current version of the Shards Server installed on the machine.

Add Cluster Overlay

• A single button Create Cluster is present on this overlay. Pressing it will create a new cluster up to your max allowed cluster count, or will result in a failure in the case you are at your cluster limit.

FAQ

Can I provide a custom directory override for my own Base or Mod directory?

• Yes you can override most machine specific configuration options by creating a "ClusterConfigOverride.xml" file and placing it inside the launcher_data directory. Overrides are enclosed as follows:

<ClusterConfigOverride>

<DataDirectory>/../MyBaseFolder</DataDirectory>

<ModDirectory>/../MyModFolder</ModDirectory>

</ClusterConfigOverride>

Can I use the log browser plug-in remotely?

• Yes you can enable remote access to the log browser plug-in by setting the "remoteAllowed" property to true inside of /launcher_data/settings.json.
• Note: You'll also need to make sure the port is open, and you should take measures to secure this.

Can I make my region servers have visible consoles?

• Yes you can enable visible consoles on region servers with Launcher-0.5.23 and higher. To enable this in the launcher_data/settings.json file set "serverconsole" to true. Make sure to restart the launcher process afterwards for the change to take affect.
• Note: This spawns a console per region server process, it is recommended to use a software solution like ComEnu (https://conemu.github.io/) to move these into a tabbed interface if so desired.

Troubleshooting

My machine failed to setup locally, with an error that npm isn't found?

• Are you running a custom node.js installation? If so you will need to follow the Manual Setup steps to install the client portion of web launcher. These steps are also listed below for easy reference.
  • Make sure you have NodeJS version 8 or higher installed, as well as the VS C++ 2013 runtime installed, and .net 4.5 installed.
  • Download the client side launcher distribution zip. The link for this is included in the Manual Setup panel.
  • Create an empty folder somewhere on your physical host machine, inside this folder create a /launcher folder, extract the downloaded client launcher zip distribution into /launcher.
  • From the Manual Setup prompt, download the configuration file, and place it inside the /launcher directory.
  • Open a command prompt inside /launcher, and run the following commands:
    • npm install pm2 extract-zip -g
    • npm install
    • node bin\launcher
  • After launcher starts, end the program (Ctrl+C)
  • Double click /launcher/launcher_start.bat to restart the launcher process.
  • To ensure launcher auto start on computer login, run the following commands:
    • npm install pm2-windows-startup -g
    • pm2-startup install
    • pm2 save (make sure the launcher process is currently running so its saved to the dump file pm2 save creates)

My machine is showing up as red and offline despite setup being completed.

• Inside the launcher folder you can run launcher_start.bat or launcher_restart.bat to start or restart the local launcher process.

Shards Server installs keep failing or hanging.

• Make sure you don't have anti-virus running that could be causing issues. (Lots of anti-virus likes to detect ShardServer.exe as a potential threat due to the binary obfuscation.) Also make sure you are running under a user account that has appropriate permissions to modify files and create files at that location.

Is there a way to see error logs for the local launcher?

• Yes, at a command prompt you can use the following commands to work with the client side launcher installs.
  • pm2 status - This will show the status of all locally running processes, including the launcher if its active. Included is unique id and name identifiers per process these are used to work with additional pm2 commands.
  • pm2 log <process_name or process_id> shows a portion of the log file for the process if any. Log length can be extended by passing in --lines <number of lines> example: pm2 log launcher-09ac71b9bb5ab5 or pm2 log 0 if launcher-09ac71b9bb5ab5 was process id 0.

I deleted my machine in the web launcher, but I continue to see it inside of pm2 status, what can I do?

• Execute a pm2 delete <process_name or process_id> that matches the deleted machine. Than execute a pm2 save.

I'm trying to run multiple machines on the same physical host, each with the log browser plug-in and am running into trouble?

• Log browser by default attempts to bind to port 1776, currently there isn't any handling for when this fails. In the case of running multiple log browsers plug-ins on a single physical host, you'll want to specify a different port for each log browser plugin. You can do this by editing the /launcher_data/settings.json file.