diff --git a/docs/tinkering/factory-reset.md b/docs/tinkering/factory-reset.md deleted file mode 100644 index f56f6e6d..00000000 --- a/docs/tinkering/factory-reset.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -layout: default -title: Factory reset -parent: Tinkering -nav_order: 400 ---- -## Factory reset - -It is possible to reset various aspects the BitBoxBase to factory settings, either through the BitBoxApp (not implemented yet) or by creating a trigger file on the backup USB flashdrive. - -In case of a forgotten password (set in the BitBoxApp Setup Wizard), it can be reset as follows: - -* On the backup flashdrive, create a file named `reset-base-auth`. -* The flashdrive must contain a valid reset token, created on initial setup or subsequent backups -* Plug the flashdrive into the BitBoxBase -* Restart the device -* The authentication is now reset, run the BitBoxApp Setup Wizard again to set a new password. - -Other reset options will be implemented in the future. diff --git a/docs/tinkering/maintenance-menu.md b/docs/tinkering/maintenance-menu.md new file mode 100644 index 00000000..e8b6b083 --- /dev/null +++ b/docs/tinkering/maintenance-menu.md @@ -0,0 +1,56 @@ +--- +layout: default +title: Maintenance menu +parent: Tinkering +nav_order: 400 +--- +## Maintenance menu + +Using the BitBoxApp as user interface requires the Middleware on the BitBoxBase to always be available. +Only then the node management dashboard is reachable the user can log in with the management password to be able to interact with the device. + +In cases where this is not possible, e.g. because of a forgotten password or an internal error that prevents the Middleware to be reachable, the Maintenance Menu is available locally on a HDMI screen as a fallback. + +![Maintenance Menu on HDMI port](maintenance-menu.png) + +### Features + +The Maintenance Menu serves both the initial factory setup and a user-triggered factory reset. + +#### Factory setup + +The goal of the factory setup is to allow basic tasks like loading pre-synched Bitcoin blocks without knowing the device credentials. + +Current features: + +* Creating a Bitcoin / Electrs blocks snapshot to an external USB drive +* Loading snapshot from an external USB drive to the internal SSD +* Delete any files created during device testing (SSH / SSL certificats, application data, logs etc.) +* Wiping the factory credentials + +#### Factory reset + +The following options allow the user to reset the device in case of a forgotten management password or an internal configuration issue. + +* **Authentication reset**: the BitBoxApp will allow to set a new management password on next connect +* **Configuration reset**: factory defaults are restored (Redis database, new SSH and SSL keys...), without touching any Bitcoin or Lightning data +* **Disk image reset**: in case an over-the-air update is no longer possible, an official, signed BitBoxBase release image named `update.base` can be flashed from the USB flashdrive + +It is also possible to flash a custom-built, unsigned firmware update using the "Disk image reset" functionality, but only if the BitBoxBase has been previously configured to accept unsigned updates (calling `bbb-config.sh enable unsigned_updates` from the command line). +This setting cannot be set from the Maintenance Menu. + +### Authentication + +Access to the Maintenance Menu is a sensitive operation and requires the possession of a "maintenance token". +This token is stored in `.maintenance-token` on the USB flashdrive, and updated with every system configuration backup. +It is a random number and acts as the authentication secret. +The BitBoxBase itself stores the SHA256 hashes of all previously created token in `/data/maintenance-token-hashes`. +Deleting this file revokes all previously issued maintenance token. + +On every boot, the systemd [`startup-maintenance.service`](https://github.com/digitalbitbox/bitbox-base/blob/master/armbian/base/scripts/startup-maintenance.service) calls the script [`systemd-startup-maintenance.sh`](https://github.com/digitalbitbox/bitbox-base/blob/master/armbian/base/scripts/systemd-startup-maintenance.sh) which checks if a USB flashdrive containing a maintenance token is plugged into the BitBoxBase. +The token is validated by comparing its SHA256 hash against the local list of previoulsy created token hashes. +If a valid token is present, the Maintenance Menu is displayed on tty2 over HDMI. +Otherwise, the script exits immediately, without the possibility of any user interaction. + +The inital BitBoxBase image flashed on new devices contains a "Shift factory token" that allows access to the menu with a maintenance token kept confidential by BitBoxBase personnel. +This factory token is [clearly marked as such](https://github.com/digitalbitbox/bitbox-base/blob/master/armbian/base/config/signatures/maintenance-token-hashes) and is removed either manually when running "Finish factory setup..." or when the first system configuration backup is created, usually at the end of the Setup Wizard. diff --git a/docs/tinkering/maintenance-menu.png b/docs/tinkering/maintenance-menu.png new file mode 100644 index 00000000..ff43b982 Binary files /dev/null and b/docs/tinkering/maintenance-menu.png differ