Proxy Support

From Resonite Wiki
This page is about an upcoming Resonite feature which has not been released nor tested. Information on this page is subject to change and might be outdated.


On some computer networks, you might need to use a Proxy Server to access the internet.

In these cases, you'll need to do some additional setup to make Resonite work with your Proxy Server. You can follow this page to get that setup.

Creating a Startup Config File

Proxy support is configured via a Startup Config File. So if you don't have one of those, create it in the same folder as Resonite's main executable (Resonite.exe).

By default, the config file should be named Config.json.

Adding the Proxy Configuration Section

Within the Config.json file. You'll need to add the following:

{
    "proxy": {

    }
}

Proxy Configuration Options

The Proxy section, contains your proxy configuration. Depending on your setup, you'll need a number of properties:

Property Description Example
autoDetect Set this to true, to tell Resonite to try and automatically detect the proxy configuration. true
address Allows you to specify the web address where Resonite can find your Proxy. Include the Url and Port 127.0.0.1:8080
localBypass When set to true, will bypass the Proxy for local domains such as localhost, 127.0.0.1 true
credentialStore The Credential mode for the proxy. There are a number of options. See #Authentication
username Username for the proxy, only used when credentialStore is set to "UsernamePassword" See #Authentication
password Password for the proxy, only used when credentialStore is set to "UsernamePassword" See #Authentication
required When set to true, Resonite will test the proxy before it starts up and halt if this test fails. See #Testing
test When set to true, Resonite will test the proxy before it starts up to ensure that traffic will run through it correctly. However, if the proxy test fails Resonite will continue to run as per normal. See #Testing

Authentication

To setup authentication you need to configure the credentialStore property to an appropriate value for your authentication needs, pick one of the following values:

  • "UsernamePassword" - Allows you to manually specify a Username and Password for the proxy, specify the username and password with the username and password properties that are described above.
  • "NetworkCache" - Retrieves the credentials from the NetworkCache. TODO: Prime has no idea what the NetworkCache is.
  • "Kerberos" - Retrieves the credentials from Kerberos. TODO: Prime has no idea what kerberos is.
  • "DefaultSystemCache" - Retrieves the credentials from the Default System Cache.

Testing

With either required or test is set to true, Resonite will test your Proxy connection before starting up.

This test makes a single web-request to Resonite's home-page using the proxy to validate connectivity.

If the test fails and required is set, then Resonite will halt start-up. This is recommended in business or security sensitive installations where you want to ensure that traffic goes through your proxy.

Examples

A basic proxy

{
    "proxy": {
        "address": "127.0.0.1:8080"
    }
}

A basic proxy, with Username and Password Authentication

{
    "proxy": {
        "address": "127.0.0.1:8080",
        "credentialStore": "UsernamePassword",
        "username": "ProbablePrime",
        "password": "Cheese"
    }
}

A basic proxy, that is required

{
    "proxy": {
        "address": "127.0.0.1:8080",
        "required": true
    }
}

Troubleshooting

SkyFrost WebProxy test failed

If when starting up Resonite you see a message stating that the "SkyFrost WebProxy test failed", then it means that Resonite tested the proxy you have configured and that this test failed.

Additionally, if your proxy configuration is required then Resonite will have shutdown.

You can resolve this in a number of ways:

  1. Validate your Proxy Configuration, the rest of this page provides information on all of the options.
    • You may need to contact your systems administrator for assistance.
  2. Disable or clear your proxy configuration by removing it from your Startup Config File
  3. Set the "required" property to false, which will enable Resonite to continue running even when this test fails.