Skip to content

oodproxy client installation instructions

Jump to bottom
jdeananderson edited this page Nov 4, 2025 · 15 revisions

Table of Contents

Linux Installation

To access VNC or RDP desktops directly from Linux, follow these steps.

1. Download the Client Package

Download the latest .deb installer from the GitHub Releases page.

2. Install the Package

Open a terminal and run:

sudo apt install ./oodproxy-client_x.x.x_all.deb

3. Dependencies

The installer installs required dependencies, including:

  • socat
  • gpg
  • tigervnc
  • freerdp

If any of these are missing, parts of oodproxy-client may not work.

4. Configuration

No manual configuration is required. Each time oodproxy-client runs, it:

  • Downloads a configuration file from the Open OnDemand job.
  • Establishes a secure VNC or RDP connection using the provided settings.

Windows Installation

To access VNC or RDP desktops directly from Windows, install the following:

Installing Stunnel

Stunnel is used to establish a secure encrypted connection to the HPC cluster.

  1. Download the installer from the Stunnel Downloads Page.
    Look for a file named like stunnel-latest-win64-installer.exe.

  2. Run the installer.

  3. During installation, a prompt may ask for certificate details:

    Country Name (2 letter code) [PL]:

    Note: You can simply press Enter repeatedly or close the prompt.
    The certificate generated during this step will not be used.

  4. Choose whether to install for all users (admin privileges) or just the current user.

Installing TurboVNC

TurboVNC is the VNC client used to connect to Linux desktops.

  1. Download TurboVNC from the TurboVNC Releases.
    The file name will look like TurboVNC-<version>.exe.

  2. Run the installer.
    Installation requires administrator privileges.
    Follow the standard installer prompts.

Installing the oodproxybyu Client

  1. Download the ood_proxy_byu_setup.exe client installer from the latest GitHub release.

  2. Double-click the installer.

    • Ensure Stunnel and TurboVNC are already installed.
    • The installation is quick and straightforward.
    • No manual configuration is required. Each time the oodproxybyu client runs, it uses a configuration file downloaded from the Open OnDemand job and launches a secure VNC or RDP connection using that information.

Note for Enterprise Clients in a Windows Domain

Why Policy Exceptions Are Needed on Domain Clients

The ood_proxy_byu client retrieves a temporary Windows password for your job’s 7lbd VM from the Open OnDemand server and inserts it into the local Windows Credential Manager.
Once stored, the client connects to the remote RDP server.

Domain-joined Windows clients, by default, do not allow credentials from the local Credential Manager.
They require domain authentication instead. Because HPC cluster VMs are not domain members and use one-time passwords, a local policy exception is needed.

This exception allows local credentials to authenticate to a single IP: 127.12.25.37.
This loopback address is used by stunnel to create a secure tunnel to the remote HPC host.
The address is hard-coded into the Windows ood_proxy_byu client and will not change.

What Policies Are Added

The policy installer adds four registry keys.
These can also be applied manually through local policy if preferred.

The installer checks for these keys on domain-joined clients before allowing installation:

Root: HKLM; Check: IsDomainJoined; Subkey: "SOFTWARE\Policies\Microsoft\Windows\CredentialsDelegation"; ValueType: dword; ValueName: "AllowSavedCredentials"; ValueData: 1
Root: HKLM; Check: IsDomainJoined; Subkey: "SOFTWARE\Policies\Microsoft\Windows\CredentialsDelegation"; ValueType: dword; ValueName: "AllowSavedCredentialsWhenNTLMOnly"; ValueData: 1
Root: HKLM; Check: IsDomainJoined; Subkey: "SOFTWARE\Policies\Microsoft\Windows\CredentialsDelegation\AllowSavedCredentials"; ValueType: string; ValueName: "1"; ValueData: "TERMSRV/127.12.25.37"
Root: HKLM; Check: IsDomainJoined; Subkey: "SOFTWARE\Policies\Microsoft\Windows\CredentialsDelegation\AllowSavedCredentialsWhenNTLMOnly"; ValueType: string; ValueName: "1"; ValueData: "TERMSRV/127.12.25.37"

The uninstaller will attempt to remove these keys.
If you have no other related credential policies, all will be removed.
If you have other policies, only the entries for 127.12.25.37 will be removed.

Using the oodproxybyu Client

Once installed, follow these steps to use the oodproxybyu client:

  1. Launch a desktop job (Linux or Windows) through your HPC cluster’s Open OnDemand interface.

  2. You will see an Open OnDemand job card similar to the following:

    rdp_card
    Example: Open OnDemand job card with VNC and RDP buttons highlighted.

  3. Click the VNC or RDP button on the card (highlighted in red above).

  4. Your browser will download a .oodproxybyu configuration file.

  5. Click the downloaded file in your browser’s download menu:

    oodproxybyu_download
    Example: Config file download in browser.

  6. The oodproxybyu client will:

    • Create a secure encrypted tunnel.
    • Launch TurboVNC or your system’s RDP client.
    • Connect you directly to your desktop session.

“Your credentials did not work” Error (on a Windows client)

There are several possible causes for authentication failure on Windows:

  1. Domain Policy Overrides
    Domain-joined clients may have group policies that override local credential exceptions, even if installed correctly.

  2. Local or Domain Restrictions
    Policies on the machine or domain may prohibit the use of saved credentials in the Windows Credential Manager.

  3. Windows Defender Credential Guard
    If the error message says
    “Windows Defender Credential Guard does not allow using saved credentials,”
    you must disable Windows Defender Credential Guard before authentication will work properly.
    This issue affects both standalone and domain-joined machines.

Clone this wiki locally