Skip to main content

TitanHQ Product Docs

Editing the Global Custom JSON Configuration

Warning

Custom JSON is recommended for advanced users only. Incorrect JSON configuration can cause your OTG 2 devices to stop working, so please edit with caution.

Custom JSON configuration can be added to the global device configuration from Settings > Device Configuration . This custom JSON configuration is:

  • Applied to all new devices during OTG 2 installation.

  • Pushed out to any existing devices currently using the default configuration the next time they connect to WebTitan. Updates are not pushed to any active devices that have a custom JSON configuration applied in Environment > Devices.

Important

Device exceptions take precedence over filters. Filters added using JSON are ignored on any device with a device exception assigned. However, any non-filter JSON will be applied as expected.

Follow the steps below to add or edit custom JSON configuration to the global device configuration.

  1. Go to Settings > Device Configuration.

  2. Scroll to JSON Configuration (Default for Devices) and select to expand.

    WT-SL-global-JSON-config.jpg
  3. Slide the Edit JSON Configuration slider to activate the editor and edit the content.

    The content is validated when you save and only valid JSON format is accepted. See https://www.json.org/ external_link.png for information on JSON format.

  4. When you have finished editing, click Save to save your changes and update the device configuration for this device, or click Reset to revert to the device configuration template.

    If saved, the OTG 2 agent syncs with WebTitan every hour to get the latest configuration. OTG will also retrieve the latest configuration following a network change, or following a machine power event.

Custom JSON Configuration Examples

Custom JSON configuration can be added after OTG installation to handle adjustments other than filters to a device. Filters can now be managed from the UI in WebTitan using device exceptions. If a device exception is applied to a device, any filters entered using JSON will be ignored.

See Device Exceptions.

The examples below describe common OTG situations for users and the JSON configuration you can use for that situation.

Warning

Incorrect JSON configuration can cause OTG devices to stop working, so please edit with caution and test carefully.

There is a helpful JSON formatter and validator available at https://jsonformatter.curiousconcept.com/ external_link.png

See Editing the Custom JSON Configuration for a Single Device for details on how to view and edit the configuration for a single device.

See Editing the Global Custom JSON Configuration for details on pushing configuration changes out to all devices.

Note

JSON rules accept CIDR notation. For example:

"rule": "203.0.113.0/24"

Example 1: To hide the OTG OTG-W2-tray-icon.jpg icon from the system tray on a user machine after OTG installation.

Note

The show/hide system tray feature is available with WebTitan OTG 2 for Windows version 2.0.3 or later.

In the configuration example below, "tray_type" can have the following values:

  • "hidden": hides the tray icon.

  • "default": reads the registry value of "hide" or "unhide".

 {
   "cfg":{
      "persistent":{
         "key":""
      },
      "runtime":{
         "locations":[
           
         ],
         "user":"",
         "otg":{
 "tray_type":"hidden"
         }
      }
   },
   "filters":[]}

Example 2: If the public IP of a device is 203.0.113.0, use the default machine DNS resolver.

Tip

This filter can be managed from the UI using device exceptions. If a device exception is applied to a device, any filters entered using JSON will be ignored. See Device Exceptions.

{
   "filters":[
      {
         "rule":"203.0.113.0",
         "resolvers":[
            
         ]
      }
   ]
}

Example 3: If the public IP of a device is 203.0.113.0, use 198.51.100.0 as the DNS resolver.

Tip

This filter can be managed from the UI using device exceptions. If a device exception is applied to a device, any filters entered using JSON will be ignored. See Device Exceptions.

{
   "filters":[
      {
         "rule":"203.0.113.0",
         "resolvers":[
            "198.51.100.0"
         ]
      }
   ]
}

Example 4: If the public IP of a device is either 198.51.100.0 or 56.56.56.57 then use 203.0.113.0 as the DNS resolver.

Tip

This filter can be managed from the UI using device exceptions. If a device exception is applied to a device, any filters entered using JSON will be ignored. See Device Exceptions.

{
   "filters":[
      {
         "rule":"198.51.100.0",
         "resolvers":[
            "203.0.113.0"
         ]
      },
      {
         "rule":"56.56.56.57",
         "resolvers":[
            "203.0.113.0"
         ]
      }
   ]
}

Example 5: If a device is accessing the domain “example.com”, use 203.0.113.0 as the DNS resolver.

Tip

This filter can be managed from the UI using device exceptions. If a device exception is applied to a device, any filters entered using JSON will be ignored. See Device Exceptions.

{
   "filters":[
      {
         "resolvers":[
            "203.0.113.0"
         ],
         "domain":"example.com"
      }
   ]
}

Example 6: When a device is accessing the domain “example.com”, and the public IP of the device is 203.0.113.0, use 198.51.100.0 as the DNS resolver.

Tip

This filter can be managed from the UI using device exceptions. If a device exception is applied to a device, any filters entered using JSON will be ignored. See Device Exceptions.

{
   "filters":[
      {
         "resolvers":[
            "198.51.100.0"
         ],
         "domain":"example.com",
         "rule":"203.0.113.0"
      }
   ]
}

The IP addresses used in these examples are those reserved for documentation purposes per RFC 5737 external_link.png.

Adding a VPN to your Device Configuration

WebTitan OTG 2 recognizes and supports the VPNs listed below by default. If your VPN name matches against this list, it is recognized as an interface to ignore and does not need any further configuration changes.

It is important to note the following about how VPN names are matched:

  1. VPN names are matched against this list using fuzzy-matching, so if you have a VPN named VPN-123 or 123-VPN, it will be recognized.

  2. VPN names are case-sensitive, so if you have a VPN named vpn-123-abc it will not be recognized and you will need to add it to your configuration using the guidelines below to be identified.

Recognized VPNs

  • VPN

  • TAP

  • Cisco AnyConnect

  • Citrix Virtual Adapter

  • Juniper

  • SonicWALL Virtual NIC

  • PANGP

  • Fortinet

  • anywhere access

Adding a VPN to your Configuration

If you have a VPN that is not recognized by matching against the list above, you can add it to your device configuration using JSON config similar to the example below, but edited with your own VPN name(s).

In this example, if you want to add a VPN named My-Office to your configuration, use the following JSON:

{"cfg":{"persistent":{"key":""},"runtime":{"locations":[],"user":"","otg":{"log_level":"diagnose","interfaces_to_ignore":[ "TAP", "VPN", "Cisco AnyConnect", "Citrix Virtual Adapter", "Juniper", "SonicWALL Virtual NIC", "PANGP", "Fortinet", "anywhere access", "My-Office"]}}},"filters":[]}

It is important to note the following:

  1. VPN names in the JSON config are case-sensitive, so any entry made must match your VPN name exactly in terms of case. For example, in the case above where your VPN name is My-Office, entering my-office or My-office will not work.

  2. The VPN list you push out overwrites the existing VPN list, so it is better to append your VPN name to the existing list as shown above. For example, if you push out configuration with a single VPN name, e.g. My-Office, that will overwrite the Recognized VPNs listed above with just that single VPN name.

  3. VPN configuration changes can be pushed out to all your OTG 2 devices, or just to a single OTG 2 device: