From 4a8ce9939ea49434334b893e05ce6db24a19f07d Mon Sep 17 00:00:00 2001 From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Date: Fri, 27 Sep 2024 10:19:49 +0200 Subject: [PATCH] Locked out: improve structure, add steps on connecting terminal (#34933) * Locked out: improve structure, add steps on connecting terminal * Remove scenarios for non-owners * Add steps for VM * Apply suggestions from code review * Move steps * Apply suggestions from code review --------- Co-authored-by: Stefan Agner --- source/_docs/locked_out.md | 67 +++++++++++++++++++++++++------------- 1 file changed, 45 insertions(+), 22 deletions(-) diff --git a/source/_docs/locked_out.md b/source/_docs/locked_out.md index 4ebded88ef11..cd40aced017c 100644 --- a/source/_docs/locked_out.md +++ b/source/_docs/locked_out.md @@ -15,19 +15,42 @@ or need to recover your data. ## Forgot username -If you’ve forgotten your username, ask the owner to help you. -If you are using the {% term "Home Assistant Operating System" %} and have access to the Home Assistant server, you can connect a terminal and enter the `auth list` command. This command lists all users that are registered on your Home Assistant. +### Symptom: I'm the owner and I forgot my username + +You are the **owner** of the Home Assistant server and you cannot login because you forgot your username. + +#### Remedy + +1. Check if the following conditions are met: + - you are using the {% term "Home Assistant Operating System" %} + - you have access to the Home Assistant server. +2. Open a terminal connection to Home Assistant: + - If you are using a Home Assistant Green, follow these steps [to access the console](https://green.home-assistant.io/guides/use-terminal/). + - If you are using a Home Assistant Yellow, follow these steps: + - [to access the console from Windows](https://yellow.home-assistant.io/guides/use-serial-console-windows/) + - [to access the console from Linux or macOS](https://yellow.home-assistant.io/guides/use-serial-console-linux-macos/). + - If you are using another system, connect keyboard and monitor. The procedure might be similar the one used for Green. + - If you are using a Home Assistant OVA (virtualization image): + - Access the system console by opening the terminal through your virtualization platform's interface (for example, Proxmox, VMware, VirtualBox). + - Follow the platform-specific steps to interact with the virtual machine's console. +3. In the terminal, enter the `auth list` command. + - This command lists all users that are registered on your Home Assistant. ## Forgot password -If you are not the owner or do not have administrator rights, ask the owner to give you a new password. +### Symptom: I'm the owner and I forgot my password -- In the navigation pane on the left, check if you see the **Settings** menu listed above the **Notifications**. - - If you don't, you do not have administrator rights. +You are the owner or administrator of Home Assistant and forgot your password. -If you are the owner or have administrator, there are different methods to reset a password, depending on your setup: +### Remedy: resetting an owner's password -### To reset a password while still logged in (including Supervised) +If you are the owner or have administrator, there are different methods to reset a password, depending on your situation: + +- [Reset a password while still logged in](#to-reset-a-password-while-still-logged-in-including-supervised) +- [Reset an owner's password when logged out](#to-reset-an-owners-password-via-console) +- [reset a user's password, via the container command line](#to-reset-a-users-password-via-the-container-command-line) + +#### To reset a password while still logged in (including Supervised) The method used to reset a password depends on your user rights: @@ -40,12 +63,12 @@ The method used to reset a password depends on your user rights: 2. Reset your password via this new administrator account (and then [delete this new account](/docs/locked_out/#to-delete-a-user)). - Your configuration will remain, and you don't have to do a new onboarding process. -### To reset an owner's password, via console +#### To reset an owner's password, via console Use this procedure only if the following conditions are met: - You know the username. -- You can access the [Home Assistant console](/hassio/commandline/) **on the device itself** (not via the SSH terminal from the add-ons). +- You can access the Home Assistant console **on the device itself** (not via the SSH terminal from the add-ons). 1. If you are using a Home Assistant Yellow or Green, refer to their documentation. - If you are using a Home Assistant Yellow, refer to the following procedure: @@ -63,7 +86,7 @@ Use this procedure only if the following conditions are met: - **Troubleshooting**: If you see the message `zsh: command not found: auth`, you likely did not enter the command in the serial console connected to the device itself, but in the terminal within Home Assistant. 4. You can now log in to Home Assistant using this new password. -### To reset a user's password, via the container command line +#### To reset a user's password, via the container command line If you are running Home Assistant in a container, you can use the command line in the container with the `hass` command to change your password. The steps below refer to a Home Assistant container in Docker named `homeassistant`. Note that while working in the container, commands will take a few moments to execute. @@ -73,7 +96,7 @@ If you are running Home Assistant in a container, you can use the command line i 4. `exit` to exit the container command line 5. `docker restart homeassistant` to restart the container. -### To reset a user's password, as an owner via the web interface +#### To reset a user's password, as an owner via the web interface Only the owner can change other user's passwords. @@ -85,17 +108,7 @@ Only the owner can change other user's passwords. 5. Confirm the new password by entering it again, and select **OK** again. 6. A confirmation box will be displayed with the text **Password was changed successfully**. -### To delete a user - -You need to be an owner or have administrator rights to delete a user. - -1. Go to {% my people title="**Settings** > **People**" %} and select the person which you want to delete. - - Note: you cannot delete the owner. -2. At the bottom of the dialog box, select **Delete**. - - A confirmation dialog box will be displayed. -3. To confirm, select **OK**. - -### To prepare the system to start a new onboarding process +## Preparing the system to start a new onboarding process If you lose the password associated with the owner account and the steps above do not work to reset the password, the only way to resolve this is to start a new onboarding process. @@ -139,3 +152,13 @@ For Windows or macOS you will need third party software. Below are some options. - Windows: (read-only access to the SD) - macOS: + +## Deleting a user + +You need to be an owner or have administrator rights to delete a user. + +1. Go to {% my people title="**Settings** > **People**" %} and select the person which you want to delete. + - Note: you cannot delete the owner. +2. At the bottom of the dialog box, select **Delete**. + - A confirmation dialog box will be displayed. +3. To confirm, select **OK**.