How do I roll back from 1.8.3+ to a version prior without losing the ability to login?

[foosel]

With OctoPrint 1.8.3, the password hashing has been changed to use the Argon2 hashing algorithm. Any existing accounts will be migrated to the new hashing format on their first login under 1.8.3 or later, and the accessControl.salt value will be stripped from the config once all accounts have been migrated as it is no longer needed. This however means that downgrading to an earlier version will result in no longer being able to login, since earlier versions of OctoPrint 1.8.3 have no idea what to do about the Argon2 hashes and require accessControl.salt as well.

However, OctoPrint 1.8.3 and later come prepared for this scenario and will create a backup of both your users.yaml and config.yaml files, to make sure you can manually roll those back should for whatever reason you need to downgrade to a version prior 1.8.3.

Backed up files

You can find these backups in OctoPrint's config base directory:

• users.v1.yaml
• config.cleanup_legacy_hashes.yaml (only exists if the salt has been removed)

Please note that a later version of OctoPrint will make sure to remove these files again. If you are sure you do not need to downgrade, you can also delete them manually right away, or back them up to a secure location and delete them then.

Downgrading

To downgrade, you'll need to SSH into your OctoPrint server and then follow these steps (assuming Linux):

1. Shut down the OctoPrint server. On OctoPi you can do that via

   sudo service octoprint stop
   

   On manual installations it depends on how you have set things up.
2. Roll back the users.yaml backup:

   cp ~/.octoprint/users.v1.yaml ~/.octoprint/users.yaml
   

3. Check if there is a config.cleanup_legacy_hashes.yaml:

   ls ~/.octoprint/config.cleanup_legacy_hashes.yaml
   

   If there is (the command doesn't return an error), copy that back over config.yaml:

   cp ~/.octoprint/config.cleanup_legacy_hashes.yaml ~/.octoprint/config.yaml
   

4. Restart OctoPrint. On OctoPi you can do that via

   sudo octoprint service restart
   

   On manual installations it depends on how you have set things up.

Manually installed or custom base directory?

If you have OctoPrint manually installed or are using a custom base directory via --basedir, you'll need to adjust ~/.octoprint above to match the OctoPrint base directory used by your installation.

Windows or Mac?

If you are running your OctoPrint server under Windows or on Mac, the base directory ~/.octoprint will instead be %APPDATA%/OctoPrint on Windows and ~/Library/Application Support/OctoPrint on macOS, unless otherwise specified via commandline. Substitute accordingly.