Signing In from a Browser

The Peios desktop runs on the Peios machine and is displayed in your browser. To open it, you need the machine's address, the port it is configured to listen on, and an account on that machine.

If you have just installed Peios with the graphical or text installer, complete First-boot setup first. On a live installation medium, follow Install on a PC instead: the installer and its temporary account are different from a normal sign-in.

1. Open the machine's address #

Open https://<machine-address>:7780, replacing <machine-address> with the machine's address or name. Use the configured port if an administrator changed it.

The desktop service, GXWI, serves HTTPS only. An HTTP request is redirected to HTTPS; it does not serve an unencrypted desktop.

2. Verify the certificate before entering credentials #

Each machine creates its own certificate. A browser does not initially know whether to trust it, so a warning on first use is expected.

Follow The machine's certificate to compare the browser's SHA-256 fingerprint with the fingerprint shown at the machine's own console. Do not use a page received over the connection you are trying to verify as the source of that fingerprint. If the fingerprints differ, do not sign in.

That guide also explains importing the certificate, name mismatches, renewal and why a live medium presents a new certificate after each boot.

3. Sign in and choose your task #

Sign in with an account on this machine. The desktop and its tools use that account's authority; machine-wide changes may require an administrator account or specifically delegated access.

• Desktop Settings changes your wallpaper, clock, dock, shortcuts and default applications.
• Manage the machine points to software, services, accounts, networking and storage tasks.
• Troubleshoot a problem covers reachability, refused sign-in and missing records.

If the machine shows an installation or setup overlay instead of a sign-in screen, follow that flow's guide. While an overlay is configured, normal sign-in and desktops are unavailable.

GXWI replaces Atrium #

GXWI completely replaces Atrium. Use the HTTPS connection and certificate verification steps above; the old Atrium connection and application instructions are retired.

The desktop is reached in a browser at https:// and the machine's address, port 7780 unless an administrator has chosen another. GXWI serves it over HTTPS alone, with a certificate the machine made for itself the first time GXWI started. No certificate authority has vouched for it, so a browser warns the first time it is opened, until it is told to trust it.

Opening http:// instead is answered with a redirect to the same address under https://, and with nothing else: no page is ever served without encryption.

Check the fingerprint before going past the warning #

The warning is the browser saying it cannot tell this certificate from one someone between you and the machine made up. You can: every certificate has a SHA-256 fingerprint, and the machine shows you its own.

The managed console login banner shows the fingerprint before sign-in when GXWI has made its certificate. Read it on the machine's own trusted console. If the banner says it is unavailable, or to read the current fingerprint after renewal, sign in locally and print the public file, which any account may read:

$ cat /var/state/gxwi/certificate.sha256
B8:39:98:AB:E7:F6:64:25:BC:0D:DE:56:F4:78:2E:21:3D:D8:AB:FF:EF:78:8A:81:6E:94:99:17:94:83:73:C3

Read it there, and not from a page in the browser: a page that came over the connection you are checking would show whatever someone in the middle of it wanted. Once you trust the connection, a terminal on the desktop reads the same file.

In the browser, open the warning's details and view the certificate. Its SHA-256 fingerprint is the same 32 pairs of hex digits, though some browsers separate them with spaces rather than colons. If the two match, the connection is to this machine and nobody can read it on the way. If they do not, do not sign in.

Firefox may still describe a connection with a certificate exception as insecure, even when it uses TLS. That label alone does not establish whether the traffic is encrypted or whether the peer is the right machine. Check the presented certificate against the console fingerprint as above. Importing the verified certificate establishes trust in it; name and validity checks still apply.

Trust the verified certificate #

The certificate is in /var/state/gxwi/certificate.pem, also readable by anyone. After checking its fingerprint through the trusted console, copy it to the device you browse from and add it to that browser's or system's trusted certificates. This establishes trust in that certificate; it does not remove name-mismatch, expiry or other certificate warnings.

The reviewed certificate generator includes the machine name at creation, localhost, and the loopback addresses 127.0.0.1 and ::1. It does not include the machine's other network addresses. An existing certificate may have been generated by an earlier version or under an earlier machine name: inspect the certificate actually presented. Trusting it does not make an address or name absent from that certificate valid.

An imported certificate lasts until the machine renews it, once a year (see Renewal): import the new one then.

A certificate only gone past at the warning, not imported, also costs the waiting page: GXWI keeps a page in the browser that it shows while the machine is restarting or cannot be reached, and a browser keeps such a page only for a certificate it trusts. Without it, a tab left open while the machine restarts shows the browser's own error, and loads again by hand.

No HSTS #

GXWI deliberately sends no Strict-Transport-Security header. HSTS tells a browser to refuse any certificate warning for the site from then on, which with a certificate of the machine's own making would leave nobody a way past the first warning, including after the machine's key changes.

Where the key is kept #

GXWI makes the key once and keeps it. It never replaces a key it cannot read: it stops, and says so. Move the files aside to have a new key made; every browser that trusted the old certificate then warns again.

Renewal #

A certificate lasts a year, from the day before it was made. GXWI renews it once fewer than 30 days of it remain, for the same key: the machine is the same machine, but the certificate, and so its fingerprint, is new. Each renewal means one more warning in every browser that went past the old one, and importing the new certificate.pem again for anyone who imported the old. Check the new fingerprint as you did the first.

Renewal uses the machine's current hostname for the certificate's common name and DNS name, alongside localhost, 127.0.0.1 and ::1. A machine rename is therefore picked up at the next renewal; renaming alone does not renew a certificate that is still within its normal lifetime.

GXWI looks when it starts, once a day while it runs, and when it is reloaded:

$ svctl reload gxwid

Nothing restarts, and nobody signed in is signed out. Connections already open carry on; the next one the browser makes is shown the new certificate. A renewal is recorded as the event gxwid.certificate.renewed, which carries the old and new fingerprints.

Installation and first boot #

On a live medium /var/state is in memory, so every boot makes a new key and the warning comes back each time. installerd attempts to carry that key and certificate into the installed system, whether you use its console or browser surface. In the reviewed installer, an absent key skips the transfer and a copy failure is logged without failing the installation. The installation continues, so its completion message does not prove certificate continuity. A failed copy can leave partial state; it does not guarantee a clean new identity or working HTTPS on the next boot.

If the installed system presents the same verified certificate, existing trust may continue subject to the browser and address checks above. If its fingerprint changes, verify it again through the installed machine's trusted console before entering credentials. If you cannot do that during first boot, complete setup on the console first, then verify before using browser sign-in. Follow First-boot setup.

The older peios-install script is a separate path: the installed system makes its own key when GXWI first starts. Do not infer its certificate behavior from installerd's transfer attempt.