3

Add Routing Via Config File

Toby Chui edited this page 2025-02-09 13:53:15 +08:00

Table of Contents

• ProxyType (Host or Vdir)
• Auth Methods (AuthMethod) value
• Deprecated Structures

Other than editing routing in the web UI, you can also create a config file and let Zoraxy load it on startup. You can put your config file under conf/proxy/ as JSON file with file extension ".config". For example, here is an example of (ST).test.localhost.config ** This config structure is for Zoraxy v3.1.7 or above**

{
 "ProxyType": 1,
 "RootOrMatchingDomain": "test1.localhost",
 "MatchingDomainAlias": [
  "test2.localhost"
 ],
 "ActiveOrigins": [
  {
   "OriginIpOrDomain": "example.com",
   "RequireTLS": true,
   "SkipCertValidations": false,
   "SkipWebSocketOriginCheck": true,
   "Weight": 1,
   "MaxConn": 0
  }
 ],
 "InactiveOrigins": [
  {
   "OriginIpOrDomain": "broken.example.com",
   "RequireTLS": true,
   "SkipCertValidations": false,
   "SkipWebSocketOriginCheck": true,
   "Weight": 1,
   "MaxConn": 0
  }
 ],
 "UseStickySession": false,
 "UseActiveLoadBalance": false,
 "Disabled": false,
 "BypassGlobalTLS": false,
 "VirtualDirectories": [
  {
   "MatchingPath": "/firework/",
   "Domain": "example.com/fw/",
   "RequireTLS": true,
   "SkipCertValidations": false,
   "Disabled": false
  }
 ],
 "HeaderRewriteRules": {
  "UserDefinedHeaders": [
   {
    "Direction": 0,
    "Key": "X-Foo-Bar",
    "Value": "hello,world",
    "IsRemove": false
   }
  ],
  "RequestHostOverwrite": "",
  "HSTSMaxAge": 0,
  "EnablePermissionPolicyHeader": true,
  "PermissionPolicy": {
   "accelerometer": [
    "*"
   ],
   "ambient_light_sensor": [
    "*"
   ],
   "autoplay": [
    "*"
   ],
   "battery": [],
   "camera": [
    "self"
   ],
   "cross_origin_isolated": [
    "self"
   ],
   "display_capture": [
    "self"
   ],
   "document_domain": [
    "*"
   ],
   "encrypted_media": [
    "*"
   ],
   "execution_while_not_rendered": [
    "*"
   ],
   "execution_while_out_of_viewport": [
    "*"
   ],
   "fullscreen": [
    "*"
   ],
   "geolocation": [],
   "gyroscope": [],
   "keyboard_map": [],
   "magnetometer": [],
   "microphone": [
    "*"
   ],
   "midi": [],
   "navigation_override": [],
   "payment": [],
   "picture_in_picture": [
    "*"
   ],
   "publickey_credentials_get": [],
   "screen_wake_lock": [],
   "sync_xhr": [
    "*"
   ],
   "usb": [],
   "web_share": [
    "*"
   ],
   "xr_spatial_tracking": [],
   "clipboard_read": [
    "*"
   ],
   "clipboard_write": [
    "*"
   ],
   "gamepad": [],
   "speaker_selection": [],
   "conversion_measurement": [],
   "focus_without_user_activation": [
    "*"
   ],
   "hid": [],
   "idle_detection": [
    "*"
   ],
   "interest_cohort": [
    "*"
   ],
   "serial": [],
   "sync_script": [],
   "trust_token_redemption": [],
   "unload": [
    "*"
   ],
   "window_placement": [
    "*"
   ],
   "vertical_scroll": [
    "*"
   ]
  },
  "DisableHopByHopHeaderRemoval": false
 },
 "EnableWebsocketCustomHeaders": false,
 "AuthenticationProvider": {
  "AuthMethod": 0,
  "BasicAuthCredentials": [
   {
    "Username": "user",
    "PasswordHash": "SHA_512_HASHED_PASSWORD"
   }
  ],
  "BasicAuthExceptionRules": [
   {
    "PathPrefix": "/public/"
   }
  ],
  "BasicAuthGroupIDs": null,
  "AutheliaURL": "",
  "UseHTTPS": false
 },
 "RequireRateLimit": false,
 "RateLimit": 100,
 "DisableUptimeMonitor": false,
 "AccessFilterUUID": "default",
 "DefaultSiteOption": 0,
 "DefaultSiteValue": "",
 "Tags": [
  "private",
  "storage",
 ]
}

ProxyType (Host or Vdir)

0. Root (Reserved)
1. Host
2. Vdir

Auth Methods (AuthMethod) value

0. No auth
1. Basic Auth
2. Authelia (Experimental)

Deprecated Structures

This config structure is for Zoraxy v3.0.2 or above

{
  "ProxyType": 1,
  "RootOrMatchingDomain": "a.example.com",
  "MatchingDomainAlias": [
    "b.example.com",
    "c.example.com"
  ],
  "Domain": "target.example.com",
  "RequireTLS": true,
  "BypassGlobalTLS": true,
  "SkipCertValidations": false,
  "SkipWebSocketOriginCheck": true,
  "VirtualDirectories": [
    {
      "MatchingPath": "/teacat/",
      "Domain": "sorae.co",
      "RequireTLS": true,
      "SkipCertValidations": false,
      "Disabled": false
    },
    {
      "MatchingPath": "/imus/",
      "Domain": "imuslab.com",
      "RequireTLS": true,
      "SkipCertValidations": true,
      "Disabled": false
    }
  ],
  "UserDefinedHeaders": [
    {
      "Key": "X-Custom-Header",
      "Value": "foo,bar"
    }
  ],
  "RequireBasicAuth": false,
  "BasicAuthCredentials": [
    {
      "Username": "test",
      "PasswordHash": "PASSWORD_SHA512_HASH_HERE"
    },
    {
      "Username": "user",
      "PasswordHash": "PASSWORD_SHA512_HASH_HERE"
    }
  ],
  "BasicAuthExceptionRules": [
    {
      "PathPrefix": "/public/api"
    }
  ],
  "AccessFilterUUID": "default",
  "Disabled": false,
  "DefaultSiteOption": 0,
  "DefaultSiteValue": ""
}

Here is another example that is use for default site (previously named Proxy Root). The file must be named as root.config

{
 "ProxyType": 0,
 "RootOrMatchingDomain": "/",
 "Domain": "imuslab.com",
 "RequireTLS": true,
 "BypassGlobalTLS": false,
 "SkipCertValidations": false,
 "VirtualDirectories": null,
 "RequireBasicAuth": false,
 "BasicAuthCredentials": null,
 "BasicAuthExceptionRules": null,
 "DefaultSiteOption": 1,
 "DefaultSiteValue": "imuslab.com",
 "Disabled": false
}

Here are some key items for the proxy config

• ProxyType: 0 = root and 1 = host. For root, name your config file root.config
• RootOrMatchingDomain: Matching rules or keywords, use / for default site router
• Domain: Proxy target / backend
• RequireTLS: Proxy target require TLS (https) connection
• BypassGlobalTLS: Allow this rules to be accessed via port 80 endpoint (if enabled)
• SkipCertValidations: Skip proxy target TLS error, for self sign certificate
• SkipWebSocketOriginCheck: Skip websocket origin check, default enable and usually won't cause any security issues
• AccessFilterUUID: The ID of the access rule filter used, must be matching with the "ID" field inside the access config file