BURSU PAM

What BURSU PAM is

BURSU PAM is a privileged access management (PAM) gateway from BURSUsofts. It is a server that sits between administrators and the servers they manage. A person connects not to the target server but to the gateway; the gateway signs in to the target server itself with a password or key that the person never sees or knows, records everything that happens in the session, lets an auditor watch the session live and terminate it, and writes every action to an audit log protected against unnoticed editing.

What the gateway can do

Who works with the gateway

The console has four roles. They are covered in detail in the chapter “Roles”; here they are listed so that you know which chapter is for whom.

How the gateway is built

The gateway is a single .NET 10 process (the bursu-pam-gateway service) on your server, next to a PostgreSQL database. It accepts people's connections on its own ports, checks whether the connection is allowed, opens the connection to the target server itself and passes the session through itself, recording it.

  User                                           BURSU PAM gateway                           Target servers
 ───────────────                ──────────────────────────────────────────────           ────────────────
  BURSUcm (PAM Gateway) ─HTTPS─►  web console and client API (port 443)
                        ─SSH───►  SSH entry                  (port 2222) ─── SSH ──────►  Linux, Unix
  OpenSSH, PuTTY, WinSCP ──────►      │                                   ─── Telnet ───►  network equipment
  mstsc, .rdp file ────────────►  RDP entry                  (port 3389) ─── RDP ──────►  Windows
  VNC viewer ──────────────────►  VNC entry                  (port 5900) ─── VNC ──────►  Linux, macOS
  psql / mysql / sqlcmd ───────►  database ports (15432 / 13306 / 11433) ─────────────►  databases
                                       │
                 rules · secrets · recording · live view · audit
                                       │
             PostgreSQL (catalogue, log)   /var/lib/bursu-pam (keys, recordings)   SIEM (syslog)

The path of one session

1. Sign-in. The user connects to the gateway. From BURSUcm, after signing in to the console with a password and a TOTP code, the client receives a one-time ticket for one connection; from an ordinary SSH client, with a name of the form login:server, a password and a TOTP code.
2. Rule check. The gateway checks whether there is a valid access rule (or an approved request) for this person, server and account, and what is allowed in the session: terminal, files, clipboard.
3. Signing in to the target. The gateway decrypts the account's secret and signs in to the target server itself. For SSH it compares the target's host key with the one confirmed by the administrator, for RDP and VNC it compares the certificate.
4. Recording and watching. Everything that passes through the session is recorded; an auditor sees the session live and can terminate it. Commands are checked against the command control policies.
5. End. The session ends when the user logs out, the idle time runs out, the rule ends or an auditor terminates it. The recording is closed and signed, and the events go to the audit log and to the SIEM.

Secrets and the encryption key

The passwords and keys of the target servers are stored in the database in encrypted form. They are encrypted by the gateway's master key, which lies in the key directory /var/lib/bursu-pam/keys, not in the database. So a copy of the database without the key directory is useless — no secret and no recording in it can be read. The master key is protected in one of two ways, chosen in the first-setup wizard:

• Protected by the operating system (recommended) — the key lies in a file that only the gateway service can read; after a reboot the gateway starts by itself.
• Sealed with a passphrase — after each restart of the service the administrator enters the passphrase on the /unseal page; while the gateway is “sealed”, it does not work. See “Sealed mode”.

In case the key is lost or the passphrase is forgotten, the wizard shows a recovery key once. Print it and keep it offline, in a safe — not on the gateway server.

Audit log and recordings

Every event (a sign-in, a settings change, the start and end of a session, a command, a file transfer…) is written to the audit log. The entries are linked into a hash chain: each contains the hash of the previous one, and the gateway regularly sets checkpoints. If someone changes or deletes a row directly in the database, the integrity check will show it. Session recordings are stored in the /var/lib/bursu-pam/recordings directory together with signed descriptions (manifests) and hashes.

Isolation of graphical sessions

Every RDP and VNC session and every recording rendering task (live view, player, MP4 export) runs in a separate “worker” process with strict Linux kernel restrictions: its own control group (cgroup v2) with limits on memory, processes and processor, Landlock (a ban on file access) and seccomp (a system call filter). That is why the gateway needs these kernel features — see “Requirements”. SSH sessions and the web console do not depend on them.

Requirements

The gateway server

Database

You need PostgreSQL 15 or newer. The simplest is the local PostgreSQL 16 from the Ubuntu archive: the package pulls it in by itself and creates the database bursu_pam and the role bursu-pam, which signs in through a Unix socket without a password (peer authentication). You can also use an external PostgreSQL server — then the gateway needs only the PostgreSQL client, and you must install it before the package (otherwise apt will pull in the full PostgreSQL server itself), and the connection string is passed separately (see “Database on another server”).

Ports

Port 22 stays with the machine's own SSH server (for administering it), port 5432 with its own PostgreSQL. The numbers can be changed with the bursu-pam-configure command. The package does not touch the firewall — you open the ports yourself, see “Network and firewall”.

The gateway's outgoing connections: to the target servers (their SSH, RDP, VNC, Telnet and database ports), to domain controllers (LDAPS and Kerberos, if directory sign-in is used), to the SMTP server and webhook addresses (notifications), to the SIEM receiver, and — only if you press the button yourself for online activation or turn on the daily check — to https://bursucm.com (see “Licence”). Without the internet the gateway works fully; the licence is activated with a request code.

Certificate

With no configuration, the gateway creates a self-signed certificate itself (ECDSA P-256, for two years), and the browser will warn about it at the first sign-in — this is expected. For use in an organisation it is better to issue a certificate with your certificate authority for the gateway's name (for example pam.example.org) — see “Gateway certificate”. If VNC is enabled, the name by which clients address the gateway must be in the certificate.

Users' workstations

• Browser — any modern one, for the console. The console works without JavaScript too.
• An authenticator app on a phone for TOTP codes (6 digits, 30 seconds, SHA-1): Google Authenticator, Microsoft Authenticator, FreeOTP, Aegis and similar.
• BURSU Connection Manager (optional) — Windows or Linux/macOS, the PAM Gateway mode. Or ordinary clients: OpenSSH, PuTTY, WinSCP, FileZilla, mstsc, a VNC viewer, psql, mysql, sqlcmd.

Quick start: from an empty Ubuntu to the first recorded session

This path takes about half an hour. You need an Ubuntu 24.04 (amd64) server with a permanent address, SSH access to it with sudo rights, and internet access to the Ubuntu package archive (the package pulls in PostgreSQL and libraries). In the examples the gateway's address is 192.0.2.10; substitute your own.

1. Prepare the server. Update the system (sudo apt update && sudo apt upgrade), check the time (timedatectl — the line System clock synchronized: yes) and, if you will use Kerberos sign-in, set the full host name (sudo hostnamectl set-hostname pam.example.org).
2. Copy the package and verify its authenticity. Copy to the server the whole release folder you received from BURSUsofts (it holds the .deb, SHA256SUMS, SHA256SUMS.asc and the key bursu-pam-release.gpg), and in that folder run the check from the section “Verifying the package”.
3. Install the package with one command.

   sudo apt install ./bursu-pam_1.0.0_amd64.deb

   The package will create the account bursu-pam, the directories, the database bursu_pam and the file /etc/bursu-pam/gateway.json, and then ask a few questions about the address and ports. Press Enter at every question — the defaults give a working gateway on one server — and at the end answer y to Apply?. In detail — “Ports and protocols”.
4. Write down the address and the setup code. The last lines of the installation look like this:

     Open in a browser:  https://192.0.2.10/setup
     Setup code:         XXXX-XXXX-XXXX

   The code is single-use; if you lost it — sudo cat /var/lib/bursu-pam/setup-code.
5. Open the ports. If ufw is enabled on the server, the installer printed ready commands sudo ufw allow …/tcp — run them. If there is another firewall between the users and the gateway, open the same ports there. See “Network and firewall”.
6. Go through the first-setup wizard. Open https://192.0.2.10/setup in a browser, agree to continue despite the warning about the self-signed certificate and go through 7 steps: setup code → language → key mode → recovery key (print it) → first administrator → TOTP and recovery codes → done. In detail — “First setup”.
7. Sign in and turn on the licence. Click Go to sign-in, sign in with the password and the code from the app, open Settings → Licence. If there is internet — Start the 7-day trial online → Send this one call. If not — Start the 7-day trial in the Request codes (offline) block, then the code is entered on bursucm.com from any computer. While there is no licence, the gateway lets no session through and allows no changes. In detail — “Licence”.
8. Add a server. Servers → Create server: name, SSH protocol, address and port. On the server card, confirm the host key. In detail — “Servers”.
9. Add a server account. On the server card, the accounts tab (or Accounts → Add account): the login on the target server and its password or SSH key. The gateway stores the secret encrypted; it cannot be shown afterwards. See “Accounts and secrets”.
10. Create a user. Users → Create user: login, name, the User role, a temporary password. At the first sign-in they will change the password and bind TOTP. See “Users”.
11. Create an access rule. Access rules → Create rule: who (a user or a group), to what (a server and an account), what is allowed (terminal, files). See “Access rules”.
12. Connect. From BURSUcm: the PAM Gateway storage mode, the gateway address, the user's sign-in — the server appears in the catalogue, and a double click opens the session (in detail). Or from any terminal:

    ssh -p 2222 ivanov:web01@192.0.2.10

    where ivanov is the gateway user's login and web01 is the server's name in the console; the gateway asks for the user's password and the TOTP code (in detail).
13. Look at the recording. Sign in to the console as the administrator: Sessions shows the running session (it can be watched live and terminated), and after logout — the recording with search by the typed text. See “Sessions and recordings”.

Installing the package

Verifying the package

A release comes as a folder, not a single file. It holds: the package bursu-pam_1.0.0_amd64.deb, inputs.manifest (what the package was built from), lintian.txt (the package check report), the test report suite-report.<commit>.txt, the checksum list SHA256SUMS, its signature SHA256SUMS.asc and the BURSUsofts public key bursu-pam-release.gpg. Copy the whole folder to the server and run this in it:

gpg --show-keys --with-colons bursu-pam-release.gpg | grep '^fpr'
gpgv --keyring ./bursu-pam-release.gpg SHA256SUMS.asc SHA256SUMS && sha256sum -c SHA256SUMS

• The first command prints the key fingerprint. Compare it with the fingerprint that BURSUsofts gave you through another channel (a letter, a phone call) — not with the one that lies next to the package: gpgv trusts any key from the file passed to it.
• The second command must end without errors: gpgv prints Good signature, and sha256sum -c prints OK for each of the four files. BAD signature means the sum list has been replaced; FAILED on a file means the file itself has been replaced or damaged. In both cases do not install the package and contact the supplier.
• If you copied only the .deb, sha256sum -c will report three missing files — this is not damage, but an incomplete folder.

Installation

sudo apt install ./bursu-pam_1.0.0_amd64.deb

Be sure to put ./ before the file name — otherwise apt will look for the package in the repositories. apt itself fetches the dependencies from the Ubuntu archive: PostgreSQL 16, the Kerberos libraries (libgssapi-krb5-2), ICU, OpenSSL, jq and others.

What the package does

After unpacking the files, the package runs the program bursu-pam-setup (it can also be run again — a second run changes nothing). In order:

1. Account. Creates the local system account bursu-pam: with no password, no login shell, its own group with nobody else in it, and no additional groups. If an account with that name already exists but does not meet these requirements (for example, it is in the docker group or has a shell), the installation stops and names the command that fixes it.
2. Directories. /etc/bursu-pam (root:bursu-pam, 0750), /var/lib/bursu-pam (bursu-pam, 0700), /var/backups/bursu-pam (root, 0700). It never touches the contents of existing directories.
3. Database. On the first running local PostgreSQL cluster of version 15+, it creates the role bursu-pam (LOGIN only, no password and no special rights) and the database bursu_pam, which this role owns and which nobody else can access. It does not change the files pg_hba.conf and postgresql.conf.
4. Sign-in check. Makes sure the role signs in to its database through a Unix socket with peer authentication — without a password.
5. Configuration. Writes /etc/bursu-pam/gateway.json (root:bursu-pam, 0640) — only if it does not exist yet. An existing file is never overwritten; if the package would suggest different contents, they are put beside it in gateway.json.proposed.

Then the package runs the check bursu-pam-check --quiet (it prints only warnings and errors and does not interrupt the installation), enables the bursu-pam-gateway service and — on a new installation in a terminal — asks the questions about ports (the next chapter), after which it starts the gateway.

On the first start the gateway itself creates its tables in the database, and in the data directory a self-signed certificate and the file with the one-time setup code, /var/lib/bursu-pam/setup-code.

What lies where

The package contains no passwords, keys, certificates or licence.

What the installation looks like in a terminal

An example of the output of a new installation on a server with the address 192.0.2.10 (put together from the texts of the installation scripts; apt's own lines are shortened). Your lines may differ a little — for example, in the set of check warnings.

$ sudo apt install ./bursu-pam_1.0.0_amd64.deb
…
Setting up bursu-pam (1.0.0) ...
bursu-pam-setup: account bursu-pam: created (system account, no login shell, no password)
bursu-pam-setup: /etc/bursu-pam: created root:bursu-pam 0750
bursu-pam-setup: /var/lib/bursu-pam: created bursu-pam:bursu-pam 0700
bursu-pam-setup: /var/backups/bursu-pam: created root:root 0700
bursu-pam-setup: PostgreSQL 16/main: role bursu-pam created (LOGIN only, no password)
bursu-pam-setup: PostgreSQL 16/main: database bursu_pam created, owned by bursu-pam, closed to PUBLIC
bursu-pam-setup: peer authentication of bursu-pam over /var/run/postgresql: ok
bursu-pam-setup: /etc/bursu-pam/gateway.json: written (root:bursu-pam 0640)
WARN hostname: the host name pam is not fully qualified; Kerberos needs the FQDN (…)
bursu-pam postinst: a few questions follow (Enter takes the default; Ctrl+C keeps the defaults; later: sudo bursu-pam-configure)
BURSU PAM gateway - listeners and ports
Press Enter to take the value in [brackets]. Nothing changes until you confirm at the end.
…  (the questions — see the next chapter)
  Open in a browser:  https://192.0.2.10/setup
  Setup code:         XXXX-XXXX-XXXX
  (lost it? sudo cat /var/lib/bursu-pam/setup-code)
  (the browser will warn about the self-signed certificate - expected; continue)

Installing without questions

The questions are asked only if this is a new installation, the output goes to a terminal, systemd is running, and neither DEBIAN_FRONTEND=noninteractive nor BPAM_NO_WIZARD=1 is set. In other cases (an automated installation, an upgrade) the gateway starts with the default ports (console 443, SSH 2222; RDP, VNC and the database entries are off), and instead of the code only the command that will show it is printed:

sudo DEBIAN_FRONTEND=noninteractive apt install -y ./bursu-pam_1.0.0_amd64.deb
sudo bursu-pam-configure --next-steps        # browser address and setup code

The ports can be set later with the same command, sudo bursu-pam-configure.

Database on another server

If the database will be on a separate PostgreSQL server (version 15+), create the role and the database there yourself (the database owner is that role; do not give the role extra rights) and pass the gateway an Npgsql connection string.

Pass the string with the password only through standard input, so that it does not get into the process list. The redirection < is done by your shell, not by sudo, so the file with the string must be accessible to you yourself: put it in your own home directory with rights for you only.

(umask 077; nano ~/pam-connstring.txt)        # one line, see below
sudo bursu-pam-setup --connection-string - < ~/pam-connstring.txt
rm ~/pam-connstring.txt
sudo systemctl enable --now bursu-pam-gateway
sudo bursu-pam-configure

The file holds one line, for example:

Host=db.example.org;Port=5432;Database=bursu_pam;Username=bursu_pam;Password=…;SSL Mode=VerifyFull

Delete the file right after the configuration is written (the second command). Remember: in this case the database password is stored in gateway.json (the file is readable only by root and the service), and the package does not make an automatic database copy before an upgrade — you make the copy on the database server.

If at installation the host turned out to have no running PostgreSQL (or no client was found), the package will report provisioned except the database and will not start the gateway — after fixing it, run sudo bursu-pam-setup again and sudo systemctl enable --now bursu-pam-gateway.

Ports and protocols: bursu-pam-configure

bursu-pam-configure is a short wizard in the terminal that sets the gateway's address and ports. On a new installation the package calls it itself; later you can run it as many times as you like:

sudo bursu-pam-configure                 # questions; Enter takes the value in [brackets]
sudo bursu-pam-configure --next-steps    # only: where to go in the browser, and the setup code

Nothing changes until you answer y to the last question. On a repeat run the current settings become the defaults.

The questions

The wizard will not let you choose a port already taken by another program (it names the program and the process number), a port chosen twice, or port 5432. On a repeat run, a protocol that was turned off earlier is offered as off by default.

If VNC is enabled and the gateway's self-made certificate does not contain the chosen address, the wizard asks Let the gateway make a new certificate? (the old one is kept as a .bak file). The answer y puts the old certificate aside (a copy gateway.pfx.bak-…), and the gateway creates a new one with this address. Browsers and BURSUcm clients that already trusted the old certificate will ask for confirmation once more. With the answer n, VNC stays written in the settings, but the gateway will not open it (Settings → VNC will say Address not in the certificate) until the certificate contains this name; at the end the wizard says that VNC is not listening yet. If you installed your own certificate (certificatePath), this question is not asked — the name must already be in your certificate.

What happens after “y”

1. The current gateway.json is copied to /etc/bursu-pam/gateway.json.bak-<UTC time>.
2. Only the answers are written to gateway.json; all the other parameters stay as they were.
3. The gateway restarts; the wizard waits up to 20 seconds for the console port to answer (on the first start, while the gateway prepares the database, up to 60 seconds, and says so).
4. If the gateway did not come up, the previous file (and the previous certificate) is put back, the gateway restarts with it, and the wizard shows the last 30 lines of the service log — they show what is wrong. Exit code 1.
5. If it came up, the wizard reports which ports are already listening. SSH, RDP, VNC and the database entries open only after the /setup wizard is finished (and in sealed mode, after unsealing), so until then it prints opens once the first-run setup in the console is finished.
6. At the end: the host check lines, numbered next steps (with ready commands sudo ufw allow …/tcp if ufw is on; the wizard itself does not change the firewall) and the console address with the setup code.

An example dialogue (Enter everywhere except the last question):

1. The address people and their programs use to reach this gateway: a DNS name (pam.example.org) or an IP address.
   The console link and VNC sessions use it.
   Address [192.0.2.10]:

2. The web console (administration, and where users sign in) is served over HTTPS.
   Console HTTPS port [443]:

3. SSH: people connect their SSH client (ssh, PuTTY) to the gateway, which signs in to the target server for them.
   SSH port (not 22: the server's own SSH keeps it) [2222]:

4. Let people open RDP (Windows remote desktop) sessions through the gateway? [Y/n]:
   RDP port [3389]:

5. Let people open VNC (remote screen of Linux and macOS desktops) sessions through the gateway? [Y/n]:
   VNC port [5900]:

6. Database fronts: people connect their usual database tool to the gateway, which signs in to the database server for them.
   Port 5432 is not offered: this server's own PostgreSQL, which holds the gateway's data, uses it.
   Offer PostgreSQL through the gateway? [Y/n]:
   PostgreSQL front port [15432]:
   Offer MySQL / MariaDB through the gateway? [y/N]:
   Offer Microsoft SQL Server through the gateway? [y/N]:

Summary:
  Address                192.0.2.10
  Console (HTTPS)        https://0.0.0.0:443
  SSH                    0.0.0.0:2222
  RDP                    0.0.0.0:3389
  VNC                    192.0.2.10:5900
  PostgreSQL front       192.0.2.10:15432
  MySQL front            off
  SQL Server front       off

Apply? This restarts the gateway; open sessions are closed. [y/N]: y

Saved. The previous file is /etc/bursu-pam/gateway.json.bak-20261102T101500Z. Restarting the gateway...
The gateway runs with the new settings.
  SSH (port 2222) opens once the first-run setup in the console is finished.
  RDP (port 3389) opens once the first-run setup in the console is finished.
  VNC (port 5900) opens once the first-run setup in the console is finished.
  PostgreSQL front (port 15432) opens once the first-run setup in the console is finished.

Checking this server (bursu-pam-check --quiet):

Next steps:
  1. Open https://192.0.2.10/setup in a browser.
  2. Enter the one-time setup code (below).
  3. In the console: create the administrator, then install the licence.
  4. The firewall (ufw) is on. Let the gateway's ports in:
       sudo ufw allow 443/tcp
       sudo ufw allow 2222/tcp
       sudo ufw allow 3389/tcp
       sudo ufw allow 5900/tcp
       sudo ufw allow 15432/tcp

----------------------------------------------------------------------------------------------
  Open in a browser:  https://192.0.2.10/setup
  Setup code:         XXXX-XXXX-XXXX
  (lost it? sudo cat /var/lib/bursu-pam/setup-code)
  (the browser will warn about the self-signed certificate - expected; continue)

When the /setup wizard has already been completed, Console: https://…/ is printed instead of the /setup address and the code.

Exit codes

First setup (the /setup wizard)

Until the gateway is configured, it has only one page — https://<address>/setup; any other address leads to it. The seven-step wizard creates the encryption key, the first administrator and the basic settings. It asks first for a one-time code — so that the gateway is not “seized” by whoever opens the page first.

Step 1 · Setup code

Enter the code from the installation output (the format XXXX-XXXX-XXXX, 12 characters; hyphens and case do not matter). If the output is lost: sudo cat /var/lib/bursu-pam/setup-code or sudo bursu-pam-configure --next-steps. The file is readable only by the service and root; the path to it is also written to the service log (the code itself, never). A wrong code: The setup code did not match. No more than 10 attempts a minute from one address.

Step 2 · Language

Default console language — the default language of the console: English, Русский, Українська, ქართული, Deutsch, Español, Português, Português (Brasil). Each user then chooses their own language in the profile and on the sign-in page.

Step 3 · Key mode

Where to keep the key with which the gateway encrypts the account secrets:

• Protected by the operating system (recommended) — the key lies in the key directory, and only the service can read it. After a reboot the gateway starts by itself. Choose this option if you are not sure.
• Sealed with a passphrase — after each restart of the service, the administrator enters the passphrase on the /unseal page. More reliable if a disk is stolen, but while the gateway is sealed it does not work (nobody can connect). Set Passphrase and Repeat the passphrase — at least 12 characters.

The mode can be changed later in Settings → Encryption key (in detail).

Step 4 · Recovery key

The wizard shows the recovery key — once. Without it the secrets cannot be recovered if the key file is lost or the passphrase is forgotten.

1. Click Download .txt or Print and save the key offline: the printout in a safe, the file on a medium kept separately from the server. Do not keep the key on the gateway itself.
2. Tick I have saved the key in a safe place.
3. In the Last 4 characters of the key field, enter the last 4 characters of the key — this checks that the key has really been saved.

Step 5 · Administrator

The first administrator; they will create the other users in the console.

Step 6 · Two-factor sign-in

1. Scan the QR code with an authenticator app or enter the key by hand (parameters: SHA-1, 6 digits, 30 seconds).
2. Enter the current six-digit code in Code from the app and click Next. The code did not match. Check the time on the phone. — check the time on the phone.
3. The wizard will show ten recovery codes — each works once, in case the phone is lost. Save them separately from the phone, tick I have saved the recovery codes and click Next.

Step 7 · Done

The summary: the key mode, the administrator with the second factor set up, and Setup code — no longer valid, the file is deleted. Two buttons: Go to sign-in — the ordinary sign-in page, and Next: start the 7-day trial or install a licence — Settings → Licence. The gateway lets no session through until it has a licence — go straight to “Licence”.

If the wizard was interrupted

The wizard's progress is kept only in the gateway's memory and is tied to the browser; after 30 minutes without actions, on a restart of the service or on entering the setup code again, it is erased. If you closed the window, open /setup, enter the setup code again (it is valid until the end of the wizard) and choose the language again. The wizard then continues from the place determined by what is already done: if the key is created, a choice appears at step 3; if the administrator is created, the wizard goes straight to step 6. Do not close the page until you have saved the recovery key: it is shown once and will not be shown again after the tab is closed at step 4. If the key was already created last time, a choice appears at step 3: Continue with this key (if you saved its recovery key) or Create the key again — the old key and its recovery key are deleted; this is possible only while there is neither an administrator nor a single secret. If files from a deleted key remain in the key directory, the wizard names them — move them elsewhere and repeat.

Sealed mode and /unseal

The /unseal page appears in two cases. While it is open, the console and connections to servers are unavailable.

The gateway is sealed

You chose the Sealed with a passphrase mode, and the service restarted (a server reboot, a package upgrade, systemctl restart). Enter the Passphrase and click Unseal. The gateway will open and start all the entries (SSH, RDP, VNC, databases).

If the passphrase is forgotten, click Recover with the recovery key: enter the Recovery key, set a New passphrase and Repeat the passphrase, click Recover and unseal.

The encryption key is unavailable

The mode is “protected by the OS”, but there is no key file or it does not fit this database (for example, the database was restored to a new server without the /var/lib/bursu-pam/keys directory). Enter the recovery key and click Recover the key. If after recovery the gateway says The key was recovered and lists problems with the key directory — fix them before the next restart of the service; the recovery key remains valid.

No more than 5 attempts a minute from one address; every attempt, successful or not, is written to the audit log. Errors: The passphrase did not match., The recovery key did not match.

Licence

The gateway is licensed by the number of active servers (those enabled in the console); the number of users is not limited. The licence is a file signed by BURSUsofts (.bpl), which the gateway checks itself, without any connection to the internet. It is bound to the installation (Installation ID) and to this server (a fingerprint based on /etc/machine-id).

The page: Settings → Licence (/system/licence), for Administrator only. It works in any licence state. Every action on it requires a fresh confirmation: the gateway may ask for your password and code once more (You may be asked for your password and code again first.).

The Status card

The states (the label in the corner of the card): No licence, Trial, Active, Ends soon (for a paid licence — 7 days or less to the end), In grace (paid only), Ended, Activated on another host, Released.

The 7-day trial licence

The trial licence gives all the features for 7 days and up to 25 active servers; there is no grace period after it. A trial licence can be obtained once for one installation; under the portal's terms, also one trial licence per organisation (an offline trial is issued through a bursucm.com account). A trial licence has no Ends soon label: it shows Trial until the last day and then immediately Ended, so write down its end date in advance.

With the internet — one button

1. In the Online — one call per click block, click Start the 7-day trial online.
2. The window shows exactly what will be sent (What is sent): the installation identifier, the server fingerprint, the gateway version, the number of active servers, the gateway time, when the setup was completed, a one-time number, the licence sequence number and the gateway's public key — with the gateway's signature. No names, addresses or organisation data.
3. Click Send this one call. A few seconds later: The 7-day trial licence is installed.

The gateway contacts bursucm.com only when you click the button; the rest of the time it sends nothing. If internet access is only through a proxy, set it in the Proxy server block (see below).

Without the internet — a request code

1. In the Request codes (offline) block, click Start the 7-day trial, then Make the request code.
2. The gateway shows the Request code and its QR code (you can Download as .txt). The portal accepts a code once; the gateway remembers the request — while there is no answer, the page shows Waiting for an answer: ….
3. From any computer with the internet, go to https://bursucm.com/pam/activate (a bursucm.com account is needed), paste the code (or scan the QR with a phone) and get the licence file .bpl.
4. Carry the file into the closed network and install it: Install a licence → Licence file (or paste the text into Or paste the licence) → Install. Done: The licence was installed.

The paid licence

When you buy, you receive an activation key of the form BPK- and 20 characters. To buy a licence for a specific installation, the seller may need the Claim code of this installation (the Claim code block on the page): it assigns the installation to your organisation on bursucm.com/pam/licences. The block is visible while the trial licence is in force (or a licence without an organisation name); after a paid licence with an organisation name, the code is forgotten and the block is gone. The trial itself does not need the code. Keep the claim code secret — anyone who has it can assign the installation to themselves.

• Online: Activate with an activation key → enter the Activation key → Send this one call → The licence from your activation is installed.
• Offline: Activate a paid licence → Make the request code → the code is entered at https://bursucm.com/pam/activate, where you choose the paid entitlement → the resulting file is installed through Install a licence.
• A ready file. If BURSUsofts sent a .bpl file, simply install it through Install a licence. Only the block between the BEGIN and END lines is read, and the signature is checked.

Renewal and the daily check

A new licence (a renewal, more servers) is installed the same way: with a file, with the online button Check now (one call — to fetch a ready licence, if there is one) or by turning on Background check-in: Turn the background check-in on — once a day the gateway itself asks bursucm.com about renewals. The check is off by default. If it fails for a week in a row, a warning appears in the bell.

A licence received automatically that is worse than the current one (fewer servers, a shorter term, a shorter grace period, fewer host servers, does not include this server) is not installed by itself: the page will say The licence … was received but not installed, because it … — install it by hand if you really need it.

Proxy

If the gateway reaches the internet only through an HTTP proxy, enter it in Proxy address (empty = the system's setting), for example http://proxy.example.org:3128, and click Save the proxy. Use the system default — return to the system setting. A proxy with a login and password is not supported; the address is only http://host:port or https://host:port.

Moving to another server

The licence is bound to a server. If you moved the gateway (restored it from a backup onto a new machine), the state becomes Activated on another host. For a paid licence there is a moving grace period — at least 14 days (or more, if so written in the licence), during which everything works; the page shows how many days have been used. In that time move the licence: Move the licence to this host online (one call) or the offline code Move the licence to this host. The number of moves is limited by the licence terms. After the grace period ends, new sessions and changes are refused.

Releasing an installation

Before taking a gateway out of service, release the licence so that it can be activated on another server: Release… → enter the serial number of the current licence to confirm → one of the options:

• Release and show the release code — the gateway sends nothing and shows the Release code, which you enter on the portal yourself. The code is shown only once — copy it before leaving the page.
• Release and tell bursucm.com now (one call) — the release is reported to the portal at once, no code is needed.

When the licence ends: what stops and what keeps working

The end of a licence is a “soft stop”, not a shutdown. A paid licence gets the Ends soon label and a warning in the bell 7 days before the end; after the end a grace period applies (In grace, its length is written in the licence), when everything still works. A trial licence has no label, no warning and no grace period: Trial until the last day, then immediately Ended. After the end (and after the grace period of a paid licence):

If more servers are enabled than the licence allows, after the grace period sessions are let through only to servers within the limit, and changes are refused until the extra servers are switched off. A server cannot be enabled beyond the limit at once: The licence allows … active servers. Switch off a server or extend the licence.

The gateway does not trust its own time

The gateway makes sure a licence cannot be extended by turning the clock or rolling back the database. If the licence state file /var/lib/bursu-pam/licence-state.json is missing or damaged and at the same time the signed timestamp in the audit log does not match, if the database turned out to be older than the state file (restored from an old copy), or rows disappeared from the log, the page says The gateway cannot trust its own time: new sessions and changes are refused, and a restart does not help. There is one way out — a licence issued in response to a request made after this state began:

• if a paid licence is in force — Request a support licence (an offline code or the online button) and send it to BURSUsofts;
• otherwise — an activation request (Activate a paid licence); a trial licence does not get out of this state.

If the gateway's clock has moved forward, the button Re-base the licence to this gateway's time may appear — it recalculates the licences to the gateway's current time. So restore the database together with the /var/lib/bursu-pam directory from one and the same copy (see “Backups”).

Licences received

A table of all the licences received: Serial, Seq, Kind, Servers, Term, Received (how it was received — uploaded, online, check-in, restored from the state file; by whom and when) and Status — In force, Pending, Superseded, Released, Ended.

All the messages of the licence page and what to do about them are in the chapter “Troubleshooting → Licence”.

The gateway.json file

/etc/bursu-pam/gateway.json holds only what the gateway needs to know before it connects to the database: where the database is, which addresses and ports to listen on, where the certificate and directories are. Everything else is configured in the console and stored in the database. The file is created by bursu-pam-setup, the ports in it are changed by bursu-pam-configure; it is edited by hand only for parameters that the wizard does not have.

• The format is JSON; the gateway allows // comments and trailing commas, but bursu-pam-configure and bursu-pam-check read only pure JSON — do not add comments if you use the wizard.
• The gateway rejects an unknown parameter and does not start — so a typo does not silently turn into a default value. Parameter names are not case-sensitive.
• Rights: root:bursu-pam 0640 (the file may contain the database password). Checked by bursu-pam-check.
• After editing: sudo systemctl restart bursu-pam-gateway (sessions in progress will be cut off). If the gateway did not come up, journalctl -u bursu-pam-gateway -n 50 will name the wrong parameter.
• An example with comments: /usr/share/doc/bursu-pam/gateway.json.example.

The file that the installation creates:

{
  "connectionString": "Host=/var/run/postgresql;Port=5432;Database=bursu_pam;Username=bursu-pam",
  "listenUrl": "https://0.0.0.0:443",
  "dataDirectory": "/var/lib/bursu-pam",
  "keyDirectory": "/var/lib/bursu-pam/keys",
  "sshListen": "0.0.0.0:2222",
  "rdpWorkerPath": "/opt/bursu-pam/workers/RdpWorker",
  "vncWorkerPath": "/opt/bursu-pam/workers/bursu-pam-vnc",
  "vncLauncherPath": "/opt/bursu-pam/workers/bursu-pam-vnc-launch"
}

Parameters

Gateway certificate

One certificate serves the console (HTTPS) and all the gateway's TLS entries (VNC with TLS, the database entries). BURSUcm clients remember (pin) the gateway's certificate at the first connection and ask for confirmation again if it changed.

Self-signed certificate

If certificatePath is not set, on the first start the gateway creates /var/lib/bursu-pam/gateway.pfx: ECDSA P-256, SHA-256, the name CN=<machine name>, valid for two years; if VNC is enabled, vncAdvertisedName is added to it. Browsers warn about such a certificate — this is expected; check the fingerprint and continue. For permanent use, a certificate from your certificate authority is better.

The gateway only reads the created file from then on: it does not renew the certificate after the two years pass and does not add the VNC name to it if VNC was enabled later. The expiry is visible in Settings → Status. To get a new self-signed certificate (after the expiry or after turning on VNC), put the old file aside and restart the service — the gateway will create a new one:

sudo mv /var/lib/bursu-pam/gateway.pfx /var/lib/bursu-pam/gateway.pfx.old
sudo systemctl restart bursu-pam-gateway

BURSUcm users will see the new certificate and confirm it once.

Your own certificate

1. Issue a certificate for the gateway's name (for example pam.example.org; if users also come by IP, add the IP to the alternative names). If VNC is enabled, the name from vncAdvertisedName must be in it.
2. Put the files where bursu-pam can read them but other users cannot. The /etc/bursu-pam directory is read-only for the service — that is fine: the file must already exist.

   sudo install -d -o root -g bursu-pam -m 0750 /etc/bursu-pam/tls
   sudo install -o root -g bursu-pam -m 0640 gateway.pfx /etc/bursu-pam/tls/gateway.pfx

3. Add to gateway.json the PKCS#12 variant:

   "certificatePath": "/etc/bursu-pam/tls/gateway.pfx",
   "certificatePassword": "file-password"

   or PEM:

   "certificatePath": "/etc/bursu-pam/tls/gateway.crt",
   "certificateKeyPath": "/etc/bursu-pam/tls/gateway.key"

   (certificatePassword — only if the key is encrypted). From a .crt (and from a .pfx) the gateway reads only the first certificate — its own, with the private key; it does not assemble the chain from the file and does not give it to clients. So the clients must trust the intermediate certificate authority themselves (for example, distribute it to the workstations with a group policy or a package of trusted certificates).
4. sudo systemctl restart bursu-pam-gateway and open the console — the browser should show your certificate. Warn BURSUcm users: the client will ask once to confirm the new certificate.

Renewal: replace the file under the same path and restart the service.

Network and firewall

The package and the wizard never change the server's firewall. Open the ports yourself.

ufw

If ufw is on (sudo ufw status → Status: active), bursu-pam-configure prints ready commands for the chosen ports. A typical set:

sudo ufw allow 443/tcp      # console and BURSUcm clients
sudo ufw allow 2222/tcp     # SSH, SFTP, SCP, Telnet devices
sudo ufw allow 3389/tcp     # RDP (if enabled)
sudo ufw allow 5900/tcp     # VNC (if enabled)
sudo ufw allow 15432/tcp    # PostgreSQL entry (if enabled)

It is better to limit the sources to the users' network: sudo ufw allow from 10.20.0.0/16 to any port 2222 proto tcp. Do not forget to leave access to port 22 for administering the server itself before turning on ufw (sudo ufw allow 22/tcp).

Target servers

On the target servers, allow the service ports only from the gateway's address. An example for Linux with ufw: sudo ufw allow from 192.0.2.10 to any port 22 proto tcp and deny the rest; for Windows — a Windows Firewall rule for RDP (3389) with the gateway as the remote address. Do the same for VNC, Telnet and the database ports.

Reverse proxy and NAT

If a reverse proxy stands in front of the console, list its address in trustedProxies. If the gateway is published through NAT or port forwarding, set the external addresses in sshPublicHost/sshPublicPort, rdpPublicHost/rdpPublicPort and dbPublicHost — the gateway tells these to clients.

Maintenance

The service and logs

systemctl status bursu-pam-gateway            # is it running
sudo systemctl restart bursu-pam-gateway      # restart (sessions are cut off; in sealed mode — /unseal again)
journalctl -u bursu-pam-gateway -n 100        # the last log lines
journalctl -u bursu-pam-gateway -f            # the log in real time
journalctl -u bursu-pam-gateway --since today

The service log contains no passwords, setup codes or connection strings. The audit log (who did what) is in the console, see “Audit log”.

Host check: bursu-pam-check

sudo bursu-pam-check            # one line per check: OK, WARN or FAIL
sudo bursu-pam-check --quiet    # only WARN and FAIL

It only reads, changes nothing and does not go onto the network. The exit code is 1 if there is at least one FAIL. Run it as root — otherwise some of the checks will not run.

Upgrading

sudo apt install ./bursu-pam_<new version>_amd64.deb

1. The package stops the gateway (all sessions are cut off) — do the upgrade in a maintenance window and warn the users.
2. Before replacing the files it makes a database copy: /var/backups/bursu-pam/pre-upgrade-<old version>-<time>.dump (the last two are kept). Free space is needed — twice the size of the database, otherwise the upgrade stops and names both numbers.
3. If the copy could not be made (no space, the database is unavailable) or the gateway did not stop, the upgrade is cancelled: you will see the line NOT upgrading - …, a dpkg error, and the old version is running again.
4. The new version updates the database schema when it starts. gateway.json and the data are not touched; the questions about ports are not asked on an upgrade.
5. In sealed mode, open /unseal after the upgrade.

For a remote database the package makes no copy (it says so in one line) — make the copy yourself before the upgrade.

Rolling back to the previous version

Only for a database on the same server. Everything written after the upgrade will be lost — first copy the copy file elsewhere.

The /var/backups/bursu-pam directory and the copy file belong to root and are closed to others, and the redirection < is done by the shell of whoever types the command, not by sudo. So run the block as root: first sudo -i, then the commands without sudo.

sudo -i
systemctl stop bursu-pam-gateway
runuser -u postgres -- psql -c 'DROP DATABASE bursu_pam'
bursu-pam-setup                                    # creates an empty bursu_pam owned by bursu-pam
runuser -u bursu-pam -- env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin \
    pg_restore -h /var/run/postgresql -d bursu_pam --exit-on-error < /var/backups/bursu-pam/pre-upgrade-<old>-<time>.dump
apt-get install -y --allow-downgrades /path/to/bursu-pam_<old version>_amd64.deb
exit                                               # return to your own shell

Backup and restore

Restoring needs three things, and all three are required:

1. The database bursu_pam — the catalogue, users, rules, the audit log;
2. the directory /var/lib/bursu-pam — the master key (keys/), session recordings, the licence state, the certificate;
3. the recovery key from the /setup wizard — offline, in a safe, never on this server.

(   # subshell: umask will not stay in your shell
  umask 077
  sudo runuser -u bursu-pam -- pg_dump -Fc -h /var/run/postgresql bursu_pam > bursu_pam.dump
  sudo tar -C /var/lib -czf bursu-pam-data.tar.gz bursu-pam
)

The archive contains keys — keep it as securely as the keys themselves, separately from the database copy. Without the master key from keys/, neither the secrets nor the recordings from the database copy can be read; a database copy without the data directory is useless. Make both parts at the same time: a database restored from a copy older than the licence state file puts the gateway into the “does not trust its own time” state (see “Licence”).

Restoring on a new server: install the same package, stop the service, restore the database (DROP DATABASE, bursu-pam-setup, pg_restore — as in the rollback above), unpack the archive into /var/lib (owner bursu-pam), start the service. If the key file is missing or does not fit, the gateway will open the /unseal page for the recovery key. The licence then needs to be moved to the new server (“Moving”).

Recordings on another disk

The service can write only to /var/lib/bursu-pam. To keep recordings on a separate disk:

sudo install -d -o bursu-pam -g bursu-pam -m 0700 /srv/pam-recordings
sudo systemctl edit bursu-pam-gateway
#   [Service]
#   ReadWritePaths=/srv/pam-recordings
# in gateway.json:  "recordingsDirectory": "/srv/pam-recordings"
sudo systemctl restart bursu-pam-gateway

Or, more simply, mount a separate disk straight onto /var/lib/bursu-pam/recordings.

Ubuntu updates and restarts

The package installs /etc/needrestart/conf.d/bursu-pam.conf so that the needrestart utility, after apt upgrade, does not restart the gateway by itself (a restart cuts off all sessions). After library updates, sudo needrestart -b will show the gateway as waiting for a restart — restart it in a maintenance window.

Removal

sudo apt remove bursu-pam     # stops the service, removes only the package files
sudo apt purge bursu-pam      # the same, plus the service state; NOTHING more

Neither remove nor purge deletes /var/lib/bursu-pam (keys and recordings), /etc/bursu-pam, /var/backups/bursu-pam, the database bursu_pam, the role and the account bursu-pam — a reinstallation will pick them up. Final removal is irreversible; do it only after making sure the recordings and keys are no longer needed by anyone:

sudo runuser -u postgres -- psql -c 'DROP DATABASE bursu_pam'
sudo runuser -u postgres -- psql -c 'DROP ROLE "bursu-pam"'
sudo rm -r /var/lib/bursu-pam /etc/bursu-pam /var/backups/bursu-pam
sudo deluser --system bursu-pam

Before taking the gateway out of service, release the licence (“Releasing an installation”).

Web console

The console is the gateway's own set of web pages. In it the administrator creates users, servers and access rules, the auditor reads the logs, the approver decides on requests, and an ordinary user sees what they have access to. The console opens in a browser at the gateway's address; the address and the certificate are set during installation (see the sections Network and ports and Gateway certificate). The console also works without JavaScript. Every form is protected against request forgery, and pages are not stored in the browser cache.

What a person sees in the console depends on their roles. The roles are described in the section Roles; menu items that a role cannot open are not shown at all (they are not “greyed out”, they are hidden).

Signing in: the “Sign in to the console” page

The page address is /signin. Everyone who opens the console without a valid session lands on it. If they wanted to open a specific page before that, the gateway returns them to exactly that page after sign-in.

A banner may appear above the form: the text that the administrator set in the Banner text setting (Sign-in and MFA). It usually carries a warning that activity is monitored.

The gateway answers sign-in errors with the same phrase every time, so that the answer does not reveal whether such a login exists: Incorrect login or password. It answers this way for a wrong password, an unknown login, a disabled user, and a person who is not a member of any mapped directory group. The exception is a lockout: Account temporarily locked until {0}. (the time is in the gateway's time zone). All sign-in error texts are collected in the chapter “Troubleshooting”.

Sign-in steps and the order of pages

Signing in consists of several steps. Each next step is shown only when it is needed.

The start page: the administrator and the auditor land on Overview (if the gateway is not yet licensed, the administrator lands on the Licence page first); the approver lands on Approvals; everyone else lands on My profile.

Until a person has completed all the steps, the gateway lets them go nowhere except the page of the current step. Any other page sends them back to that step.

The code from the app: the “Two-factor sign-in” page

The address is /signin/totp. Under the heading is the login being signed in. On the page:

• six boxes 6-digit code (the digits can be typed one after another or pasted all at once), the hint “Enter the 6-digit code from the authenticator app.” and the Confirm button;
• the link Enter a recovery code: the page switches to the Recovery code field (sample xxxxx-xxxxx) and the text “Enter one of your recovery codes. Each code works once.”; the link Enter a code from the app leads back;
• the Sign in as another user button: it ends the sign-in in progress and returns to the sign-in page.

The code has six digits and comes from the authenticator app (RFC 6238: SHA-1, 6 digits, 30-second step). The same code cannot be used twice. If the code is not accepted, the page says The code did not match. Check that the time on the phone is accurate.

Changing a temporary password: the “Choose your password” page

The address is /signin/password. It is shown to a person whose password was issued by an administrator. The text: “The administrator gave you a temporary password. Choose your own to continue.” The fields:

If it is too short: The password must be at least N characters long. The length is counted in characters after standard Unicode normalisation.

For a directory (domain) user this page shows, instead of the form, the heading Change your domain password (for LDAP, Change your directory password), a text about where to change the password, and a single Sign out button. The gateway never writes to the directory, so the password is changed only with the directory's own tools.

TOTP setup: the “Set up two-factor sign-in” page

The address is /signin/enrol. Signing in to the console is protected by a second factor, a code from an app on the phone. The page is shown to a person who does not yet have one, if the Require TOTP setting is on (it is on by default). The steps:

1. Scan the code. The block 1. Scan the code in the authenticator app shows a QR code. If you have nothing to scan with, enter the key by hand: it is shown under the caption “Or enter the key by hand:”, and below it are “Account: login” and the parameters “SHA-1, 6 digits, 30 seconds”.
2. Enter the code. In the field 2. Code from the app enter the six digits from the app and press Next. If the digits are not accepted, the page says The code did not match. Check the time on the phone.
3. Save the recovery codes. After the correct code, ten one-time codes are shown (the block Save your recovery codes). They are needed if the phone is lost. Each code works once. The buttons are Download .txt (the file bursu-pam-recovery-codes.txt) and Print. Keep the codes apart from the phone.
4. Confirm. Tick I have saved the recovery codes and press Next. Without the tick the button does not work.

The secret is tied to the session that showed it. If you open this page again in another window at the same time, the new secret replaces the previous one, and a warning appears on the old page: “Another session of this account started a new authenticator setup, so the code shown here before no longer works.” If setup has already been completed in the other window by then, this sign-in is closed and the person returns to the sign-in page. After confirmation the gateway ends all the other sessions of this person.

Signing in with Windows

The Sign in with Windows button leads to the page /signin/windows. The browser must send the Kerberos ticket to the gateway by itself. After the ticket a second factor is still needed: if the person has no TOTP, setup is offered at once (even when the Require TOTP setting is off); if they have it, the code is requested, unless the browser is “remembered” (see the One code covers Windows sign-ins for (hours) setting). If sign-in fails, the page returns to the sign-in form with one of the phrases; all of them are listed in the chapter “Troubleshooting”. Setup is described in detail in the section Signing in with Windows (Kerberos).

Re-confirmation: the “Confirm it is you” page

The address is /reauth. For dangerous actions the gateway asks for the password and the code again, even if the person has already signed in. Such a confirmation is valid for 10 minutes and is tied to the current session. After confirmation the gateway returns the person to the page they were sent from.

There is one error for both the password and the code: The password or the code did not match. A wrong password or a wrong code is counted in the same way as at sign-in and leads to an account lockout. When the password and the code are correct, the failure counter is reset.

Confirmation is required for: changing roles, setting a password for another person and resetting their second factor; adding, changing and deleting a directory and the mappings of its groups; changing the encryption key and the key mode; creating a new authenticator app and new recovery codes in the profile; weakening the sign-in settings; and for a number of actions in other parts of the console (rules, licence, SIEM and so on, which are described in their own sections).

Signing out: the “Sign out” page

The Sign out item in the user menu ends the session at once, without asking. The page /signout with the question “End your console session?” and the Sign out button opens only if you go to that address directly (for example, from a bookmark). After signing out, the session is closed on the gateway, not only in the browser. Signing out also “forgets” this browser for signing in with Windows (the remembered device).

Session lifetimes

The end of a session is not accompanied by a message: the person is simply taken to the sign-in page, and after signing in, to the page they were on. The session identifier is kept in the cookie __Host-bpam-session (HTTPS only, not accessible to scripts). At every sign-in step the gateway issues a new cookie value.

Account lockout

Five wrong passwords in a row lock the account for 15 minutes. Both numbers are settings (Failed attempts before a lockout and Lockout length, min), and they are read at every sign-in. Details:

• Not only wrong passwords are counted, but also wrong second-factor codes and failed re-confirmations.
• A correct password does not reset the counter by itself; the counter is reset when sign-in is fully completed or when re-confirmation succeeded with the password and the code.
• If more time has passed since the last failure than the lockout lasts, the count starts again.
• A locked-out person sees Account temporarily locked until {0}. The administrator can lift the lockout early with the Unlock button in the user's card.
• A lockout of a directory user works in the same way. In addition, the directory's own lockout also applies: it looks like “Incorrect login or password”.

The layout of the window

Every console page consists of a top bar, a side menu and a work area.

The top bar

• On the left: the Menu button (on a narrow screen it opens the side menu) and the name BURSU PAM; it leads to the start page.
• Alerts is the bell (see The bell).
• Language is the drop-down list of languages. The choice is saved at once.
• Switch theme is the button with a moon: it switches between the light and dark themes.
• The user menu (User menu): the person's name. It has three items: My profile, Language and theme and Sign out.

The side menu

The menu is built by role and shows only what the person can open. The Collapse menu button at the bottom collapses the menu. For an approver, next to the Approvals item there is the number of requests waiting for their decision. The My profile item is shown in the side menu only if, apart from the common items (My access and Help), nothing else is available to the person, that is, they have the single role User; for everyone else “My profile” is available in the user menu at the top.

Menu and settings sections: English and Russian

The console is translated into eight languages. The screenshots and this guide show the English interface. Below are all the side-menu items and all the tiles of the Settings section with their English and Russian labels from the translation files (nav.*, sethub.*, role.*) and with an indication of who sees them.

The side menu

The items of the “Audit” group and the pages “Approvals”, “Command control”, “Device profiles” and “Emergency access” are described in the parts of the guide on audit, requests and resources. The My access item is covered in the part for users.

The tiles of the “Settings” section

Role names

The “Alerts” bell

The bell is an icon in the top bar. The number on it is the count of current problems. It is shown to the administrator, the auditor and the approver, and also to anyone who has their own request notifications. Clicking it opens a list; if there are no problems, it says No current problems. An item with a link leads to the page where the problem can be dealt with; for a person who cannot open that page, the item is shown without a link.

The list of problems itself (this is the general picture; the details are in the sections the items lead to):

• The person's own entries: Requests waiting for your decision: {0}, Your requests that were decided: {0}, Commands waiting for your confirmation: {0}, and also those about emergency access (Emergency access used and not yet reviewed: {0} and Emergency access reviews overdue: {0}).
• General problems for the administrator and the auditor: the encryption key is sealed or out of date, users locked out in the last hour, the local log queue, a change of a server's host key, directories that are unmonitored or lack a confirmed root certificate, session recording failures, low disk space, clock drift, a SIEM export failure, licence problems, a break in the log chain and others (the full list of states is in the section Status).

Strips above the content

• Licence warning. A red or yellow strip that everyone signed in sees while the licence has expired, is in its grace period, is tied to another server or is not installed. For the administrator the strip has the link Open the licence page. The texts and actions are in the section “Licence”.
• Emergency access strip. While a person's own emergency access is in force, every page says: “Emergency access is active until {0}. This use is recorded and will be reviewed.”
• Result of an action. After saving, deleting or another action on a page, a green (success) or yellow (warning) strip with a message is shown for a short time: for example, Saved., Deleted., Created.
• Watermark. If the Watermark setting is on, the signed-in person's “login (Name)” is repeated diagonally across the whole console window.

Interface language

The console language is chosen for each person separately. The gateway picks the language in this order, taking the first that fits:

1. the language saved in the person's profile (after the first choice in the console);
2. the browser's language cookie (a choice on the sign-in page or in the top bar);
3. the browser's Accept-Language header;
4. the default language chosen during the gateway's initial setup;
5. English.

Eight languages are available: English (en), Deutsch (de), Español (es), Português — Portugal (pt), Português — Brasil (pt-br), Русский (ru), Українська (uk), ქართული (ka). A choice in the top bar or on the Language and theme page is written to the profile and to a cookie (for a year) and goes into the audit log as “Language changed”.

The “Language and theme” page

The address is /preferences. It opens from the user menu and is available to everyone signed in. There are two forms:

The “My profile” page

The address is /profile. Anyone signed in can open it. For a person with only the User role this is the whole console, apart from “My access” and the help. What is on the page:

A new authenticator app: the “New authenticator app” page

The address is /profile/totp (the Set up again button). Re-confirmation is needed (10 minutes). The steps: press Start, scan the new QR code, enter the code from the new app and press Confirm. Until confirmation, the previous app keeps working. After confirmation the gateway issues ten new recovery codes (“New recovery codes replace the old ones”), ends all the person's other sessions and forgets their remembered devices. The Done button returns to the profile.

New recovery codes: the “New recovery codes” page

The address is /profile/codes (the Create new ones button). Re-confirmation is needed. Press Create new codes: the previous codes stop working at once, and ten new ones are shown once. Save them with the Download .txt button or print them (Print).

Common list elements

The lists of users, groups and many other objects work in the same way:

• Quick filters are “chips” above the table. Each has the number of records on its right. The selected chip is highlighted; All clears the filter.
• The search box (the Search field with a hint, for example “Login, name, group”). The / key moves the cursor to the box. The search is truncated to 200 characters; wildcard characters have no special meaning.
• The create button (for example, Create user), the Actions menu with bulk actions (it appears after rows are ticked with the checkboxes), CSV (an export of the whole list, taking the filter and search into account; the export is written to the audit log as “audit.export”) and Refresh.
• A click on a column heading sorts by that column; a second click changes the direction.
• At the bottom: “Total: N”, the Per page choice (15, 30, 50 or 100; 15 by default) with the Apply button, and the page numbers.
• A bulk action on the ticked rows asks for confirmation: “Apply this action to the selected rows?” If nothing is ticked: “Nothing was selected.” If the filter found nothing: “Nothing matches this filter.”

Confirmations and unsaved changes

Dangerous actions (disabling, deleting, resetting) ask for confirmation in a window with the Confirm and Cancel buttons. If JavaScript is off, the same confirmation is shown on the page itself, in the block “Confirm the action”. Forms with fields warn you if you close the page with unsaved changes. The Reset button returns the fields to the values the page opened with.

Time and time zone

The gateway stores time in UTC and shows it in the time zone set in gateway.json by the displayTimeZone parameter (for example, Asia/Tbilisi). If the parameter is not set, the time zone of the gateway's operating system is used. Dates and times are shown in the format of the chosen language. This time zone is the same for all users; it cannot be changed in the profile. See the section gateway.json.

Users

The Users section (address /users) is the list of people who sign in to the console and connect to servers through the gateway. The section is available only to the administrator (Administrator). There are two kinds of users:

• Local. They are created by the administrator. The login and the password are stored in the gateway's database (the password only as an irreversible hash). The first administrator is created by the initial setup wizard (see the section Initial setup wizard).
• Directory users (Active Directory or LDAP). They appear by themselves on their first successful sign-in. They have no password on the gateway; the name, roles and group membership come from the directory (see Directories).

The list of users

The address is /users. Above the table are the quick filters (Quick filters); each shows the number of people:

The search (Login, name, group) searches by login, name and group name. The columns of the table:

The columns Login, Name, Groups, State and Last sign-in can be sorted. On the right of a row are the Edit button (directory users do not have it) and the More actions menu: Open the card, Access (the “Access” tab of the card), Log (the “Log” tab). The CSV button exports the list, taking the filter and search into account; the export goes into the audit log.

Bulk actions. Tick rows with the checkboxes and open the Actions menu: Enable and Disable. For Disable the gateway asks for confirmation. Rows for which the action changes nothing are skipped without an entry in the log. If you enable a directory user whom the directory still disables, the gateway warns you: “Done for the selected rows. Users the directory disables stay disabled.”

Creating a user

The Create user button opens the page /users/new (“Create user”). The hint on the page: “A user created by an administrator changes the password and sets up TOTP at the first sign-in.”

(An asterisk marks required fields.)

After you press Create the page shows “User {0} is created.” If the password was generated by the gateway, the Temporary password block appears below: “Give it to the user separately from the login. It is shown only now; they change it at the first sign-in.” The password is shown once; you must write it down at once. The buttons are Open the card and Create user (to create another one). If you entered the password yourself, there is no password block.

What goes into the audit log: the creation of the user (User created) with the roles, the groups and the “password generated” flag. If a group you added the person to is named in the request template as an approvers' group, an event about a new approver is written as well.

Editing a user

The Edit button (list or card) opens /users/{id}/edit (“Edit user {0}”). The fields are the same as at creation, except the login (read only) and the password block. The differences:

• Roles. The checkboxes are available only for 10 minutes after re-confirmation. While there is no confirmation, under the checkboxes it says “Changing roles needs you to confirm who you are.” with the link Confirm who I am. If roles are changed without confirmation, the form refuses: “Confirm who you are before changing roles.”
• Temporary password. Empty means the password stays as it was (“Leave empty to keep the current password.”). If you enter a password, re-confirmation is needed: “Confirm who you are before setting a password.” The person must change the new password at their next sign-in; all their sessions are closed, and the sign-in lockout, if there was one, is lifted (if you change the password for yourself, only the current session is kept).
• Active. The switch disables or enables the user.
• The form carries the version number of the record. If another administrator managed to change the same person, saving is refused: “The record was changed by another administrator — open it again.”

After Save the gateway returns to the card with the message Saved. One event is written to the log for each change: the person's details, adding and removing groups, a change of roles (with the old and new value), enabling or disabling, a password reset.

Directory users cannot be changed here: they have no Edit button, and going to the address leads to the card with the explanation “This is set by the directory for domain users and cannot be changed here.”

The user card

The address is /users/{id}. In the heading: the name, the login, the directory label (for a directory user), the Edit button (except for directory users) and the Disable / Enable button. The tabs: Main, Groups, Access, Tokens, Log.

The Main tab consists of two blocks.

The Details block: Login, Name, E-mail, Roles, Groups (labels that link to the groups), State (for a locked user, “until {0}”; for a directory user, the explanation “disabled in the directory”, “expired in the directory”, “in no mapped group” or “no longer in the directory”), Two-factor sign-in (TOTP and “recovery codes left: N of 10”, or Not set up), Last sign-in, Created, Change password at the next sign-in. For a directory user, instead of the last one there is the Source block with the explanation “Roles, directory groups, name and password of a domain user come from the directory.” and the link Group mappings to the directory's card.

The Quick actions block:

The Groups tab is “The user's groups”: a table (Name, Description, Rules, the number of the group's rules). At the top right are a group selector and the Add to group button. The Remove button asks: “Remove {0} from the group {1}? The group's rules stop applying to them.” A group in which the person is a member because of the directory carries the label from the directory; if the membership comes only from the directory, there is no Remove button, because it is managed by the directory's group mapping. If the person is in no groups: “The user is in no group.”

The Access tab is “Access to servers”: “From every rule in effect and every future one, directly and through groups.” The columns are Server, Address, Accounts, How (directly or through a group), Rule (a link), Valid until. If there are no rules: “No rule gives this user access.” This tab is read only. Remember: only a person with the User role can go to servers.

The Tokens tab is “BURSUcm tokens” (sign-ins of the BURSUcm app through the gateway): the columns Issued, Expires, State; the Revoke button revokes the token immediately (“Token revoked.”). Below is Remembered devices (devices remembered for signing in with Windows) and the Forget devices button (re-confirmation and confirmation of the action are needed: “Forget every remembered device of this person? Their next Windows sign-in asks the code.”).

The Log tab shows the latest audit log events about this person and a link to the whole log.

Directory users

• The account appears on the first successful sign-in of a person who belongs to at least one mapped group. “Directory user created” is written to the log.
• The gateway roles and groups of such a person are determined by the group mappings (see Group mapping). In the console you can do only the following by hand: add them to a gateway group (this is a separate, “manual” membership that the directory does not touch), disable them in the console, reset MFA and end sessions.
• States in the directory: disabled in the directory, expired in the directory, in no mapped group, no longer in the directory. In all these cases the person cannot sign in. Disabling in the directory ends their sessions at once; a lockout in the directory blocks new sign-ins but does not end sessions already in progress.
• If a directory group mapping names only a gateway group (without a role), the person gets no roles, and only the User role goes to servers (see Roles). For a directory person to be able to connect to servers, at least one of their mappings must give the User role.
• A directory user's password is changed in the directory.

Groups

A group gathers people so that one access rule applies to all of them at once, both the current members and those who join later. The Groups section (address /groups) is visible only to the administrator. A gateway group is not connected to a directory group until you map them (see Group mapping).

The list of groups

The address is /groups. If there are no groups yet, the screen “No groups yet” is shown with the explanation “A group gathers users so one access rule covers all of them, now and when people join later.” and the Create group button.

Creating and editing a group

The Create group button opens /groups/new, the Edit button opens /groups/{id}/edit (“Edit group {0}”). The form:

The group card

The address is /groups/{id}. The buttons in the heading are Edit and Delete. The tabs:

• Main: the Details block (name, description, number of members and rules, creation date) and the latest log events about the group.
• Members: choosing people in the Add members field (“New members get the group's access at once.”) and the Add members button. In the table of members: Login, Name, State and the Remove button (with the confirmation “Remove {0} from the group {1}? The group's rules stop applying to them.”). The label from the directory is on members who came from the directory; if the membership comes only from the directory, there is no Remove button. While there are no members: “The group has no members.”
• Rules: the rules that name the group (Name, Valid until, State, which is Enabled or Disabled). If no rule names the group: “No rule names this group.” Rules are created in the “Access rules” section (see Access rules).

Deleting a group

The Delete button in the card asks: “Delete the group {0}? Its members ({1}) stay, but lose the access its rules ({2}) give.” A group cannot be deleted if:

• the group is used in a directory mapping: The group is used by a directory mapping. Remove the mapping first.;
• command control policies refer to the group: Command policies still apply to this: {0}. Edit the policies first. (change the policies first; see the section Command control).

When a group is deleted, the people remain, but lose the access that the rules of this group gave them. “Group deleted” is written to the log.

The audit log records: the creation, change and deletion of a group, and the adding and removing of a member (“Member added”, “Member removed”). If a member of the group becomes an approver as a result, an event about a new approver is written as well (it also produces an item in the bell).

Roles

A role determines what a person sees in the console and what they can change in it. A person can have several roles. Roles are set in the user form (Users) and, for directory users, in the group mappings (Directories). The role names in the interface are Administrator, Auditor, Approver, User.

Roles and console sections

In the table: “yes” means sees and can change; “read” means sees but does not change; “—” means the section is hidden.

Administrator and Approver are incompatible

One person cannot be an administrator and an approver at the same time. The point of the rule: whoever manages the access rules must not approve the requests made under them. What happens:

• In the user form, if both roles are chosen, the gateway refuses: Approver and Administrator exclude each other: nobody approves requests while managing the rules. Choose one of the two. The general error A person cannot be both an Administrator and an Approver. gives the same reason.
• In a directory: if a person's groups give both roles, the Approver role is not granted, and a warning appears in the bell: Directory roles refused (Administrator wins over Approver): {0}. The exception: if the person already has Approver (and not Administrator), and the mappings now give both, the role that was already there stays, that is, Approver, and Administrator is rejected. More in the section Group mapping.

The local administrator (the “emergency sign-in”)

The gateway always keeps at least one active local administrator with TOTP set up. This rule is checked at every change that could break it. The administrator role of a directory user is not counted, because the directory can take it away at any moment (for example, when the directory is unavailable you must still be able to sign in). Therefore:

• you cannot remove your own administrator role (“You cannot remove your own Administrator role.”);
• you cannot disable yourself (“You cannot disable yourself.”);
• you cannot disable, remove the role from, or reset MFA for the last active local administrator with TOTP: At least one active administrator with two-factor sign-in must remain.

The administrator created by the initial setup wizard is local. Do not delete or disable them until you have created another local administrator with TOTP. Do not confuse this “emergency” account with the Emergency access function (emergency access to a server under a rule), which is described in the part about requests (see Emergency access).

Directories (Active Directory and LDAP)

A directory lets employees sign in to the gateway with their domain password, without a separate account and password on the gateway. The gateway supports Active Directory and ordinary LDAP servers (OpenLDAP, 389 Directory Server, FreeIPA). The section is in Settings → Directories (address /system/directories) and is available only to the administrator. Several directories can be connected at the same time.

How it works:

• The gateway goes to the directory under a service account (bind): it looks up the person by login and reads their groups. The person's password is checked by a separate “bind” on their behalf and is not stored anywhere.
• The connection is by LDAPS only (encrypted). Trust in the server is built on “root pinning”: the administrator confirms one root certificate, and the gateway accepts only servers whose certificate was issued under that root. The system certificate authorities are not used.
• The person gets their gateway roles and groups through group mappings: “directory group → role and/or gateway group”. A person who is in no mapped group cannot sign in.
• The gateway watches the directory and reacts to changes: a person disabled in the directory loses access at once, and a change in group membership is applied within seconds.

The list of directories

The address is /system/directories. The hint: “Active Directory domains and LDAP servers whose users sign in to the gateway. Roles and gateway groups come from the directory groups mapped here.” If there are no directories, it says: “No directory is connected. Only local users sign in.” The Add directory button creates a directory.

Adding and changing a directory

The Add directory button opens /system/directories/new (“Add directory”); the Edit button in the card opens /system/directories/{id}/edit (“Change directory”). Both pages require re-confirmation (10 minutes).

(An asterisk marks required fields.)

After Create the gateway opens the card with the message “Directory added.” “Directory added” is written to the log (the kind, the number of servers, the “default” flag); on a change, “Directory changed” is written with the list of changed fields, the certificate-reset flag and the password-change flag (the password itself does not go into the log).

The directory card

The address is /system/directories/{id}. In the heading: Edit and Delete (see Deleting and turning off). The blocks of the card:

• Connection: the kind, the servers, both DNs, the suffixes and NetBIOS (for AD), the default flag, the Bind DN, Turned on, State, Last change seen (when the directory last reported a change) and Gateway users from it (how many gateway users came from this directory).
• Root certificate: the confirmed root (the SHA-256 fingerprint or “Not confirmed yet”), the Check connection button, the root presented by the server, the Confirm this certificate button and the upload of a root file.
• Windows sign-in (Kerberos), for AD only (see Signing in with Windows).
• Group mappings (see Group mapping).

Actions on the card that change something (confirming and uploading a certificate, mappings, deleting, turning off) require re-confirmation (10 minutes); without it the gateway redirects you to the confirmation page and brings you back. The Check connection button and the group search do not require re-confirmation. Actions that contact the directory are limited: 10 presses a minute from one address, and the group search 20 a minute per session.

Checking the connection

The Check connection button changes nothing. It tries to sign in under the service account, run a user search and find out whether the server can report changes, and at the same time it reads the certificate that the server presents. The result is in the log entry “Directory connection checked”. Success looks like this: “Signed in as the service account; entries found: N.” and, below, “The directory reports changes.” (or “This directory does not report changes; access is re-checked at the next sign-in or connection.”). If it fails, one of the messages is shown (all of them are also listed in the chapter “Troubleshooting”):

Confirming the root certificate

Until the root is confirmed, the gateway does not use the directory: it never trusts a server's certificate “on its word”. The root can be confirmed in two ways.

1. Press “Check connection”. If the server sent a certificate chain together with the root, Presented root (the SHA-256 fingerprint) and Answered by (which server answered) appear under the result. Compare the fingerprint with a reference obtained through an independent channel (from the owner of the certificate authority) and press Confirm this certificate. The gateway reads the chain once more and saves the root only if it is the same one you saw and if the certificate of every configured server is built under it and names that server.
2. Upload the root file. An Active Directory domain controller usually sends only its own certificate, without the root (“The directory did not send its root certificate. Upload it (.cer or .pem).”). Export the root certificate of the domain's certificate authority (DER or Base-64) and upload it in the Root certificate file field with the Upload button. Files .cer, .crt, .pem, .der up to 64 KB are accepted, and only a self-signed certificate-authority certificate.

The result: “The certificate is confirmed.” and the log entry “Directory certificate confirmed”. Possible refusals:

Group mapping

The Group mappings block on the directory card: “A person in a mapped group signs in with the role and joins the gateway group given here. A person in no mapped group cannot sign in.” For each directory group you choose a role and/or a gateway group (one of them is enough: “Choose a role or a gateway group.”). The block is available only after the root is confirmed (“Confirm the root certificate first: until then the gateway does not search this directory.”).

1. Find the group. In the Find a directory group field enter part of the name (up to 128 characters) and press Search. If there are no groups: “No group matches.” A group that is already mapped is marked already mapped. The group search returns a limited number of matches; refine the query.
2. Choose what it gives. In the Role list: no role, User, Auditor, Approver or Administrator; in the Gateway group list: no group or one of the gateway groups.
3. Press “Map”. The mapping is saved: “Mapping saved.” The gateway immediately reads the directory's people again: “what the mapping gives reaches them within seconds”. If the directory cannot be read at that moment: “Mapping saved. The directory cannot be read now: what the mapping no longer gives is already taken away; what it gives arrives once the directory can be read again.”

An existing mapping can be changed right in the table (the Role and Gateway group lists, the Save button) or deleted (Delete, with the confirmation “Remove the mapping of {0}?”). A change and a deletion are applied to all the directory's people at once: what the mapping has stopped giving is taken away immediately; what it gives arrives when the directory has been read.

How rights add up:

• A person gets the union of everything given by the group mappings of the groups they belong to (including nested groups).
• One directory group is mapped only once. A user's primary group (for example, Domain Users in AD) cannot be mapped: “A user's primary group (Domain Users) cannot be mapped: Active Directory does not list it as a membership.”
• Membership of a gateway group obtained from the directory is marked in the card as from the directory and is removed automatically together with the mapping. Manual membership (added by the administrator in the console) is not touched by the directory.
• Administrator and approver are incompatible (Roles). If the mappings give both roles at once, Administrator is granted and Approver is rejected. If the person already has Approver (and not Administrator), and the mappings now give both roles, Approver stays and Administrator is rejected. The rejected role is shown in the bell: Directory roles refused (Administrator wins over Approver): {0}. Note that the hint on the card (“A person whose groups give both Administrator and Approver gets Administrator only”) describes only the first case.
• A gateway group that a mapping refers to cannot be deleted until the mapping is removed (The group is used by a directory mapping. Remove the mapping first.).

Watching and reconciliation

• For each turned-on directory with a confirmed root, the gateway keeps a subscription to changes in the user and group branches (Active Directory notifications; for LDAP, syncrepl or persistent search). A change arrives within seconds. The state watched means the subscription is working.
• In addition, the gateway periodically reconciles all the directory's people again (at least once every 15 minutes), and also at every sign-in of a person and when their ticket for connecting to a server is checked.
• Disabling or deleting a person in the directory, their losing all mapped groups, or a password change in the directory ends their sessions and revokes their tokens. A lockout in the directory blocks new sign-ins but does not end sessions already in progress.
• If the directory is unavailable, the gateway does not “allow just in case”: access that is being taken away is taken away; access that is being granted waits until the directory can be read. If the directory is unavailable at sign-in, the person sees “The directory is not available. Try again later or contact the administrator.” Local users, including the emergency administrator, can always sign in.

Deleting and turning off a directory

The Delete button in the card heading asks: “Delete directory {0}?” It is visible only when nobody has yet signed in from this directory. If people have already signed in from the directory, it cannot be deleted: “Users signed in from this directory exist. Turn the directory off instead of deleting it.” Instead, the card has a Turn off button with the question “Turn off directory {0}? Its users cannot sign in until it is turned on again.” (after it: “Users signed in from this directory exist, so it cannot be deleted. It is turned off; turn it on again in its settings.”). The directory can be turned on in the change form (Turned on). “Directory deleted” or “Directory changed” is written to the log.

Signing in with Windows (Kerberos)

For Active Directory you can turn on the Sign in with Windows button on the sign-in page: an employee who has signed in to the domain gets into the console without entering a password (the gateway still asks for the second factor afterwards). The button appears on the sign-in page only if everything is ready for at least one turned-on AD directory (SPN, domain account or keytab, the check passed).

The Windows sign-in (Kerberos) block on the AD card shows whether sign-in is on, the SPN, the key version number (kvno) and the encryption types, and leads to the page /system/directories/{id}/kerberos (“Windows sign-in (Kerberos)”).

Gateway on Linux: the key file (keytab)

On Linux the gateway needs a keytab file with the keys of the service name HTTP/…. The Keytab block shows Principal (the SPN and the realm), Key version (kvno), Encryption types, Uploaded (when and by whom) and, after a key replacement, “Previous key (kvno N) kept until” (the previous key stays for another 10 hours so that tickets already issued keep working). The buttons are Upload keytab (a field for choosing a .keytab file) and Remove keytab (with the confirmation “Remove the keytab of {0}? Windows sign-in through this directory stops.”). The file is stored encrypted on the gateway; its contents are not visible in the console.

How the administrator gets a keytab. The keys must be “salted” the way the domain controller salts them for the account that holds the SPN. For a user account the salt is REALM + sAMAccountName. Any of three ways (the gateway shows the same hint on the page):

1. MIT ktutil (nothing needs to be changed in Active Directory):

   ktutil
   addent -password -p HTTP/<host>@<REALM> -k <kvno> -e aes256-cts-hmac-sha1-96 -s <REALM><account>
   addent -password -p HTTP/<host>@<REALM> -k <kvno> -e aes128-cts-hmac-sha1-96 -s <REALM><account>
   wkt gateway.keytab

   Here <kvno> is the value of the account's msDS-KeyVersionNumber, and <account> is its sAMAccountName (without the domain).
2. msktutil. The utility works out the right salt and key version for the service account itself; see the utility's documentation for its parameters.
3. ktpass with the parameters +setpass +setupn on the domain controller. Remember that ktpass sets a new password for the account and raises the key version, so other keytabs of that account stop working.

Requirements for the file: format version 0x0502 (written by ktpass and ktutil); at least one entry; all entries for this directory's realm and this directory's SPN; size up to 64 KB; AES keys only (RC4, DES and 3DES make the whole file rejected). If the file has only AES128, it is accepted with a warning (AES256 is recommended). After upload the gateway immediately tests the key with a trial ticket. The log: “Kerberos keytab changed” (without the key contents).

Gateway on Windows

On Windows no keytab is needed: the gateway service runs under a domain account (a gMSA is recommended), and the SPN is registered on it. Instead of the Keytab block, the page shows The service runs as (which account the service runs under) and Host joined to the domain (whether the computer is joined to the domain). For those who will sign in, the gateway computer must grant the right “Access this computer from the network”; if a Tier-0 group policy forbids it, signing in with Windows does not work for these people.

The “Check Kerberos” button

The Check Kerberos button starts a check and shows rows with a level (ok, info, warn, bad): whether the keytab and the environment are valid, who holds the SPN, whether the kvno values match, whether weak encryption types are allowed, whether delegation is enabled, whether the service account belongs to groups, whether a trial ticket with channel binding is accepted, whether port 88 of the controller is unreachable, whether the clocks drift (at a 3-minute drift there is a warning; at 5 minutes sign-in stops working). All the rows are listed in the chapter “Troubleshooting”. The check writes “Directory connection checked” to the log.

Additional hints on the page:

• Browsers send the ticket only to names that are in their policy: the “Local intranet” zone or AuthServerAllowlist for Edge and Chrome, network.negotiate-auth.trusted-uris for Firefox. Set this up with a group policy.
• Signing in with Windows requires the encrypted TLS connection to end at the gateway (end-to-end TCP pass-through only). If trusted proxies are specified in gateway.json, the page warns about this.
• The Channel binding for console sign-ins setting (Sign-in and MFA) determines whether channel binding is needed. The default value is required.

Linux and the LDAPNOINIT variable

On Linux the gateway must be started through its own systemd unit (bursu-pam-gateway.service): it sets LDAPNOINIT=1, without which sign-in through a directory does not work. The reason: without this variable the LDAP library reads the system file /etc/ldap/ldap.conf, which on Ubuntu points to the system set of certificate authorities; the gateway would then trust any public authority, not only the root you confirmed. So without the variable the gateway refuses to connect to directories (a safe refusal):

• domain sign-ins answer “The directory is not available…”;
• the bell shows the directory as “not watched” (Directories not watched);
• Check connection reports that LDAPNOINIT=1 is not set on the Linux gateway.

The solution: start the gateway with the systemd unit that the package installs. Local accounts, including the emergency administrator, can sign in regardless. On Windows nothing extra is needed: the root is checked by the gateway's own mechanism. Each directory has its own trust folder on disk, <dataDirectory>/directories/<id>/, which the gateway rewrites itself; do not put files there.

Known limitations of signing in through a directory

• Nested groups outside the group branch. Members of nested groups are found through the chain (AD LDAP_MATCHING_RULE_IN_CHAIN). But if an intermediate group lies outside the Groups base DN branch, a change to it does not arrive as a notification and is applied at the next reconciliation (no later than 15 minutes) or at the next sign-in or ticket check. Keep such groups inside the group branch or specify the domain root.
• LDAP without the ppolicy overlay. Without the pwdChangedTime attribute a password change in the directory is not detected: the person's old sessions are not closed, and an expired password looks like a wrong one. In both cases the gateway refuses rather than allows. On OpenLDAP and 389-DS, turn on ppolicy.
• A lockout in the directory blocks new sign-ins and new tickets but does not end sessions already in progress (Windows behaves the same way with the sessions of a locked account); disabling does end them.

The “Settings” section: gateway settings

All the gateway settings are collected on one page, Settings (address /settings). It is the only side-menu item for everything the administrator configures on the gateway. The page is visible only to the administrator: the other roles have no Settings item. The hint on the page: “Everything an administrator configures on the gateway, in one place. Each tile opens its page; changes are audited as before.”

The page consists of tiles gathered into four groups. Each tile is a link to a settings page with a short caption. The pages themselves are still at the addresses /system/…: browser bookmarks and links from the bell work as before.

General rules for the settings pages:

• Every settings record goes into the audit log together with the old and new value.
• Settings that lower protection (for example, turning off two-factor sign-in) require re-confirmation of identity (re-confirmation). Strengthening protection does not require confirmation.
• If another administrator managed to save the same page before you, the gateway writes nothing and reports: “The record was changed by another administrator — open it again.” Open the page again and repeat the change.
• Before you leave a page with unsaved edits, the browser warns about losing the changes.

Sign-in and MFA: sign-in and two-factor protection

The Sign-in and MFA page (address /system/auth, administrator only) sets the console sign-in rules for everyone: whether a TOTP code is mandatory, the lockout after failed attempts, the password length, the idle time, the lifetime of BURSUcm tokens, the text on the sign-in page, the watermark and the Windows sign-in options. The hint at the top of the page: “Every change goes into the audit log with the old and the new value.”

All fields are saved with one Save button and take effect at once (except for sign-ins already in progress at their intermediate steps). The Reset button puts back in the form the values it had when you opened it. After saving, the page shows “Saved.”.

Which changes need a fresh confirmation

A change that lowers security cannot be made on a stolen session alone. If you try to lower security without a recent confirmation of your identity (10 minutes), the page is not saved and next to each such field the message “Confirm who you are before this change: …. It lowers sign-in protection.” is shown (for turning TOTP off: “Confirm who you are before turning two-factor sign-in off.”) with the link Confirm who I am. Go through the confirmation and come back to the page; you will have to enter the values again.

• These need confirmation: turning off Require TOTP, raising the number of attempts, shortening the lockout, lowering the minimum password length, raising the idle time, raising the token lifetime, turning off the watermark, raising the time a Windows code is “remembered”, switching to When the browser sends it.
• These do not: any tightening, and changing the banner text.

Encryption key: the encryption key

The gateway stores the passwords and keys of server accounts (the Accounts section) in encrypted form. The encryption key is the gateway's “master” key. The Encryption key page (address /system/key, administrator only) shows its state and lets you change the key itself or the way it is protected. Hint: “The key the gateway encrypts account secrets with. Changing the key or its mode needs a fresh confirmation and a typed word.”

The first creation of the key and the mode are chosen during the initial setup (Initial setup); entering the passphrase at every start is described in the section “Unseal”.

Two modes of key protection

What the page shows

Additional messages on the page:

• The red box “The encryption key was changed, and this gateway still holds the previous one in memory. Restart the gateway (a sealed gateway will need its passphrase).” — in place of the action buttons. Until the service is restarted, writing new secrets does not work. Restart the service and check the audit log.
• The warning “These key files were set aside in the key directory. One may be the old key from before a change: delete it once you are sure it is not another database's key.” with a list of files and the explanation “The console cannot remove them: an administrator of the server's operating system can archive or delete them.” Old key files are set aside after a change, not deleted: you must delete them by hand on the server, after making sure the file is not needed.

Changing the key (Change the key)

The page /system/key/rotate (“Change the encryption key”). It needs a fresh confirmation (10 minutes) and a typed word. The operation is limited to 5 times a minute.

The “What happens” block lists the consequences:

• “The gateway makes a new key and re-encrypts all N secrets with it.”
• “The old recovery key stops working; the new one is shown once.”
• “Connections are not accepted during the change (seconds).”
• “The change goes into the audit log.”

1. Open the form. On the Encryption key page, click Change the key. If the gateway is in Sealed mode, the form has the field Current unseal passphrase.
2. Enter the details. For Sealed mode, the current passphrase. Then type the confirmation word in the field “Type … to continue” — it is shown in the field's caption. The word depends on the interface language: in English it is CHANGE, in Russian СМЕНИТЬ. Type it exactly, in capital letters and in the language shown on the page; spaces at the edges are ignored.
3. Click “Change the key”. The gateway creates a new key, re-encrypts all the secrets and shows the New recovery key block with the warning “The key is shown once. The old recovery key no longer works.”
4. Save the new recovery key. The Download .txt button downloads the file bursu-pam-recovery-key.txt; the Print button prints the key. Keep it apart from the server.
5. Tick “I have saved the new key” and click “Done”. Without the tick the gateway does not go on: “Tick “I have saved it” first.” Result: “The encryption key is changed.”

Changing the mode (Change the mode)

The page /system/key/mode. The mode switches between Protected by the OS and Sealed. It needs a fresh confirmation, the recovery key and a typed word; no more than 5 times a minute. The target mode is determined by the current one: from the OS mode the page leads to Sealed (Switch to sealed mode), from Sealed to the OS mode (Switch to OS-protected mode).

The texts on the pages: when switching to Sealed, “After this every restart of the gateway needs the passphrase you set here; until then nothing can connect.”; when switching to the OS mode, “After this the gateway opens the key at start by itself; the passphrase is no longer used.” Result: “The key is now sealed. Keep the passphrase safe: every restart needs it.” or “The key is now protected by the OS.”

If key files that could not be removed are left after the mode change, the page lists them: “These key files hold the key without the passphrase and could not be deleted; delete them by hand:” (after switching to Sealed) or “The key file could not be written: after a restart the gateway will ask for the recovery key. Check the key directory's permissions:” (after switching to the OS mode). In the first case, delete the listed files by hand on the server; in the second, check the permissions on the key directory.

If the key's mode changed while the page was open, the gateway does nothing and writes: “The mode of the key changed after this page was opened, so nothing was done. Open the page again and check the current mode.”

If the outcome of a change is unknown

If the database did not confirm that the operation finished, the page writes: “The outcome of the key change is unknown — check the audit log and the key state; do not repeat the change until you are sure.” An explanation follows: “If the change did happen, the key held in the gateway's memory is out of date: restart the gateway (a sealed gateway then needs its passphrase) and check the key's state on the encryption key page and in the audit log.” The buttons on the page lead to Encryption key and to the audit log (Audit log). Do not repeat the change until you have made sure from the log that it did not go through.

Status: the state of the gateway

The Status page (address /system/status, administrator only) only shows the state of the gateway and changes nothing. Hint: “Read only. The certificate, the address and the trusted proxies are changed in gateway.json, then the service is restarted.” At the top is the path to the working configuration file: “Changed in gateway.json (… on this system), then a restart of the service. There is no certificate upload through the console in the first version.” Replacing the certificate is in the section “Certificate”.

The “Gateway” block

Further down in the same block come the check rows. Each has a colour: green is fine, yellow is attention, red is a fault, grey is off. The same checks are visible in the bell (The bell). Only the rows that relate to what is configured are shown:

The “Certificate” block

Servers

A server in BURSU PAM is a machine or device that people connect to through the gateway: a Linux server over SSH, a Windows server over RDP, network equipment over Telnet or SSH, a desktop over VNC, a PostgreSQL, MySQL or SQL Server database. For each server the gateway stores the address, port, protocol, folder and the verified “fingerprint” of the server (a host key or a certificate). The logins and passwords the gateway uses to sign in to the server are stored separately — those are the accounts.

You work with servers in the console, in the menu group Resources, item Servers (address /servers). Only an Administrator sees and changes the page. An auditor (Auditor) is not shown these pages; they see only the device profiles.

A server must accept connections from the gateway only

The gateway cannot do this for you: the firewall rule is configured in your network. The console checks that the server is reachable from the gateway's side (the Test the connection button), but it does not check whether the server is closed to everyone else. Check this yourself: from an ordinary workstation, a connection to the target server must fail.

For Telnet this is especially important: Telnet sends everything, including the password, in clear text. Use it only on a management network that only the gateway reaches (see Telnet).

The server list and folders

The Servers page is divided into two parts. On the left is the folder tree (Folders): the row All servers and your folders with the number of servers in each. On the right is the table of servers of the selected folder; above the table are the folder's path and the note with subfolders: when you select a folder, you also see the servers of the nested folders.

When a folder has no servers, the console says that servers are the machines you connect to through the gateway, and offers to create the first server or to move existing ones with the Move to folder command.

Folders

Folders exist so that you can give access to a whole group of servers at once: a rule on a folder covers its subfolders and the servers you add later. Folders form a tree of any depth.

The Folder actions menu (three dots above the tree) creates a top-level folder (New folder). The menu on a folder's row (Actions for the folder …) contains:

Every folder action is written to the audit log (folder.create, folder.rename, folder.move, folder.delete), and a move and a deletion also make the gateway check the rights of open sessions again.

Creating a server: the common fields

The Create server button opens the form /servers/new. The edit form (/servers/<id>/edit) is the same. It has two sections: Main and State. Some fields appear only for certain protocols — the rest are hidden.

The form buttons: Create (when editing, Save), Reset (put back the values the form opened with), Cancel.

An SSH server

This is the main case: Linux, Unix, macOS, and also network equipment with SSH. The fields are the common ones (see above); SSH has no separate fields except the optional Device profile. Choose a device profile only if the server's accounts need privileged mode (the enable command and so on): then you need a built-in network device profile.

What the target SSH server must support. The gateway connects to targets with this set of algorithms (the list is fixed in the gateway and cannot be configured):

• the server's host key: ECDSA nistp256 / nistp384 / nistp521, RSA with SHA-512 or SHA-256 (rsa-sha2-512, rsa-sha2-256). The gateway does not accept an Ed25519 key: a server that has only an Ed25519 host key cannot be verified by the gateway;
• key exchange: ECDH nistp384 / nistp256, Diffie-Hellman group16-sha512 / group14-sha256;
• ciphers: AES-256-GCM and AES-256-CTR; MACs HMAC-SHA2-256 and HMAC-SHA2-512; no compression.

While it works, the gateway keeps one connection to the server per session. Until the host key is confirmed, sessions to this server are not opened: the server's page says Not confirmed — sessions are refused until it is.

Getting and confirming the host key is described in detail in the subsection The SSH host key. Sign-ins by password and by private key for accounts are described in the section Accounts.

A Telnet server

For a Telnet server:

• a Device profile is required: it describes how the gateway recognises the device's prompts and enters the login and password (see Device profiles). If no profile is chosen: A Telnet server needs a device profile. When you choose Telnet, the console fills in the default profile (Generic Unix) itself;
• accounts sign in with a password only. If the server already has accounts with a private key, it cannot be switched to Telnet: This server has key accounts; a Telnet server signs in with a password only. Delete them first.;
• Telnet has no server identity, so there is no host key and nothing to confirm (Not checked — Telnet has none);
• to create it you must tick the box The password crosses the network between the gateway and this server in clear text and confirm your identity. If the box is not ticked: Tick the acknowledgement to use Telnet. If there is no identity confirmation: Confirm who you are before making this server use Telnet. Saving an already existing Telnet server does not require this again.

In the list and on the card a Telnet server carries the label Not encrypted to the server.

An RDP server

The gateway opens an RDP session on the server on behalf of an account with a password, and the user connects to the gateway with their own RDP client (the .rdp file can be downloaded on the page “My access”, see My access).

The separate fields of the form:

More conditions:

• the accounts of an RDP server sign in with a password only. If there are accounts with a key: This server has key accounts; an RDP server signs in with a password only. Delete them first.;
• an RDP server is created switched off until its certificate is confirmed: the console reminds you Saved, but the server is inactive: confirm the RDP server's certificate.;
• RDP with TLS must work on the target: the gateway uses TLS/CredSSP (NLA) protection; the gateway does not use the “standard” RDP protection (without TLS). If the server offers only that, the check will say: The server offers no TLS: only the old RDP security, which the gateway does not use.

Confirming the certificate and how the buttons work are described in the subsection Certificates and fingerprints. What exactly an RDP session is allowed (drives, clipboard, printers, USB, sound) is set by the rules and the page File, clipboard and device policy.

A VNC server

For VNC you must choose on the form how the gateway signs in to the server (the Sign-in to the server field). There is no default: a person makes the choice. Six options:

For the four weak types (rows 3–6 of the table) a box I understand and accept this appears on the form, together with a text about the specific danger. Without the box: Tick the box to accept the weak connection to this server. Without a fresh confirmation of identity: Confirm who you are before making this server use a weak connection. If you choose another type, the box is cleared.

You need to know three things exactly:

• the accounts of a VNC server sign in with a password only; keys are not supported (This server has key accounts; a VNC server signs in with a password only. Delete them first.). For the types “TLS, no sign-in” and “No sign-in (not encrypted)” the account is created without a password (the account type No sign-in);
• if you change the sign-in type and the existing accounts do not suit it: An account of this server does not fit the new sign-in type. Change or delete it first.;
• a VNC server with any TLS type is created switched off: A VNC server with a TLS sign-in type stays inactive until its certificate is confirmed after saving.

A user's connection to the gateway over VNC works differently: the client signs in with a one-time code from the console or from BURSUcm (the section Connecting over VNC).

Database servers: PostgreSQL, MySQL, SQL Server

For databases the gateway acts as a proxy: the user connects with their own client (psql, DBeaver, SSMS and so on) to the gateway and enters a “pass” instead of a password. The gateway itself signs in to the database with the server account. It signs in only with an SQL login and password; Windows sign-in (SSPI), Entra ID and certificate sign-in are not supported.

In the list of protocols the database is called PostgreSQL, MySQL or SQL Server. There is no separate item for MariaDB: a MariaDB server that speaks the MySQL protocol is chosen as MySQL.

What matters:

• the gateway always encrypts the connection to the database (TLS) and checks the “fingerprint” of the database certificate's key (SPKI SHA-256). Until the fingerprint is confirmed, the server is inactive: A database server stays inactive until its certificate is confirmed. The exception is PostgreSQL with “Allow an unencrypted connection” on: there is no certificate and nothing to confirm;
• database accounts sign in with a password only: This server has key accounts; a database server signs in with a password only. Delete them first.;
• for “read only” access, create a user with minimal rights on the database itself and add it as a separate server account. The server card tells you how (for PostgreSQL: a role with only CONNECT and SELECT; for MySQL: SELECT on the schema; for SQL Server: a login with the role db_datareader);
• the person's login, the server name and the account name together make up the user name for the client. If it is too long for the database protocol, a pass cannot be issued: The person's login, the server and the account together are too long for this database protocol. Shorten the server or account name.

The server card

Clicking a server's name opens the card (/servers/<id>). In the header are the buttons Edit and Delete; for a switched-off server there is a state label beside them. The tabs:

Deleting a server (Delete) asks for confirmation: Delete the server … and its N accounts with their secrets? Rules that name it directly stop leading to it. The accounts and their secrets are deleted together with the server, rules that named the server directly stop leading to it (a rule is left with “Nowhere” if nothing else is chosen). Open sessions to this server end at once.

The SSH host key: how to get it, confirm it and what changes

The host key is the SSH server's “passport”. The gateway remembers it at first contact (the “trust on first use” method, TOFU) and then, at every connection, checks that the server presents the same key. If the key changes (the server was replaced or reinstalled), the gateway refuses to connect, and the account's secret is not sent to such a server.

1. Open the server card. Until the key is confirmed, the Host key block says Not confirmed — sessions are refused until it is, and in the server list the name carries the label Key not confirmed.
2. Click “Test the connection”. The gateway connects to the server's address and port (for no longer than 20 seconds), reads the key presented and shows the Connection check block with the fingerprint in the row Presented host key. If you chose an account in the Sign in as list, the gateway will try to sign in; the option Key only, no sign-in means “only read the key”. The sign-in is made only against an already confirmed key — otherwise the gateway does not send the password: Confirm the key first; the sign-in is tested against a confirmed key only.
3. Compare the fingerprint. The console hints: Before confirming, compare it with ssh-keygen -lf /etc/ssh/ssh_host_ecdsa_key.pub on the server itself. That is, on the server itself run ssh-keygen -lf /etc/ssh/ssh_host_ecdsa_key.pub (for RSA, ssh_host_rsa_key.pub) and compare the SHA256:… line with the one the console shows. The gateway prefers an ECDSA key; if the server has none, an RSA key is shown — then compare with ssh_host_rsa_key.pub. Always compare with the key of the same type that the gateway showed.
4. Click “Confirm this key”. The gateway connects to the server again and saves the key only if the server presents exactly that one. If in the meantime the server showed another key: The server now presents another key than the one you checked. Check again. After success: Host key confirmed. Confirming an SSH key does not require re-entering the password, but it is written to the audit (hostkey.confirm).

The result of the check after confirmation reads as follows:

What changes when the key is reset: when the server's address (Address) or port changes, the confirmed key is deleted, and the console writes Saved. The host or port changed: confirm the host key again. After changing the address or port, go through steps 2–4 again. The SSH protocol cannot be “confirmed in advance”: a key can be confirmed only by seeing it.

Certificates and fingerprints: RDP, VNC and databases

For servers with TLS the gateway checks the certificate's “fingerprint” the same way as the SSH host key: at first contact it is shown to the administrator, the administrator compares it with the server itself and confirms, and after that the gateway accepts only that one. A summary:

Confirming the certificate does not switch the server on automatically. After Confirm this certificate the console writes Certificate confirmed. Switch the server on to use it.; turn on the Active switch on the card (the Active button in the Quick actions block) or in the edit form.

The certificate is confirmed again (the gateway will say so itself) if you changed the server's address, port or protocol, and for VNC also the sign-in type. The confirmed record is deleted and the server is switched off: Saved. The address, port or protocol changed: check the connection and confirm the certificate again. (for VNC: Saved. The address, port or sign-in type changed, so the confirmed certificate was removed.). A simple change of the description, folder or name does not touch the certificate.

RDP

1. Allow NTLM for the server. Without this the check refuses: Not checked: this RDP server is not marked as allowing NTLM, and in this version an RDP server is reached with NTLM only.
2. Open the card and click “Test the connection”. The button's hint: Connects and shows the server's TLS certificate; no sign-in is tried. The gateway connects, goes through the security negotiation and the TLS handshake and sends nothing further: neither a password nor credentials. Presented certificate is shown.
3. Compare the fingerprint. The console: Before confirming, compare it with the SHA-256 fingerprint of the Remote Desktop certificate on the server itself. On a Windows server, for example, in PowerShell:

   $c = Get-ChildItem 'Cert:\LocalMachine\Remote Desktop' | Select-Object -First 1
   ([BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash($c.RawData)) -replace '-','').ToLower()

   Compare the hexadecimal digits; letter case and separators do not matter. If the store holds several certificates, compare with the one that the Remote Desktop service uses.
4. Click “Confirm this certificate”. The console will ask you to confirm your identity (re-enter the password and code), then connect to the server again and save the certificate only if the server presented exactly that one. Otherwise: The server now presents another certificate than the one you checked. Check again. The event is written to the audit (rdp.cert.confirm).
5. Switch the server on (Active).

The result of the check: Matches the confirmed certificate — the server presented the confirmed certificate; Differs from the confirmed certificate … — another was presented (a certificate renewal or a substitution; confirm again only after checking). The check errors: The server offers no TLS: only the old RDP security, which the gateway does not use, The server did not answer as an RDP server, The TLS handshake with the server failed, The server could not be reached (see Troubleshooting).

The Clear the certificate button (after the identity confirmation and the question Clear the confirmed certificate of …? The server is switched off until a certificate is confirmed again.) removes the confirmation and switches the server off. Use it when you have to confirm the certificate afresh (for example, a new one was issued on the server).

VNC

For VNC the card has a Check connection block and a Server certificate block (Subject, Public key (SHA-256), Confirmed …). If the certificate is not confirmed, it says Not confirmed. This server cannot be used until its certificate is confirmed.

1. Click “Check connection”. The hint: Shows what the server offers and its certificate; it signs in only with an account, and on a TLS server only once its certificate is confirmed. The check steps are listed in the table below.
2. Compare the certificate with the one installed on the VNC server itself (Before confirming, compare the certificate's SHA-256 fingerprint with the certificate on the VNC server itself.). The console shows the SHA-256 of the certificate's public key.
3. Click “Confirm this certificate” (an identity confirmation will be needed). The certificate is pinned if the server presented exactly that one. The message: The certificate is pinned. Switch the server on to use it.
4. Switch the server on.

To check the sign-in as well, choose an account in the Also sign in with the account list; the option Offered types only, no sign-in means “only read what the server offers”. The account's secret is sent only to a confirmed certificate (for TLS servers) or to an unencrypted server if you accepted that risk. For the weak sign-in types, an identity confirmation is asked before the sign-in (Confirm who you are before the gateway signs in to this server.).

The state of each step: ok, failed, skipped, not reached. If a step failed, the console explains the reason (the list of reasons is in the chapter Troubleshooting). The Clear the certificate button removes the pin and switches the server off (The certificate pin was removed and the server switched off.).

If the VNC session worker for this server crashes, a warning appears on the card: The session worker for this server crashed N times in the last 24 hours.

Databases

On a database server's card the check button is called Check connection (hint: Connects and shows the server's certificate and version; no sign-in is tried). The gateway shows Subject, Issuer, Valid, Key (SPKI SHA-256), Certificate SHA-256 and the server version (Server version). Confirmation is the Confirm this certificate button (to replace an already confirmed one, Confirm the new certificate), with re-entry of the password and code. To compare the fingerprint on the server itself from the certificate file, you can run: openssl x509 -in server.crt -pubkey -noout | openssl pkey -pubin -outform DER | openssl dgst -sha256.

• If the server shows a different key than the confirmed one: The server now shows a different certificate key. Connections are refused until you confirm it.
• If a PostgreSQL server has the “without encryption” mode on and the server really offers no encryption: The server offers no encryption; it is reached unencrypted, as the switch on its form allows.
• SQL Server with its own “fallback” certificate: This is SQL Server's own fallback certificate: it changes at every service start, and each restart needs a new confirmation. Provision a certificate (mssql-conf set network.tlscert on Linux, SQL Server Configuration Manager on Windows). Install a permanent certificate on the server, otherwise you will have to confirm again after every restart.

The Test sign-in button checks the sign-in of the chosen account (the Sign in as list). Hint: Signs in with the stored password of the account you choose; you are asked to confirm who you are first. The result: The account signed in. or The account could not sign in: … with a short reason (the list of reasons is in the chapter Troubleshooting). The password is sent only to a confirmed certificate or (PostgreSQL without encryption) in a protected SCRAM exchange.

The licence limit on active servers

The gateway's licence limits the number of active servers. You cannot create an active server, switch on a switched-off one, or save a form so that a server would become active, beyond the limit: The licence allows N active servers. Switch off a server or extend the licence. The refusal is written to the audit log (licence.limit). You can always switch a server off. The licence state and its renewal are on the Licence page (the section “Licence”).

If the licence has expired, there is no licence, or there are more active servers than allowed and the grace period has ended, the console refuses changes altogether (servers included), for example: The licence has ended: changes are refused. Upload a licence on Settings → Licence. The full list is in the chapter Troubleshooting.

It is better to keep servers you created “in reserve” switched off: inactive servers do not use up the limit.

What happens to open sessions when a server is changed

After a server is saved, switched off, moved to another folder or deleted, and after its certificate is cleared, the gateway checks the rights of all open sessions again (on SSH, RDP, VNC and databases). A session whose rights have gone (the server is switched off or deleted, the certificate is removed) is closed with a message the user can understand. Changing the name or description does not affect open sessions.

Every change to a server is written to the audit log: server.create, server.update, server.delete, server.test (the connection check, with the result), hostkey.confirm, rdp.cert.confirm, rdp.cert.clear, vnc.cert.confirm, vnc.cert.clear, server.db_tls_pin, server.db_test. The events contain no passwords or keys; for the Telnet check only the steps reached are recorded.

Device profiles

A device profile is a set of “hints” for the gateway on how to sign in to a Telnet server and how to enter privileged mode on a network device. Telnet has no single sign-in procedure: each device writes its own prompt (“Username:”, “login:”, “Password:”) and reports an error in its own way. The profile describes which lines the gateway must recognise to enter the login and password at the right time.

The profile pages are in the menu group Resources, item Device profiles (/servers/profiles). An Administrator sees and changes profiles. An Auditor sees the list and the profile cards read-only: this way an auditor can check by what rules the gateway signs in to devices. The buttons for creating, changing, deleting, duplicating and testing against a transcript are not shown to them.

The profile list

The table has the columns Name (with the Built-in badge on built-in ones), Line end sent and Wait per step, seconds. The New profile button creates your own profile; the Edit button in a row exists only for your own profiles. The page's hint: How the gateway signs in on a Telnet server, and enters privileged mode on a network device.

Built-in profiles come with the gateway, updates keep them, and they cannot be changed or deleted (Built-in profiles are kept by updates and cannot be changed; duplicate one to adapt it.). There are six:

The profile card and copying

The profile card (/servers/profiles/<id>) shows all its fields: Name, User name prompt, Password prompt, Signed-in prompt, Refused login, Wait per step, seconds, Line end sent, and for built-in ones also Privileged step, User name suffix, Fixed answers. The row Servers using it lists the servers that use the profile.

The Duplicate button makes a copy named “Copy of …” (if that name is taken, “Copy of … 2”, “Copy of … 3” and so on) and opens it for editing. The privileged step, the user name suffix and the fixed answers are not carried over when copying: they are available only in built-in profiles. The console warns about this: Privileged mode is available only with the built-in profile. So a copy suits ordinary devices with a login and password sign-in; for a device that needs privileged mode, use the built-in profile.

The Delete button on your own profile asks Delete profile …?. A profile used by at least one server cannot be deleted: The profile is used by these servers: … A built-in profile cannot be deleted: A built-in profile cannot be changed or deleted.

Creating and changing your own profile

The New profile button opens the form /servers/profiles/new. The template values are regular expressions. The gateway applies them to the end of the last received line and matches them with a safe algorithm that does not hang on “heavy” expressions.

The hint under the templates: A .NET regular expression, at most 512 characters, matched at the end of the last line. Backreferences, lookarounds and atomic groups are not supported. Possible template errors: This is not a valid regular expression., At most 512 characters., Backreferences, lookarounds and atomic groups are not supported., This regular expression is too costly to check against device output. Simplify its repetitions. Edits while the form is open are protected against a “lost update”: if another administrator changed the profile, you get The record was changed by another administrator — open it again.

Testing a profile against a session transcript

Under the profile form (and on the card) is the Test against a transcript block: you paste what the device shows, and the gateway checks whether it would sign in with this profile. The test does not need a connection to the device and uses no real passwords. Hint: Paste what the device shows; mark where the gateway types with ⟨user⟩ and ⟨password⟩, or paste a TelnetProbe capture.

1. Copy the device's output into the Transcript field: the prompts and answers as a person sees them.
2. Mark the places where the gateway enters data with the markers ⟨user⟩ (the name) and ⟨password⟩ (the password). For the privileged step, ⟨privileged⟩. Before each marker the gateway keeps a short pause (200 ms).
3. Click “Run the test”. The gateway replays the transcript “in virtual time” and shows a table: Step, Pattern, Matched text, Result for each step (User name prompt, Password prompt, Signed in, Refused, Privileged password prompt, Privileged mode, Fixed answer; beside it, the number of the transcript line). The result of each step: Matched, Not matched, Timed out or Skipped.
4. Read the verdict: The gateway would sign in with this profile. or The gateway would not sign in with this profile.

A transcript cannot be larger than 64 KiB (A transcript is at most 64 KiB.); an empty or unreadable transcript gives A value was not accepted. Check the form. Nothing from the test is saved. A test from the form can be run before the profile is saved: it uses the templates you entered in the form. A test from the card uses the saved templates. Only an Administrator can run the test.

Accounts

A server account is a login and a secret (a password or a private key) with which the gateway signs in to the server in place of the person. The person does not know the secret and cannot find it out: the gateway injects the secret itself at the moment of connecting. One server can have several accounts (for example, root and deploy). Which of them are available to a person is decided by the rules.

Only an Administrator sees and changes accounts. They are available in two places: on the Accounts tab of a server card (the accounts of one server) and in the general Accounts list in the menu group Resources (/accounts, the accounts of all servers — convenient for searching by login).

The account list

The page /accounts (hint: Every account of every server, to find one by login. Secrets are write-only.):

Creating an account

The Add account button on the Accounts tab of a server card opens the form /accounts/new (the general list /accounts has no create button — the list is only for searching, replacing secrets and deleting). The server whose card you came from is already chosen.

Under the secret fields the console writes: The old secret cannot be viewed. The new one is stored encrypted; the change goes into the audit log. The buttons: Create, Cancel. After creation you return to the Accounts tab of the server card. The event account.create is written to the audit (the login, server, secret type and mode; the secret itself is not recorded).

Private keys: which ones fit

• Key types: RSA and ECDSA (nistp256/384/521). Ed25519 is not supported yet: Ed25519 keys are not supported yet. Use an ECDSA or RSA key. Create a suitable key: ssh-keygen -t ecdsa -b 384 or ssh-keygen -t rsa -b 4096.
• Formats: OpenSSH (BEGIN OPENSSH PRIVATE KEY) and PEM. Encrypted PKCS#8 (BEGIN ENCRYPTED PRIVATE KEY) cannot be read; the console advises: Convert the key to the OpenSSH format with ssh-keygen -p -f <file> and paste it again.
• If the passphrase is wrong or the key is of another type: This key cannot be used: the passphrase is wrong, or it is not an RSA or ECDSA key. If the field is empty or does not contain a key: A private key in OpenSSH or PEM format is required.
• A key can be used to sign in to SSH servers. Telnet, RDP, VNC and database servers accept only a password (see the messages in the section Servers).

Replacing a secret

The row menu → Replace secret opens the page /accounts/<id>/secret (the Replace button). It shows only the type of the secret and the date of the last change; the secret itself is not shown. Enter a new password (twice) or a new key with a passphrase under the same rules. After saving: The secret is replaced. The audit gets account.secret with the type of the secret (password or key), without values. The replacement does not interrupt sessions that are already open: they continue on the old sign-in, new ones use the new secret.

For the accounts of VNC servers there is an explanation under the password field: for the “VNC password” types only the first 8 characters are significant; for “Mac user name and password” the name and the password are each at most 63 bytes (For a Mac, the name and the password are each at most 63 bytes.).

Privileged mode of a network device

On routers and switches, after signing in you often need to “raise” the privileges as well: on Cisco with the enable command and a second password, on Huawei with super. The gateway can perform this step itself, so that the person does not know the second password. The mode is turned on for an account at creation or on the page /accounts/<id>/privileged (the Save privileged mode button) and is available only if the server has a built-in network device profile chosen (Cisco IOS / IOS-XE, Cisco NX-OS, Huawei VRP). Otherwise: Privileged mode is available only with a built-in network-device profile.

A server's profile cannot be replaced by one that has no privileged step while there are accounts in privileged mode: Accounts of this server use privileged mode: choose a built-in network-device profile, or turn their privileged mode off first. A change of the mode is written to the audit (account.privileged: before and after); the privileged-mode password is not recorded.

How accounts relate to servers and rules

• An account's login is what a rule names in the Logins field. A rule allows signing in “under any of the listed logins on any of the chosen servers”.
• If a server has one account available to the person, they may leave it out when connecting; if several, they add a third part to the name (login:server:account, see the chapter Connecting over SSH).
• Deleting a server deletes its accounts together with the secrets. Deleting an account does not change the rules, but they stop allowing sign-in with that login.
• If the gateway is closed (the encryption key is not open, see Unsealing the gateway), a secret cannot be created or replaced: The encryption key is not available.

Access rules

A rule answers the question “to whom, where, under which account, for how long and with what rights over data”. There is no access without a rule: if no rule names the person and the server, they cannot connect. The formula from the console: A rule = who × where × with which account × until when.

Only an Administrator sees and changes rules (the menu group Access, item Access rules, address /rules). A rule has one of two types:

• Standing access (permanent access) — takes effect at once and lasts to the end of its term. Described in detail here.
• By request — a person submits a request for a limited time, and approvers decide. This type is described in the section Access requests. It uses the same lists “Who”, “Where”, “Accounts” and “Data movement” as described below.

The rule list

The table /rules shows the columns Name, Type, Users, Groups, Servers, Accounts (All or Specified (N)), Data (in brief: files, terminal, copies), Starts / Ends and State. The filter chips: In effect, Ending ≤ 7 d, Not started yet, Expired, Disabled. Search: Name, user, server. The Create rule button creates a rule. Group actions on the ticked standing rules: Enable, Disable, Delete.

The rule states in the State column: In effect, Ends in N d (ending soon), Not started yet, Expired, Disabled. An empty list: No access rules yet and an explanation that a rule says who can connect to which servers, with which accounts and until when.

Creating and changing a rule

The Create rule button opens the form /rules/new. At the top is the type switch: Standing access / By request (hint: Standing access applies at once. By request lets people ask for a limited time; approvers decide.). The type of a rule is chosen at creation and does not change afterwards (The type of a rule is chosen when it is created and cannot be changed.). The edit form (/rules/<id>/edit) is the same. The sections are numbered in order:

The form buttons: Create / Save, Reset, Cancel. The time rules are simple: only “from” and “until”. There are no recurring windows (“on weekdays from 9 to 18”) in rules; for one-off work set a term, for periodic work create rules for the needed intervals or use access by request.

The rule card

Clicking the name opens the card (/rules/<id>). The header is the name, the state label and the buttons Edit and Delete. The tabs:

If a rule is left with “nobody” or “nowhere” (Nobody / Nowhere) — for example, a group or a server was deleted — the console warns: This rule names nobody or nowhere (its group, user or server was deleted), so it gives no access. Edit it to name them, or delete it.

What happens to open sessions

A rule is checked not only at the moment of sign-in. The gateway evaluates the rights of every open session again as soon as anything that could take access away has changed, and also at the moment a rule that gives the session access ends:

• a rule ended by its term, was disabled or deleted; a person was disabled or lost their roles; a group was changed or deleted; a server was switched off or deleted; an account was deleted; a folder was moved or deleted; a person changed their password (for direct SSH connections) — the session is closed, and the person sees a message (for example, Your access to this server has ended. The session is closed.);
• if several rules give access, the session lives while at least one applies; the gateway checks access afresh and does not follow the “first” rule;
• a rule was narrowed (a file or clipboard direction removed, a device or input switched off): narrowing takes effect at once, and the open session gets the new rights from the next packet. If the terminal of an SSH session is switched off by the rule, the shell and commands are closed with the message Your access rule no longer allows a terminal on this server. The session is closed., while file transfer remains available;
• a rule was widened (a device or direction added): an RDP device that was not offered at connection cannot be added to a running session — the widening takes effect at the next connection (A device the session did not offer when it started cannot be added to it: a change that allows more takes effect at the next connection.);
• for access granted by request, a few minutes before the end the person sees a warning, and on revocation they see by whom the access was revoked.

Closing by term is exact: for each session the gateway sets a timer for the nearest end of the rule that gives it access. If the gateway's database is unavailable for a time, open sessions continue (a failed check does not count as “no”), and new ones are not opened.

Deleting a rule (Delete) asks: Delete the rule …? The access it gives ends at once. A by-request rule that already has requests cannot be deleted — it can only be disabled (A rule that has requests cannot be deleted; disable it instead.). All rule changes are written to the audit (rule.create, rule.update, rule.enable, rule.disable, rule.extend, rule.delete) with a description of what changed.

File, clipboard and device policy

These permissions are set in an access rule, in the Data movement section. They answer the question “what can a person take off the server and bring onto it” and apply to every session. The fields are common to all protocols; the table shows which of them apply to which protocol.

Fields and defaults

How rules combine

If several rules give a person access, the resulting permissions are their union: the direction of files and of the clipboard is the union of the directions; Terminal, copies, recording of clipboard text, RDP devices and screen control are “on in at least one rule”. Copies are kept if any rule requires them, and the size limit is the largest among the rules where copies are on. The result is worked out at sign-in, remembered for the session and recalculated when the rules change (see What happens to open sessions).

USB in RDP

USB redirection passes the whole device (drives included) and does not follow the file rule. That is why it can be switched on only together with Upload and download: USB devices can be allowed only together with “Upload and download” for files. The hint on the field: USB redirection moves whole devices, drives included, and does not follow the file rule. It can be switched on only together with “Upload and download” for files.

SFTP and SCP: how they differ from the terminal

• File transfer goes through a separate channel that the gateway parses itself: every operation is checked against the direction, a log is kept (the File transfers page), a hash of the transferred data is calculated and, if needed, a copy is saved.
• The file size and the total volume per session are limited by the Sessions → File transfer settings (Largest file, MB, All files in one session, MB). Exceeding a limit stops the transfer.
• If the rule does not allow the terminal, only sftp and scp work; a shell, commands, rsync and sftp -s are refused. SCP in WinSCP mode needs a shell on the server and is therefore refused too (switch WinSCP to SFTP).
• File transfer is not available for Telnet servers.

Typical set-ups: files only — Terminal off, File transfer set to “Upload and download” or to one direction; shell only — Terminal on, files off (remember limitation 1); RDP without data leaving — clipboard, files and devices off (you can leave the sound from the server on).

What the user sees on a refusal is listed in the Troubleshooting chapter (the “File transfer” group). How a user connects over SFTP and SCP is described in the section Connecting over SFTP and SCP.

Settings: the gateway SSH key

The /system/ssh page (menu System → Settings → the Gateway SSH key tile, “Security” group). Only an Administrator sees it. This is a read-only page: it has no settings apart from the copy buttons. The page hint: The key SSH clients see when they connect to the gateway. BURSUcm and OpenSSH remember it on first use.

This is the key of the gateway itself (what people's SSH clients see), not the key of any target server — server keys are described in the Servers section. The gateway creates it once, when the page is first opened, and uses the ECDSA nistp256 type.

If the gateway key changes (for example, the gateway was reinstalled on a clean database), every client that remembered the old one shows a key-change warning. This is normal protection: the person must compare the new fingerprint with this page.

Settings: signing of .rdp files

The /system/rdp-signing page (the RDP file signing tile, “Security” group). Only an Administrator sees and changes it. The page title is Signing of .rdp files.

When a person downloads an .rdp file from the “My access” page (see My access), the gateway can sign it. A signed file shows Remote Desktop who published it, and a change to any signed line breaks the signature (A signed .rdp file shows Remote Desktop who published it, and a change to any signed line breaks the signature. The certificate must be trusted on the computers that open the file.). Without a signature, Remote Desktop warns the person every time the file is opened: There is no signing key: .rdp files are not signed, and Remote Desktop warns the person who opens one.

Which certificate fits. The file is no larger than 64 KiB; it holds exactly one certificate with an RSA private key of at least 2048 bits; the certificate allows digital signature (the “key usage” extension is either absent or contains digitalSignature); its validity period has already begun and has not yet ended. On upload the gateway signs a trial file itself and checks the signature; if the key does not match the certificate, it is rejected at once rather than at every download. The reasons for a refusal are in the error table below and in the Troubleshooting chapter.

Storing and removing the key are written to the audit log as the rdp.signing_key event (the thumbprint; for a refusal, the reason). The approaching end of the certificate's validity is raised as a warning on the overview page.

Settings: sessions

The /system/sessions page (the Sessions tile, “Sessions and protocols” group). Only an Administrator sees and changes it. The page hint: How sessions through the gateway are recorded and how long they may stay idle. Input recording, idle time and the banner apply to new sessions only; running sessions keep theirs.

The page is one form with the Save and Reset buttons. All values are saved at once; every changed value is written to the audit log as a setting.change event (the old and the new value). If another administrator saved the form while you were editing, you will see The record was changed by another administrator — open it again.; open the page again. An invalid number: Enter a whole number from … to ….

Which changes require identity confirmation

A change that weakens oversight or affects privacy requires a fresh confirmation of identity (entering the password and code again, valid for 10 minutes). Changes that tighten things do not require confirmation.

• switching on SSH input recording (Recording what people type needs your password and code again.);
• switching on keystroke recording in RDP (Recording keystrokes needs your password and code again.) or the typed-text index (Indexing typed text needs your password and code again.);
• shortening the recording term; raising the SSH idle time; raising or removing the RDP session length limit; raising the RDP idle time; raising or removing the limit on file size and on the per-session total; shortening the term for keeping copies;
• changing the banner text (any change of the banner's text), because any other text could remove the phrase “the session is being recorded”.

Other cases: Confirm who you are before this change: … It lowers session protection. and the Confirm who I am link.

Settings: VNC

The /system/vnc page (the VNC tile, “Sessions and protocols” group). Only an Administrator sees and changes it. Hint: Limits for VNC sessions through the gateway. A change applies to new sessions only; running sessions keep theirs.

Listener

The first block shows whether the gateway is ready to accept connections from VNC clients. It is read-only: The listener is set in the gateway's configuration file (vncListen and vncAdvertisedName) and is changed there; it cannot be changed here. Fields: State, Host (the name that the gateway gives to clients — vncAdvertisedName), Port.

Limits and parameters

A value outside the range: Enter a whole number from … to …. Raising limits in a way that weakens protection (the number of sessions, idle time, length, clipboard size, the handshake and update limits, the number of exports, viewer memory) and switching off the binding of the code to the address require identity confirmation: Confirm who you are before weakening a limit. Removing the length limit (0) is also a weakening. The playback and export parameters of frame rate, length and size are not affected by this list. After saving: Saved.

Settings: databases

The /system/databases page (the Databases tile, “Sessions and protocols” group). Only an Administrator sees and changes it. Hint: Limits, pass lifetimes and protections for database connections through the gateway. A change applies to passes and connections made after the save; ones already open keep what they started with.

A database user gets a “pass” on the “My access” page and enters it in the client as the password (see Connecting to databases). The pass is shown once but is not single-use: it can open several connections during its validity period (8 hours by default, no more than 16 connections), and the first connection must be made within 2 minutes of it being shown. The settings define the lifetime of passes, the number of connections and the protection.

New values apply to passes and connections created after saving; those already open keep their old ones. Changes are written to the audit as the db.settings event (the changes and the list of weakenings). Raising a limit, extending a term, switching off a protection (channel binding, Strict), reducing the statement text and changing the version string are weakenings: These changes weaken protection and need you to confirm your password: … and the Confirm who I am link. When two administrators edit at the same time: The record was changed by another administrator — open it again.

Access requests

Not everyone needs permanent access to a server. For rare tasks it is more convenient for a person to ask for access for a limited time themselves, and for someone else (an approver) to make the decision. This is how access requests work. This section describes the user's side: how to ask for access, how to follow a request, how to extend access or give it back early. The approver's side is described in the section Approving requests, and emergency access without approval in the section Emergency access.

How it works

• The on-request rule (By request) is created by an administrator in the Access rules section. On its own it permits nothing. It only defines who may ask, for which servers and accounts, who approves, how many approvals are needed, for how long one may ask, and how long to wait for a decision.
• A request is a particular person's ask for access to a particular account on a particular server for a stated period. A request always has a reason (text) and sometimes a ticket number.
• Access appears when the request is approved (or approved automatically, if the rule is set up that way). The gateway itself records a separate permission for that period. It cannot be changed: it either ends at its time or is revoked.

Request states

Requesting in the web console

The /access/requests page opens from the My access menu (the Access requests tab). Any signed-in user can see it. The page has two tabs: Available to request and My requests.

The “Available to request” tab

The table shows everything you may ask for. Columns: Server, Account, Limits (the longest period, for example Up to 8 h), Approval and Access period (the window of time in which the rule permits access at all, if it is limited).

The Approval column says one of two things:

• Approvals needed: N and below it Approvers who can decide: M — how many approvals are required and how many people are currently entitled to give them.
• Granted at once; the reason is recorded — the rule is automatic: access is granted at the moment of the request, but the reason is still recorded.

At the end of the row is the Request access button. If you already have a pending request for this pair, a Request pending label stands in place of the button. If an administrator has allowed you emergency access to this pair, there is also a red Emergency access button next to it (see Emergency access).

The “Request access” window

The window opens with the Request access button. At the top it says: Server …, account ….

The Send request button sends the request. The result is a message at the top of the page: Request … sent. (wait for a decision) or Request … sent and approved automatically. (the rule is automatic, access has already been granted).

What the gateway checks on submission

• No more than 10 pending requests per person. More is refused: You have too many requests waiting. Wait for a decision or cancel one.
• If you already have a pending request for the same pair, a second one is not created: the gateway shows the message You already have a request waiting for this server account. and points to the first.
• If you already have the right to connect for the whole requested interval, the request is rejected: You already have access to this server account for that whole period.
• If fewer people can approve than the quorum needs, the request is not accepted: Nobody can approve this request now. Contact the administrator. You are never counted as an approver of your own request.
• If several rules apply to the pair, the strictest is the governing one: first by the largest number of approvals needed, then by the shortest period, then the oldest.
• If the server is beyond the number the licence was bought for, or the licence has ended, the request is not accepted (the messages This server is beyond the number of servers the gateway's licence allows. Contact the administrator. and The gateway's licence has ended. Contact the administrator.).

A refusal is written to the audit log as a request.create event with the outcome “denied”. The list of messages is in the Troubleshooting chapter.

The “My requests” tab

Your requests, newest first. Columns: No., Server, Requested, Access period, State. Under the row you can see who decided and when (Decided by …), and if the access was revoked, who revoked it and why (Revoked by …: …). While a request is waiting, the hour up to which to wait is shown: Decision due by …. An empty list: You have made no requests.

When you open the My requests tab, all decided requests are marked as seen and the notification about them in the bell disappears (Your requests that were decided: …).

When access ends or is revoked

• At its time. Access is valid for exactly the approved interval. When it ends, the gateway closes the sessions that were held by this access.
• A warning. A few minutes before the end (5 by default, set on the Notifications page, 0–30; 0 switches it off) the gateway writes the line Your granted access ends in … minutes. File an extension request if you need more time. into the open SSH session. The BURSUcm client shows the same warning as a pop-up message.
• Revocation. Access can be taken back early by the person who requested it (Release access), by an administrator (the /rules/grants page, titled Grants) and by an approver of that rule (the Active grants tab on the Approvals page). Sessions on this access are closed at once, and Your granted access was revoked by …. The session is closed. is written to the terminal. Extensions that depended on the revoked access are cancelled (pending ones) or revoked as well (approved ones).
• The rule was switched off. All pending requests under it are cancelled, and an e-mail is sent about it. Access already granted remains, unless the administrator ticked Also revoke access already granted from this rule.

If you connect over plain SSH

If you have no access now but can request it, the gateway refuses the connection and itself suggests the way: Access is not allowed now. You can request it in the web console: … (with the console address) or, if the console address is not set, … under My access, Access requests. File a request on the /access/requests page and connect again after it is approved.

Requesting from BURSUcm

The BURSUcm client (Windows and Universal) can file and follow requests without the web console. The gateway must be connected as a directory source (see BURSUcm).

• A second root, On request, appears in the connection tree. It lists the servers to which you have no access but can request it. Each row has the explanation Access to this server is given on request. The state is shown by icons: waiting, Approved. Access starts … (approved, will start later), or until HH:mm for running access.
• A double click or the Request access... item opens the Request access window (for an extension it is called Extend access). The fields are the same as in the console: Server (read-only), Account (a list, if there are several accounts), Start (When approved or At a set time with a date YYYY-MM-DD and a time HH:MM), Duration (with the Custom... option and the hint minutes, 1 to …), Reason with a counter, Ticket (or Ticket (optional)) and Format: …. The buttons: Cancel, the red Emergency access (only if emergency access is allowed) and Send request.
• Under the window title the client says how the request will be considered: Approved automatically; the request is recorded. or Approvals needed: N. People who can approve: M., and below it Rule: ….
• After sending, the same window turns into a status panel: Waiting for approval · X of Y approved · expires …, Approved · starts …, Approved · active until …, as well as the final lines This access has ended., The request was denied., The request was cancelled., Nobody answered in time; the request expired., The access was revoked. The panel's buttons are Cancel request and Connect now (when the access is running). If the gateway is unreachable, the panel says cannot reach the gateway, trying again and keeps polling; if polling has stopped — The status is no longer updated. Open My access requests to see it.
• The File → My access requests... menu opens the list of your requests (titled My access requests, hint Your requests, newest first. A running access can be given back or extended.) with the columns Server, Account, State, Period, Answers and the buttons Refresh, Release, Extend..., Cancel request, Close. When access is given back, the client asks: Give this access back now? Sessions running on it end. An empty list: You have no access requests yet. Ask for access from the On request list.
• The request stages in the client: Waiting for approval, Scheduled, Active, Ended, Denied, Cancelled, Expired, Revoked.
• The pop-up warning before the end: Your access to … as … ends at …. Extend it in My access requests. After the end: Your access to … as … has ended. with the option to request access again at once.

The client checks the fields itself before sending and shows clear messages: A reason is required., The reason must be at most 1000 characters., Enter the ticket number., The ticket number must be at most 64 characters., The duration must be from 1 minute to …, The start must be later than now., The start can be at most 7 days ahead., The period must lie inside the time this access may be requested for. The gateway's answers are shown in the same phrases as in the console (see Troubleshooting).

Approving requests

A section for people with the Approver role. It describes the /approvals page (menu Access → Approvals), on which an approver decides on access requests and confirms commands held by command control. The approver's usual working day is described in the section The “Approver” role.

Who can approve

A request can be decided by a person who at the same time:

• is enabled and holds the Approver role;
• is named as an approver in the on-request rule — personally or through a group (the rule's Approvers field);
• is not the author of that request. Deciding your own request is impossible: the page simply does not show it.

If you cannot decide a request or it does not exist, the page answers the same way — “not found” (HTTP 404). This way an approver does not learn about other people's requests they are not admitted to. An administrator does not see the Approvals page: the Administrator and Approver roles are incompatible (more in the section The “Approver” role).

The page tabs

The tabs come in this order. Each list is limited to 100 rows.

The number on the badge in the side menu counts only requests waiting for a decision. Commands awaiting confirmation are not included; they are covered by the Commands tab and the bell.

The request card

The title is Request №. The card has: Requester, Server and account, Access period, Reason, Ticket, Rule, Approvals: X of Y and Decisions so far (who has already approved or refused, with comments; while there is nobody — None yet.). Two references are added to help you judge: This person's last five requests and This person's last five sessions on this server.

If the rule's conditions have changed since the request was filed, a warning above the buttons says what will happen when you approve: … now governs this access, so approving will cancel this request., No rule offers this access any more, so approving will cancel this request., The ticket no longer meets the rule's terms, so approving will cancel this request. or The rule now allows at most … minutes: the grant will be that long.

Approve or deny

Results: Your approval is recorded; more approvals are needed. (the quorum has not been reached yet), Approved. The access is granted. (the quorum is reached, access granted), Request denied.

Quorum. The number of approvals needed is set by the rule (from 1 to 5, from different people). A request gets access when the needed number of approvals has been collected from people who are still entitled to approve at that moment. If one of those who voted has meanwhile lost the role or been removed from the rule, their vote is not counted; in the history this shows as Vote dropped: this approver no longer qualified at the final count. When approvers proposed different periods, the shortest of those proposed is granted.

Waiting. If a request is not decided within the time the rule sets (240 minutes by default), it expires.

The “Active grants” tab

For each access you can see the person, server, account and period. The Revoke button asks Revoke the access of … to …? Open sessions end at once. and accepts the optional field Reason (kept in the log) (no more than 1000 characters). Revoking closes open sessions, and extensions that depended on this access are cancelled or revoked. Messages: Access revoked. and Access revoked, and … extension(s) that depended on it. If the access has already ended or been revoked, it will say This access has already ended or was taken back.

Confirming commands

If the command control policy contains an Ask a second person rule, the line the user typed is held until the confirmer allows it (see Command control). Such lines are shown on the Commands tab. The list updates itself, without reloading: New commands appear here as soon as they are held. The page does not need to be reloaded. If the connection is lost: The live connection was lost. Reload the page to see what is waiting.

• When you open the tab, you are sent to identity confirmation if there is no fresh confirmation. The page shows how long it is still valid: Your confirmation is valid for another …. When it has run out: Your confirmation has run out, so Allow is off until you confirm again. A command does not wait for you to confirm, so do it in advance.
• The card: Command held for confirmation, Person, the server and account, Policy and entry, Confirmations: X of Y, Time left: … s, Command (passwords and keys are hidden where they can be recognised).
• A reminder: You confirm a text, not a program. Aliases, functions and key bindings can make a line do something other than what it says.
• Last screen rows — the last rows of the session screen (if the policy includes Show the last screen rows to the confirmer). They are labelled From the target: the server itself wrote them, it can fake any output, so they prove nothing.
• Lines read earlier in this session — earlier lines of the session. Lines that change commands or keys (alias, function, bind) are marked redefines a command or a key.
• The Watch live link is there only for a person who is also an Auditor: only an auditor can watch a session live.

You cannot confirm your own session: This is your own session. Another person has to decide. If the time runs out, the command is refused automatically (a timeout is a refusal). If the line changed while it waited, the confirmation is invalid: The held line is not the one you were shown, so it was refused. Right after the gateway restarts, the page does not accept decisions until the check of waiting commands is finished: The decision could not be saved. Try again.

The bell and notifications

In the console's top bar is the Alerts bell. An approver always has it. An ordinary user sees it only when there is something to show. The items that matter for this section:

• Requests waiting for your decision: … — a link to the Waiting for me tab.
• Commands waiting for your confirmation: … — a link to the Commands tab.
• Your requests that were decided: … — for the requester; a link to My requests.
• For an administrator: Rules that no one can approve now: …, New approvers without a console change: …, Directory roles refused (Administrator wins over Approver): ….

The other items in the bell are described in the sections Emergency access, Notifications and Command control.

Emergency access

Emergency access (in English break-glass, “break the glass”) is a way to get onto a server without approval when the work cannot wait. It is designed so that it cannot be used unnoticed: the person confirms who they are with a fresh code from an authenticator app, states a reason, and everyone responsible is alerted at once. Every use must afterwards be reviewed by another person.

How an administrator switches emergency access on

Emergency access is configured in the on-request rule (the Access rules section), in two fields:

Emergency access can be switched on only when an alarm will really get through: if no channel (SIEM export, e-mail or webhook) has delivered in the last 24 hours, the gateway refuses: Cannot be switched on: no alarm channel (SIEM export, e-mail or webhook) has delivered in the last 24 hours. Set one up under System, send a test and try again. First set up the channels on the Notifications page. Widening the circle of people, servers or accounts while emergency access is on requires a fresh confirmation of identity.

How a person uses emergency access

Conditions: you are marked for this “server — account” pair, and you have a confirmed authenticator app (TOTP; set up in your profile). If there is no app: Emergency access needs a confirmed authenticator app. Set one up in your profile first.

1. Open the window. On the /access/requests page, the Available to request tab, press the red Emergency access button in the row of the pair you need (in BURSUcm, the Emergency access button in the request window).
2. Read the warning. This skips approval. You will be let in to … as … for … minutes. The use is recorded and must be reviewed afterwards. Use it only if the work cannot wait. Below it says who will be alerted: The moment you confirm, Approvers, Auditors and Administrators are told in the console, the emergency alarm recipients by e-mail or webhook, and the SIEM export records the event.
3. Fill in the fields. They are listed below.
4. Confirm. Press Use emergency access. On success: Emergency access granted until …. This use will be reviewed. The access is valid from that moment for the period set by the rule and is not extended.

Limits

• No more than 2 uses per person in 24 hours (this value cannot be changed in the console).
• No more than one running emergency access per person and server: You already have emergency access to this server account.
• Wrong codes are counted. If the account is locked because of wrong codes, the form reports the lock and the time when it ends. In addition, submitting the emergency access form is limited to 10 attempts a minute per person (an HTTP 429 response).
• A use is not refused because the alarm channels are silent: the event is recorded all the same, and the log keeps whether a channel was alive.
• The licence is checked just as for an ordinary request.

If a use is refused, the form comes back with a message and the code field is cleared. The possible messages: Emergency access is not available to you for this server account., Emergency access needs a confirmed authenticator app. Set one up in your profile first., Write a reason of at least 20 characters., Enter the six-digit code from your authenticator app., The code is wrong or was already used., You already have emergency access to this server account., The limit of emergency accesses is reached. Contact the administrator.

What everyone sees during and after

• The person. In the console, a banner is visible on every page: Emergency access is active until …. This use is recorded and will be reviewed. In an SSH session that is held only by emergency access, the terminal shows the line Emergency access: this use is recorded, the responsible people have been told, and it will be reviewed. Before the end they get the same warning as with ordinary access; in BURSUcm it reads Your emergency access to … as … ends at …. It cannot be extended. Emergency access cannot be extended; it has no Extend button, only Release access.
• Approvers, auditors and administrators. A red item Emergency access used and not yet reviewed: … appears in the bell; an administrator additionally sees Emergency access reviews overdue: ….
• The emergency alarm recipients (the list on the Notifications page) receive an e-mail Emergency access was used: request #… and a webhook.
• SIEM. The use gets into the export as a separate event.
• Commands. For sessions that are held only by emergency access, the built-in policy Break-glass audit (built in) applies automatically: the gateway records every line it can read. It cannot be changed or deleted. Passwords typed at a sudo prompt are not stored: the input is not recorded.

Review after use

Every use must be reviewed within the term set by a setting (72 hours by default; the value cannot yet be changed in the console). The review may be done by an enabled Approver or Auditor who is not the person who used the access. An administrator alone cannot review.

The /audit/breakglass page (menu Audit → Emergency access) is available to the Administrator, Auditor and Approver roles. Three tabs:

• Waiting for review — uses without a review;
• All uses — all uses (30 per page);
• Command list — the command lines read by the gateway in the sessions of the selected use.

The table columns: Person, Server and account, Reason, Ticket, Used, Sessions, Review. The review state: Waiting for review (Review due by …), Overdue (Review overdue since …) or Reviewed (Reviewed by … on …). The Sessions and Command list links are visible only to an auditor and an administrator; an approver sees the text of commands only on this page. An empty page: Emergency access has not been used.

The review button opens the Review this use window:

The Close the review button closes the review: Review closed. It cannot be closed again (This use has already been reviewed.), and you cannot close the review of your own use (You cannot review your own use.); to the person who used the access, the page says: Another Approver or an Auditor reviews your use of emergency access; you cannot close the review. The review also works when the licence is exhausted.

Notifications

The /system/notifications page (menu System → Settings → Notifications) is for the administrator only. It sets how the gateway tells people about requests, decisions and emergency access: by e-mail and by a signed webhook. The failure of a channel never blocks a request: the gateway retries delivery and raises an item in the bell.

The mail password and the webhook secret are write-only: after saving they are no longer shown. If a value is saved, the text under the field says A value is saved. Leave the field empty to keep it; type a new one to replace it.

Page fields

Testing and delivery state

• Send a test e-mail sends a test message to your account's address (subject BURSU PAM test message). The test uses the settings already saved: Save the settings first: the test uses the saved ones. If your account has no address: Your account has no e-mail address. Add one in your profile first.
• Send a test webhook sends a test message to the saved address.
• The result: The test message was sent. or The test message was not sent: … with the reason (the list of reasons is in the Troubleshooting chapter). While the licence does not allow changing settings, tests are refused.
• The Delivery card shows, per channel — E-mail, Webhook and SIEM export — the state and the time Last delivered (Never if nothing has been delivered yet; not set up if the channel is not configured).

Which events and to whom

Each recipient gets the e-mail in their own language (the language of their account), and if it is not set, in the gateway's default language. The e-mail has no “approve” button: it leads to the console and says that a decision can be made only after signing in.

The webhook receives every event as JSON with the fields id, event, at; if the event concerns a request, request, state, requester, server, account, period and reason are added (a long reason is truncated). Headers: X-Bursu-Timestamp (the time in Unix seconds) and X-Bursu-Signature: v1=…, where the value is an HMAC-SHA256 of the string “time, dot, body” with your secret. The receiving side must check the signature and reject old messages. The User-Agent is BURSU-PAM-webhook/1.

Delivery. Messages sit in a persistent queue and are resent after a failure: up to 20 attempts with pauses from 1 second to 5 minutes. The wait for the mail server is 60 seconds, for the webhook 10.

The bell

The items connected with this section: Notifications are failing: … (a channel is not delivering), No push channel (SIEM, e-mail, webhook) has delivered in the last 24 hours, so an alarm could go unheard. (an alarm may go unheard), Emergency access used and not yet reviewed: …, Emergency access reviews overdue: …. The usual path: open the Notifications page, look at the Delivery card, send a test.

Command control

Command control is a protective barrier and a log for people who work on servers through the gateway. The gateway reads the lines a person types in the terminal and, according to rules (policies), allows them, flags them, holds them until a second person confirms, refuses the line or closes the session.

What works where

While a policy applies, only the environment variables LANG, LC_* and TZ are passed to the server; the rest are dropped. A shell without a terminal (ssh -T) is refused: there is nothing to read. The exception is a session held only by emergency access: there only the built-in policy Break-glass audit (built in) works, and a terminal is not required.

The “Command control” page

The address is /commands, menu Access → Command control. The page is seen by the Administrator and the Auditor; an auditor only reads, an administrator changes. At the top are an explanation, the What command control cannot stop link and the counter Commands waiting for confirmation: …. Four tabs: Policies, Pattern groups, Tester, Starter packs.

How it is organised: pattern groups and policies

1. A pattern group (Pattern group) answers the question “what to look for”: a set of patterns, for example all variants of the delete command.
2. A policy (Policy) answers the question “what to do”: whom and which servers it applies to, and in what order its entries are listed (an entry = a pattern group + an action). The first matching entry decides.
3. Several policies can apply to one person on one server. Each judges separately, and the strictest result wins. A policy added later can only tighten.

Pattern groups

The Pattern groups tab: columns Group, Patterns, Syntax, Used by; the New group button. An empty list: No pattern groups yet.

The Try it in the tester link opens the check. A group that a policy uses cannot be deleted (A policy uses this group. Take it out of the policy first.).

Policies

Addresses: /commands/policies/new (create), /commands/policies/{number} (card), /commands/policies/{number}/edit (edit). The card has Edit, the on/off switch (Enable / Disable), Delete and the What this affects now block (which servers and people currently fall under the policy). The built-in policy Break-glass audit (built in) cannot be changed, switched off or deleted.

The entry actions:

When a policy is switched off, the gateway asks Switch this policy off? The commands it checks run unchecked from the next moment.; on deletion — Delete this policy? Its past events stay in the audit log.

Checking a line

The Tester tab (Try a command line) shows how the gateway will read a line. Nothing is run and no session is touched: Nothing is run and no session is touched.

The Check the line button shows: Words (words), Simple commands (simple commands), Without wrappers (sudo, env, nice and the like), Matching entry, Result. The possible outcomes: No entry matches., Nothing matched, so the line would run., Nothing matched, and an allow-list policy refuses what it does not list., The gateway cannot see what this line runs: …, The line is unfinished (…), This line cannot be shown safely to a confirmer, so it could not be confirmed. The limit is 30 checks a minute per person, otherwise Too many checks in a minute. Wait a moment.

Ready-made packs

The Starter packs tab holds 19 templates, grouped by family: Linux (6), Cisco (3), Huawei (3), MikroTik (3), one-off commands (1) and databases (3). Each states what it relies on (Relies on …). The Make a policy button creates the policy switched off: Policy … was created disabled. Review it before you switch it on. Check the entries, set the scope and switch it on. There is no Allow-list pack for interactive shells: it breaks prompts and programs.

What the user sees in the terminal

The gateway writes in plain text on a separate line, without a prefix, in the gateway's default language (an SSH session has no language of its own).

Pressing and holding Enter does not cause a session timeout: while a check is under way, the session counts as active. Keys typed during a hold are queued (up to 4 KiB) and checked in turn after the decision; if the line was refused, the queue is discarded.

Confirmation by a second person

You will wait for confirmation no longer than the value of Wait for a command confirmation, seconds (120 seconds by default; set on the Notifications page). Waiting out the time is a refusal. The confirmer sees the command on the Commands tab of the Approvals page, see Confirming commands. If there is no suitable confirmer at all, the command is refused at once: No second person is available to confirm this command, so it was not run. No more than one command per session, three commands per person and fifty for the whole gateway can wait for confirmation at the same time; beyond that the line is not run and the gateway writes Too many commands are waiting for confirmation on this gateway; this one was not run. Try again shortly.

Command control and clients

On a server with command control, BURSUcm (Windows and Universal) switches off its tmux for that connection and sends no integration lines to the shell. Because of this, the “Files” panel following the shell's folder and the command marks for the AI assistant do not work. An icon Command control is on appears on the terminal tab with the hint: Command control is on: the gateway checks the commands typed on this server, and tmux is off for this connection. This app types nothing into the shell here, so Files does not follow the shell's folder and the AI assistant has no command marks.

What control cannot see

• Interpreters: python -c, perl -e, awk, vi :! run commands that the line does not show.
• Programs with a shell escape: less, man, find -exec, git.
• Aliases and functions set earlier in the session or in the shell's start-up file.
• Tricks with variables and quoting (a command in $x), history expansion (!!), a script uploaded over SFTP and then run.
• ssh onwards from the target server to another; stty -echo and rebinding of keys (bind, bindkey, zle): the gateway notices the common cases, but not all.
• Programs that read commands from their own input (psql, mysql, sqlite3, gdb, expect, vim -es) and input in full-screen programs, editors and password prompts. Such lines count as “unreadable” and are accounted for.

What the gateway records: a line that was read and matched a policy (or any line, if recording of all lines is on) goes into the session's command list with passwords and keys masked (masking is not guaranteed) and is deleted together with the recording. The audit log does not contain the command text — only a fingerprint, the policy and the result. The command text is read by the Auditor and the Administrator; the Approver — only what was sent to them for confirmation, and the emergency access reviews.

The “Approver” role

The Approver role (“approver”) is assigned to a person in the Users section (or comes from a directory group). An approver does not configure the gateway but makes decisions: on access requests, on held commands and on emergency access reviews. The role gives no access to servers by itself.

Incompatibility with the administrator

The same person cannot be both an Administrator and an Approver: one cannot approve access and at the same time write the rules by which it is granted. On assignment the form says Approver and Administrator exclude each other: nobody approves requests while managing the rules. Choose one of the two. and, on saving, A person cannot be both an Administrator and an Approver. If a person receives both roles from directory groups, Administrator wins, the Approver role is refused and appears in the alerts (Directory roles refused (Administrator wins over Approver): …).

An administrator who needs to approve needs a separate account with the Approver role.

What an approver sees and can do

What an approver does not see: the configuration pages (servers, accounts, rules, users, system), the audit log, session recordings, commands outside confirmation. Other people's requests that they are not admitted to they do not see at all.

An approver's working day

1. Sign in to the console. The Access menu has an Approvals item with the number of waiting requests on its badge. The bell reminds you of requests and of commands waiting for confirmation.
2. Confirm your identity. To allow (to approve a request or a command) you need a confirmation, valid for 10 minutes. Confirm in advance, especially if you are on duty for commands: a waiting command does not stop for you.
3. Work through “Waiting for me”. For each request, read the reason, the ticket number and the period, and look at what the person has already requested and done on this server. Approve, with a shorter period if needed, or refuse with a comment.
4. Watch the “Commands” tab if you are a confirmer of a policy. Decide by checking against the card; remember that you are confirming a text, not a program.
5. Check “Active grants” if you need to revoke access early (the person has finished the work, suspicions, an error in the request).
6. Review the uses of emergency access on the Emergency access page and close the review with a verdict and a note. You cannot close reviews of your own uses.

Overview: the state of the gateway

The Overview page (address /overview) is the first thing an administrator or an auditor sees after signing in. It answers two questions: “is everything all right with the gateway” and “what has been happening lately”. The page changes nothing; it only shows. The Administrator and Auditor roles can see it; a user with the User role alone and an approver (Approver) cannot open this page.

All the reads for the page together are given no more than five seconds, and each value is read separately. If a value could not be read or did not finish reading in time (for example, the database did not answer), a dash “—” or the word unknown stands in place of the number, and the rest of the page works as usual. A dash is not a gateway error but the message “could not find out”; refresh the page in a minute.

The “Where to start” block

The block is visible only to an administrator and only while at least one step is not done. It lists four steps before the first connection: Add a server, Add a server account, Create a user, Create an access rule. A completed step is ticked on its own; a step that is not done has an Open button that leads to the page where you create it. The counter on the right shows “{number done} of 4”. When all four steps are done, the block disappears. The step “create a user” counts as done only when there is an enabled user with the User role: an administrator, an auditor and disabled accounts do not count.

The number cards

The sign-in chart and the latest events

The Console sign-ins chart (“Successful sign-ins and refusals per day”) shows, by day, the number of successful sign-ins (Successful) and refusals (Refused) to the web console. The Period switch is Week (7 days, the default) or Month (30 days). Days are counted in the display time zone set in gateway.json (displayTimeZone, see gateway.json).

The Latest events block shows the ten most recent events of the audit log. The title of an event is a link to its card. The Audit log button opens the full log.

The Health block: what each tile means

The Health block (“Checked when the page opens (at most every 30 s)”) is the gateway's self-check. The state is read when the page opens and no more often than once every 30 seconds, so after you fix a problem the tile may not turn green at once. Each tile has a state word on the right: fine (green, all well), attention (yellow, take a closer look), problem (red, act), off (grey, the feature is switched off). The word is a link to the page where the problem is fixed, if you have the right to open it. An auditor sees the tiles, but the links to the settings pages do not work for them (settings are open only to an administrator).

Six tiles are always shown:

The other tiles appear only when the corresponding feature is set up:

The “Alerts” bell

The top bar of every page has the Alerts bell. It gathers only current problems: all the yellow and red tiles of the Health block plus a few messages that the Health block does not have. If there are no problems, it says No current problems. Both the administrator and the auditor see the messages; the link to the page that fixes the problem is given only to someone who has the right to open it.

Sessions: lists, watching, ending

The Sessions section of the Audit group in the side menu answers the questions “who is working on the servers now” and “who worked there earlier, and when”. The pages of the section are visible to Administrator and Auditor. An approver (Approver) and an ordinary user do not open them. An auditor can view, search, play recordings and end sessions, but configures nothing (“Auditor” section).

How the section is organised

In the side menu the section has one item — Sessions — for all protocols. There are no separate items for SSH, RDP, VNC and databases. On every page of the section the heading is the same — Sessions — and under it is a strip of five tabs: