Pax8 Partner Guides

Downloading and Installing OTG for Mac

Read Before Installing OTG for Mac to understand some important prerequisites before following the steps below to download and install OTG.

Installation is recommended using the command line for both a single install or multiple installs across your network using your preferred deployment method, e.g. group policy.

Ensure you are logged in with administrator privileges before following the steps below.

  1. Click here to download the Mac OTG install file (otg_setup.pkg). The current version of OTG for Mac is 1.4.

  2. Open a terminal and change directory so you are in the same directory as otg_setup.pkg, downloaded in step 1.

  3. Run the following command to initiate installation: sudo installer -pkg otg_setup.pkg -target /

    Important

    You are required to provide your WebTitan Cloud credentials as parameters below. This allows for the automatic creation of your Roaming Locations in WebTitan Cloud. These parameters are used once and not stored.

  4. During installation, an administrator must create a command script based on the sample shown below with parameters edited for your WebTitan Cloud. When passed to OTG, these details create the roaming location key for this device.

    There are four required parameters described in the table below and also several optional parameters which are described further down this page.

    sudo /Applications/WebTitanCloud.app/Contents/MacOS/WebTitanCloud WTC_SERVER_URL=http://mycloud.webtitancloud.com:8080 DNS_RESOLVER=1.2.3.4 CUSTOMER_EMAIL=myemail@mycompany.com CUSTOMER_PASSWORD=mypassword

    The command must be on a single line with no line breaks.

    Note

    With Catalina 10.15 or later, you may get a shell response similar to the following if your password contains a wildcard character:

    zsh: no matches found: CUSTOMER_PASSWORD=xxx

    To correct this, wrap your password in single quotes.

    Required Parameters:

    Parameter

    Description

    Example

    WTC_SERVER_URL

    The URL and port number of your WebTitan Cloud instance. You can get the FQDN by opening a terminal window and typing nslookup followed by the IP of your WebTitan Cloud e.g. nslookup 1.2.3.4

    http://wtc1.webtitancloud.com:8080

    DNS_RESOLVER

    The IP address of the WebTitan Cloud DNS resolver to send DNS requests to.

    1.2.3.4

    CUSTOMER_EMAIL

    The email address for the customer account under which the roaming location will be added.

    docs@titanhq.com

    CUSTOMER_PASSWORD

    The password previously created for the customer account under which the roaming location will be added. If the password contains special characters, wrap it in single quotes.

    'pa$$word!1'

  5. Enter your custom script in the terminal window and press Enter.

  6. When the script has run, OTG will produce output in the terminal window. If the configuration is successful, WebTitan Cloud OTG has been configured will display. An error message will be displayed if there is a problem with the parameters.

After Installing OTG for Mac

There are a number of things to note after OTG installation:

  • Assuming your current external IP address is not configured to be bypassed, OTG will connect to your WebTitan Cloud account and start filtering.

  • After installation, OTG connects to WebTitan Cloud and creates a new roaming location and a new user that will match the macOS account username. The user will have a unique identifier made from the username appended with the computer name, e.g. docs@TRAINING-Mac. If the Mac is a member of a domain, then the user identifier will be the username appended with the domain name.

  • Users created via OTG are assigned the default customer policy, but this can be changed to a new or different policy as required.

  • OTG automatically downloads and installs the WebTitan Cloud SSL certificate to Mac Keychain. This allows the WebTitan Cloud block page for HTTPS sites to be shown without an error.

Optional OTG Installation Parameters

When creating your command line script for installing OTG, as well as the four required parameters there are also several optional parameters which you can use:

Parameter

Description

LOCATION_NAME

When creating a roaming location, OTG assigns the Windows or Mac computer name by default. To change this you can specify a LOCATION_NAME value.

LOCATION_NAME should not be used if installing multiple OTGs, as the roaming location names must be unique.

Example: LOCATION_NAME=Training-PC

LOCATION_NAME_SUFFIX

If specified, a LOCATION_NAME_SUFFIX is appended to the LOCATION_NAME and separated using '@', e.g LOCATION_NAME@LOCATION_NAME_SUFFIX

LOCATION_NAME and LOCATION_NAME_SUFFIX should not be used together if installing multiple OTGs, as the roaming location names must be unique.

Example: LOCATION_NAME_SUFFIX=Laptop

BYPASS_IPS

A remote user may visit a location (e.g. main office) which is also using WebTitan Cloud or any other internal filtering solution for filtering. In this case, you may want OTG to be disabled while there. To do this, the office's public facing IP can be added to a list of bypass IP when OTG is installed. When the user leaves the office, OTG will detect the IP change and start filtering again.

When OTG is in bypass mode, the OTG tray icon will show "status: ignored".

To bypass multiple IPs (e.g. several locations) use a comma to separate them:

Example: BYPASS_IPS=88.88.88.88,22.99.99.99

To bypass a range of IPs use a hyphen to separate the two addresses:

Example: BYPASS_IPS=88.88.88.88-88.88.88.99 (no spaces between the hyphen and IPs).

TRAY_TYPE

Controls the WebTitan Cloud OTG information, logo and popup notifications in the Windows system tray or macOS menu bar. Values can be:

  • 0 - hide the tray icon.

  • 1 - only show tool tip, but no notification balloon. (default)

  • 2 - show both tool tip and notification balloon.

Example: TRAY_TYPE=2

DYNAMIC_FORWARD

Used conditionally forward requests for particular domains to specific DNS servers, based on the current external IP address.

This is useful if you want to treat domains differently depending on where the user is, e.g. if a company's internal domain is the same name as its external domain and where access to the local office resources are impacted if routed externally. The format is:

DYNAMIC_FORWARD= [site]@[external IP]-[Resolvers, …];

Example: DYNAMIC_FORWARD=mycompany.com@123.177.20.80-10.1.0.34;somewhere.com@83.76.163.216-56.11.11.11,192.168.1.1, meaning:

When external IP is 123.177.20.80, a query for *.mycompany.com will be forwarded to 10.1.0.34

and

When external IP is 83.76.163.216, a query for *.somewhere.com will be forwarded to 56.11.11.11 or 192.168.1.1

FORWARD_DOMAIN

Unconditionally forward any requests for the local domain to a local DNS server (rather than to WebTitan Cloud). If enabled, on startup OTG will attempt to get the name of local domain and will store the DNS settings provided, for example by the DHCP server of that local domain.

When OTG detects requests for the local domain (or subdomains), it doesn't send them to WebTitan Cloud, but to the stored IP of the local DNS server.

Can be set either true or false, e.g. FORWARD_DOMAIN=true

RPC_PORT

Allows OTG to specify a port for communication with WebTitan Cloud other than the default 7771.

Note

If this parameter is supplied, private cloud WebTitan Cloud servers must also be configured to listen on the port specified.

Example: RPC_PORT=7772