Lockout recovery process

Administering Bitbucket Server

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

This page describes how to recover administrator access for Bitbucket Server 5.X+, and later. For releases prior to that, please refer to the documentation specific to that version.

As an administrator, you may find yourself locked out of Bitbucket Server and unable to log in. This situation can arise when all users are managed externally from Bitbucket Server, and Bitbucket Server becomes unable to access those user directories for some reason, including:

  • The external user directory server is not accessible (because the network is down, or the directory is down, or the directory has been moved to another IP address).
  • Users are managed within a Jira application and the Application Link from Bitbucket Server to a Jira application has been accidentally deleted.
  • The admin password has been forgotten or lost.
  • The admin account is shaded by a remote account in an LDAP or Jira application that is connected to Bitbucket Server but which is unavailable.

 

The lockout recovery process for Bitbucket Server is:

  1. Edit the <Bitbucket Server installation directory>\bin\_start-webapp.sh file (or _start-webapp.bat on Windows) and add the "-Datlassian.recovery.password=temporarypassword" value to the JVM_SUPPORT_RECOMMENDED_ARGS property. The property value must be non-blank, and should look like this when you've done that:

    # Occasionally Atlassian Support may recommend that you set some specific JVM arguments.
    # You can use this variable to do that. Simply uncomment the below line and add any required
    # arguments. Note however, if this environment variable has been set in the environment of the
    # user running this script, uncommenting the below will override that.
    #
    JVM_SUPPORT_RECOMMENDED_ARGS=-Datlassian.recovery.password=temporarypassword


    Here we are using "temporarypassword", but you should use your own value.
     

  2. Start Bitbucket Server manually by running <Bitbucket Server installation directory>\bin\start-bitbucket.sh (or start-bitbucket.bat on Windows).
  3. Log in to Bitbucket Server using the 'recovery_admin' username and the temporary password specified in Step 1.
  4. Repair your Bitbucket Server configuration. We strongly recommend that you do not perform other actions while Bitbucket Server is in recovery mode.
  5. Confirm your ability to log in with your usual admin profile.
  6. Shut down Bitbucket Server, remove the atlassian.recovery.password argument from _start-webapp.sh (or _start-webapp.bat on Windows), and restart Bitbucket Server as usual.
Last modified on Oct 13, 2020

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.