Troubleshooting

“A licence is required”

The agent answers a licence is required: this server is in restricted mode to every command it refuses, in the app and after dev in a terminal. The app says the same thing in its own words: Licence required at launch or under Settings › Account, or a notice above the server’s screens. The cause is one of these.

• The organisation holds more servers than its free ones, and no licence. A licence expired, or was never granted. Ask for one at support@pupitre.studio, or delete servers in the console down to the free ones; then Refresh in the app. See licence.
• Another organisation is active. Your servers are on an organisation other than the one this computer works for. From the launch screen, Open the settings, then Servers › Your organizations, and Make active on the right one.
• The organisation is suspended by the platform. The console says why; write to support@pupitre.studio.
• The console has not answered for more than seven days. The app says so. Reconnect this computer, and the next answer clears it.

On the server itself, the dev commands read the enrolment and the licence from two files only root opens, and rerun themselves through sudo to get there. From an account whose sudo asks for a password, the command says so: type sudo dev <command>.

Restricted mode

A server goes into restricted mode when the platform answers that its organisation’s licence is suspended, when the server is deleted from the console, or when the agent has not reached the platform for seven days.

What still works: reading the server’s state, the diagnosis, updating the agent and migrating its configuration, enrolment, and a sync with the platform. Everything else is refused — installs, configuration changes, project actions, secrets. Nothing that already runs is stopped: services and projects keep going, and SSH as dev works as before.

It lifts on its own. The agent reads the platform every thirty seconds: once the licence is valid again, the next read gives the server back. When the organisation’s licence is valid and the server stays restricted anyway — it lost its token, for instance — the notice in the app offers Re-enrol this server: a fresh enrolment token reaches the agent, and nothing else on the machine is touched.

A licence that expires does not restrict anything at first: seven days of grace, then suspension. See licence.

fail2ban banned your own address

core.hardening writes this jail in /etc/fail2ban/jail.d/pupitre.local:

[sshd]
enabled = true
backend = systemd
port = 22
maxretry = 5
findtime = 10m
bantime = 1h

The port reads 22,443 when you asked for SSH on 443 as well. There is no ignoreip: your address is treated like any other. Five failed SSH attempts within ten minutes — a client still trying root after the hardening closed it, a script retrying in a loop — ban that address for an hour.

The symptom: from your network, ssh hangs or is refused and the app no longer reaches the server, while the server answers from anywhere else.

Wait the hour, or unban yourself from another address — another network, your phone’s connection:

sudo fail2ban-client status sshd
sudo fail2ban-client set sshd unbanip 203.0.113.7

The first command lists the banned addresses; yours is among them. The last way in is the console your host provides — VNC, serial, or rescue mode: it is not SSH, so neither fail2ban nor the SSH settings stand in the way.

To keep an address from ever being banned, do not edit pupitre.local: core.hardening writes it again the next time it is configured. Put the exception in a file of your own, then reload:

# /etc/fail2ban/jail.d/ignore.local
[sshd]
ignoreip = 127.0.0.1/8 ::1 203.0.113.7

sudo fail2ban-client reload

The sudo password of dev

As dev, sudo asks for a password for everything but pupitred serve and pupitred binary install. That password is in Settings › Servers, on the server’s card: Sudo password of dev, to show or copy, then paste when the terminal asks. The dev commands need none, except dev db dump, dev db import and dev backup now, for which sudo asks for it on the terminal.

The card says Not on this computer when you open it from another computer than the one that hardened the server, when the keychain was emptied, or on Linux without a keychain once the app has quit. The gestures that need the privileged session — installing, securing, restoring a backup, among others — do not go through until this computer has the password. The button beside it, Enter the sudo password of dev, asks for it: copy it from the app of a computer that keeps it, then Keep on this computer. The app keeps it only once sudo on the server has accepted it. Running the securing again from a computer without the password is not possible: it is itself a privileged gesture. A computer that keeps it can replace it by running the securing again.

Lost everywhere, set a new one from your host’s console, signed in as root, then enter it in the app:

passwd dev

An install step failed

A failed step stops its module, not the install: the other modules go on. The install screen names the module and the step it stopped at, and offers Try again — or Try the 3 services again when several failed. When other modules depend on the one that failed, the screen says so. You can also try again later from Services. Every step is idempotent: replaying runs what is left and changes nothing that is already in place.

A module marked installed, with a warning is installed; the warning names what to check.

On the server, the journal gives the command that replays a failed step:

sudo tail -n 50 /var/log/pupitre.log

Under the failed step, a line reads replay: sudo pupitred install --only=<module> — relance : when the install ran in French. The agent keeps the values and secrets the app sent for the install, so that command replays with the same configuration. Two more commands help:

• pupitred report prints the last install’s report, with the replay of each failed step;
• dev doctor runs a short diagnosis, and dev status shows what runs, the ports and the services.

The steps themselves are described in the onboarding, step by step.

The app ran into an error

When the app runs into an error it did not expect, it offers Relaunch: it reopens where it was, and the sessions on your servers keep running. What happened is written on your computer, in a file support will ask you for:

• macOS: ~/Library/Application Support/Pupitre/logs/main.log
• Windows: %APPDATA%\Pupitre\logs\main.log
• Linux: ~/.config/Pupitre/logs/main.log

The file keeps only errors, with no password or token, and the three before it alongside (main.1.log…). Attach it to your message to support.