TFS 2018 Update 3 is out, what changes for Search

TFS 2018 Update 3 is finally out and in release notes there is a nice news for Search functionality, basic security now enforced through a custom plugin. Here is what you can read in release notes

Basic authorization is now enabled on the communication between the TFS and Search services to make it more secure. Any user installing or upgrading to Update 3 will need to provide a user name / password while configuring Search (and also during Search Service setup in case of remote Search Service).

ES is not secured by default, anyone can access port 9200 and interact with all the data without restriction. There is a commercial product made by ElasticSearch Inc to add security (Called Shield), but it is not free.

Traditionally for TFS search servers, it is usually enough to completely close port 9200 in the firewall (if the search is installed in the same machine of Application Tier) or to open the port 9200 of Search Server only for Application Tiers instances if Search services are installed on different machine, disallowing every other computer of the network to directly access Elastic Search instance.

Remember to always ensure minimum attack surfaces with a good Firewall Configuration. For ElasticSearch the port 9200 should be opened only for TFS Application Tiers.

Here is the step you need to perform when you upgrade to Update 3 to install and configure search services: first of all in your search configuration you can notice a warning sign, nothing was really marked as wrong, so you can teoretically move on with configuration.


Figure 1: Search configuration page in TFS Upgrade wizard, notice the warning sign and User and Password fields

When you are in the review pane, the update process complain for missing password in the Search configuration (Figure 1). At this point people get a little bit puzzled because they do not know what to user as username and password.


Figure 2: Summary of upgrade complains that you did not specified user and password in search configuration (Figure 1)

If you move on, you find that it is Impossible to prosecute with the update because the installer complains of a missing ElasticSearch plugin installed.

The error ElasticSearch does not have a plugin AlmSearchAuthPlugin installed is a clear indication that installation on Search server was outdated.


Figure 3: During Readiness check, the upgrade wizard detect that search services installed in the search server (separate machine) missed some needed components.

The solution is really simple, you need to upgrade the Search component installation before you move on with Upgrading the AT instance. In my situation the search server was configured in a separate machine (a typical scenario to avoid ES to suck up too resource in the AT).

All you need to do is to copy search installation package (You have a direct link in search configuration page shown in Figure 1) to the machine devoted to search services and simply run the update command.


Figure 4: With a simple PowerShell command you can upgrade the installation of ElasticSearch in the Search Server.

The –Operation update parameter is needed because I’ve already configured Search services in this server, but for Update 3 I needed also to specify a user and password to secure your ES instance. User and password could be whatever combination you want, just choose a secure and long password. After the installer finished, all search components are installed and configured correctly; now  you should reopen the Search configuration page (Figure 1) in the upgrade wizard, specify the same username and password you used during the Search Configuration and simply re-run readiness checks.

Now all the readiness checks should pass, and you can verify that your ElasticSearch instance is secured simply browsing port 9200 of your search server. Instead of being greeted with server information you will be first ask for user and password. Just type user and password chosen during Search component configuration and the server will respond.


This is a huge step to have a more secure TFS Configuration, because without resorting to commercial plugin, ElasticSearch is at least protected with basic authentication.

Remember to always double check your TFS environment for potential security problems and always try to minimize attack surface with a good local firewall configuration.

I still strongly encourage you to configure firewall to allow for connection in port 9200 only from TFS Application Tier machines, because is always a best practice not to leave ports accessible to every computer in the organization.

Gian Maria.

Creating a Wiki with code in VSTS

Information spread is one of the key of success for Agile Teams, the ability to quick find information about a project, definition of UBIQUITOUS LANGUAGE and everything that can be related to the project should be prominent for each member of the project. In this scenario, the information should also be near where it need to be, but at the same time it should be widely available to every member of the team.

There are some concepts, like UBIQUITOUS LANGUAGE that should be near the code (name of classes should adhere to the UBIQUITOUS LANGUAGE) but at the same time we want that kind of information to be widely available. There are also other type of information that should be near to code, like guidelines, instruction on how to start working with a project etc, but that kind of information should be available even outside the code.

Where to place information is a really though decision, putting information in Code made it near to where it need to be used, but it can be less discoverable and usable

Luckily enough VSTS has a really good solution for this scenario, Wiki that are stored inside a repository. You can in fact use any folder of any Git Repository and starting creating a Wiki in Markdown, commit files, and then have VSTS render them as Wiki in the appropriate section. This has the double advantage of having information into the code, but at the same time the information is available via web wiki.

Yes, you could browse markdonw files directly from code repository since long time in the past, but having it converted to wiki is a major advantage, because readers does not need to know how to browse code. Here is an example how a looks like in the code repository


Image 1: Browsing of Markdown file directly in code browser

As you can see, markdown files inside code repository can be rendered without problem inside VSTS Code browsing. This is ok, but the information is not discoverable and it is not 100% friendly.

Forcing people to find information browsing in the Code section of VSTS is acceptable for developers, but not for other member of the team

Here are the problem: first you need to go to Code Browsing, then you need to choose a repository, know that the wiki is in a specific path (ok if you use wiki folder it is obvious 🙂 ) and lastly you are browsing information in the context of a repository (you have the tree at the left etc. Another annoying problem is that you should understand which branch to use to browse the most up-to-date and correct version of the wiki, Ex: is the Master or Develop branch that contains the most correct and reviewed version of the wiki?

If you go on the Overview section of the team project and navigate in the Wiki Section you have the option of publishing code as wiki. As you can see in Figure 2, it is just a matter of specifying to VSTS repository, branch, path and name of the wiki.


Figure 2: Publish part of a repository as wiki

Once the wiki is published it is more discoverable, because it is listed in the apposite section of the menu and it has a specific name, that is not related to the repository.


Figure 3: Code published as wiki

As you can see from Figure 3, you have several advantages, first of all everyone can simply open Wiki section and find the information, wiki is rendered outside the context of a code browsing, and you can list all the wiki available for this project with a simple selector (2). The most interesting fact is that the real wiki is implemented as code in a folder of a Git Repository and can evolve with the same pace of the code.

If you really care about your documentation, you can also use branching to modify a wiki and create a pull request to validate those modification before they are public for everyone.

Gian Maria Ricci.

Run SonarCloud analysis in VSTS / TFS Build

Running a SonarQube analysis for TFS or VSTS is really easy because we can use a pre-made build tasks that requires few parameters and the game is done. If you have open source project it made lot of sense to use a public account in SonarCloud, so you do not need to maintain a sonar server on-premise and you can also share your public account with the community.

For open source projects, SonarCloud is available for you with zero effort and thanks to VSTS and TFS you can automate the analysis with few steps.

The first step is creating an organization in Sonar Cloud, if you prefer you can just login with your GitHub account and everything is ready. After the creation of the organization, you should create new project and generate a key to send analysis to SonarCloud server, everything is made with a simple wizard and it takes only a bunch of seconds to have your project created and ready to be used.

Once you have your project key and token  you need to add the endpoint of SonarCloud to the list of available endpoints. You only need to give the connection a name, specify as Server Url and add the token generated during project creation.


Figure 1: Configuration of sonar cloud endpoint

Now you can configure build to perform the analysis, the first task is the “prepare analysis Task”, as you can see in Figure 2. You should select the Endpoint created in previous step, fill the project key and project name, but you need also to specify a couple of properties in the advanced section . The first one is sonar.organization and it is required or the analysis will fail. This is the only difference from on-premise SonarQube server, where you do not need to add organization name.


Figure 2: Configuration of the prepare analysis task.

The other setting to be specified in Additional Properties is the, to perform branch based analysis, a feature that is available in sonarcloud and it is available on-premise only with enterprise version. You can simply use the $(Build.SourceBranchName) to use the current branch if you are using Git.


Figure 3: Analysis performed on NStore project with branch analysis enabled.

The cool part of the process is that, SonarCloud require zero installation time and less than one minute to create the first project and thanks to the VSTS / TFS build engine you can automate the analysis in less than 2 minutes.

Gian Maria.

Troubleshoot “service unavailable” in TFS

Yesterday I’ve started an old virtual machine with an old version of TFS and when I try to access the instance I got a “Service Unavailable” error.


Figure 1: General Service Unavailable error for TFS Web interface

This error happens most of the time if you have wrong user credentials in the worker process used by IIS to run the TFS Application. To verify this assumption, you can simply open IIS Manager console and verify the status of the worker process that is used to run IIS (Figure 2)


Figure 2: The application pool in IIS is stopped.

As you can verify from Figure 2, the IIS app pool used to run service is stopped, if I tried to start again the pool, it immediately stopped again. This is usually the symptom of  bad authentication, this means that the pool is running with wrong user credentials. You can verify this in Event Viewer log, but absolutely avoid messing with the setting of the Application Pools directly, this is a task that should be demanded to the administration console.

As a general rule, you should never manually edit the configuration used for TFS in your IIS instance, everything should be done through the correct command

To fix this error open the Admin console and verify the Service Account used to run your TFS Instance


Figure 3: Application tier configuration, you can view Service Account user.

You can run Service Account with standard NETWORK SERVICE account, but I prefer using specific domain account, because I have more control on how all TFS Services will authenticate on the other machine of the domain. I changed the password of that account a couple of month ago, but that specific VM was never updated with the new credentials.

This is something that can happens in a domain, especially if you care about security and you force every account to change password every certain number of months. In this scenario my TFS instance cannot start again because it was still configured with the old password, but you can fix it with a couple of clicks.


Figure 4: Reapplying account can save your days when password of service user account of TFS was changed.

If you look in figure 4, the solution is really simple, because the Reapply Account command gives you the ability to re-enter the new password for the account, use the test function to verify that it is correct and once you press OK, the administration console takes care of everything.


Figure 5: Result of re-applying the account.

As you can see in Figure 5, the account is used not only in the application Tier, but also for Message Queue, TFSJobAgent and so on. This is the reason why I warned you not to fix the credential in IIS manually, doing this does not fix every place where wrong authentication are used.

Everything was green now green in the console, so I immediately tried to access the instance again, to verify that indeed everything is up and running again.


Figure 6: Everything is up and running again.

Gian Maria.