> For the complete documentation index, see [llms.txt](https://axiomemu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiomemu.gitbook.io/docs/dataserver/dataserver-ini.md).

# DataServer.ini

Database connection, port, logging, and license for DataServer

Primary configuration file for DataServer. All keys live under a single `[DataServerInfo]` section.

## File Location

```
DataServer/DataServer.ini
```

Loaded once at startup. Changes require a DataServer restart.

## Configuration

All keys belong to section `[DataServerInfo]`.

| Key               | Type   | Default     | Effect                                                                                                                                                                    |
| ----------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DataServerODBC`  | string | *(empty)*   | ODBC DSN name for SQL Server. Must exist in Windows ODBC Data Sources on the DataServer host. Required.                                                                   |
| `DataServerUSER`  | string | *(empty)*   | SQL login user. Leave empty to use Windows Authentication if the DSN is configured for it.                                                                                |
| `DataServerPASS`  | string | *(empty)*   | SQL login password. Leave empty when using Windows Authentication.                                                                                                        |
| `DataServerPort`  | int    | `55960`     | TCP port GameServers connect to. Must match each GameServer's DataServer port setting.                                                                                    |
| `AdvancedLog`     | 0 or 1 | `0`         | Enables verbose per-packet logging on both inter-server dispatchers (GS-DS and the extended guild/castle/gens channel). Noisy; use only when diagnosing a specific issue. |
| `LicenseKey`      | string | *(empty)*   | 64-char hex license token tied to this DataServer instance. Required; empty or invalid prevents startup.                                                                  |
| `ControlPort`     | int    | `55991`     | TCP port for the Axiom Server Manager control channel (status, logs, commands, graceful shutdown). `0` = off.                                                             |
| `ControlKey`      | string | *(empty)*   | Shared password for the control channel. Must match this instance's `ControlKey` in the Server Manager. Empty = no password.                                              |
| `ControlBind`     | IP     | `127.0.0.1` | Address the control channel listens on. `127.0.0.1` = only this machine can connect. Not in the shipped file; add the line to change it.                                  |
| `ControlInstance` | string | *(empty)*   | Label shown in the Server Manager to tell instances apart. Not in the shipped file; add the line to set it.                                                               |

{% hint style="warning" %}
The shipped `DataServer.ini` comment says the control channel "listens on 127.0.0.1 only". That is just the default: `ControlBind` can change it. Set a `ControlKey` **before** you bind to a LAN or public address - with an empty key, anyone who can reach the port can control the server.
{% endhint %}

## Database Schema Check

At startup DataServer reads the highest `Id` in table `dbo.AxiomSchemaVersion`. If the table is missing, or the highest `Id` is below `2`, DataServer logs `[Schema] NOT STARTING`, closes its SQL connections and does **not** open `DataServerPort`. GameServers cannot connect.

Fix: run the update from the Axiom Server Manager, or run the numbered scripts from the server package's `migrations` folder (the log message calls it `SQL\Migrations`; files `0001_*.sql`, `0002_*.sql`, ...) in order against the `MuOnline` database. Then restart DataServer.

## Connection Pool

DataServer opens the primary connection plus 4 pool connections, all using the same DSN and credentials. The pool size is fixed at compile time and not configurable via the INI.

Implications for SQL Server sizing:

* Each DataServer consumes 5 concurrent SQL logins
* The SQL login must permit at least 5 simultaneous sessions
* Under load, all 5 can be busy at once; plan `max worker threads` and `max connections` accordingly

## AdvancedLog

| Value | Output                                                                                                      |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| `0`   | Standard log only (connections, errors, summary lines)                                                      |
| `1`   | Adds per-packet header logging for the main GS-DS dispatcher and for the extended guild/castle/gens channel |

Leave off in production. Enable temporarily when tracing a specific save or load path, then disable; the extra I/O slows the server under load.

## Important Behavior

* Keys are read with the Windows INI parser. A missing file or missing key yields the documented default (empty string for text keys, the listed integer for numeric keys), so a missing or unreadable `DataServer.ini` results in an empty DSN and an empty license key, which then fail license activation and the SQL connect
* License activation runs before anything else. An empty or invalid `LicenseKey` stops the process before the SQL connect is attempted
* Primary database connection is attempted first; pool connections open next. Either failure keeps the TCP port closed, so GameServers cannot connect
* License activation requires the license service to be reachable at startup. Offline grace only applies to heartbeats after a successful activation, not to the activation itself
* Quotes, trailing spaces, and BOM can cause silent value truncation
* Related files loaded from the DataServer root alongside this INI: [`AllowableIpList.txt`](/docs/dataserver/allowableiplist.md) and [`BadSyntax.txt`](/docs/dataserver/badsyntax.md)

## Examples

{% tabs %}
{% tab title="Minimal local setup" %}
{% code title="DataServer.ini" %}

```ini
[DataServerInfo]
DataServerODBC = MuOnline
DataServerPort = 55960
LicenseKey = YOUR-KEY-HERE
```

{% endcode %}
{% endtab %}

{% tab title="Production with SQL auth" %}
{% code title="DataServer.ini" %}

```ini
[DataServerInfo]
DataServerODBC = MuOnline
DataServerUSER = mu_app
DataServerPASS = <strong-password>
DataServerPort = 55960
AdvancedLog = 0
LicenseKey = YOUR-KEY-HERE
ControlPort = 55991
ControlKey = <long-random-secret>
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Common Issues

* **Startup freezes at "Loading files..."** - `LicenseKey` is empty, invalid, or the license service is unreachable
* **"Could not connect to database"** - DSN name typo, wrong credentials, or the DSN targets the wrong SQL Server instance
* **"Could not connect pool connection N"** - primary login works but the SQL login's session limit is below 5
* **GameServer cannot reach DataServer** - `DataServerPort` changed but GameServer config was not updated, or a firewall blocks the port
* **`[Schema] NOT STARTING` in the log** - the database is older than this DataServer. Apply the migrations (see [Database Schema Check](#database-schema-check)) and restart
* **Server Manager cannot connect to DataServer** - `ControlPort` is `0`, or `ControlKey` differs from the one set in the Server Manager
* **Excessive log noise, slow responses** - `AdvancedLog` left at `1` under production load

## Related Pages

* [AllowableIpList.txt](/docs/dataserver/allowableiplist.md) - GameServer IP whitelist loaded alongside this INI
* [BadSyntax.txt](/docs/dataserver/badsyntax.md) - forbidden substrings for character and guild names
* [ConnectServer.ini](/docs/connectserver/connectserver-ini.md) - sibling INI for ConnectServer using the same parser conventions