Migrating Octopus host to a new Active Director forest

Hi Support
We are migrating to new AD forest as part of company consolidation. One the last items remaining on our list was migrating Octopus Deploy host system Windows 2012 R2 . Our initial attempt to simply add server to new domain , resulted in octopus failing to display webpage but not visible errors, nor did I see anything in logs. Once we moved sever back, all functionality returned.
Do you have any documentation on migrating octopus host?
I could attempt using Microsoft’s ADMT tool, however rolling back would be more difficult after the changes made by ADMT.
is there any attributes in configuration file we need to edit or ApiKeys and encryption keys ?

Hi Michael,

Thanks for reaching out. Octopus is not exactly designed to handle a domain switch scenario. It is though possible to do it, but there are some things that you’re gonna have to keep in mind:

  • If the Octopus service account was running ander an AD account, you’re gonna have to change that account to one from the new domain.
  • The user logins from the old domain will stop working, as in Octopus we create our own users/teams and map them to AD SIDs, and these will change between domains.

These are some steps that we’d recomend you to follow for the domain switch:

  1. While on the working domain, change Octopus to use username/password authentication and set the user/pass of your admin account. You can find out how to do that on this link http://docs.octopusdeploy.com/display/OD/Active+Directory+authentication
  2. Move the server to the new domain.
  3. Make sure the Octopus Server service account is correct and that the service starts and runs properly. For the moment you might wanna run it under “Local system account” to avoid any dependency from AD. If the service doesnt start, please check on the Event Viewer for anything related to Octopus and send us the event logs. Also please send us your Octopus Server logs ( c:\Octopus\Logs on a default install)
  4. Try signing in using the username/password authentication.
  5. Change Octopus to use domain authentication on the new domain, and set the administrator account for it (same link as in (1), but this time for AD authentication).
  6. Login with the new administrator and start adding everyone back in from the new domain to the right teams etc
  7. Clean up all references to the teams/users from the old domain.

Please keep us posted on your progress.



Thanks Dalmir. This was extremely helpful.
I have one more question. All of the user accounts on the new domain will have the sid history from the previous domain and have the same UserPricipalName and same SamAccountName. Will this allow us to keep the same permissions as before or we would have re-do all our groups as well?

Hi Michael,

Sorry for the delay. We haven’t tested that scenario thoroughly (as its not that common for people to switch forests :wink: ), so we are not 100% sure if the same logins will work or not. We are optimistic though because you’ll be keeping the same Account Name and SIDs.

Worst case scenario, you’ll have to setup the permissions manually, hopefully for the last time (unless you’re planning to move to another forest again in the future). I’d personally recommend you to use AD groups instead of singular AD users, to reduce the work if it comes to this.