Server configuration file

Almost everything in DartRelay is set in the console. A few settings belong to one particular server, or must keep working when the console cannot be reached. Those live in a small file on each server, dartrelay.config.json. This page explains where the file is, how it relates to the console, and every setting an administrator may need to put in it.

When you need this file

Most administrators never touch it. You need it when:

• You are locked out of the console, for example by a sign-in challenge that cannot be completed or an endpoint that stops DartRelay listening, and need a recovery switch.
• One server in a pool must differ from the others, for example to start drained.
• A setting must be fixed on a server so that nobody can change it from the console. A value in the file overrides the console and is shown there as locked.
• Hosts are prepared over WinRM and you need to adjust how DartRelay connects to it.

Where the file is

The file lives in DartRelay's data folder, the App_Data folder inside the installation folder, beside the SQLite database (if you use SQLite), the logs and the keys that protect stored passwords:

<installation folder>\App_Data\dartrelay.config.json

• It does not exist until somebody creates it. A new installation runs perfectly well without it. Create it as a plain text file with that exact name.
• The console shows the exact path it reads. The recovery box on Authentication → Security and the foot of System → Load balancer both print the full path this server uses.
• Upgrades leave it alone. The data folder is kept when you upgrade, so a setting placed here survives every upgrade.
• Only administrators can open it. The installer locks the data folder to the local system account and Administrators, so edit the file from an elevated editor (for example, Notepad started with Run as administrator).

Format

The file is JSON. Every setting sits inside one top-level "DartRelay" object, grouped into sections. In this guide a key is written with colons between the levels: DartRelay:Proxy:ForwardLimit means the ForwardLimit value inside the Proxy section inside DartRelay.

Example

{
  "DartRelay": {
    "Proxy": {
      "TrustedProxies": [ "10.0.0.10", "10.0.0.11" ],
      "ForwardLimit": 1
    },
    "PublicUrl": "https://apps.example.com",
    "Node": {
      "Draining": false
    },
    "Security": {
      "CaptchaDisabled": true
    }
  }
}

Only include the settings you need. Anything you leave out takes its value from the console or its default.

Writing values

• Switches take true or false. DartRelay also understands the forms people commonly type, such as "yes", "no", 1 and 0. A value it cannot read as a switch is ignored, as though it were not there, and the log names it.
• Lists are written in square brackets, as in the example.
• Backslashes in Windows paths must be doubled: "C:\\Certificates\\portal.pfx".
• Add, do not replace. If the file already exists, add your setting to it rather than overwriting the file, or you may remove a setting somebody else put there.

A file with a mistake in it

A file that is not valid JSON, for example because of a missing comma or quote, does not stop DartRelay. The server starts without it, records an error in the log, and shows a banner in the console saying the file could not be read. Fix the mistake and the file is read again the next time the DartRelay service starts.

How the file and the console work together

The file is one of several places DartRelay reads its server configuration from. Within that configuration a later source wins over an earlier one:

1. DartRelay's built-in defaults.
2. Settings the installer placed in the Windows service's environment, such as the port.
3. dartrelay.config.json on this server.
4. Values given on the command line, used only by support engineers.

For the settings that can also be changed in the console under System → Load balancer, a value in the file overrides the console, field by field, for that one server only. The console shows such a field as locked: it is disabled, carries a set on this server label, and the page gives the path of the file. To let the console's value apply again, remove the setting from the file. The recovery switches described below are read only from the server's configuration and have no console equivalent.

Values in the file are read when the DartRelay service starts, so a change takes effect from the next start of the service.

Settings moved into the console in version 1.9

Before version 1.9, load balancer settings such as trusted proxies, the public URL and sign-in by header had to be written in this file on every server, which made it easy for two servers in a pool to disagree. They are now set once under System → Load balancer. On the first start after upgrading to 1.9 or later, DartRelay copied any such values from the file into the console and removed them from the file, keeping a dated backup copy beside it (the original name with .bak added). Any comments in the file were not kept. A value that differed from what the console already held was left in the file and noted in the log; it still overrides the console on that server.

Settings reference

All keys below sit under DartRelay. "In the console" says where the same setting can be changed without the file, if it can.

Load balancer and proxy settings

These describe the load balancer, reverse proxy or application delivery controller in front of DartRelay. Set them in the console under System → Load balancer unless one server genuinely needs a different value. See Load balancer and ADC integration.

Sign-in by header itself is switched on in the console. DartRelay refuses to turn it on unless at least one trusted proxy is set, because otherwise anybody could send the header.

Pool membership (this server only)

These identify a server within a pool. They are written by the installer when a server joins an existing installation and are not shown in the console. Leave them as they are, apart from Node:Draining. See Running several servers (pools).

The database connection is chosen in the setup wizard, or by the installer when a server joins, and is also kept in this server's data folder. Change the database from the console rather than by hand; see Databases and migration.

Recovery switches

These exist so you can get back into a DartRelay that the console cannot fix, because the problem stops you reaching or signing in to the console. They are read only from the server's configuration, never from the database, for exactly that reason. Remove them again once the problem is fixed.

Host preparation over WinRM

DartRelay normally checks and prepares hosts over Windows file sharing. When that route is not available, and always when DartRelay runs on Linux, it uses WinRM instead. See Adding and preparing hosts.

Older settings

The data folder's location

The data folder, and so this file, is the App_Data folder inside the installation folder. Its location is set when DartRelay is installed and is not changed from inside this file, because DartRelay has to know where the data folder is before it can find the file.

Worked examples

Example: getting back in after a sign-in challenge problem

An administrator switched the sign-in challenge to a third-party provider, the provider's keys were wrong, and now nobody can sign in to the console.

1. On the DartRelay server, open an elevated editor and open (or create) App_Data\dartrelay.config.json in the installation folder.
2. Add the switch, keeping anything already in the file:

   {
     "DartRelay": {
       "Security": { "CaptchaDisabled": true }
     }
   }

3. Save the file. From the next start of the DartRelay service the challenge is off.
4. Sign in, fix the challenge settings under Authentication → Security, then remove the switch from the file.

Example: one server starts drained for maintenance

A pool has two servers. You want the second to come up after maintenance without receiving new sessions until you have checked it. Add "Node": { "Draining": true } to that server's file. When you are satisfied, undrain it from System → Load balancer and set the value back to false (or remove it) so it does not start drained next time.

If something goes wrong

• The console shows a banner saying the configuration file could not be read. The file is not valid JSON. Common causes are a missing comma between settings, a missing closing brace, single backslashes in a path, or the same key written twice. DartRelay is running without the file until it is fixed.
• A setting in the file seems to have no effect. Check the spelling and capitalisation of each level, that it sits inside the "DartRelay" object, and that the DartRelay service has started since you saved it. Check the file is the one whose path the console prints.
• A console field is greyed out with "set on this server". This server's file overrides it. Remove the setting from the file if the console should decide.
• Two servers in a pool behave differently. Compare their files: a value in one server's file applies to that server only.
• You cannot save the file. The editor is not running as an administrator.

Related pages