Kamal: Created page with "= Administration Server = The Administration Server manages account-level authorization and operational metadata for Spire. It maintains each account's role (trader, manager,..."

2025-12-01T21:45:00Z

Created page with "= Administration Server = The Administration Server manages account-level authorization and operational metadata for Spire. It maintains each account's role (trader, manager,..."

New page

= Administration Server =

The Administration Server manages account-level authorization and operational metadata for Spire. It maintains each account's role (trader, manager, administrator, or service), market-data entitlements, risk parameters, and trading permissions. By centralizing these attributes, it enforces access control, entitlement visibility, and trading eligibility across the system.
The server integrates with the Service Locator to enumerate accounts and with a MySQL database to persist administrative data.

== Configuration ==
The Administration Server is configured via a YAML file that defines network interfaces, database connection, Service Locator integration, and market-data entitlements. Below is the structure of the configuration file with example values:

<pre>
---
server:
# Primary network interface and port the Administration Server binds to.
interface: "0.0.0.0:20100"

# List of addresses the server is reachable at (for registration with Service Locator).
# Typically includes both public-facing and local addresses.
addresses: ["198.51.100.5:20100", "10.0.0.5:20100"]

data_store:
# The address of the MySQL server (host:port).
address: "127.0.0.1:3306"

# The username for authenticating with MySQL.
username: spireadmin

# The password for the MySQL user.
password: 1234

# The name of the database schema where data is stored.
schema: spire

service_locator:
# The address of the Service Locator (host:port).
address: "10.0.0.5:20000"

# The account username used by the Administration Server to authenticate with the Service Locator.
username: administration_service

# The password for the Administration Server's Service Locator account.
password: admin_password

entitlements:
# Market-data entitlement definitions.
# Each entitlement specifies pricing, applicable exchanges, and message types.
- name: Demo Entitlements
price: 0.00
currency: USD
group: demo_entitlements
applicability:
# source: the venue disseminating the market data
# messages: market data message types
# BBO - best bid offer quotes
# BOOK - book quotes
# TAS - time and sales
# IMB - order imbalances
- source: CHIC
messages: [BBO, BOOK, TAS, IMB]
- source: XTSE
messages: [BBO, BOOK, TAS, IMB]
- source: XTSX
messages: [BBO, BOOK, TAS, IMB]
...
</pre>

== Installation & Setup ==

A <code>setup.py</code> script is provided to generate the final <code>config.yml</code>.
The script supports the following arguments:

<pre> python setup.py
--local 0.0.0.0 # Local interface (default: auto-detected IP)
--world 198.51.100.5 # Global/public interface (optional)
--address 10.0.0.5:20000 # Service Locator address (default: local_interface:20000)
--password [REQUIRED] # Administration password
--mysql_address 127.0.0.1:3306 # MySQL server address
--mysql_username spireadmin # MySQL username
--mysql_password secretpw # MySQL password (default: --password if omitted)
--mysql_schema spire # MySQL schema
</pre>

== Risk State Initialization Utility ==

A reset script (<code>reset_risk_states.py</code>) is provided to initialize or reset the risk state for all accounts and is typically run on a daily basis.

== Operations ==

The Administration Server is controlled using three operational scripts: <code>start.sh</code>, <code>stop.sh</code>, and <code>check.sh</code>.
Log files are generated in the format:

<pre> srv_YYYYMMDD_HH_MM_SS.log </pre>

Upon startup, older log files are moved into the <code>logs/</code> directory.

=== check.sh ===

The <code>check.sh</code> script verifies whether the server is currently running by inspecting the PID recorded in <code>pid.lock</code> and testing whether the associated process exists.
If the server is not running, it prints:

<pre> AdministrationServer is not running. </pre>

=== start.sh ===

The <code>start.sh</code> script:

Exits immediately if the server is already running

Creates a <code>logs/</code> directory if necessary

Moves any existing <code>srv_*.log</code> files into <code>logs/</code>

Starts the <code>AdministrationServer</code> process in the background

Writes the PID to <code>pid.lock</code>

Reads network interfaces from <code>config.yml</code> and waits until the server is listening on at least one configured address

This ensures the server is fully initialized before the script exits.

=== stop.sh ===

The <code>stop.sh</code> script:

Reads the PID from <code>pid.lock</code>

Sends <code>SIGINT</code> to request a graceful shutdown

Waits for termination using exponential backoff (up to 300 seconds)

Sends <code>SIGKILL</code> if the server fails to stop cleanly

Appends a forced-termination message to the most recent log file (if applicable)

Removes the <code>pid.lock</code> file

This guarantees consistent shutdown behavior across normal and exceptional conditions.

Administration Server - Revision history

Kamal: Created page with "= Administration Server = The Administration Server manages account-level authorization and operational metadata for Spire. It maintains each account's role (trader, manager,..."