Preparation Installation Operation Tips, tricks and traps Debugging

There’s an old joke that goes “Q: Why do people take an instant dislike to <InsertNameOfUnpopularPolitician>?” “A: It saves time”. And so it is with SEFAUtil.

Without doubt SEFAUtil is an indispensable utility. “Secondary Extension Feature Activation Utility” – to give it its full name – ships in the Lync and Skype for Business “Resource Kit” (“ResKit”) download pack. When correctly integrated into the topology it gives support staff the ability to query, set and cancel all manner of call-forwarding and team/delegation settings from the comfort of their cube, without needing to visit the user or reset their AD password in order to do it remotely (after signing in as that user). It’s a godsend when someone goes on leave unexpectedly or has a catastrophic PC failure with an urgent incoming call pending, and as equally helpful when configuring the settings for executives and other ‘sensitive’ users.

Unfortunately however SEFAUtil is terribly slow in operation, “finicky” to use, seemingly inconsistent (even on its good days) and (as it’s a free-standing executable) not so easily automated or batched.

There have been calls for years to have SEFAUtil reborn as native commandlets within SfB but until now that’s not borne fruit.

Fellow SfB MVP Matt Landis pounced upon this opportunity and through his company landiscomputer.com has released “SEFAUtil Server”. This utility ships as an installable MSI file and (just like SEFAUtil) it needs to be installed as a trusted application into your pool – but that’s where the similarities end.

You interact with “SEFAUtil Server” using PowerShell, which provides the feedback and input formatting lacking in the free-standing EXE. It delivers performance that’s out of this world when compared to the original. If you’ve not been there before: trust me, you’ve missed a world of pain.

Preparation

1. Identify (or create) the machine you’re going to install SEFAUtil Server on. TechNet for Lync 2013 says “you can collocate a trusted application server with a Standard Edition server” although for Skype for Business the rule of exclusion by omission applies: as the co-residency of a Trusted App on a Front-End is not stated as being supported, it’s not. I’ll defer to your common sense here: if this is a tiny single SE deployment it’s going to be hard to argue for a new server on which to run SEFAUtil Server. At the other end of the scale however it’s safest to quarantine it to its own machine, if only to reduce the number of support staff needing to RDP to the server to execute the commands.
2. If the server above is new:
   1. make sure it has .NET 3.5 installed:

      Install-WindowsFeature Net-Framework-Core

   2. Likewise, ensure .NET 4.5.2 is installed. You can download the web installer from here.
   3. You need the SfB server media. You’ll need to get that from MSDN or your Microsoft licencing portal – or you might find it still on one of the existing SfB servers.
   4. The server will want patching, so download the latest “SkypeServerUpdateInstaller” from here.
3. Under the hood SEFAUtil Server is a UCMA utility, and it uses the old-school auto-discovery methods to find your servers. You need at least ONE of these in your internal DNS server:
   • SRV    _sipinternaltls._tcp.<YourSipDomain>
   • SRV    _sip._tls.<YourSipDomain>
   • A         sipinternal.<YourSipDomain>
   • A         sip.<YourSipDomain>

   I’m guessing you’ll already have a record called “sip” so you can skip this step. Beware that if you choose to add “sipinternal” you’ll need to replace the certificate on the pool’s Front-End(s) with one that includes “sipinternal.<YourSipDomain>” as a SAN. Use my Update-SfbCertificate.ps1 script to fast-track this.

4. Download SEFAUtil server from here – but don’t install it just yet.
5. DON’T feel tempted to download the separate UCMA Runtime (“UcmaRuntimeSetup.exe”). In my experience that isn’t required – the native UCMA bits that come from the SfB media are sufficient.

Installation

1. SEFAUtil Server needs you to define a port that it will listen on, so let’s find an unused one. Matt suggests 5500 which is as good as any. Just type this command into a CMD or PowerShell window, and if you just get the prompt back with no further display, you’re good:

   netstat -ano | findstr 5500

   

   So if you’re installing SEFAUtil server on a Front-End server, port 49152 would be a bad choice:

   

2. Paste the following commandlets into an elevated P$ Window on a machine with the SfB PowerShell module installed (like your Front-End), and substitute the placeholder names with your real values. If you’re installing SEFAUtil server onto your Front-End server or pool, all those FQDNs will be the same value:

   $Site = Get-CsSite –Identity <SiteName>
   New-CsTrustedApplicationPool –id <SefautilServerFQDN> –Registrar <FEServer/PoolFQDN> -site $Site.SiteId 
   New-CsTrustedApplication –ApplicationId sefautilserver –TrustedApplicationPoolFqdn <SefautilServerFQDN> –Port <Port>
   Enable-CsTopology
   New-CsTrustedApplicationEndpoint -TrustedApplicationPoolFqdn <SefautilServerFQDN> –ApplicationId sefautilserver -SipAddress "sip:sefautilserver@<YourSipdomain.com>" -DisplayName "SEFAUTIL Server"

   If any of the above give errors, check the pasting or editing process didn’t add or remove any spaces, and that you didn’t accidentally leave any of my placeholder values, or the “<>” characters – but note the quotation marks around the values for SipAddress and DisplayName *are* required.

   Beware: Enable-CsTopology might break your response groups! See traps below.

3. If this machine is new to the SfB topology, mount or Unzip the SfB media. If it’s pre-existing, you can skip to Step 4.
   1. From this point we assume the media is drive D. Open an elevated CMD window to D:\Setup\amd64\ and run “vcredist_x64.exe”
   2. Move one directory deeper to D:\Setup\amd64\setup\ and run “ocscore.msi”. This step installs Skype for Business PowerShell and the Deployment Wizard, however we won’t be using the latter in this process.
   3. Navigate to  “C:\Program Files\Skype for Business Server 2015\Deployment”
   4. Run:

      Bootstrapper.exe /BootstrapLocalMgmt /MinCache /SourceDirectory:D:\Setup\amd64\

   5. Every test I ran threw an error at this point, complaining that “Language ca-ES is missing files”:
      
      If you encounter this too, simply repeat the command – based upon my experience it will complete OK the second time.
   6. Before we go starting services, now’s the best time to patch it. Close any PowerShell windows you may have open.
   7. Navigate to and run the SkypeServerUpdateInstaller from within this CMD window.
   8. Once that’s complete, close the CMD Window.
   9. Launch a new elevated PowerShell window. (If this is a Server 2008 machine, open the “Skype for Business Server Management Shell” instead).
   10. Run:

       Enable-CsReplica

   11. Run:

       Start-CsWindowsService

   12. Run:

       Invoke-CsManagementStoreReplication -Force

   13. Run “CertUtil” to reveal the name of your Root CA & and any Intermediates:
       
   14. Request a Default certificate for the server, pasting the appropriate “config” value from the above as the value for the “-CA” parameter:

       Request-CSCertificate -New -Type default -CA "dc.contoso.com\<certificate authority>" -FriendlyName "<A Friendly Name for your new cert>" –Verbose

       

   15. The response to the above will include the new certificate’s thumbprint. Add it to this command:

       Set-CsCertificate -Type Default –Thumbprint <thumbprint>

       

   16. Run:

       Enable-CsTopology

       Beware: this might break your response groups! See traps below.

   17. Run:

       Get-CsManagementStoreReplicationStatus

   18. If all’s well by this stage your server should be replicating OK. If this server shows “UpToDate: True”, proceed to Step 4.
4. Install “SefaUtilServer.msi”
   1. 
   2. 
   3. 
   4. 
   5. 
   6. 
5. Check the new SEFAUtil Server Service is started before you continue. Refer to the Debugging section below if it’s not.
6. If you have a PowerShell window open, close it (as it won’t have the new commandlets accessible).
7. Open an Elevated PowerShell window: this ensures the new module is loaded and the commandlets are available to us.
8. Now you need a licence. Thankfully this can be performed online in an instant (or two) with this commandlet:

   Set-SefautilServerRegistration –Name <YourOrgName> –EmailAddress <YourCorpEmailAddress@YourDomain.com> –PhoneNumber <YourPhoneNumber> -ImplementationType SelfImplement

9. The above step should succeed and display the key on-screen. If it returns an “internal server” error you might need a reboot – see Debugging below. Assuming the licence request came back OK you’re done here – it’s loaded and ready to use. Jump to step 12.
   
   Note that you’ve received a free Community Edition key that’s licenced forever, and a time-bombed trial of the Enterprise Licence.
10. If your server doesn’t have Internet access the above step will fail, in which case e-mail sales#landiscomputer.com and request a licence. Tell them Greig sent you. ;-)
11. If you’ve received a licence via e-mail, you can load that key thus:

    Set-SefautilServerRegistration –RegistrationKey "<LicenceKey>"

12. OK, you should be good to go!

Operation

Here are the commandlets added with this new module:

Here’s an example of me querying my own account:

Note that in the above you can easily see who my Team Call members & Delegates are, and that I currently have sim-ring activated to my mobile phone. Unanswered calls will ring to voicemail after 20 seconds, but only during the working hours set in my Outlook calendar.

That “call forward to voicemail after 20 seconds” is a bit tricky to interpret from the above – it’s actually the result of having “CallForwardTo” blank (which implies voicemail), “CallForwardingEnabled” set to False – so we don’t have an ‘immediate’ call forward active – and a “UserOnlyWaitTime” of 00:00:20. Thankfully that’s a bit easier to set with some of the switches – see below.

Here are some sample commandlets to help you:

• Send unanswered calls to voicemail after 30s:

  Set-CsUserForwarding -SipAddress greig@gislync.com -DisableForward -UnansweredCallWaitTime 30 -UnansweredCallsToVoicemail

• Sim-ring to my mobile (or any telephone number):

  Set-CsUserForwarding -SipAddress greig@gislync.com -EnableSimRing Other -OtherDestination "+1234567890"

• Flush my existing Team and add 2 new members. Set them to start ringing after a 5s delay:

  Set-CsUserTeamMembers -SipAddress greig@gislync.com -RemoveAllMembersFirst -AddMembers jessica@gislync.com,chode@gislync.com -DelayRingTime 5

 

Don’t overlook the inbuilt help if you’re struggling to determine the correct syntax:

get-help Set-CsUserForwarding

Tips, Tricks & Traps

• Fixed in this 2019 update: You will see some weird behaviour in both the client and in operation if you add a “tel:” prefix to a phone number in one of the destination fields: you only need the E.164 number inside quotes. e.g.:
  
• If your “DelayTime” for Delegation or Team Call ringing isn’t being honoured, it’s because the value you’ve set isn’t at least 5s lower than the UnansweredCallWaitTime.
• You don’t need to specify the “sip:” prefix for the user you’re changing, or when adding new Delegates or Team Call members.
• Remote PowerShell to the SEFAUtil Server may not work. (If you have been able to resolve this, please ping me directly so I can update the post, or add some comments below).
• The otherwise innocuous “Enable-CsTopology” command has a bit of a chequered history. Depending on the patch version of your Front-Ends, running it might stop calls presenting to Response Group agents. Refer this Kb article.

Debugging

Here are a handful of bugs you might encounter and hopefully the fixes for them:

SEFAUtil Server Service won’t start

This one will be logged in Event Viewer under Windows Logs / Application: EventID 1024

.NET Runtime version : 4.0.30319.34014 - This application could not be started.This application requires one of the following versions of the .NET Framework:
 .NETFramework,Version=v4.5.2
Do you want to install this .NET Framework version now?

Fix: install this .NET Framework version now! (Refer Prep Step 2B).

Certificate problem

Also under Windows Logs / Application: EventID 0

Error in GetCsUserForwarding
FailureReason=IncorrectNameInRemoteCertificate
The target principal name is incorrect
Microsoft.Rtc.Internal.Sip.TLSException: outgoing TLS negotiation failed; Wrong target principal name configured.

Fix: One of the SANs in the DNS list up in “Preparation” is missing from the certificate on the Front-End server. Pounds to peanuts it’s the “sipinternal” A record.

No endpoint listening

There was no endpoint listening at net.pipe://localhost/landistechnologiesLLC/SefautilServer that could accept the message.

Fix: The SEFAUtil Server Service isn’t running.

Not Registered

To use this feature, you need to register this installation of SefautilServer. Run the Set-SefautilServerRegistration cmdlet.

Fix: It looks like you’ve missed the Registration step. Return to Installation Step 8.

Missing SRV Record

Windows Logs / Application: EventID 0

ResponseCode=504 ResponseText=Server time-out
Reason=Unable to resolve DNS SRV record
Microsoft.Rtc.Signaling.RegisterException:The endpoint was unable to register. See the ErrorCode for specific reason.

Fix: Annoyingly it doesn’t say which one, but it shouldn’t take you long. In my testing it became apparent that the absence of this record *won’t* automatically generate the above error.

Internal Error

This is a generic catch-all error, manifesting itself in response to PowerShell commands to the SEFAUtil Server module:

The server was unable to process the request due to an internal error

Fix: This one could be lots of things.

If you get it in response to *every* command (and perhaps you’ve not yet commissioned SEFAUtil server):

• Check the Windows Logs / Application event log for more detailed information.
• Is the SEFAUtil Server service running?
• Check the server is able to resolve at least ONE of the DNS names in Preparation Step 3. The absence of these won’t necessarily log anything to the Event Log.
• Check the Topology commandlets in Installation Step 2. Did that process complete without errors?
• If you ran Installation Step 2 before the SEFAUtil server had been built and attached to the domain, re-run “Enable-CsTopology”
• Open an elevated Command window at C:\Program Files\Skype for Business Server 2015\Deployment and run “bootstrapper.exe” (with no other parameters).
• Patch the server?
• Reboot the sucker! Seriously: I know it’s low-tech, but I battled this error for an hour through the deployment stage on my new server and what got me past it was a reboot!
• Only once you’ve exhausted all above I’d suggest you consider updating the cert on ALL Front-End servers in the pool adding “sipinternal.<YourSIPDomain>” as a SAN.

If it’s only in response to certain commands:

• Bad input format. Perhaps you’ve not correctly formatted the input fields.
• You’ve mistyped the user’s SIP address. An EventId=0 error saying “404 /Reason=User does not exist” will have been logged under Windows Logs / Application.

References & more reading

Thanks to those who’ve asked and answered questions on the support forum. Some of the above has been sourced directly from there, although the meat of this post is from 4+ separate installations in two unrelated forests, with many different attempts to break and repair it.

• The Trusted App setup steps have been shamelessly appropriated from James Cussen’s Call Pickup Group Manager post.
• The command-line based server install came from this TechNet article.
• SEFAUtil Server DNS Record requirements.
• Matt’s Trusted App installation steps.
• Details on using SEFAUTIL Server.
• The Yammer community-based support forum.

Revision History

7th March 2017. This is the initial release.
8th March 2017. Corrected references to DNS requirements. Thanks Japheth.
28th March 2018. Added the warning about Enable-CsTopology to the Traps section. Thanks to my colleague Andrew for bringing this shortcoming to my attention.
22nd August 2019: Updated the “tel”: issue in Tips, noting it has been fixed in the 2019 update.
5th October 2019: Updated the download link.
 

– G.