New-HybridConfiguration

This cmdlet is available only in on-premises Exchange.

Use the New-HybridConfiguration cmdlet to create the HybridConfiguration object and set up a hybrid deployment between your on-premises Exchange organization and a Microsoft 365 for enterprises organization.

For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax.

Syntax

New-HybridConfiguration
   [-ClientAccessServers <MultiValuedProperty>]
   [-Confirm]
   [-DomainController <Fqdn>]
   [-Domains <MultiValuedProperty>]
   [-EdgeTransportServers <MultiValuedProperty>]
   [-ExternalIPAddresses <MultiValuedProperty>]
   [-Features <MultiValuedProperty>]
   [-OnPremisesSmartHost <SmtpDomain>]
   [-ReceivingTransportServers <MultiValuedProperty>]
   [-SecureMailCertificateThumbprint <String>]
   [-SendingTransportServers <MultiValuedProperty>]
   [-ServiceInstance <Int32>]
   [-TlsCertificateName <SmtpX509Identifier>]
   [-TransportServers <MultiValuedProperty>]
   [-WhatIf]
   [<CommonParameters>]

Description

A hybrid deployment offers organizations the ability to extend the feature-rich experience and administrative control they have with their existing on-premises Microsoft Exchange organization to the cloud. The New-HybridConfiguration cmdlet is used with the Hybrid Configuration wizard and is typically configured when the hybrid deployment is initially created by the wizard. We strongly recommend that you use the Hybrid Configuration wizard to create the HybridConfiguration object and configure your hybrid deployment with the Exchange Online organization.

For more information, see Exchange Server hybrid deployments.

You need to be assigned permissions before you can run this cmdlet. Although this topic lists all parameters for the cmdlet, you may not have access to some parameters if they're not included in the permissions assigned to you. To find the permissions required to run any cmdlet or parameter in your organization, see Find the permissions required to run any Exchange cmdlet.

Examples

Example 1

New-HybridConfiguration

This example creates the hybrid configuration named Hybrid Configuration with the default hybrid configuration settings.

Parameters

-ClientAccessServers

This parameter is available only in Exchange Server 2010.

The ClientAccessServers parameter specifies the Exchange Server 2010 SP2 servers with the Client Access server role installed that will be configured to support the hybrid deployment features. At least one Client Access server must be defined and be externally accessible from the Internet on ports 80 and 443. The servers will be configured to enable the following:

  • Mailbox Replication Service (MRS) Proxy The MRS Proxy service configuration on the Client Access servers will be enabled.
  • Virtual Directories The Client Access servers will host the default Web sites for the Exchange Web Services (EWS), offline address books, and ActiveSync services.
  • Outlook Anywhere The Client Access servers will have Outlook Anywhere enabled.
Type:MultiValuedProperty
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Server 2010

-Confirm

The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding.

  • Destructive cmdlets (for example, Remove-* cmdlets) have a built-in pause that forces you to acknowledge the command before proceeding. For these cmdlets, you can skip the confirmation prompt by using this exact syntax: -Confirm:$false.
  • Most other cmdlets (for example, New-* and Set-* cmdlets) don't have a built-in pause. For these cmdlets, specifying the Confirm switch without a value introduces a pause that forces you acknowledge the command before proceeding.
Type:SwitchParameter
Aliases:cf
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False
Applies to:Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019

-DomainController

The DomainController parameter specifies the domain controller that's used by this cmdlet to read data from or write data to Active Directory. You identify the domain controller by its fully qualified domain name (FQDN). For example, dc01.contoso.com.

Type:Fqdn
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False
Applies to:Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019

-Domains

The Domains parameter specifies the domain namespaces that are used in the hybrid deployment. These domains must be configured as accepted domains in either the on-premises Exchange organization or the Exchange Online service. The domains are used in configuring the organization relationships and Send and Receive connectors used by the hybrid configuration.

Type:MultiValuedProperty
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019

-EdgeTransportServers

The EdgeTransportServers parameter specifies the Edge Transport servers that are configured to support the hybrid deployment features. The Edge Transport server must be externally accessible from the Internet on port 25. The accepted values for the EdgeTransportServers parameter are either the full or short computer name of an Edge Transport server, for example, either edge.corp.contoso.com or EDGE. Separate server names with a comma if defining more than one Edge Transport server.

When configuring the EdgeTransportServers parameter, you must configure the ReceivingTransportServers and SendingTransportServers parameter values to $null.

Type:MultiValuedProperty
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Server 2013, Exchange Server 2016, Exchange Server 2019

-ExternalIPAddresses

The ExternalIPAddresses parameter is a legacy parameter that specifies the publicly accessible inbound IP address of Microsoft Exchange Server 2010 Hub Transport servers. The only configuration change that should be made with this parameter is to change or clear the legacy Exchange 2010 Hub Transport server IP address value. The IP address must be Internet Protocol version 4 (IPv4) based only.

Type:MultiValuedProperty
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019

-Features

The Features parameter specifies the features that are enabled for the hybrid configuration. One or more of the following values separated by commas can be entered. When using the Hybrid Configuration wizard, all features are enabled by default.

  • OnlineArchive: Enables the Exchange Online archive for on-premises Exchange and Exchange Online organization users.
  • FreeBusy: Enables free/busy calendar information to be shared between on-premises Exchange and Exchange Online organization users.
  • MailTips: Enables MailTips information to be shared between on-premises Exchange and Exchange Online organization users.
  • MessageTracking: Enables message tracking information to be shared between on-premises Exchange and Exchange Online organization users.
  • OWARedirection: Enables automatic Microsoft Outlook on the web redirection to either the on-premises Exchange or Exchange Online organizations depending on where the user mailbox is located.
  • SecureMail: Enables secure message transport via Transport Layer Security (TLS) between the on-premises Exchange and Exchange Online organizations.
  • Centralized: Enables the on-premises servers to handle all message transport between the on-premises Exchange and Exchange Online organizations, including message delivering to the Internet for both organizations. If this value is $false, the on-premises server and Exchange Online organization are each responsible for their own Internet message delivery.
  • Photos: Enables the sharing of user photo data between the on-premises Exchange and Exchange Online organizations. This feature works in tandem with the PhotosEnabled parameter in the OrganizationRelationship cmdlets in a hybrid deployment. If the Photos parameter is $true, the PhotosEnabled parameter is automatically set to $true. If the Photos parameter is $false, the PhotosEnabled parameter is automatically set to $false. When running the Hybrid Configuration wizard for the first time, the default value is $true.
Type:MultiValuedProperty
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019

-OnPremisesSmartHost

The OnPremisesSmartHost parameter specifies the FQDN of the on-premises Mailbox server used for secure mail transport for messages sent between the on-premises Exchange and Exchange Online organizations.

Type:SmtpDomain
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019

-ReceivingTransportServers

The ReceivingTransportServers parameter specifies the Mailbox servers that are defined in the outbound connector configuration of the Microsoft Exchange Online Protection (EOP) service included as part of the Microsoft 365 organization. The servers defined in the ReceivingTransportServers parameter are designated as the receiving servers for secure mail messages sent from the Exchange Online organization to the on-premises Exchange organization in a hybrid deployment. At least one Mailbox server must be defined and be externally accessible from the Internet for secure mail to be enabled between the on-premises Exchange and Exchange Online organizations. The accepted values for the ReceivingTransportServers parameter are either the full or short computer name of a Mailbox server, for example, either mbx.corp.contoso.com or MBX. Separate server names with a comma if defining more than one Mailbox server.

If configuring the EdgeTransportServers parameter in the hybrid deployment, the ReceivingTransportServers parameter value must be $null.

Type:MultiValuedProperty
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Server 2013, Exchange Server 2016, Exchange Server 2019

-SecureMailCertificateThumbprint

This parameter is available only in Exchange Server 2010.

The SecureMailCertificateThumbprint parameter specifies the thumbprint of the X.509 certificate to be used as the certificate for hybrid deployment secure message transport. This certificate cannot be self-signed, must be obtained from a trusted certificate authority (CA) and must be installed on all Hub Transport servers defined in the TransportServers parameter.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Server 2010

-SendingTransportServers

The SendingTransportServers parameter specifies the Exchange Mailbox servers that are defined in the inbound connector configuration of the EOP service included as part of the Microsoft 365 organization. The servers defined in the SendingTransportServers parameter are designated as the receiving servers for secure mail messages sent from the on-premises Exchange organization to the Exchange Online organization in a hybrid deployment. At least one Mailbox server must be defined and be externally accessible from the Internet for secure mail to be enabled between the on-premises Exchange and Exchange Online organizations. The accepted values for the SendingTransportServers parameter are either the full or short computer name of a Mailbox server, for example, either mbx.corp.contoso.com or MBX. Separate server names with a comma if defining more than one Mailbox server.

If configuring the EdgeTransportServers parameter in the hybrid deployment, the SendingTransportServers parameter value must be $null.

Type:MultiValuedProperty
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Server 2013, Exchange Server 2016, Exchange Server 2019

-ServiceInstance

The ServiceInstance parameter should only be used by organizations manually configuring hybrid deployments with Office 365 operated by 21Vianet in China. All other organizations should use the Hybrid Configuration wizard to configure a hybrid deployment with Microsoft 365. The valid values for this parameter are 0 (null) or 1. The default value is 0 (null).For organizations connecting with Office 365 operated by 21Vianet in China, set this value to 1 when manually configuring your hybrid deployment.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Server 2013, Exchange Server 2016, Exchange Server 2019

-TlsCertificateName

The TlsCertificateName parameter specifies the X.509 certificate to use for TLS encryption. A valid value for this parameter is "<I>X.500Issuer<S>X.500Subject". The X.500Issuer value is found in the certificate's Issuer field, and the X.500Subject value is found in the certificate's Subject field. You can find these values by running the Get-ExchangeCertificate cmdlet. Or, after you run Get-ExchangeCertificate to find the thumbprint value of the certificate, run the command $TLSCert = Get-ExchangeCertificate -Thumbprint <Thumbprint>, run the command $TLSCertName = "<I>$($TLSCert.Issuer)<S>$($TLSCert.Subject)", and then use the value $TLSCertName for this parameter.

Type:SmtpX509Identifier
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Server 2013, Exchange Server 2016, Exchange Server 2019

-TransportServers

This parameter is available only in Exchange Server 2010.

The TransportServers parameter specifies the Exchange Server 2010 SP2 servers with the Hub Transport server role installed that are configured to support the hybrid deployment features. At least one Hub Transport server must be defined and be externally accessible from the Internet for secure mail to be enabled between the on-premises and cloud-based organizations.

Type:MultiValuedProperty
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Server 2010

-WhatIf

The WhatIf switch simulates the actions of the command. You can use this switch to view the changes that would occur without actually applying those changes. You don't need to specify a value with this switch.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False
Applies to:Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019

Inputs

Input types

To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn't accept input data.

Outputs

Output types

To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn't return data.