Edit

Share via

Initialize-HgsServer

Module:
HgsServer Module

Initializes the Host Guardian Service server.

Syntax

PrimaryServer_HgsDomain (Default) 

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>]

PrimaryServer_SecureDomain 

Initialize-HgsServer
    [-HgsServiceName] <String>
    -JeaAdministratorsGroup <ADGroup>
    -JeaReviewersGroup <ADGroup>
    -ServiceAccount <ADServiceAccount>
    [-UseExistingDomain]
    [-LogDirectory <String>]
    [-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>]

AdditionalServer 

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.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_SecureDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Confirm

Prompts you for confirmation before running the cmdlet.

Parameter properties

Type:SwitchParameter
Default value:False
Supports wildcards:False
DontShow:False
Aliases:cf

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-EncryptionCertificatePassword

Specifies the password for the certificate file specified in EncryptionCertificatePath.

Parameter properties

Type:SecureString
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_HgsDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
PrimaryServer_SecureDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-EncryptionCertificatePath

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

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_HgsDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
PrimaryServer_SecureDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-EncryptionCertificateThumbprint

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

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_HgsDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
PrimaryServer_SecureDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Force

Forces the command to run without asking for user confirmation.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HgsServerIPAddress

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

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

AdditionalServer
Position:1
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HgsServiceName

Specifies the HGS name.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_HgsDomain
Position:1
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
PrimaryServer_SecureDomain
Position:1
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HgsVersion

Reserved for future use.

Parameter properties

Type:HgsVersion
Default value:$script:HgsSupportedLevels[0]
Accepted values:HgsVersion1503, HgsVersion1704
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_HgsDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
PrimaryServer_SecureDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Http

Indicates that the HGS server is accessible over HTTP.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HttpPort

Specifies the HTTP port of the HGS server.

Parameter properties

Type:UInt16
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Https

Indicates that the HGS server is accessible over HTTPS.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HttpsCertificatePassword

Specifies the password to the certificate file identified by HttpsCertificatePath.

Parameter properties

Type:SecureString
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HttpsCertificatePath

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

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HttpsCertificateThumbprint

Indicates the thumbprint of the HTTPS certificate.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HttpsPort

Specifies the HTTPS port of the HGS server.

Parameter properties

Type:UInt16
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-JeaAdministratorsGroup

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

Parameter properties

Type:ADGroup
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_SecureDomain
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-JeaReviewersGroup

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

Parameter properties

Type:ADGroup
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_SecureDomain
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-LogDirectory

Specifies the directory for the output log.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments: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.

Parameter properties

Type:ADServiceAccount
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_SecureDomain
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-SigningCertificatePassword

Specifies the password for the certificate file identified by SigningCertificatePath.

Parameter properties

Type:SecureString
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_HgsDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
PrimaryServer_SecureDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-SigningCertificatePath

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

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_HgsDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
PrimaryServer_SecureDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-SigningCertificateThumbprint

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

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_HgsDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
PrimaryServer_SecureDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TrustActiveDirectory

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.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_HgsDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
PrimaryServer_SecureDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TrustTpm

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.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_HgsDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
PrimaryServer_SecureDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments: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.

Parameter properties

Type:SwitchParameter
Default value:False
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_SecureDomain
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-UseHgsDomain

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

Parameter properties

Type:SwitchParameter
Default value:False
Supports wildcards:False
DontShow:False

Parameter sets

PrimaryServer_HgsDomain
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-WhatIf

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

Parameter properties

Type:SwitchParameter
Default value:False
Supports wildcards:False
DontShow:False
Aliases:wi

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.