On this page
ShaWeR
Overview
ShaWeR (Shared Web Runtime) is the shared web runtime for UpAndCoding extensions to BroadSQL: the local web server their browser interfaces share, such as Desk. It is an extension by UpAndCoding, free of charge, with no licence key. It serves your own computer only and signs people in with a ShaWeR user, a password and, when turned on, a code from an authenticator application.
BroadSQL without ShaWeR opens no network port, and installing ShaWeR does not change that: the port opens only when you type SHAWER START, or a command that says it starts ShaWeR, such as DESK. ShaWeR does not need Desk. Desk needs ShaWeR.
ShaWeR listens on 127.0.0.1 (or ::1) only and refuses any other address. By default it serves the browser of that computer and nothing else. To reach it from elsewhere, put a reverse proxy with HTTPS in front of it on the same machine and configure both ShawerPublicUrl and ShawerTrustedProxies: see Reaching ShaWeR from another computer. Until you set both, a request arriving through a proxy is refused.
Requirements
| Requirement | Detail |
|---|---|
| BroadSQL | 5.6.0, Windows x64 or Linux x64. ShaWeR runs in the Java included in BroadSQL. |
| Browser | Chrome, Edge or Firefox, on the same computer as BroadSQL. |
| Two-factor authentication (optional) | An authenticator application that supports time-based codes (TOTP), for example on your phone. |
ShaWeR provides Web API 1.1. An extension that uses ShaWeR depends on a Web API version, not on a ShaWeR release, and a minor version only adds, so every extension written for 1.0 still runs. SHAWER STATUS; shows both versions.
Installation
ShaWeR is downloaded on its own, free of charge, and needs no licence and no other extension: Downloads.
Latest version: 1.1.0 (Web API 1.1).
Download BroadSQL-ShaWeR-1.1.0.zip SHA-256 checksum
SHA-256: f84cd814ff4bc559b49a80ab2b76b4bc4dc0059a11bbf2e889e465e9aa3a1d1c
Extract the ZIP into the BroadSQL installation folder: it puts broadsql-shawer.jar in extensions/, with the guide in docs/ShaWeR/. Start BroadSQL and enter the master password. Check the SHA-256 of the file you downloaded against the checksum above if you want to.
It is also included in the Desk download, as a second, separate extension: an installation that already has Desk has ShaWeR and needs nothing else.
To uninstall, close BroadSQL and delete extensions/broadsql-shawer.jar. Extensions that need ShaWeR then say so and open nothing. The ShaWeR users stay in the Connections Definition File until you install ShaWeR again.
Getting started
Every SHAWER command runs in the BroadSQL console, which has your master password.
Create a user. The password is asked twice at a hidden prompt, never typed in the command:
SHAWER USER ADD alice;
A user name has 1 to 32 letters, digits, ., _ or -, and starts with a letter or a digit; it is stored in lower case. A password has 12 to 256 characters, with at least 5 different characters.
Start ShaWeR:
SHAWER START;
It prints the protocol, the address, how people sign in, the web extensions it serves and any warning. The address holds this installation's Instance ID and is the same every time: see The address. Open it in your browser and sign in with the user and its password.
SHAWER STOP; ends every browser session and closes the port. LOGOUT and EXIT stop ShaWeR too.
When the console needs its master password again after a period of inactivity, every browser session ends at once. Enter the master password in the console, then sign in again.
Configuration
Settings
Optional keys of the BroadSQL INI file: conf/broadsql.ini. A setting never starts ShaWeR. A missing key means its default. An invalid value means its default, with a notice from SHAWER START; the exceptions are ShawerBindAddress, where an invalid value stops the start, and ShawerTotp, where it means REQUIRED. A change applies at the next SHAWER START: type SHAWER STOP; then SHAWER START;.
| Key | Default | Values | Effect |
|---|---|---|---|
ShawerPort | 8080 | 1024 to 65535 | The port. A port already in use stops the start. |
ShawerBindAddress | 127.0.0.1 | 127.0.0.1, localhost, ::1 | The local address. Any other value stops the start. |
ShawerProtocol | HTTP | HTTP, HTTPS | See HTTPS. |
ShawerKeystore | none | a file | The certificate file for HTTPS, as written. |
ShawerKeystoreType | PKCS12 | PKCS12, JKS | The format of that file. |
ShawerTotp | OPTIONAL | OPTIONAL, REQUIRED | See Two-factor authentication. |
ShawerLaunchLinks | ON | ON, OFF | OFF turns off the links that console commands such as DESK open. |
ShawerRememberDays | 14 | 0 to 90 | How many days "Remember me" keeps you signed in on a browser. 0 removes the box. See Remember me. |
ShawerSessionIdleMinutes | 60 | 1 to 1440 | A browser session ends after this many minutes without an action. |
ShawerSessionMaxHours | 12 | 1 to 168 | The longest a browser session lives. |
ShawerMaxFailedLogins | 5 | 3 to 20 | Failed sign-ins in a row that lock a user. |
ShawerLockoutMinutes | 15 | 1 to 1440 | How long the lock lasts. |
ShawerMaxRequestKb | 1024 | 1 to 65536 | The largest request accepted, in KB. |
ShawerMaxThreads | 16 | 2 to 256 | Requests served at the same time. |
ShawerTimeoutSeconds | 120 | 10 to 3600 | Request and response time limit. |
ShawerLogRequests | OFF | ON, OFF | ON logs one line per request. |
ShawerPublicUrl | none | an address | The address people type when a reverse proxy serves ShaWeR, such as https://www.example.com/broadsql/. See Reaching ShaWeR from another computer. |
ShawerTrustedProxies | none | IP addresses | The addresses of the reverse proxies allowed to serve that address, such as 127.0.0.1. |
ShawerShutdownGraceSeconds | 2 | 0 to 60 | Time given to requests in progress when ShaWeR stops. |
WebPort, the name Desk 1.0 used, is still read as a deprecated name of ShawerPort. WebContextPath is ignored: the path of the address is your installation's own Instance ID.
Users, passwords, two-factor secrets and the certificate password are not settings: they are stored in the Connections Definition File, encrypted with your master password, and never in the INI file or a log. A change to a user applies at once.
The sign-in page
You sign in to a BroadSQL instance, not to ShaWeR. The page is headed Sign in to BroadSQL followed by this installation's Instance ID, for example Sign in to BroadSQL C6MVER39XDZS9KT7, so that you can tell two instances apart; it carries BroadSQL's own brand and colours and links the documentation. ShaWeR is the web runtime behind it and is not what people are asked to sign in to.
Asking for an application you are not signed in to takes you straight to that page, and signing in takes you straight back to the application you asked for. Opening /desk/ while signed out goes to the sign-in page and then to Desk, with no page in between telling you to sign in and no list of applications to pick from. The same holds behind a reverse proxy, on the public address.
The address of the instance itself, without an application, shows a short list of the applications installed in it, for when you open it on purpose. Nobody is ever routed through that list on the way to an application they asked for.
A session that has expired, or that ended because the console needs its master password again, behaves the same way: you are taken to the sign-in page, which says why, and back to where you were.
Signing out is a real sign-out: it ends the session on the server, so another tab of the same browser cannot go on using it, and it forgets a remembered sign-in on that browser. Closing a tab is not signing out. Desk has a Sign out button in its header, next to the name you signed in with; the instance's own page has one too.
Two-factor authentication
Two-factor authentication adds a 6-digit code from an authenticator application to the password. It is set up per user.
ShawerTotp | Effect |
|---|---|
OPTIONAL (default) | A user with two-factor authentication on must type a code. A user without it signs in with the password. Console links work. |
REQUIRED | Every user must have two-factor authentication on. A user without it is refused, with a message to set it up in the console. Console links are off. |
An invalid value of ShawerTotp means REQUIRED, the stricter policy.
Set it up for a user. Start the enrolment:
SHAWER USER TOTP alice;
It prints a secret and an otpauth:// address. Add the account to your authenticator application with that secret (or that address). Two-factor authentication is still off. Then confirm it with the code the application shows now:
SHAWER USER TOTP CONFIRM alice 123456;
Two-factor authentication is now on, and eight recovery codes are printed once. Store them somewhere safe, away from the device. From now on, alice types the current code on the sign-in page after the password. A code is accepted once: a code already used is refused, even within its 30 seconds. The device clock must be correct within 30 seconds.
SHAWER USER LIST; shows each user's two-factor state: ON, PENDING (enrolment not confirmed) or OFF.
Recovery codes. A recovery code, such as K7M2Q-9XRTB, replaces the 6-digit code once. Each code works one time. When all are used, sign in with the application's code, and get eight new recovery codes by enrolling again (TOTP, then TOTP CONFIRM). A new confirmation replaces all earlier recovery codes.
Enrol again. SHAWER USER TOTP alice; for a user who already has two-factor authentication turns it off until the new CONFIRM. Under OPTIONAL, the user can sign in with the password alone during that time; under REQUIRED, not at all. Confirm without delay.
Lost device. Turn two-factor authentication off, then set it up again on the new device:
SHAWER USER TOTP RESET alice;
SHAWER SESSIONS REVOKE alice;
SHAWER USER TOTP alice;
SHAWER USER TOTP CONFIRM alice 123456;
RESET forgets the secret and the recovery codes. It does not end the browser sessions already open: SHAWER SESSIONS REVOKE alice; does.
Users, sessions and administrators
| Command | Effect |
|---|---|
SHAWER USER ADD <name> [ADMIN]; | Creates a user. ADMIN makes it an administrator. |
SHAWER USER PASSWORD <name>; | Changes the password and ends that user's browser sessions. |
SHAWER USER REMOVE <name>; | Removes the user and ends their browser sessions. |
SHAWER USER UNLOCK <name>; | Lifts a lock after too many failed sign-ins. |
SHAWER SESSIONS; | Shows how many browser sessions are open. |
SHAWER SESSIONS REVOKE [<name>]; | Ends every browser session, or those of one user, and forgets their remembered sign-ins. |
An administrator may use the pages an extension reserves for administrators. ShaWeR and Desk 1.0 reserve none: every user can use Desk. Users are managed only in the console, never in the browser.
Each user's own folder
An extension can keep things for the person using it, and ShaWeR gives it one folder per user to keep them in:
<BroadSQL installation>/shawer/users/<key>/<extension>/
<key> is drawn at random when the user is created and is stored with the user in the Connections Definition File. It is not the user name: a name can be removed and given to somebody else, and a key cannot, so a user removed and created again with the same name starts with an empty folder and never sees what the previous holder kept. BroadSQL Desk uses this for each user's Recent, Kept, History and Exports.
What this means for you:
| Permissions | ShaWeR creates the folders readable and writable by the account running BroadSQL only (rwx------ on Linux), so a systemd service account keeps its state to itself. The installation folder must be writable; when it is not, Desk still works and says that nothing is kept between sessions. The folder is taken the first time a user asks for anything, so after fixing the permissions, run DESK STOP; then DESK; for that user's workspace to be kept again. |
| Nothing is served | No address reaches these files. They are not part of any extension's published files. |
| No secret | A password, a two-factor secret and a licence key are never written there; they stay in the Connections Definition File, which your master password encrypts. These files are protected by file permissions only, so a backup of the installation folder contains them in clear. |
| Removing a user | SHAWER USER REMOVE <name>; removes the user and the key, so nobody can reach the folder again. The folder itself is left on disk rather than deleting somebody's work as a side effect; delete shawer/users/<key>/ by hand when you want the space back. |
| Upgrading | A user created by a release before 5.6.0 has no key yet. One is drawn the first time it is needed, and nothing is migrated, because nothing was kept per user before 5.6.0. |
Remember me
The sign-in page has a Remember me box. It is never ticked for you. Leave it clear and your sign-in lasts as long as the browser is open, as before. Tick it and that browser can be closed and reopened without signing in again, for ShawerRememberDays days (14 by default, 90 at most, 0 to remove the box).
What it does, exactly:
- The password is always required, and so is the two-factor code of a user who has two-factor authentication on. Being remembered follows a complete sign-in; it never replaces one.
- The browser keeps one extra cookie holding two random values and nothing else. Your password and your two-factor secret are never stored in the browser, and never appear in an address.
- ShaWeR keeps one row per remembered browser in the Connections Definition File, which your master password encrypts. It holds no password either: only a fingerprint of the cookie's secret half, which cannot be turned back into a cookie.
- The time limit is absolute. It is set when you tick the box and using it never pushes it further out, so a remembered browser asks for your password again within the configured number of days whatever it does.
- Each use replaces the secret half of the cookie, so a copy taken earlier stops working as soon as you come back.
How it ends:
| What you do | Effect |
|---|---|
| Sign out | Ends the session and forgets that browser. Closing the tab is not signing out. |
SHAWER SESSIONS REVOKE [<name>]; | Ends the sessions and forgets the remembered browsers, so a restart does not sign them in again. |
SHAWER USER PASSWORD <name>; | Forgets every remembered browser of that user. |
SHAWER USER REMOVE <name>; | The same, with the user. |
| The time limit | The row and the cookie are worthless, and the next visit asks for the password. |
LOGOUT in the console | The Connections Definition File closes, so nothing can be remembered until the master password is entered again. |
On a shared or public computer, leave the box clear. Whoever can read the files of a browser profile can continue a remembered sign-in from that profile, without your password, until it expires or you come back and the secret is replaced. That is what remembering means, and it is why the box is optional, limited in time and revocable.
Console links
DESK and similar commands open your browser with a link that signs you in without a ShaWeR user, because your master password already proves who you are. The link:
- works once, within two minutes, then is refused;
- signs in as the user
console, an administrator, whose sessionsSHAWER SESSIONS REVOKE console;ends, and whose own folder isshawer/users/console/, separate from every ShaWeR user's; - is off when
ShawerLaunchLinks=OFForShawerTotp=REQUIRED. The command then prints the address: sign in there with a ShaWeR user.
The address
The address is http://127.0.0.1:<port>/<Instance ID>/, where the Instance ID is the identity BroadSQL keeps in its settings file, such as C6MVER39XDZS9KT7. It is the same address every time: stopping and starting ShaWeR, or restarting BroadSQL, does not change it, so a bookmark keeps working. SHAWER STATUS; always shows it.
Two things follow from the address holding the Instance ID. A request that names another path gets Not found, so another local web server never receives ShaWeR's cookie. And the path is not a password: everything behind it needs a signed-in session, so knowing the address gets nobody in.
If BroadSQL cannot write an Instance ID in its settings file, the path is drawn at random at every start instead, and SHAWER START; says so.
Reaching ShaWeR from another computer
ShaWeR listens on 127.0.0.1 and nothing else, in every release. To open Desk from another computer, put a reverse proxy such as Nginx in front of ShaWeR, on the same machine, and let the proxy hold the certificate and the public name. ShaWeR then serves one stable public address, and people sign in with their ShaWeR user, password and two-factor code, with no link from the console.
This is off until you set both settings:
ShawerPublicUrl=https://www.example.com/broadsql/
ShawerTrustedProxies=127.0.0.1
ShawerPublicUrl is the address people type. Its host, its port and its path are yours to choose; ShaWeR writes every link, redirect, page address and cookie for it. ShawerTrustedProxies lists the addresses of the proxies allowed to serve it, which for a proxy on the same machine is 127.0.0.1. Until both are set, a request that arrives through a proxy is refused with Forbidden: ShaWeR is only for the browser of this computer, never through a proxy.
Point the proxy at the internal address, which SHAWER STATUS; prints. With ShawerPort=9369 and the Instance ID C6MVER39XDZS9KT7, a complete Nginx server block is:
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name www.example.com;
ssl_certificate /etc/letsencrypt/live/www.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/www.example.com/privkey.pem;
# the address without its final slash, so that both forms work
location = /broadsql {
return 301 https://$host/broadsql/;
}
location /broadsql/ {
# the final slash on both sides replaces /broadsql/ with the instance path
proxy_pass http://127.0.0.1:9369/C6MVER39XDZS9KT7/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $remote_addr;
# Desk keeps a request open while a statement runs
proxy_read_timeout 300s;
proxy_buffering off;
client_max_body_size 16m;
}
}
Four lines matter, and the rest is ordinary Nginx:
- The final slash on both sides of
proxy_passis what replaces the public path with the instance path. Without it, Nginx forwards/broadsql/...unchanged and ShaWeR answersNot found. Host $hostsends the public name. ShaWeR serves the public address only to a request whose host is the one inShawerPublicUrland whose proxy is inShawerTrustedProxies.X-Forwarded-Proto $schemetells ShaWeR that the browser is on HTTPS, so the session cookie is markedSecure.X-Forwarded-For $remote_addrtells ShaWeR which computer is signing in, so a wrong password is counted against that computer and not against the proxy.
Then check and reload Nginx (sudo nginx -t, then sudo systemctl reload nginx), create a user if you have none (SHAWER USER ADD alice;), and open https://www.example.com/broadsql/. Nothing has to be typed in the console again, and the address stays the same across restarts of ShaWeR and of BroadSQL.
What this changes, and what it does not. Everything that protects ShaWeR on your own computer still applies through the proxy: the password, two-factor authentication, the session lifetimes, the lock after failed sign-ins, the request token of every page, and the refusal of requests coming from another site. What changes is who can reach the sign-in page: anybody who can reach your proxy. Before you open it, give every user a strong password, set ShawerTotp=REQUIRED so that a password alone is never enough, keep the certificate valid, and restrict the proxy itself when the address is not meant for the whole internet. ShawerBindAddress still refuses to leave 127.0.0.1, so ShaWeR itself is never on a network interface: the proxy is the only way in, and you control it.
HTTPS
Without HTTPS, traffic stays on your computer but is not encrypted. To encrypt it:
- Put a certificate in a PKCS12 (or JKS) file.
- Set
ShawerProtocol=HTTPSandShawerKeystore=<the file>. - Store the file's password once:
SHAWER TLS PASSWORD;(asked at a hidden prompt).SHAWER TLS CLEAR;removes it. SHAWER STOP;thenSHAWER START;.
Only TLS 1.2 and 1.3 are offered. These settings encrypt the connection to 127.0.0.1 on this computer. To serve ShaWeR to other computers, do not open its port: use a reverse proxy, as in Reaching ShaWeR from another computer, and let the proxy hold the certificate.
Security notes
- After
ShawerMaxFailedLoginsfailures in a row, a user is locked forShawerLockoutMinutes. A computer that fails 20 times in 10 minutes is made to wait. The sign-in page gives the same answer whether the user exists or not. - Passwords are stored as salted PBKDF2 verifiers. Two-factor secrets and recovery codes are protected by the encryption of the Connections Definition File: keep your master password strong.
- Anyone who can use your BroadSQL console can manage ShaWeR users and open Desk with a console link. Lock your computer when you leave it.
Commands
| Command | Action |
|---|---|
SHAWER; or SHAWER STATUS; | Shows whether ShaWeR runs, where, its versions, the web extensions it serves or refused, and the open sessions. |
SHAWER START; | Opens the port and shows the address. A second SHAWER START; changes nothing. |
SHAWER STOP; | Ends every browser session, stops the web extensions and closes the port. |
SHAWER USER ADD <name> [ADMIN]; | Creates a user; the password is asked twice. |
SHAWER USER LIST; | Lists users, role, two-factor state and lock. |
SHAWER USER PASSWORD <name>; | Changes a password; ends that user's sessions. |
SHAWER USER REMOVE <name>; | Removes a user; ends their sessions. |
SHAWER USER UNLOCK <name>; | Lifts a lock. |
SHAWER USER TOTP <name>; | Starts a two-factor enrolment. |
SHAWER USER TOTP CONFIRM <name> <code>; | Turns two-factor authentication on; prints eight recovery codes once. |
SHAWER USER TOTP RESET <name>; | Turns two-factor authentication off; forgets the secret and recovery codes. |
SHAWER SESSIONS; | Shows how many browser sessions are open. |
SHAWER SESSIONS REVOKE [<name>]; | Ends all browser sessions, or one user's. |
SHAWER TLS PASSWORD; | Stores the certificate password in the Connections Definition File. |
SHAWER TLS CLEAR; | Removes it. |
Words are not case sensitive. SHAWER cannot be typed in Desk: it asks for passwords and controls the server that shows Desk.
Licence
ShaWeR is free of charge and requires no licence. It is a shared component used by UpAndCoding extensions for BroadSQL.
Troubleshooting
| Problem | Action |
|---|---|
SHAWER is an unknown command | Check that extensions/broadsql-shawer.jar exists, then run SHOW EXTENSION ERRORS;. |
port ... is already used by another program | Set another ShawerPort, then SHAWER START;. |
... is not a loopback address | Set ShawerBindAddress to 127.0.0.1, or remove it. |
| HTTPS does not start | The message names the cause: no ShawerKeystore, a missing file, no stored password (SHAWER TLS PASSWORD;) or a wrong one. |
No ShaWeR user exists | SHAWER USER ADD <name>; |
Sign-in failed | Wrong user, password or code, a code already used, a clock more than 30 seconds off, or a locked user: SHAWER USER LIST; shows locks, SHAWER USER UNLOCK <name>; lifts one. |
Too many failed sign-ins from this computer | Wait ten minutes. |
Sign-in is not available: the BroadSQL console is locked | Enter the master password in the console. |
Two-factor authentication is required and not set up | SHAWER USER TOTP <name>; then SHAWER USER TOTP CONFIRM <name> <code>;. |
| Device lost, or no recovery code left | SHAWER USER TOTP RESET <name>;, then enrol again. |
| An extension is listed as refused | SHAWER STATUS; gives the reason: a Web API version this ShaWeR does not provide, a name already used, or a damaged JAR. Other extensions are not affected. |
| The session ended | One hour without an action by default, 12 hours at most, or the console needed its master password again. Sign in again. |
| BroadSQL runs on a Linux server, over SSH | 127.0.0.1 is that server, not your computer: a browser on your computer cannot open the address as is. Either forward the port through SSH, for example ssh -L 8080:127.0.0.1:8080 user@server with ShawerPort=8080, then open the address on your computer, or serve a stable public address through a reverse proxy: Reaching ShaWeR from another computer. ShaWeR keeps listening on the server's loopback only either way. |
Forbidden: ShaWeR is only for the browser of this computer, never through a proxy. | Set both ShawerPublicUrl and ShawerTrustedProxies, then SHAWER STOP; and SHAWER START;. SHAWER STATUS; lists the trusted addresses it is using. |
Forbidden: this address is only served as 127.0.0.1 or localhost through the proxy | The host the proxy sends is not the host of ShawerPublicUrl. Check proxy_set_header Host $host;, and that the name, and the port when there is one, match the setting exactly. |
Not found through the proxy | proxy_pass is missing the instance path or a final slash. It must end with /<Instance ID>/, and the location must end with a slash too. |
| Through the proxy the pages load but the buttons do nothing | The links are built for ShawerPublicUrl: check that it is the address people actually type, path included. Sign out and in again after changing it. |
| Signing in through the proxy works, then every page asks to sign in again | The cookie is marked Secure when the proxy reports HTTPS, so it is sent over HTTPS only. Serve the public address over HTTPS, or set ShawerPublicUrl to the http:// address you really use. |
| The address changes at every start | This installation has no Instance ID. SHAWER START; says so; check the InstanceId setting of conf/broadsql.ini. |
A WARNING about a Shawer... setting | That setting is invalid or no longer used, so its default was applied: the message names it and what it accepts. Correct it in conf/broadsql.ini, then SHAWER STOP; and SHAWER START;. A command that starts ShaWeR for you, such as DESK, shows these warnings too; SHAWER STATUS; lists them at any time. |
Found something wrong or unclear on this page? Tell us, with the page address.