Open-E Tang Server for Windows ver 1.1.0

From Open-E Wiki
Revision as of 12:02, 15 October 2026 by Ai-B (talk | contribs) (New Extension article: Open-E Tang Server for Windows 1.1.0)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

The Open-E Tang Server for Windows (oe-tang) is the key server for Network-Bound ZFS Encryption (NBZE). It holds the keys that let your storage server unlock its encrypted pools automatically. The storage server unlocks only while it can reach a Tang server. A storage server that has been removed from your network cannot reach one, so its pools stay locked.

Note: This article describes version 1.1.0 of the Open-E Tang Server for Windows. If you installed a newer version, refer to the matching Extension:Open-E_Tang_Server_for_Windows_ver_<version> article. The storage server side (adding Tang servers, enabling network unlock for a pool) is described in Extension:Network-Bound_ZFS_Encryption_rev_01.

Requirements

  • Windows Server 2016 or later, or Windows 10/11, 64-bit.
  • An administrator account.
  • A free TCP port on the Windows machine. The default is 7500; see Troubleshooting below if it is taken.
  • The IP addresses of the storage server. In an HA cluster, the addresses of both nodes.

Where to run it

  • Run two Tang servers. Install oe-tang on two separate Windows machines. The storage server needs to reach only one of them, so a single reboot or outage does not block unlocking.
  • Never run the Tang server on the storage server it unlocks, or in a virtual machine stored on that storage server. After a full power loss the storage server could not unlock itself, because its Tang server would be locked inside it.
  • Keep the Tang server inside your site. It must not be reachable from the internet or through a VPN from outside. Being on your network is what grants the right to unlock, so allow only the storage server through the firewall.
  • Plain HTTP is intended. The protocol never sends the storage keys over the network, so TLS is not needed.

Setup

  1. Run oe-tang-setup-<version>.exe and confirm the administrator prompt.
  2. On the Settings page enter:
    • Storage server addresses: the IP addresses of the storage server, both nodes of an HA cluster, separated by commas (a network such as 192.168.10.0/24 also works). Only these addresses can reach the Tang server through the Windows Firewall.
    • Port: keep 7500 unless that port is already used on this machine.
  3. Finish the setup. The setup checks the entries before it continues. It then:
    • installs the program in C:\Program Files\Open-E\Tang;
    • creates the keys in C:\ProgramData\Open-E\Tang\db, accessible to SYSTEM and Administrators only (existing keys are kept);
    • installs and starts the Windows service oe-tang (Open-E Tang Server). It starts with Windows and restarts itself if it fails;
    • creates a Windows Firewall rule for the listed addresses only.
  4. Open the Open-E Tang Server window (see below) to read the signing key thumbprint. You compare it when you add the server on the storage server.
  5. Repeat on the second Windows machine.
  6. On the storage server, add both Tang servers as described in Extension:Network-Bound_ZFS_Encryption_rev_01.

The details list at the end of the setup ends with a firewall check. Lines starting with WARNING need attention, for example the firewall being off for a network profile or another rule opening the port to any address.

Every setup run, attended or not, is recorded in C:\ProgramData\Open-E\Tang\logs\setup.log (settings, each step with its result). Open it as administrator.

Setup options

  • Update: run the setup again (the same or a newer version). The current settings, including the addresses and the port, are pre-filled and the keys are kept. An update keeps the service and its firewall rule: it stops the service only while it replaces the program, starts it again at once and then applies the settings. If a step fails, the service keeps running with its previous settings.
  • Interrupted setup: if the setup was interrupted (closed, killed, machine restarted) and the service is stopped, run the setup again. It repairs the installation and keeps the keys and settings.
  • Silent installation (for deployment tools):
 oe-tang-setup-<version>.exe /S /ALLOW=192.168.10.21,192.168.10.22 /PORT=7500
Exit code 0 means success, 2 invalid settings, 3 a failed step. For an update, /ALLOW and /PORT may be left out: the current addresses and port are kept. For an unattended run, setup.log is the place to look when the exit code is not 0.
  • Uninstall: Settings → Apps → Open-E Tang Server → Uninstall. This removes the service, its firewall rule and the program. The keys and log are kept unless you tick Keys and log. Deleting the keys means pools connected to this server can then be unlocked only with their passphrase. Silent uninstall (keeps the keys):
 "C:\Program Files\Open-E\Tang\uninstall.exe" /S

The Open-E Tang Server window and tray icon

Tray icon. When the setup finishes, and at every sign-in, an icon in the notification area shows the state of the Tang server (Windows may place it under the ^ arrow of hidden icons): green (running and answering), amber (running but not answering) or red (stopped). Windows shows a notification when the server stops, stops answering or runs again. Right-click the icon for Open, Start service, Stop service and Exit (closes only the icon; the server keeps running).

Window. Start menu → Open-E Tang Server, or double-click the tray icon. It asks for administrator rights. Only one window is open at a time: starting it again brings the open window forward (or flashes its taskbar button).

  • Status
    • Service state and Local check. It checks only that the Tang server answers on this machine. Whether the storage servers can reach it is checked with Check now in the storage server's Network-Bound Encryption panel; the Firewall box shows the firewall side.
    • Port with Change…: moves the server to another port. It refuses the current port and a port that is in use, and warns you first. It changes the listening port and the firewall rule (same addresses) and restarts the service. If the service does not start or does not answer on the new port within about 5 seconds, everything is undone and the server runs again on the old port. Afterwards, change the address on every storage server (the port is part of it) and click Update all pools.
    • Allowed addresses of the firewall rule, with Change… (both nodes of an HA cluster; removing an address asks you to confirm).
    • Tang server URL: a drop-down of this machine's usable IPv4 addresses and Copy, which copies only the URL. Choose the address the storage servers can reach. If it shows No IPv4 address of this machine is usable, check the network adapters.
    • Signing key thumbprint with Copy.
    • Firewall check, with Copy firewall check.
    • Start, Stop, Restart.
  • Keys: every key with its thumbprint, use, state (offered or old), date and last unlock. Rotate keys…, Retire old keys… and Back up keys… (see below).
  • Log: the last 1000 requests, filtered by All, Unlocks or Errors. Open log file, Event Viewer.
  • About: version, key folder, log file, program folder and a link to the help (this article).

Everything in the window can also be done with oe-tang.exe (see Command line below).

What the Tang server stores

  • Its own keys, in C:\ProgramData\Open-E\Tang\db: a signing key and an exchange key. They are what the storage servers' connections need. After a key rotation, the old keys are kept there until you retire them. Back them up, and keep the backup secret.
  • A log of requests (log file and Windows Event Log): the address of the storage server, the time and which key was used. No secrets.
  • Nothing per pool: no passphrase, no pool key, no pool name or ID, and no list of storage servers. Adding a pool or updating a pool's connection on the storage server never writes anything to the Tang server; the connection is stored on the pool itself.

Back up the keys

Use Back up keys… on the Keys tab, or copy the folder C:\ProgramData\Open-E\Tang\db (as an administrator) to a secure, offline location. Without these keys, pools connected to this server can only be unlocked with the pool passphrase.

Treat the backup as a secret. Anyone who has it and a stolen storage server can unlock the server's pools.

Restore the keys

A backup is a folder oe-tang-keys-<date>-<time> with the key files (*.jwk). File names starting with a dot are old keys from a rotation; keep the names unchanged.

On the same machine (keys deleted or damaged):

  1. Stop the service (Stop on the Status tab, or oe-tang.exe stop).
  2. As an administrator, copy all *.jwk files from the backup folder into C:\ProgramData\Open-E\Tang\db.
  3. Start the service and check the Keys tab: the signing key thumbprint must be the one the storage servers confirmed.

On a new machine:

  1. Run the setup as described above. It creates a new key pair.
  2. Stop the service and delete the new *.jwk files from C:\ProgramData\Open-E\Tang\db. Otherwise the server offers two signing keys.
  3. Copy all *.jwk files from the backup folder into that folder, start the service and check the Keys tab as above.
  4. If the machine has another IP address or port, change the Tang server's address on every storage server and click Update all pools (see Extension:Network-Bound_ZFS_Encryption_rev_01).

Watching unlocks

Every request is logged: the address of the storage server and the time, no secrets.

  • Log tab of the window, or the log file C:\ProgramData\Open-E\Tang\logs\oe-tang.log with one line per request. Local health checks of the server's own address are not logged.
  • Windows Event Viewer → Windows Logs → Application, source oe-tang. Unlocks are Information events (ID 1), errors returned to clients are Warnings (ID 2) and fatal errors are Errors (ID 3).

An unlock you did not expect, for example outside a reboot or maintenance window, is worth investigating.

Key rotation

Rotate keys periodically, or immediately if the key folder may have been exposed. Do one Tang server at a time:

  1. On the Tang server, on the Keys tab, click Rotate keys… (or run oe-tang.exe rotate). It creates new keys and restarts the service. The old keys stay available for existing pool connections but are no longer offered.
  2. On the storage server, fetch and confirm the new thumbprint in the Tang servers panel (compare it with the Keys tab or oe-tang.exe list) and click Update all pools. See Extension:Network-Bound_ZFS_Encryption_rev_01.
  3. Only when all pools are updated, click Retire old keys… (or run oe-tang.exe retire -y) and confirm that all pools are re-connected. This restarts the service, and the old keys stop working at once. Doing it earlier would leave pools that still use the old keys unable to unlock through this server.

Command line

The oe-tang.exe commands run in an elevated PowerShell (Run as administrator) in the program folder: Set-Location "C:\Program Files\Open-E\Tang".

Command Purpose
.\oe-tang.exe status Service state, keys and firewall check
.\oe-tang.exe thumbprint Show the signing key thumbprint
.\oe-tang.exe list Show keys and thumbprints
.\oe-tang.exe rotate Create new keys and restart the service (see Key rotation)
.\oe-tang.exe retire -y Delete the old keys and restart the service
.\oe-tang.exe port <n> -y Move the service to port <n> (firewall rule and restart included; undone on failure). Without -y it only prints the warning. Change the address on every storage server afterwards and click Update all pools.
.\oe-tang.exe firewall -allow <addresses> Replace the allowed addresses in the firewall rule
.\oe-tang.exe firewall -remove Remove the firewall rule
.\oe-tang.exe start / stop Start or stop the service
.\oe-tang.exe serve Run in the console instead of as a service (Ctrl+C stops)
.\oe-tang.exe uninstall Remove only the service and its firewall rule; to remove everything use Apps in the Windows settings

There is no remote management interface. The keys and settings are managed only on the Windows machine, in the window or with oe-tang.exe.

Troubleshooting

Symptom Cause and fix
The service stops right after start Check Windows Event Viewer → Application, source oe-tang.
Port 7500 is in use on the Windows machine Run the setup again with another port, or use Change… next to Port in the window. Enter the server as <address>:<port> in the storage server panel and click Update all pools. To see what uses the port: Get-NetTCPConnection -LocalPort 7500
The storage server reports the Tang server unreachable In the window, check Service, Firewall and Allowed addresses (or run oe-tang.exe status) and fix any WARNING. Check any firewall between the two networks.
The setup was interrupted and the service is stopped Run the setup again. It repairs the installation and keeps the keys and settings. Details: C:\ProgramData\Open-E\Tang\logs\setup.log (open it as administrator).
Access is denied in PowerShell Run PowerShell as administrator.

Known issues and limitations

  • Windows only. This Tang server runs on Windows.
  • No remote management. Its keys and settings are managed only on the Windows machine, in the window or with oe-tang.exe.
  • Two Tang servers recommended. The storage server lists at most three Tang servers.

Changelog

ver 1.1.0

  • Tang server for Windows (oe-tang) for Network-Bound ZFS Encryption, installed as the Windows service oe-tang with a Windows Firewall rule for the storage server addresses.
  • The Open-E Tang Server window and tray icon: status, port and allowed addresses, keys, log, About.
  • Setup with update in place, repair of an interrupted setup, silent installation and setup.log.
  • The oe-tang.exe command line.
Retrieved from "https://wiki.open-e.com/default/wiki/index.php?title=Extension:Open-E_Tang_Server_for_Windows_ver_1.1.0&oldid=12470"