# Sign in

---

# Sign in

_Peios / Using Peios / Sign in_

> Choose a browser, local console or SSH sign-in route, change your own password, and find help when access fails.

Choose the sign-in route available on your machine. If you have just installed
Peios, complete [first-boot setup](/peios/using-peios/disks-and-filesystems/first-boot-setup.md)
first. Manual and legacy installation routes can provision accounts differently;
[Creating accounts](/peios/using-peios/managing-local-principals/creating-accounts.md#where-the-first-account-comes-from)
explains those distinctions.

## Choose how to connect

- **Use the desktop in a browser:** [Open the desktop](/peios/using-peios/signing-in-from-a-browser/open-the-desktop.md).
  Check the machine's [certificate](/peios/using-peios/signing-in-from-a-browser/the-certificate.md)
  before entering credentials.
- **Use a local console:** [The login command](/peios/using-peios/signing-in/the-login-command.md)
  explains the prompt, live-medium autologon and multiple-console behavior.
  Switching consoles does not lock or log out the session you leave.
- **Use a remote terminal:** [Sign in over SSH](/peios/using-peios/signing-in/signing-in-over-ssh.md).
  Verify the host fingerprint and read the access precautions before changing
  the SSH service or credential policy.

## Manage your own account

Use [passwd](/peios/using-peios/signing-in/the-passwd-command.md) to change your own password.
For your SSH keys, follow [Changing your own keys](/peios/using-peios/managing-local-principals/lps-command.md#changing-your-own-keys).
To change the name shown beside your account name, follow [Changing your own display name](/peios/using-peios/managing-local-principals/lps-command.md#changing-your-own-display-name).
Changing another account's credentials is an administration task; start with
[Manage local accounts and groups](/peios/using-peios/managing-local-principals/overview.md).

A stored password and the account's credential policy are separate. Follow
[Creating accounts](/peios/using-peios/managing-local-principals/creating-accounts.md) when
changing whether a password or SSH key is required; setting a password alone
does not change a passwordless account's policy.

## If sign-in fails

Start with [Troubleshoot a problem](/peios/using-peios/operating-peios/troubleshoot-a-problem.md#sign-in-is-refused).
Keep a working administrator route available while investigating. Do not delete
the local principal store to try to restore access: it holds the machine's
identity, and a corrupt store is different from a missing one. See
[The local store](/peios/security-fundamentals/authentication/the-local-store.md#missing-versus-corrupt).

For the model behind the prompts, read [How authentication works](/peios/security-fundamentals/authentication/overview.md)
and [Logon sessions](/peios/security-fundamentals/logon-sessions/overview.md) in Security Fundamentals.

---

# The login command

_Peios / Using Peios / Sign in_

> login is the terminal client for PGSS Logon — it collects an identifier and whatever credentials the authority asks for, and starts your shell.

`login` is the terminal client for [signing in](/peios/security-fundamentals/authentication/overview.md). It collects an identifier, renders whatever credential prompts the authority sends, installs the token it is granted, and replaces itself with your shell.

```
login [name] [options]
login --try <name> [options]
login --try-no-password <name> [options]
```

It does not know what a password is. It renders the prompts it is asked to render and returns the answers, so adding a new credential type — a one-time code, a smartcard — changes the authority and leaves `login` alone.

## Naming a principal, or not

With no name, `login` asks for one:

```
Username: alice
Logging in as alice
Password:
```

With a name, the first prompt is skipped. The `Logging in as` line comes from the authority rather than from `login`, so it will gain a realm once authorities have them.

A principal who needs no credential is signed in immediately, with no prompt at all — see [passwordless accounts](/peios/using-peios/managing-local-principals/creating-accounts.md).

## `--try` and `--try-no-password`

Both attempt a named principal and fall back to an ordinary prompt rather than failing. They differ in what they offer to collect.

**`--try <name>`** attempts the principal with `login`'s full capabilities. A principal whose policy requires no credential is signed in immediately; one whose policy calls for a password is prompted for it.

**`--try-no-password <name>`** attempts the principal while declaring that it can collect nothing, so only a principal who needs no credential can succeed. This is what a console autologon uses.

Neither flag asserts that anyone is authenticated. The authority still decides, and understating what you can collect only denies you prompts you could have rendered — so running either by hand gains you nothing you did not already have.

The first two columns below describe credential policy, not just whether a password is stored. They assume an enabled account with console logon permitted and, for password sign-in, a password set.

| | No credential required | Password required | No such principal |
|---|---|---|---|
| `login alice` | signed in | prompts | `user alice does not exist` |
| `login --try alice` | signed in | prompts, then falls back if wrong | falls back silently |
| `login --try-no-password alice` | signed in | falls back silently | falls back silently |

A fallback restarts the sign-in from `Username:`, so you are never locked to the principal that was attempted.

### When a fallback explains itself

`login` says why it fell back only if something was already on your terminal.

A `--try` that reached a password prompt has interrupted you, and dropping to `Username:` without a word would read as a fault — you typed a password and got asked for a name. So it reports first:

```
$ login --try alice
Logging in as alice
Password:
login: Password incorrect
Username:
```

A `--try-no-password` that was refused before anything was rendered has interrupted nobody, and stays quiet. That is what keeps a line about a failed autologon off the console of every machine where the principal requires a credential.

Falling back is limited to denials another principal could survive. A failure of the authority itself is reported and `login` exits, because offering a prompt that cannot work either would spin a console.

### Where existence is checked

`login` asks `/run/ident.sock` whether a principal exists, not the logon socket. The logon socket will not tell it — an authority never distinguishes an unknown principal from a bad credential — while the identity socket answers plainly, which is what it is for.

If that lookup cannot be answered, `login` attempts the sign-in anyway rather than reporting an absence. An unreachable source reported as "no such user" would turn an outage into a fact.

## Autologon on a console

A console that signs in on its own is a passwordless principal plus `--try-no-password`. On a live image, `peinit` starts:

```
/bin/login --console --try-no-password peios
```

The same service definition suits an image where `peios` requires a password: the attempt is refused before anything is rendered, and an ordinary prompt appears. No second seed, and no conditional configuration.

To require a password instead of autologon, first set the principal's password with [`lps password`](/peios/using-peios/managing-local-principals/lps-command.md), then select `lps policy <name> password`. Setting the password alone leaves the `none` credential policy and autologon unchanged.

Taking `--try-no-password` out of the `login-console` service's `Arguments` stops the automatic attempt, but does not change the account's credential policy: a principal whose policy is still `none` can still sign in at that prompt without a credential. To move the prompt to another terminal, change the service's `TTYPath` — see [controlling services](/peios/using-peios/services-and-jobs/controlling-services.md).

**System Settings** chooses it in its **Startup & Shutdown** section, under **Console Sign-In**: **Automatic Sign-In** is **Off**, or one of the local accounts. The choice is written the moment it is made, as `Arguments`: `--console`, followed by `--try-no-password` and the account if one is chosen. It applies the next time `login-console` starts, at the latest the next boot. Changing it needs write access to `Machine\System\Services\login-console`, which as shipped only Administrators have.

## GXWI information on the console

Managed `login --console` sessions show GXWI's browser address and certificate
SHA-256 fingerprint before authentication when GXWI is installed. Compare the
fingerprint on this trusted local console with the browser's certificate
details before accepting its warning. See [the machine's certificate](/peios/using-peios/signing-in-from-a-browser/the-certificate.md).

The banner reads `/var/state/gxwi/certificate.sha256` and the configured
`Machine\Software\GXWI\Listen` address and port. With the IPv4 wildcard
listener Peios ships (`0.0.0.0:7780`), it lists the machine's active
non-loopback IPv4 addresses. If the value is missing or unreadable, the
banner shows GXWI's own fallback, the loopback address `127.0.0.1:7780`. An IPv6
wildcard lists IPv6 addresses; link-local addresses that need an interface zone
are omitted. A specific listen address is displayed as configured. This is
connection information, not a check that GXWI is currently running.

Information is read once each time login starts. Missing or malformed
fingerprints and unavailable addresses are reported without preventing login.
Ordinary `login` invocations without `--console` do not show this banner.

## Options

| Option | Effect |
|---|---|
| `--try <name>` | Attempt `name`, falling back to a full prompt. |
| `--try-no-password <name>` | Attempt `name` collecting nothing, falling back to a full prompt. |
| `--console` | Reset terminal input, wait for first-boot setup to finish, and show available GXWI connection information before collecting credentials. Serial speed is preserved; setup-registry errors prevent logon. |
| `-p` | Keep the inherited environment instead of building a fresh one. |
| `-h <host>` | Record the remote peer for a sign-in originated on its behalf. Unverified. |
| `-H` | Accepted and ignored. Suppresses the hostname banner on other systems. |
| `--` | Treat everything after as a name, not an option. |

`-f` is **not** implemented. On Linux it means "trust me, they are already authenticated", gated only by the caller being root. On Peios that decision belongs to the authority, taken from the verified peer, so accepting a flag here would put an authentication bypass in an unprivileged process.

## The environment your shell starts in

Without `-p`, `login` builds a fresh environment: `HOME`, `SHELL`, `USER`, `LOGNAME`, `PATH=/bin`, and `TERM`. The shell's `argv[0]` gets a leading dash, which every shell reads as "this is a login shell, run the profile files".

`TERM` is carried through if `login` was started with one. Otherwise `login` decides it from the terminal it is on, the way a getty does elsewhere: `linux` on a virtual console (`/dev/tty1` and its siblings, the display), `vt220` on anything else (a serial line, a hypervisor's paravirtual console). `/dev/console` is whichever of those the kernel chose, and `login` resolves it through the kernel's own record of the active console rather than guessing, so one service definition on `/dev/console` gets the right answer on a machine with a display and on one without.

The home directory comes from the profile the authority sent, and **a missing one is not fatal**. `login` reports it and starts you in `/`. Refusing to proceed over an absent directory would turn a cosmetic problem into being locked out.

`login` does not create it. Two reasons, and either would be enough. It has already made your token its own by the time it changes directory, so it is you rather than the system — and `/home` lets you walk through it but not create in it. And directory provisioning has no business inside the one program that has to keep working when everything else is broken. The authority creates the directory when it grants the logon, before `login` is handed anything; reaching this fallback means the authority named no home, or could not make one.

## Exit status

`login` does not return on success — it replaces itself with your shell, so what you see afterwards is the shell's exit status.

| Code | Meaning |
|---|---|
| `1` | A usage error, a denied sign-in, or the shell could not be started. |

## Multiple local consoles

The Experimental edition provides independent login sessions on `tty1`, `tty2`
and `tty3`. Switch between them with Alt+F1, Alt+F2 and Alt+F3 at a text console,
or use `chvt 1`, `chvt 2` and `chvt 3` with the required console authority.
Switching does **not** lock or log out the session you leave.

`login-console` follows the kernel's primary console: peinit resolves a display
console to the fixed `tty1`, or uses the selected serial/paravirtual terminal.
It retains the live-medium passwordless `peios` attempt. Additional services
`login-tty1`, `login-tty2` and `login-tty3` show ordinary username prompts. On a
display-primary machine, the duplicate `login-tty1` service is skipped because
`login-console` already owns that terminal. On a serial-primary machine all
three local prompts can run alongside the serial session. Missing terminals
are skipped.

First-boot setup retains the primary console. Additional terminals wait until
both setup service definitions have been removed; they collect no credentials
while setup is pending. Logging out terminates that terminal service's remaining
processes and produces a fresh prompt with canonical input and echo restored.
A normal logout does not consume the crash-restart budget. This resets terminal
input settings; it does not implement a session lock or promise to erase all
screen history.

---

# The passwd command

_Peios / Using Peios / Sign in_

> passwd changes your own password — the authority proves your current password and sets the new one with whichever principal source holds your account.

`passwd` changes your own password.

```
passwd
```

It takes no arguments. The account it changes is the one you are signed in as: the authority reads it from your token, and the request has no field in which to name anybody else. To set another principal's password, an administrator uses [`lps password`](/peios/using-peios/managing-local-principals/lps-command.md).

## What it asks

```
$ passwd
Changing the password for alice
Current password:
New password:
Retype new password:
password changed
```

Your current password is always asked for, even though you are signed in. Being signed in shows that someone authenticated as you; it does not show that the person at the keyboard now is you, and a password changed from an unattended terminal could not be recovered by signing in again.

If the new password and its confirmation differ, or the new one is empty, you are told why and asked again. After three attempts the change ends with the password unchanged.

The prompts come from the principal source that holds your account, not from `passwd`. `passwd` renders what it is asked and returns the answers, so a source with different requirements asks for what it needs without `passwd` changing.

## How it works

`passwd` opens a credential-change conversation with the authority on `/run/logon.sock` ([PGSS §2.20](/peios/advanced-peios/pgss/logon/credential-change.md)). `authd` finds the source that holds your account from your token's SID and relays the conversation to it. `lpsd` checks your current password, sets the new one, and writes its store to disk before it reports success, so `password changed` means the next sign-in checks the new password. It records the change as an `lpsd.credential.changed` event, naming your account by SID, and records a refused change the same way with the reason, such as `wrong-credential` for a current password that did not verify.

Nothing is minted. Your current session carries on as it was, and so does every other session you hold.

## Other ways to change it

`passwd` is one client of this conversation, not the only one. A program can hold the same conversation for you. On the desktop, **My Settings** (type `my` in the launcher) does: its **Password** section collects your current password and the new one twice, and hands them over when the authority asks. The line along the bottom of the window shows what the authority said, then whether the password changed, and the fields are emptied whatever happened. An account with no password sees why in place of the form. The authority asks the same questions, applies the same rules and gives the same refusals whichever program asks; only how the questions are shown differs. A program written in Rust gets the conversation from the `credential` module of `libauthd-client`, which `passwd` itself uses.

Adding or removing your own SSH keys is a sibling conversation on the same socket, and asks for your current password the same way: see [Changing your own keys](/peios/using-peios/managing-local-principals/lps-command.md#changing-your-own-keys).

## From a script

When standard input is not a terminal, `passwd` prints no prompts and reads one line for each, in order:

```
printf '%s\n' "$current" "$new" "$new" | passwd
```

## When it refuses

| Message | Meaning |
|---|---|
| `Authentication failed.` | The current password was wrong, or the password was reset by an administrator while you were changing it. |
| `This account has no password to change. …` | The account has no password available for this change, or exists only to run a service. For an ordinary account, an administrator can set a password with `lps password` and select a policy that allows it with `lps policy`. A service principal cannot be given a credential. |
| `This account is disabled.` | An administrator has disabled the account. |
| `This account has no credential that can be changed here.` | You are signed in as an identity that no principal source holds, such as `SYSTEM`. |
| `Too many attempts. The password is unchanged.` | The new password was refused three times. |
| `cannot reach the authority …` | `authd` is not running. |
| `permission denied connecting to /run/logon.sock …` | This machine's logon socket does not admit you. See below. |

A message ending `whether the password changed is not known` means the authority went away after the change was asked for and before it said how it ended. Sign in with each password to find out which one holds.

## Who can reach the socket

Every authenticated principal can connect to `/run/logon.sock` so that `passwd` works for them. That does not let them originate a logon for anybody else, which still takes a `LogonTypes` record on their own policy entry.

A machine whose administrator has replaced the socket's descriptor with `LogonSocketDescriptor` may not admit you. See [assigning privileges](/peios/using-peios/managing-local-principals/assigning-privileges.md).

## Exit status

| Code | Meaning |
|---|---|
| 0 | The password was changed. |
| 1 | The change was refused or failed, or the authority could not be reached. |
| 2 | The command line was wrong. |

## See also

- [How authentication works](/peios/security-fundamentals/authentication/overview.md) — the conversation this is one kind of.
- [The `lps` command](/peios/using-peios/managing-local-principals/lps-command.md) — setting another principal's password, as an administrator.
- [PGSS §2.20](/peios/advanced-peios/pgss/logon/credential-change.md) — the credential-change conversation, specified.

---

# Signing in over SSH

_Peios / Using Peios / Sign in_

> Verify a first SSH connection, preserve administrator access when disabling SSH passwords, and manage the server, port and host key with ssh-settings or SSH Settings.

The SSH server lets people sign in to this machine from another over the network, with their password or one of their SSH keys. It is the `sshd` service, from the `dev.peios.openssh` package. Every SSH sign-in is a `RemoteInteractive` logon through the same authority as any other: see [How authentication works](/peios/security-fundamentals/authentication/overview.md).

That includes commands without a PTY and SFTP: the account must permit `remote-interactive`, not just `network`. An account with credential policy `none` cannot sign in over SSH. Password authentication requires an actual password and a policy allowing it; key authentication requires an enrolled key and a policy of `key` or `either`. The [SSH implementation contract](/peios/advanced-peios/pgss/logon/ssh-public-key-authentication.md) records the release-qualification and compatible-build requirements.

Four things about the server are settings:

| Setting | Where it is | Shipped as |
|---|---|---|
| Whether it runs | the `sshd` service's `Disabled` value | on, on images that include the service |
| Its port | `Machine\Software\OpenSSH` `Port` (`REG_DWORD`) | 22 |
| Whether it accepts passwords | `Machine\Software\OpenSSH` `PasswordAuthentication` (`REG_DWORD`, 0 or 1) | 1 |
| Its host key | `/var/state/sshd/ssh_host_ed25519_key`, made on first start | — |

The port and password sign-in are machine policy in the registry, not lines of `sshd_config`. `start-sshd` reads them each time the service starts and gives them to `sshd` on its command line, and a `Port` or `PasswordAuthentication` line in `/lcl/etc/ssh/sshd_config` has no effect. Other `sshd` options still go in that file.

Change them with **`ssh-settings`** on a terminal, or **SSH Settings** on the desktop (type `ssh` in the launcher), which is the same program and does the same things.

## Looking

```
$ ssh-settings
server       running
port         22
passwords    accepted
host key     SHA256:Wm3…
```

Anyone may look, except at the host key, which only SYSTEM and Administrators may read; others see why instead.

## Connect from another computer

1. From a trusted administrator session on the Peios console, or a [certificate-verified GXWI session](/peios/using-peios/signing-in-from-a-browser/the-certificate.md) as an administrator, read the machine's address, SSH service state, port and host fingerprint:

   ```
   net status
   ssh-settings
   ssh-settings fingerprint
   ```

   Check that the server is running. Choose an address on an interface reachable from the other computer; [Reading `net status`](/peios/using-peios/networking/the-net-command.md#reading-net-status) explains the interface blocks. For a direct connection, use the port shown by `ssh-settings`, which is 22 as shipped. The QEMU Makefile's host-forwarded port 2222 is a separate route described in the [build quick start](/peios/peiso/building-images/quick-start.md#open-the-web-desktop).

2. On the other computer, use your account name, the machine's address and that observed port:

   ```
   ssh -p <observed-port> <name>@<machine-address>
   ```

   Before accepting a first-connection prompt, compare its SSH host fingerprint with the trusted reading from step 1. This is the SSH host key, not GXWI's TLS certificate fingerprint. If they differ, stop and investigate; do not accept the key or discard a remembered key just to suppress a warning.

3. Sign in with the intended password or enrolled key and check that a **new shell opens**. A running service or an already-open session alone does not prove that a new sign-in works.

## Turning it on and off

```
ssh-settings on
ssh-settings off
```

`on` sets the service to start at boot and starts it now; `off` stops it and keeps it from starting. People signed in over SSH are disconnected when it stops. Each needs write access to the service's key, `Machine\System\Services\sshd`, and the right to start and stop `sshd`, which as shipped only Administrators have; see [who can manage a service](/peios/using-peios/services-and-jobs/who-can-manage-a-service.md). Without the second, the setting is still saved and takes effect at the next boot, and you are told so.

## Moving the port

```
ssh-settings port 2222
```

A port is three things that must agree, and `ssh-settings` changes all three in one registry transaction, so none is ever moved without the others:

- the `Port` value;
- `sshd`'s **port reservation**, the descriptor under `Machine\System\Network\TcpIp\PortReservations` that lets only `sshd` bind the port (see [port reservations](/peios/advanced-peios/peios-kernel/kacs/network-objects/port-reservations.md));
- the `ssh` firewall rule, `Machine\System\Network\Rules\Flow\ssh`, whose `DstPort.Equal` is the port let in (see [network policy](/peios/using-peios/networking/network-policy.md)).

It then restarts `sshd` onto the new port, which disconnects everyone signed in over SSH, you too if you are. Connect again on the new port: `ssh -p 2222 alice@host`.

A port another program has reserved is refused: a reservation naming that one port and nothing else, such as `tcp:80` for a web server, makes it that program's. A wider range that contains the port, such as `tcp:1-1023`, is fine, since reservations nest. Moving the port needs write access to all three keys, which as shipped only Administrators have.

## Keys only

`ssh-settings passwords off` disables password authentication **for SSH**. It does not require an account-wide policy of `key`. Keep the account policy `either` when its password must also work through GXWI: [GXWI does not currently offer SSH-key authentication](/peios/peiso/building-images/quick-start.md#open-the-web-desktop), so a `key`-only account cannot use that sign-in path.

With SSH passwords off, an account whose policy is `password` cannot sign in over SSH, though it can still use its password at the console and on the desktop, subject to its other sign-in restrictions.

Before changing the server:

1. Enroll a key for each person who needs SSH. They can use My Settings where permitted, or an administrator can use [`lps key add <name> <public-key-file> [label]`](/peios/using-peios/managing-local-principals/lps-command.md#credentials-and-ssh-keys). Adding a key does not change credential policy. For a password-enabled account that will also use keys, an administrator sets `lps policy <name> either`; retain that policy if GXWI password access is needed.
2. Inspect `lps show <name>` and `lps key list <name>` to check the enabled account, enrolled key, credential policy and permitted `remote-interactive` logon type. While SSH passwords are still available, make a **fresh SSH connection that actually authenticates with the enrolled key**, following the host-key check above. A connection that falls back to a password does not count as a key test. If the key test fails, stop before disabling passwords and check those account settings and the service state.
3. Verify a fresh administrator sign-in through a separate **non-SSH** route, such as the local console or certificate-verified GXWI, and keep that route available. The [last-administrator guard](/peios/using-peios/managing-local-principals/creating-accounts.md#the-last-administrator-guard) does not prove that a usable route exists. Keeping another SSH session open is insufficient: this change restarts `sshd` and ends **every SSH session**.

Only after both access paths work, disable SSH passwords:

```
ssh-settings passwords off
```

Then make another new key-authenticated SSH connection and verify that its shell opens. If it fails, use the surviving console or GXWI administrator route to inspect the settings and restore SSH password acceptance with `ssh-settings passwords on`. This reversal also restarts `sshd`; it does not change account credential policy. Keep the separate administration route until fresh SSH access has been verified again.

## The host key

```
ssh-settings fingerprint
```

The first time someone connects, their SSH client shows the server's host key fingerprint and asks whether to trust it. Compare it with this one, read on the machine itself or by someone you trust who can read it, before answering yes. The key is made on the server's first start and never replaced automatically.

## On the desktop

SSH Settings shows the same four things on one page: the server, with how it is and a switch to turn it on or off; **Port**, with **Apply** once it is changed; **Password Authentication**, as a switch; and **Host Key Fingerprint**, with **Copy**. Turning the server on happens at once. Anything that restarts or stops it — turning it off, moving the port, password sign-in either way — ends every SSH session, so it asks first, under its row, and changes nothing until it is told to go ahead. What you may not change is shown read-only, with the reason, once. Each change says what it did along the bottom of the window, including whether `sshd` was restarted.

## Exit status

| Code | Meaning |
|---|---|
| 0 | Done, or shown. |
| 1 | The change was refused or failed; the reason is printed. |
| 64 | The command line was wrong. |