Add or Modify SharePoint 2013 / 2016 Search Topology using a PowerShell built User Interface

Welcome to the SharePoint Search Topology Add / Modification Sample tool

Please read the disclaimer in the PowerShell source code.

Updated to V2_8_3 to accommodate updates from Nov 2016 (MinRole changes) and includes the Cloud SSA flag option.

If you choose to create a Cloud Search Service Application (Cloud SSA) then you will need to review the guidance
This script has the option (unchecked by default) to allow you to create a Cloud SSA but it is not the primary purpose of the script.

From SharePoint 2013 onwards there is no User Interface to modify the Search topology and you are only able to create it either via PowerShell or via the UI where you are able to create a Search Service Application on a single server in the farm.
Any modifications to the Topology will require a fairly decent knowledge of the Search Topology as well as PowerShell.
To help with this I decided to write a PowerShell script that utilizes Windows Forms and provides you a UI to view, add and modify the topology.

The code can be safely run as no changes are executed until you instruct the code to do so and you will be prompted to confirm again before it starts.
Simply scroll to the end of the blog and download via the link from the TechNet Gallery.

Special Thanks
To get this version out a few thanks need to go out to Koos Botha (Helping me with some of the Forms Code in PowerShell) and Neil Hodgkinson (His endless sharing of knowledge on Search).
There are also 2 extracts from Joe Rodgers that are highlighted in the code.
Thanks to Brian Pendergrass for his input on understanding how components flow as well as storage locations.
There were a few other inputs as well, particularly when I was looking for the “.Name” property (Paul) of one of the PowerShell commands and they know who they are.

This Release

This script does not support multiple index partitions but does allow multiple Index servers (Replicas), Index moves i.e. location changes and changing of Index servers.

This release (V2_8_3):

  • KB for Admin Issue included,
  • SP2016 supported for TAP Customers and min role changes,
  • Index location bug fix with multiple index servers and where ‘CreatorOwner’ permissions have been explicitly removed for server lockdown and hardening,
  • Search Service Applications can be created,
  • Broken Search Topologies can often be repaired (Simply select a Broken Search Service Application and choose alternate servers for the broken Components),
  • It Reads in the existing the Search Service Application Topology (There is no Server number limit in this code but remember a single Search Service application is limited to,
  • It Displays and allows Moving any components to any servers in the farm (Servers will be automatically shown and made available to the Search if they exist in the Farm).
  • Support to handle multiple Search Service Applications,
  • Support for moving the Index location including deleting the previous location if not the default. It also creates the new location for you on all servers in the farm (Remote PowerShell to be enabled but it checks for that too).

NB – Make sure all servers are Online – if a server in the farm is off or not available it will still allow it to be added to the Topology (it will be marked with a red cross) and it will come online as soon as the server is available again.

As usual please test this out in your Dev and Test environments and of course no liability can be accepted for any issues experienced or possibly caused by running the code.

How to Use it

  1. Log on to the SharePoint Server as a Farm Administrator (Local Admin is required on all SharePoint Servers as well by SharePoint when a User is added as the Farm Admin),
  2. Scroll to the bottom of the article, Click on the link to download and Save the file AddModifySearchTopologyV2_8_3.ps1 to one of your SharePoint Servers,
  3. Open the file in PowerShell ISE (Select Run as Administrator) or in a Standard SharePoint PowerShell window (Run as Administrator),
  4. If you opened it in PowerShell ISE then simply click run otherwise if you opened it in the SharePoint PowerShell window simply navigate to where you saved it and run .\AddModifySearchTopologyV2_8_3.ps1
  5. Follow the on screen messages i.e. Import, Create Now and Modify using the CheckBoxes and when ready click Create Now or Modify Topology to start
    (Remember this can take a long time to Run as the new Topology is being activated – A message will display to show when it’s compete.)

How does it Work?

It exports the current Topology to an XML file, reads in the details and displays your current topology in the Top List boxes.
It then automatically selects your Current Topology in the New Topology section below to make editing easier.
Simply click on the server names in the different component sections to make changes.

Once complete click Create Now or Modify Topology to start the process.

The code first clones the Topology, then deletes any Components you have removed and then adds any new Components to the Cloned Topology. It then Sets the new Topology as the Active Topology and removes the old, now inactive Topology.

There are some conditions in topology modification for SharePoint and some require a 2 step process i.e. Changing all Index Components.

One careful item to note is that SharePoint Search Index Component cannot just be replaced in 1 modification i.e. once it is created at least 1 Index Component must remain so basically if “Server A” is hosting the Index and you would like to move it to “Server B” then you have to add “Server B” to the Index first and apply the changes. This version now does the multi-modification for you.

Donwload the file directly from the TechNet Gallery.

Comments (68)

  1. Gurdip Sira says:

    I used this for SP2016 but get an error: Topology does not contain any components of type Microsoft.Office.Server.Search.Administration.Topology.AnaltyicsProcessingComponent and even though the SSA is created and started, on the search admin page it’s just spinning.

    1. In this case, I would suggest that you create a new SSA. The tool is often able to repair a topology but it looks like it is unable to do so in this case.
      I have never had it not be able to repair a Topology except when not all servers were online and the server could not be reached.

      Which version of SP are you running this on and what OS is being used?

  2. Sathiya says:

    Hi Scott,

    Simply amazing tool. Always I used to edit server names and components in place. This tool makes me CLICK-To-CREATE completely. I have an issue with crawling. Could you please have a look on the issue?

    1. Hi Sathiya, this has nothing to do with the tool but the following basic steps should be followed to get through crawl issues:
      Validate permissions of the crawl account i.e. make sure it has read permission for the web application that you are pointing the crawler to.
      Configure the correct URL in the schedule.
      If you have extended the web app to an external URL and require a proxy for external access then rather use the internal URL for crawling and create a search mapping to replace the URL in the query results.
      The alternative would be to provide proxy details on each crawl server and that should get the same result but then you are going through the load balancer and that may not be what you are trying to achieve.
      It looks like you are using a robots.txt file and from the responses you have received to your questions it may be best to remove all rules and start again i.e. clear the slate, crawl and validate the results and then start applying exclusions accordingly.
      There is a Search blog run by Microsoft Search Experts and Brian Pendergrass covers a lot in his blog

  3. Brian says:

    Great tool and time saver. Much appreciated.

  4. Eric says:

    Hi Scott,

    Thank you for creating this. I am unable to get this to work as I expected. What I am trying to do is move the Admin component from a server that is no longer online to another app server in my farm. When I select Modify Topology, the button goes to blue for about 15 seconds and then returns to gray. I cannot tell that anything happens in that timeframe and when I go back into Central Administration to view the Search Administration System Status, it still says that it is unable to connect to the remote server (as though it is still looking at the server that is down for the Admin component. Any idea what could be the cause? Thank you.

    1. Hi Eric, if the server is offline I don’t believe you can move it as it doesn’t exist. It sounds like you will need to create a new Search Service app. You can use the script to do that. If that server is showing elsewhere in your farm I suggest removing it in Central Admin as well so that no services try to connect to it.

      1. Eric says:


        Thanks for the quick reply. I’m sorry it has taken me so long to get back with you…I have been sick.

        I now understand that I cannot use the script to move the Admin component from an offline server, because the Admin component no longer exists. My hope is to have 2 Admin components so that I don’t run into this situation again. I am attempting to recreate a Search Service Application with your script. How can I tell if work is being completed in the background? The “Create Now” button is grayed out as I would expect while the new topology is being created. Is there a typical amount of time to create the new topology? Mine has been running for about 30 minutes now as far as I’m aware. Thanks again for your support.

        1. Eric, apologies for the delay in response. Dependent on the farm size and server specs this could take up to a few hours.
          Open Central Admin and monitor the creating there and you should see components being created and coming along.
          You can simply refresh the screen in Central admin to monitor the changes occurring.
          What version of SharePoint are you using and what server OS are you running this on?

  5. Mirza Baig says:

    Hi Scott,

    You mentioned…
    “It sounds like you have a rights issue as the location for default will be under the Search Service account. I suggest modifying the location to a set Index location. e.g. “d:\index\” dependent on what drives and disk space you have. Using the default is not recommended.”

    Can you explain what you mean by “location for default will be under the Search Service Account”. How can I see the default location, from viewing the search service account? where?

    Also, how can I resolve this rights issue.

    Thank you for the great script! It worked wonders for me. I just need assistance with this last bit. I want my index partitions on both my application servers.

    If I change the index location – will I need to create these index locations on both servers prior to running this script?

    1. Hi Mirza,
      When you install SharePoint it defaults the Index location as “C:\Program Files\Microsoft Office Servers\15.0\Data\Office Server\Applications\”.
      Processing occurs under the c:\users\svc_account location of the account configured to run the Search Service.
      The script will automatically create the locations and set permissions on the folders in case explicit permissions have been set at the root level.
      SharePoint will then automatically replicate the index over to the new location.
      This is why an Index move is an intense operation that performs multiple configuration steps and also won’t allow all index components to be changed in one step.

      I have received your contact email so will communicate via email directly.

  6. Waseel says:

    Hi Scott,
    I am trying it with admin account(Farm admin and local admin group member) I am getting below error and I have checked all the servers PS-Remoting is already enabled (WinRM is already set up to receive requests on this computer).

    What else could be the reason behind this error ?

    Enable remote PowerShell on all SharePoint servers. Run ‘Enable-PSRemoting –force’ and ‘WINRM quickconfig’ on EACH server??

  7. Chris says:

    Hi Scott, sorry was being away on project duties. I would like to help to fix this, as it still doesn’t work. Let me know how to get it going.

    1. Hi Chris, I would love to get to the bottom of the issue that only seems to affect certain people as I built in a lot of redundancy and “safety nets”.
      You should be able to email me via the contact link now and send me the error details and I will then communicate with you directly.
      I am also looking for someone to get involved with helping me finalize V3 to include index partitions as the screen layout is an issue for me right now. It just doesn’t work and makes selection of the partition too complicated so the logic is simple but the screen is complicated. Please let me know if you have a problem with the contact page?

      1. Chris says:

        I don’t seem to see the contact now link. Will that be in your profile?

  8. Wenxing Liao says:

    Hi Scott, thanks first,

    we are runing SP2013 with Search Service was created,
    when i run this tools with click IMPORT button, it’s alert that “Usage and Health Service Application Proxy is not Online”, in fact , the Usage and Health Service Application Proxy was started

    how can i fix it?

    1. This check is in place because of issues with starting Search when the Usage and Health Service Proxy is not available.
      It may just need an IISReset.
      Make sure that the Usage and Health Service is started under the services on server section.

  9. Chris says:

    First of, thanks Scott for providing this. However, when I run this in our server, nothing happens. I click the import button, but the current topology is not displayed. Everything stays blank. I don’t get any errors as well. Any idea what might be happening?

    1. Hi Chris, have you already created a Search Service App? Which version of SP are you running this on. Ping me via the email author option and I will respond to you.

      1. Chris says:

        Hi Scott, yes, the SSA is already created. We are running SP2013.

        1. Hi Chris,

          The contacts link is now available.
          Please ping me via that so I can try and assist you as I have tested this script on a large variety of SP2013 installations so I need to see what could be going wrong here.


          1. Chris says:

            Thanks Scott. I tried with the contact link, but it says spam detected. 🙂

          2. That means it detected an invalid / possible SPAM email address. I have disabled it temporarily.
            Try again.

          3. Dean Gross says:

            We had this problem and fixed by granting adding our Setup and Farm Admin accounts to the SSA Administrators role

          4. Thanks Dean. That’s a strange one because if you are using a Farm Admin account then you already have this permission set so it shouldn’t be necessary.

    2. Ram says:

      Hello Scott/Chris, I am having the same problem. Did you resolve the problem? Can you please share what you did to fix it?

      1. Ram, please ping me on this as Chris has not responded yet and I would like to assist and solve this.

        1. Ram says:

          Scott, Not sure how to ping you, couldnt find email address anywhere. I am running into same problem as Chris. When I launch the script the UI loads and shows the service app name but doesnt show the servers or the services running. Nothing happens if I client on “Import” or “Create New Service App” either

          1. Please post OS used, version of SharePoint, SQL, etc. so I can try and replicate the issue as this hasn’t changed in quite a few months so it may just be a simple SP version issue that I need to resolve.
            I will try and sort out the contact info in the meantime as well.

            To confirm, you are running this on a SharePoint server, joined to a farm and you are a Farm Admin?

          2. Hi Ram,

            The contacts link is now available.
            Please ping me via that.


  10. David Haver says:

    Really like this tool. I have run into an error with one client. The error message is Exception calling “Activate” with “0” argument(s): “Topology activation failed. Management called failed with System.InvalidOperationException: ‘Unable to change topology when Generation controller is not active’ at at Microsoft.Ceres.SearchCore.IndexController.IndexController.IsEmptyIndex(String indexSystemName) at Microsoft.Ceres.SearchCore.IndexController.IndexControllerManagementAgent.WrapCall[T](Func’2 original)”

    Can you assist with this error?

    1. Hi David,
      Please connect with me via email using the email author link so I can see what is going on in your environment.


    2. David, the Contacts link is now sorted so you can ping me there.

      1. Martin McAllister says:

        SharePoint 2016 – 2 application servers: I can create the search, the import works fine, but when I go to create the topology I get Exception calling “Activate” with “0” argument(s): “Topology does not contain any components of type Microsoft.Office.Server.Search.Administration.Admin Component”. memoryLimitMegabytes=”0″ is already set. saw some people had an issue in 2013 when this 100.

        1. What other minrole servers do you have in the farm? Please try the contact me page so I can try and help you as 2016 Search components can only be run on certain servers I.e you need either Search or Custom / special load.

  11. Mirza Baig says:

    Can I use the farm account for search service account/ and search query pool account?
    I’m assuming the search content account is the crawl account, as I have one specifically for that.

    1. Hi Mirza, It is recommended that separate accounts always be used to configure SharePoint with a least privileged configuration. If you just separated the content account then search would work as expected. Just remember that using one account for the admin pool and web app pool essentially opens up your Central Admin security and any custom solutions could actually then manipulate central admin utilizing the SPRunWithElevatedPrivileges command.

      1. Mirza Baig says:


        thanks for replying to my other comment.
        I have an issue when importing current topology and modifying it. I currently have index on my app server. I want to add the index to both my WFE.
        When adding the index and clicking “modify topology”
        I get an error at the bottom in red, “Path Could not Be Created on WFE1”
        What am I doing wrong?

        1. Mirza Baig says:

          index location is : DEFAULT

          1. It sounds like you have a rights issue as the location for default will be under the Search Service account. I suggest modifying the location to a set Index location. e.g. “d:\index\” dependent on what drives and disk space you have. Using the default is not recommended.

  12. Thank you Scott really great work , it saved lots of time and efforts for me

  13. Dean says:

    I am trying to use this on a 2013 test farm (WIndows Server 2012 R2) with one app servers and 2 WFEs. It is giving me message that I need to enable remote PowerShell on all SharePoint servers. When I followed the instruction, the WFE servers told me that remote PS was already enabled. What else should I look at to get this working?

    1. Hi Dean, make sure you take this new version (2_8_2) and also make sure you have run “Enable-PSRemoting –force” (from an Administrator PowerShell window) and “WINRM quickconfig” (Dos command but can also be run from PowerShell) on EACH server. This is required as I use remote PowerShell to create the folders for the Index servers as well as quite a few other remote commands.

      1. Kaya says:

        Hi Scott
        I’m also experiencing the same error Dean, I downloaded V2_8_2, imported my topology but when I try modifying my it i get the error “Enable-PSRemoting –force” (from an Administrator PowerShell window) and “WINRM quickconfig” on EACH server. Which I did all on all my servers servers using Administrator PowerShell window but this error persists, my index is located on “E:\Index”
        How do I get past this error?

        1. Hi Kaya, what user account are you logging in with when launching the tool as the account must be a farm admin and a local admin on all the servers as you are performing administrative tasks?

  14. Hewa says:

    Hi Scott – Awesome !! – thanks for closing a "gap" in SP2013.. 🙂

  15. Hi LesIsMore, thanks. Are you wanting to create additional databases for crawl, or analytics do you want to store 1 of the 4 default db’s on another SQL? If the latter is the case then what are you trying to achieve?

  16. LesIsMore says:

    Thank you Scott, great post. I was wondering how I can divide the SQL databases across multiple SQL servers. In this scenario, all the databases are on one SQL server. Any insight?

  17. VincentYo says:

    This is no less than absolutely f’ing brilliant!

  18. Simon P says:

    Hi Scott – I did see the note about partition support in V3, I suspected it was the case.

    Thanks for such a fast response, and good luck on finding some time to finish up V3!

  19. Hi Simon, yes that is the issue. If you review the write up for this version (2_8), I have not included Partitions as yet. I have been a bit delayed getting out V3 which will include that.

    Creating partitions and replicas is a recommended practice but currently V2_8 only handles replicas on separate servers and does not cater for Partitions.

    I will hopefully get V3 out soon.

  20. Simon P says:

    Hi Scott, awesome script! I too get a path error when modifying an existing topology: "Path ‘[redacted]’ is not Empty on all Index Servers. click IMPORT to reset and choose another location.
    The index path is unchanged from the detected one (so it’s expected that it’s not empty), and I am not moving any index components.
    I do, however, have two index partitions (for capacity), duplicated on two servers (for fault tolerance), so 4 in all.
    Could this be the issue?

    1. Hi Simon, unfortunately yes. Index Partitions are currently not catered for as can be seen in my notes. In order to cater for index partitions I have to cater for the max which is 25 I am have been unable to get the edit screen for that working at this stage. The form to edit the partitions is just too difficult to use and cater for each partition combination. It almost becomes impossible to see what partitions are setup on which servers. It’s a bit of a catch22.

  21. yusuf says:

    Scott this script is amazing! This should be packaged with SharePoint!

  22. Luis Herrera (Mexico) says:

    Great tool Scott!! thanks so much!

  23. Hi Serge and Sumeet, the Path creation is done remotely i.e. from the Server the tool is running from. It uses the Invoke-command with (mkdir path). What are you putting in as the path? I have only ever seen this happen when the account running the tool
    is not the farm admin and does not have admin rights on all the SharePoint servers?

  24. Sumeet Singhal says:

    Same Error for me also for path. Does it create some logs?

  25. Sergeluca says:

    sorry, the error message was : Path could not be created on appserver1 click IMPORT to reset and try again

  26. Serge Luca says:

    H Scott, great work ! I have the following error: "Path could not be created on click IMPORT to reset and try again"

    any idea ?

    1. Serge, ping me via messaging and let me see what is going on. What server OS are you running and have you enabled WINRM and PSRemoting?

  27. Hi Kevin, great to hear that it helped. Working on V3 and hope to have it out soon to include replicas and partitions.

  28. Kevin Wilson says:

    I had an issue with the firewall port 808 not being open on the other servers, but you are a steely eyed missile man! This is a great piece of work and saved us hours of fiddling.

  29. Yusuf Moraby says:

    Simply Awesome needed something life this Scott,

  30. Anthony Casillas says:

    Very Nice Work Scott! I am going to create a link off my blog, to point to this.

  31. Pete Williams - Senior SharePoint PFE says:

    Great work Scott

Skip to main content