Edit

Share via

Initialize-HgsServer

  • Reference
Module:
HgsServer

Initializes the Host Guardian Service server.

Syntax

Initialize-HgsServer
          [-HgsServiceName] <String>
          [-UseHgsDomain]
          [-LogDirectory <String>]
          [-Http]
          [-Https]
          [-HttpPort <UInt16>]
          [-HttpsPort <UInt16>]
          [-HttpsCertificatePath <String>]
          [-HttpsCertificatePassword <SecureString>]
          [-HttpsCertificateThumbprint <String>]
          [-TrustActiveDirectory]
          [-TrustTpm]
          [-EncryptionCertificateThumbprint <String>]
          [-EncryptionCertificatePath <String>]
          [-EncryptionCertificatePassword <SecureString>]
          [-SigningCertificateThumbprint <String>]
          [-SigningCertificatePath <String>]
          [-SigningCertificatePassword <SecureString>]
          [-HgsVersion <HgsVersion>]
          [-Force]
          [-WhatIf]
          [-Confirm]
          [<CommonParameters>]
Initialize-HgsServer
          [-HgsServiceName] <String>
          [-UseExistingDomain]
          [-LogDirectory <String>]
          -JeaAdministratorsGroup <ADGroup>
          -JeaReviewersGroup <ADGroup>
          -ServiceAccount <ADServiceAccount>
          [-ClusterName <String>]
          [-Http]
          [-Https]
          [-HttpPort <UInt16>]
          [-HttpsPort <UInt16>]
          [-HttpsCertificatePath <String>]
          [-HttpsCertificatePassword <SecureString>]
          [-HttpsCertificateThumbprint <String>]
          [-TrustActiveDirectory]
          [-TrustTpm]
          [-EncryptionCertificateThumbprint <String>]
          [-EncryptionCertificatePath <String>]
          [-EncryptionCertificatePassword <SecureString>]
          [-SigningCertificateThumbprint <String>]
          [-SigningCertificatePath <String>]
          [-SigningCertificatePassword <SecureString>]
          [-HgsVersion <HgsVersion>]
          [-Force]
          [-WhatIf]
          [-Confirm]
          [<CommonParameters>]
Initialize-HgsServer
          [-HgsServerIPAddress] <String>
          [-LogDirectory <String>]
          [-Http]
          [-Https]
          [-HttpPort <UInt16>]
          [-HttpsPort <UInt16>]
          [-HttpsCertificatePath <String>]
          [-HttpsCertificatePassword <SecureString>]
          [-HttpsCertificateThumbprint <String>]
          [-Force]
          [-WhatIf]
          [-Confirm]
          [<CommonParameters>]

Description

The Initialize-HgsServer cmdlet configures the necessary infrastructure components for Host Guardian Service (HGS) after it is rebooted.

This cmdlet performs the following configuration actions on infrastructure components of the first HGS node:

  • Creates one-node failover cluster.
  • Configures a failover cluster with a distributed network name resource corresponding to the fully qualified domain name of the HGS name: <HgsServerName>.<LocalDomain>.
  • Registers and configures the Attestation service web application with the IIS service.
  • Registers and configures the Key Protection service web application with the IIS service.
  • Configures the Attestation service signer certificate with the Key Protection service.
  • Enables Just Enough Administration on the local node.

This cmdlet makes the following configuration changes to components on an additional HGS node:

  • Adds the local node to the existing failover cluster on a node specified by the HgsServerIPAddress parameter using the credential specified in the HgsDomainCredential parameter.

  • Registers and configures the Attestation service web application with the IIS service.

  • Registers and configures the Key Protection service web application with the IIS service.

  • Configures the Attestation service signer certificate with the Key Protection service.

  • Enables Just Enough Administration on the local node.

For more information about the scenario terms, see Security and Assurance.

Examples

Example 1: Initialize the HGS on the primary node in TPM mode

PS C:\> Initialize-HgsServer -HgsServiceName "SecureFabricHgs" -EncryptionCertificateThumbprint $EncryptionCert.Thumbprint -SigningCertificateThumbprint $SigningCert.Thumbprint

This command initializes the HGS server on the primary node. By default, the server is accessible on HTTP port 80 and the Attestation service is set to TPM mode. The specified certificates are used by the Key Protection service.

Example 2: Initialize the HGS on a secondary node in TPM mode

PS C:\> $Cred = Get-Credential
PS C:\> Initialize-HgsServer -HgsServerIPAddress "100.100.100.1" -HgsDomainCredential $Cred

This command initializes the HGS server on a secondary node. By default, the server is accessible on HTTP port 80 and the Attestation service is set to TPM mode. The Key Protection service uses the encryption and signing certificates set by the primary server.

Example 3: Initialize the HGS on the primary node in Active Directory mode

PS C:\> Initialize-HgsServer -TrustActiveDirectory -HgsServiceName "SecureFabricHgs" -EncryptionCertificateThumbprint $EncryptionCert.Thumbprint -SigningCertificateThumbprint $SigningCert.Thumbprint

This command initializes the HGS server on the primary node and sets the Attestation service to Active Directory (AD) mode. By default, the server is accessible on HTTP port 80. The specified certificates are used by the Key Protection service.

Example 4: Initialize the HGS on the primary node in TPM mode and enable HTTPS

PS C:\> Initialize-HgsServer -HgsServiceName "SecureFabricHgs" -EncryptionCertificateThumbprint $EncryptionCert.Thumbprint -SigningCertificateThumbprint $SigningCert.Thumbprint -http -https -HttpsCertificatePath $PathToPfx -HttpsCertificatePassword $PfxSecureString

This command initializes the HGS server on the primary node. The server is set to be accessible by HTTP and HTTPS on the default ports, and with the specified certificate for HTTPS. By default, the server is accessible on HTTP port 80 and the Attestation service is set to TPM mode. The specified certificates are used by the Key Protection service.

Parameters

-ClusterName

Specifies a cluster name.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-EncryptionCertificatePassword

Specifies the password for the certificate file specified in EncryptionCertificatePath.

Type:SecureString
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-EncryptionCertificatePath

Specifies the path to the encryption certificate used by the Key Protection service.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-EncryptionCertificateThumbprint

Specifies the thumbprint of the encryption certificate used by the Key Protection service.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

Forces the command to run without asking for user confirmation.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HgsServerIPAddress

Specifies the IP address of the HGS server that is a domain controller for the specified HGS domain.

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-HgsServiceName

Specifies the HGS name.

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-HgsVersion

Reserved for future use.

Type:HgsVersion
Accepted values:HgsVersion1503, HgsVersion1704
Position:Named
Default value:$script:HgsSupportedLevels[0]
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Http

Indicates that the HGS server is accessible over HTTP.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HttpPort

Specifies the HTTP port of the HGS server.

Type:UInt16
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Https

Indicates that the HGS server is accessible over HTTPS.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HttpsCertificatePassword

Specifies the password to the certificate file identified by HttpsCertificatePath.

Type:SecureString
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HttpsCertificatePath

Specifies the path to the HTTPS certificate file (.pfx).

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HttpsCertificateThumbprint

Indicates the thumbprint of the HTTPS certificate.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HttpsPort

Specifies the HTTPS port of the HGS server.

Type:UInt16
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-JeaAdministratorsGroup

Identifies the Active Directory group of users who can administer HGS through Just Enough Administration.

Type:ADGroup
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-JeaReviewersGroup

Identifies the Active Directory group of users who can view, but not change, HGS settings through Just Enough Administration.

Type:ADGroup
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-LogDirectory

Specifies the directory for the output log.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ServiceAccount

Identifies the Group Managed Service Account that will be used for the Key Protection Service. The specified account must already be installed and configured for use on this machine.

Type:ADServiceAccount
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-SigningCertificatePassword

Specifies the password for the certificate file identified by SigningCertificatePath.

Type:SecureString
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SigningCertificatePath

Specifies the path to the signing certificate for use by the Key Protection service.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SigningCertificateThumbprint

Specifies the thumbprint of the signing certificate for use by the Key Protection service.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TrustActiveDirectory

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TrustTpm

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UseExistingDomain

Indicates that HGS was joined to an existing domain and did not establish its own domain (with Install-HgsServer). HGS must already be joined to the existing domain to continue.

Type:SwitchParameter
Position:Named
Default value:False
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-UseHgsDomain

Indicates that HGS was set up with its own dedicated Active Directory forest using the Install-HgsServer cmdlet.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False