Reference: Setting up the Trace zone proxy service

Use the Trace zone proxy service to establish secure Trace endpoint connections through Zone Servers. This configuration is particularly useful in network topologies that have a DMZ configuration.

The Trace zone proxy service has two parts: the Trace zone proxy (TZ proxy) and the Trace zone hub (TZ hub). The TZ hub is installed on a Tanium Module Server and the TZ proxy is typically installed on a Zone Server. The TZ hub connects to one or more TZ proxies, creating a tunnel between itself and each proxy to allow Trace remote endpoint connections to be established.

Trace zone proxy service connections and certificates

The Trace zone proxy service involves three types of connections:

  1. A TZ hub connects only to the Trace service that is identified by a trusted certificate.
  2. A TZ hub tunnel client initiates a connection to a TZ proxy tunnel service that has two-way authentication.
    1. A TZ proxy tunnel service accepts connections only from a TZ hub tunnel client that is identified by a trusted certificate.
    2. A TZ hub tunnel client connects only to a TZ proxy tunnel service that is identified by a trusted certificate.
  3. Endpoints connect to the TZ proxy that is identified by a trusted certificate.

Figure  1:  Trace zone proxy service certificates

As certificates near expiration, Trace warns you with a message on the workbench. You can expand the message for details about the specific certificate. Errors are also displayed in the same area in a red box. See the following image for examples.

Figure  2:  Trace certificate messages

Import the Trace Zone Hub solution

The Trace zone hub must be installed as a solution from the Tanium Console.

The Trace module, version 2.2.1 or later, must be installed first.

  1. From the Main Menu, click Tanium Solutions.
  2. In the Tanium Content section, select the Trace Zone Hub row and click Import Solution.
  3. Review the list of changes and click Proceed with Import.

    When the import is complete, you are returned to the Tanium Solutions page.

  4. Verify that the values in the Available Version and Imported Version columns match.

If you are using load balancers, persistence is required and they must support secure WebSocket connections.

Create a Zone Server configuration package

For each zone server, you must create a configuration package that contains the certificates and the connection information.

  1. From the Tanium Console, go to Trace.
  2. Click Settings .
  3. On the Zone Server tab, click Add Zone Server.
  4. Fill in the connection details for host name, port, external address, and external port.
    The Zone Server Proxy host name must not be an IP address.
  5. Choose what kind of certificate you want.
    • By default, you can use the auto-generated certificates.
    • If you clear the Auto-generate check box, you can browse to and upload the certificate and key files of your choice. The certificate must be in PEM format. In the certificate signing request, enable both web server and web client authentication.
  6. Click Generate Package. The package displays a Pending status. The path to the encrypted package ZIP file and encryption key displays. You need a specific encryption key to extract the configuration package on a Zone Server.

    The native Windows unzip utility does not support encrypted zip files. Use a third-party utility such as 7zip to unzip encrypted ZIP files on Windows Servers. You can use the 7za.exe utility located at C:\Program Files(x86)\Tanium\Tanium Client\Tools\StdUtils\7za.exe to decrypt and unzip the package.

If you are using split DNS, then you must generate a package for each Zone Server with the same external port and another package for the Tanium Server with the same external address.

Trace generates a deployment package for this proxy that includes all of the necessary certificates and keys. The resulting ZIP file must be handled securely.

Install the package on the Zone Server

Manually install the configuration package on the Zone Server.

(Windows) Prepare the Zone Server

Before you install the Zone Server configuration package, create a directory in which to install the package with the appropriate permissions. To follow the principle of least privilege, choose or create a non-privileged user to run the Trace Proxy service.

The following steps are for Windows Server 2012 R2, but the setup should be similar on other Windows versions.

  1. Sign in to the Zone Server as an administrator. Create the directory where you plan to install the Zone Server package, such as the <zone_server_dir>\trace-zone-proxy directory.
  2. After you create a directory, right-click the directory and go to Properties. In the Properties, click the Security tab and then Advanced.
  3. Click Disable Inheritance. In the Block Inheritance window, click Convert inherited permissions into explicit permissions on this object.
  4. Remove all permission entries except Administrators and SYSTEM.

  5. Add a permission entry for the non-privileged user that you created, giving that user full control.
  6. Assign this same user to be the owner of the directory. Click Change and enter the user name.

Install the Zone Server configuration package

If you are using split DNS, then you must generate a package for each Zone Server with the same external port and another package for the Tanium Server with the same external address.

  1. Delete the existing proxy, if one exists.

    1. On the Zone Server, open a command prompt with elevated privileges. Go to the existing proxy directory, for example: <zone_server_dir>\old_proxy\proxy directory. Run the following command:

      setup --service --uninstall

    2. Delete the proxy directory.

  2. From the Tanium Module Server, copy the Zone Server configuration package.

    The ZIP file is in the <module_server_dir>\services\trace-zone-hub-files\proxies directory. You can see the actual path in the Trace workbench, with the name of the Zone Server configuration package.

  3. Copy the configuration package to the Zone Server. Unzip the package using its encryption key from the Trace workbench into the <zone_server_dir>\trace-zone-proxy directory. If the Zone Server is running Windows, make sure that you assigned permissions to this directory. See (Windows) Prepare the Zone Server.
  4. Open a command prompt with elevated privileges. Go to the <zone_server_dir>\trace-zone-proxy\proxy directory and run the following command:

    setup --service --install

  5. Delete all copies of the Zone Server configuration package ZIP file.
  6. Repeat for each Zone Server.

(Windows) Configure Tanium the Trace Zone Proxy service

After you create the service, change the service ownership to be the non-privileged user that owns the <zone_server_dir>\trace-zone-proxy directory.

  1. Open Windows services. From the Windows Start menu, click Run. Type services.msc and click OK.
  2. Stop the Tanium Trace Zone Server service. Select the service from the list and click Stop.
  3. Right-click the service and go to Properties. Click the Log On tab.
  4. Select This account. Enter the credentials for the non-privileged user.
  5. Start the Tanium Trace Zone Server service. Verify that the service starts successfully.

Publish the packages to the hub and endpoints

After the configuration packages are deployed, share the Zone Server configuration with the TZ hub and the endpoints. All endpoints get all connection information and certificates, allowing them to connect to any proxy.

  1. From the Tanium Console, go to Trace.
  2. Click Settings .
  3. On the Zone Server tab, click Publish All.

When the publish completes, all pending proxy configurations should change to Active and all endpoints receive the external address and proxy certificate for each active proxy.

At this point, the proxy configuration package is updated with the certificates and the zone_servers.json file. The zone_servers.json file contains the connection information for all TZ Proxies and looks similar to the following example:

"zs1.local": {
			"Protocol": "wss",
			"ServerAddress": "zs1.local",
			"ServerPort": 17444,
			"ServerCerts": [ "7f8ca1c2-5a5a-49b5-b5d4-b3c9e3ee4e75.pem" ]"
			},
			"zs2.local": {
			"Protocol": "wss",
			"ServerAddress": "zs2.local",
			"ServerPort": 17444,
			"ServerCerts": [ "a2b6c241-039d-459b-ac2b-57c31e7973e1.pem" ]"
			}
		

With this change, when an endpoint receives an action to initiate a remote endpoint connection, the following logic is used to decide what connection information to use:

  • It gets the value of the registry key HKLM\Software\Tanium\Tanium Client\ServerName. This value indicates the Tanium Server/Zone Server that the Tanium Client is currently registered with.
  • It reads in zone_servers.json and looks for a key that matches the value it obtained from the registry.
    • If a match is found, it uses the corresponding connection information to establish the connection.
    • If a match is not found, the endpoint uses the direct connection information for the Trace service that is included with the action.

Upgrade the Trace zone proxy service

The Trace zone proxy service is not automatically upgraded when the Trace module is upgraded. Although you can upgrade at any time, you can choose to upgrade whenever a new version of the Trace Zone Hub solution is available. See the release notes for information about what is included in the release.

When you upgrade the Trace Zone Hub solution, you must also upgrade any TZ proxies.

Upgrade the hub

  1. From the Main Menu, click Tanium Solutions.
  2. In the Tanium Content section, select the Trace Zone Hub row and click Upgrade Solution.
  3. Review the list of changes and click Proceed with Import.

    When the import is complete, you are returned to the Tanium Solutions page.

  4. Verify that the values in the Available Version and Imported Version columns match.

Upgrade the proxy on each Zone Server

  1. Generate a new Zone Server configuration package.
  2. Install the package on the Zone Server.
  3. Repeat for each Zone Server.
  4. For split DNS, create and install a new package on the Tanium Server.
  5. Publish the packages.

Regenerate or replace certificates

If certificates expire or you need to refresh them, you can regenerate them or upload new ones.

  1. From the Tanium Console, go to Trace.
  2. Click Settings .
  3. Click the Zone Server tab.
  4. Next to the configuration name, click Settings .
  5. Next to the existing certificate name, click Delete.
  6. Choose a certificate type for each certificate that you need to replace.
    • By default, you can use the auto-generated certificates.
    • If you clear the Auto-generate check box, you can browse to and upload the certificate and key files of your choice. The certificate must be in PEM format. In the certificate signing request, enable both web server and web client authentication.
  7. Click Generate Package.
  8. Install the packages.
  9. Click Publish All.

Troubleshoot the Trace zone proxy service

If an endpoint fails to connect to the Trace service after configuring Trace zone proxy service, check the following areas.

  1. Verify that the TZ hub tunnel client can connect to the TZ proxy tunnel service.
    1. Go to the <module_server_dir>\services\trace-zone-hub-files\logs directory.
    2. Review the log for the cause of the unsuccessful connection.

  2. If the tunnel connected successfully, then look for connections coming in from the proxy.
  3. Each error message contains a class.

    • If the class is tunnel client, there is a problem between the hub and the proxy.
    • If the class is proxy client, the connection from the hub to the trace service is not working.

  4. If the proxy has an incoming connection attempt, but there is an error connecting to the Trace service, check the proxy settings on the hub and review the Trace logs.
  5. If there is no connection coming in, review the proxy logs for any connection attempts.

Look for errors in the following directories:

  • On the endpoint:
    • <tanium_client_dir>\Tools\trace\TraceWebSocketClient.log
    • <tanium_client_dir>\Downloads\Action_###
  • In the Trace service log, at <module_server_dir>\services\trace-files\logs\trace.log
  • In the proxy log, at <zone_proxy_dir>\proxy\logs

Uninstall the Trace zone proxy configuration

In certain situations, you might need to remove the Trace zone proxy configuration for troubleshooting purposes.

  1. Delete the zone server configuration from the hub and endpoints.
    1. From the Trace home page, click Settings .
    2. Next to the configuration name, click Settings .
    3. Click Delete .
    4. Click OK.
  2. Uninstall the proxy from the Zone Server.

    1. On the Zone Server, open a command prompt with elevated privileges. Go to the existing proxy directory, for example: <zone_server_dir>\old_proxy\proxy directory. Run the following command:

      setup --service --uninstall

    2. Delete the proxy directory.

The proxy is removed from the hub and the proxy certificates are removed from all endpoints.

Last updated: 5/18/2018 9:49 AM | Feedback