GUI Configuration

Custom Instance Names

You can set a custom instance name to better distinguish between multiple PrivX servers. Custom instance names are displayed in the PrivX GUI, and added to the audit events generated from the server.

To set a custom instance name for a PrivX server:

  1. Gain root-terminal access to the PrivX server.

  2. Edit the shared configuration at ​​/opt/privx/etc/shared-config.toml​​. In this file, set the custom instance name with ​privx_instance_name​​. For example:

    # A custom PrivX instance name to be shown in the header
    privx_instance_name = "​​PrivX Example Deployment 01​​"
    

    Save your changes to the file.

  3. Restart the PrivX services to apply the changes:

    # systemctl restart privx
    

Unique Headings and Watermarks for Connections

You can better distinguish connections by adding headings and watermarks to connections established via the PrivX GUI. You can configure these on Administration→Settings→Global, with the following Host watermarking settings:

  • Heading - Adds a header to the top of the connection GUI.

  • Watermark - Adds watermarks to the connection-GUI background.

Heading and Watermark JSON Syntax

Heading and Watermark are in JSON format. Both settings are arrays of objects where each object defines a heading/watermark. Each object is intended to match only certain connections, which allows having distinct headings/watermarks for different connections.

📘

Note

In situations where multiple heading or watermark objects match a connection, settings from the first matching object are applied.

Heading objects support the following keys and values:

  • selectors - Array of criteria for matching connections. Connections matching one or more of the criteria are given this heading.
  • heading - Object describing heading formatting:
    • text - Text content of the heading. Supports template substitutions.
    • color - (Optional) The background color of the heading in HEX format.
    • style - (Optional) The background color of the heading in color-name format. Overrides color.

Watermark objects support the following keys and values:

  • selectors - Array of criteria for matching connections. Connections matching one or more of the criteria are given this watermark.
  • watermark - Object describing watermark formatting:
    • text - Text content of the watermark. Supports template substitutions.

Selectors

selectors may contain any number of each criterion type. Multiple criteria are evaluated using OR: connections that satisfy any criterion are considered matching. The following criteria are available:

  • address - IP address, IP address range, or domain name. Domain names support glob wildcards.

    Example values:
    "address=192.0.2.100"
    "address=192.0.2.0/24"
    "address=target.example.com"
    "address="*.example.com"

  • port - Target port number or port range.

    Example values:
    "port=22"
    "port=8000-8080"

  • account - Target-account name. Supports glob wildcards.

  • tags - Host tag on target host. Supports glob wildcards

  • common_name - Target host's common name. Supports glob wildcards.

  • client_ip - Client's IP address or IP-address range.

    Example values:
    "client_ip=192.0.2.100"
    "client_ip=192.0.2.0/24"

  • username- Client's user name. Supports glob wildcards.

📘

Note

tags and common_name only work with connections to hosts that are saved in PrivX.

Text

text supports raw text, and the following template substitutions:

  • %u - PrivX User
  • %r - Client remote address
  • %U - Target account
  • %H - Target address
  • %P - Protocol
  • %T - Connect time

Color

color supports HTML color codes (such as #FF0000).

Style

style supports red, green, and orange.

Heading and Watermark Examples

Example Heading setting:

[
  {
    "selectors": ["address=192.0.2.0/24", "tags=prod"],
    "heading": {
      "color": "#FF0000",
      "text": "Production Server - %[email protected]%H"
    }
  },
  {
    "selectors": ["address=*.example.com", "tags=test"],
    "heading": {
      "color": "#00FF00",
      "text": "Test Server - %[email protected]%H"
    }
  }
]

With the previous Heading setting:

  • Connections to the 192.0.2.0/24 network or to hosts tagged with prod will get a red heading reading Production Server - account@host_address, where account and host_address are replaced with the target account and address respectively.

    For example, when connecting as root to 192.0.2.100. The header would read:
    Production Server - [email protected]

  • Connections to the example.com domain or to hosts tagged with test will get a green heading reading Test Server - account@host_address, where account and host_address are replaced with the target account and address respectively.

    For example, when connecting as root to 192.0.2.100. The header would read:
    Test Server - [email protected]

Example Watermark setting:

[
  {
    "selectors": ["tags=eval", "tags=test"],
    "watermark": {
      "text": "%[email protected]%r -> %[email protected]%H"
    }
  }
]

With the previous Watermark setting: