Hybrid Agent Installation

Der Hybrid Agent wird durch den HCW - Hybrid Configuration Wizard bei Auswahl von "Modern hybrid" installiert. Eine andere manuelle Installation des Agenten ist möglich aber dann fehlen die passenden Einstellungen beim Migration Endpoint etc.

Installation

Den "Modern Hybrid Weg" installieren Sie wie alle anderen Hybrid Konfigurationen über den HCW - Hybrid Configuration Wizard. Dort gibt es mittlerweile an einer Stelle aber eine neue Auswahlbox

Ich habe farblich die kleinen Unterschiede in der Beschriftung markiert. Der Client Access Service, seit Exchange 2016 auch "Frontend" genannt, muss natürlich mit Office 365 kommunizieren können aber braucht selbst nicht mehr aus dem Internet erreichbar zu sein, da der Agent eine ausgehende Verbindung zum Azure AS Application Proxy aufbaut. Der HCW installiert dabei den erforderlichen Agenten auf dem dem CAS-Server, der im HCW schon ausgewählt wurde.

Sie können die beiden MSI-Dateien auch manuell herunterladen und installieren. Allerdings hat bei mir die Installation per "Doppelklick" nicht funktioniert. Wen ich die Installation aber aus einer Admin-Shell mit MSIEXEC gestartet habe, dann wurde der hybrid Agent nicht nur installiert, sondern ich habe auch die Eingabemaske für die erforderlichen Zugangsdaten erhalten.

REM Optional installation des Hybrid Agenten aus Admin Shell mit Logging


msiexec /i MSHybridAutoUpdater.msi /l* MSHybridAutoUpdater.log
msiexec /i MSHybridService.msi /l* MSHybridService.log

Es bietet sich dann auch gleich an, eine Protokolldatei schreiben zu lassen. Mögliche Fehler sind dann einfacher zu ermitteln.

Logfile Analyse

Wenn Sie MSIEXEC mit Protokollierung genutzt haben, dann finden Sie im Logfile auch die ein oder andere Information, z.B:

Action start 00:33:42: InstallFinalize.
SFXCA: Extracting custom action to temporary directory: C:\Windows\Installer\MSIB935.tmp-\
SFXCA: Binding to CLR version v4.0.30319
Calling custom action Microsoft.ApplicationProxy.Connector.Installer.InvokePowerShellCA!Microsoft.ApplicationProxy.Connector.Installer.InvokePowerShellCA.RegisterConnector
Starting RegisterConnector CustomAction
Invoking powershell script from path 'C:\Program Files\Microsoft Hybrid Service\RegisterConnector.ps1'
Powershell script returned successfully

Das Skript startet nach der Installation ein Powershell zur Registrierung des Agenten. Leider sehe ich hier nicht die Parameter, mit denen das Skript aufgerufen wird.

Property(S): RegisterConnectorCAParameters = PSMODULESFOLDER=C:\Program Files\Microsoft Hybrid Service\Modules\; 
                  PSMODULENAME=AppProxyPSModule; 
                  SCRIPTPATH=C:\Program Files\Microsoft Hybrid Service\RegisterConnector.ps1; 
                  Feature=ExchangeOnline; 
                  REGISTRATIONHOST=registration.msappproxy.net; 
                  REGISTRATIONSCHEME=https
Property(S): RegisterConnectorFlag = true
Property(S): DISABLEPROXYRESPONSEPORTFALLBACKVALUE = #+1
Property(S): RunSetServiceStartupTypeScript = "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" 
                  -ExecutionPolicy Bypass 
                  -File "C:\Program Files\Microsoft Hybrid Service\SetServiceStartupType.ps1" "mshybridsvc"
Property(S): REMOVECONNECTORREGISTRYKEY = "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe"  
                  -ExecutionPolicy Bypass  
                  -Command (Remove-Item -Path 'Registry::HKLM\SOFTWARE\Microsoft\Microsoft Hybrid Service')
Property(S): RegisterConnectorCA = PSMODULESFOLDER=C:\Program Files\Microsoft Hybrid Service\Modules\; 
                  PSMODULENAME=AppProxyPSModule; 
                  SCRIPTPATH=C:\Program Files\Microsoft Hybrid Service\RegisterConnector.ps1; 
                  Feature=ExchangeOnline; 
                  REGISTRATIONHOST=registration.msappproxy.net; 
                  REGISTRATIONSCHEME=https
Property(S): ExecServiceConfig = SchedServiceConfig€mshybridsvc€1€restart€restart€restart€1€30€€

Der Code in "RegisterConnector.ps1" macht dann im Wesentlichen:

# if registrationHost parameter was passed with a value then this is a registration attempt for a private registration service
# The installation will not pass this value in retail builds or debug build without the registartion host and registration scheme arguments passed to installation cmdline
Import-Module AppProxyPSModule
$params = @{}
$params.add("RegistrationScheme", $RegistrationScheme)    #https
$params.add("RegistrationHost", $RegistrationHost)        #registration.msappproxy.net
$params.add("Feature", $Feature)                          #ExchangeOnline
Register-AppProxyConnector @params                        # Fragt dann nach den Zugangsdaten

Ich interpretiere dies so, dass der HybridAgent eigentlich der normale "AppProxy" Agent mit einer "privaten Registrierung" ist. Die Commandlets in dem PowerShell-Modul sind:

PS C:\> Import-Module AppProxyPSModule
PS C:\> get-command -Module appproxypsmodule

CommandType   Name                             Version  Source
-----------   ----                             -------  ------
Cmdlet        Enable-AppProxyConnector         1.0.0.0  AppProxyPSModule
Cmdlet        Register-AppProxyConnector       1.0.0.0  AppProxyPSModule
Cmdlet        Set-AppProxyConnectorADFSTrust   1.0.0.0  AppProxyPSModule
Cmdlet        Unregister-AppProxyConnector     1.0.0.0  AppProxyPSModule

Wenn Sie ein "Register-AppProxyConnector manuell starten, werden Sie nach den Anmeldedaten für ihren Tenant gefragt und am Ende erfolgt nur ein HTTP-Request:

 

Das erfolgt nicht über Graph und die Authentifizierung ist im XML-Payload als "AuthenticationToken" hinterlegt. Das verwendete Token hat folgende Properties (gekürzt):

{
  "typ": "JWT",
  "alg": "RS256",
}.{
  "aud": "https://proxy.cloudwebappproxy.net/registerapp",
  "iss": "https://sts.windows.net/463e98ae-b7d4-4af2-8ef8-3eda0b4d8a7c/",
  "appid": "55747057-9b5d-4bd4-b387-abf52a8bd489",
  "scp": "user_impersonation",
  "unique_name": "fcadmin@msxfaqlab.onmicrosoft.com",
  "upn": "fcadmin@msxfaqlab.onmicrosoft.com",
}.[Signature]

Ein Unregister-AppProxyConnector hingegen scheint einfach nur den lokalen Dienst zu stoppen. Eine Kommunikation zur Cloud konnte ich nicht erkennen.

Bislang musste ich diese CMDLets aber nie manuell verwenden. Entweder hat HCW schon alles installiert oder die manuelle Installation mit MSIEXEC hat alle Probleme beseitigt.

Fiddler

Wussten Sie, dass der HCW ihre HTTP-Proxy-Konfiguration berücksichtigt und sie damit die Schritte bei der Einrichtung analysieren können? Hier ein paar Ausschnitte:

  • Suche und Download
    Sobald sie Modern hybrid ausgewählt und die Installation gestartet haben, sehen Sie in Fiddler die beide Downloads von " MSHybriAutoUpdater.msi" und " MSHybridService.msi".

    Davor sucht er nach bestehenden Connectoren und danach aktualisiert er ggfls. den Connector.
  • Register
    Interessant ist auch der Aufruf, welchen den Agenten in der Cloud einträgt

    Die Authentifizierung erfolgt über ein Bearer-Token in der JSON-Payload und nicht im HTTP-Request-Header
    Ich konnte aber nie einen "Unregister" bei der Deinstallation sehen ()
  • Suche nach Agent
    Ob der Agent dann richtig registriert wurde oder auch bei einem Update noch vorhanden ist, bekomme wir über einen Graph-Aufruf, den ich auch bei Hybrid Agent Status weiter verwende:

Es kann also durchaus mal hilfreich sein, mit Fiddler mitzulesen, insbesondere bei Fehlern bei der Installation.

Ergebnisse

Danach finden Sie den Agenten unter den Diensten:

Er steht auf "Autostart" und läuft als "Network System".

Auch in der Registrierung finden Sie einige Hinweise. Hier erscheint auch der Port 8080 wieder.

Wie es sich für jede Windows-basierte Software gehört, stellt auch der Hybrid Agent mehrere Performance Counter bereit. Hier kann der Agent nicht verleugnen, dass er eigentlich doch ein App Proxy Connector ist.

 

Analyse und Troubleshooting

Nur weil sie nun einen Agenten in ihrem LAN haben, der von innen nach extern zur Cloud kommuniziert und dann eine lokale Verbindung zum Exchange Server aufbaut, kann immer noch viel schief gehen

  • Proxy zum Internet
    Der größte Stolperstein ist in der Regel ein ausgehender Proxy mit Authentifizierung oder Deep Inspection etc. Für die Nutzung eines Proxy muss der Hybrid Agent manuell konfiguriert werden, in dem über das Skript "C:\Program Files\Microsoft Hybrid Service\ConfigureOutBoundProxy.ps1" der Proxy in die Datei "Microsoft.Online.EME.Hybrid.Agent.Service.exe.config" eingetragen wird.
    https://learn.microsoft.com/en-us/exchange/hybrid-deployment/hybrid-agent#proxy-server-considerations
  • TLS 1.2
    Auch die HTTPS-Verschlüsselung ist mittlerweile mindestens TLS 1.2. Wenn das eine Firewall oder ein Proxy immer noch nicht kann, dann wird es an der Zeit das zu ändern.
  • Interne Ports
    Der Server, auf dem der Hybrid-Agent läuft, sollte nicht in einer DMZ stehen sondern am besten neben den Exchange Servern, damit keine Firewall die interne Kommunikation stört. Es werden nämlich nicht nur der Port 443 zum Exchange Frontend-Server benötigt, sondern auch 80, 5985(WinRM/HTTP) und 5986 (WinRM/HTTPS)

Es ist daher immer ein guter Ansatzpunkt sich die "System requirements "https://learn.microsoft.com/en-us/exchange/hybrid-deployment/hybrid-agent#system-requirements" noch einmal genau durchzulesen und auf Firewall/ProxyServer ein Logging für die IP-Adresse des installierten HCW zu aktivieren.

Für die Fehlersuche hat Microsoft schon einen sehr ausführlichen Artikel auf dem Exchange Team Blog veröffentlicht:

Wenn es dann aber immer noch nicht geht, dann ist ein Blick in die Protokolldateien, Eventlogs etc. angesagt und etwas Glück und viel Erfahrung

Wenn Sie nicht weiter kommen, dann können Sie uns gerne mit der Unterstützung beauftragen. Net at Work und MSXFAQ

Weitere Links