Share via

Configuration How To Topics

  • Article

This section contains a set of common how-to tasks related to configuring the Service Bus for Windows Server.

Service Bus Configuration How-to

  • How to rename a machine that is part of a Service Bus farm

  • How to rename the SQL server computer

  • How to rename a user domain

  • How to move a Service Bus farm to a new domain

  • How to rename the Service Bus domain

  • How to modify the gateway or container database connection strings

  • How to upgrade the Service Bus farm

  • How to renew an expired certificate

  • How to renew a certificate that has not expired yet

  • How to change the password of the RunAs account

  • How to add or remove a user from the set of namespace managers

  • How to attach a message container to a Service Bus farm

  • How to change the namespace key

  • How to change the Service Bus runtime settings (quotas)

  • How to protect the Service Bus from brute force attacks that attempt to obtain domain passwords

  • How to install the Service Bus on a server not connected to the Internet

  • How to configure Service Bus with SQL Server 2012 High Availability using AlwaysOn

  • How to configure Service Bus when installed on Windows Azure Infrastructure As A Service (IaaS) VMs

How to rename a machine that is part of a Service Bus farm

To rename a Service Bus for Windows Server farm node, do the following:

  1. Call the Remove-SBHost cmdlet on the farm node that you want to rename.

  2. Rename and reboot the Service Bus for Windows Server farm node.

  3. If the Service Bus for Windows Server farm was created with the option to use an existing certificate, call the Add-SBHost cmdlet on the farm node that has been renamed with the following parameters:

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database.

    • RunAsPassword: SecureString that contains the password of the account under which the Service Bus for Windows Server processes run.

    • EnableFirewallRules: Set to true if the firewall rules of the host should be updated to allow for Service Bus data to traverse the firewall. Otherwise, false.

    If the Service Bus for Windows Server farm was created with the option to generate the farm certificate automatically, call the Add-SBHost cmdlet on the farm node that has been renamed with the following parameters:

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database.

    • RunAsPassword: SecureString that contains the password of the account under which the Service Bus for Windows Server processes run.

    • EnableFirewallRules: Set to true if the firewall rules of the host should be updated to allow for Service Bus data to traverse the firewall. Otherwise, false.

    • CertificateAutogenerationKey: SecureString that contains the passphrase to secure the new farm certificate that this cmdlet creates.

Note

If the Remove-SBHost cmdlet returns a warning saying that it could not delete the Windows Fabric directory, manually delete the hidden folder C:\ProgramData\Windows Fabric.

How to rename the SQL server computer

To rename the SQL server that hosts the Service Bus for Windows Server databases, do the following:

  1. Call Get-SBFarm and save the cmdllet output. You will use those parameters when you restore the farm.

  2. Call the Remove-SBHost cmdlet on all farm nodes.

  3. Rename and reboot SQL server.

  4. Call the Restore-SBFarm cmdlet with the following parameters. Execute this cmdlet on one of the farm nodes.

    • RunAsAccount: Account under which the Service Bus for Windows Server services run. This account must be the same account that you used for the old farm.

    • GatewayDBConnectionString: Connection string of the existing gateway database.

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database that this cmdlet created.

    • FarmCertificateThumbprint: Thumbprint of the farm certificate of the old Service Bus for Windows Server farm. The thumbprint is part of the data obtained in step 1. Alternatively, you can find the farm thumbprint in the Service Bus for Windows Server farm database [Store].[ServiceConfig] table under ConfigName SBEncryptionCertificateThumbprint.

    • MessageBrokerPort: Port used for message broker communication. This port must be the same port that you used for message broker communication in the old farm. If not specified, the default port is used.

    • HttpsPort: Port used for HTTPS communication. This port must be the same port that you used for HTTPS communication in the old farm. If not specified, the default port is used.

    • TCPPort: Port used for TCP communication. This port must be the same port that you used for TCP communication in the old farm. If not specified, the default port is used.

    The Restore-SBFarm cmdlet creates a new Service Bus for Windows Server farm database. You can delete the old Service Bus for Windows Server farm database.

  5. For each container, call the Restore-SBMessageContainer cmdlet with the following parameters. Execute this cmdlet on one of the farm machines.

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database that you created in the previous step.

    • ContainerDBConnectionString: Connection string of the container database.

    • ID: ID of the message container.

  6. If the Service Bus for Windows Server farm was created with the option to use an existing certificate, call the Add-SBHost cmdlet on the farm node that has been renamed. The certificate must be present on the machine. Execute the cmdlet with the following parameters:

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database that you created in step 4.

    • RunAsPassword: SecureString that contains the password of the account under which the Service Bus for Windows Server processes run.

    • EnableFirewallRules: Set to true if the firewall rules of the host should be updated to allow for Service Bus data to traverse the firewall. Otherwise, false.

  7. If the Service Bus for Windows Server farm was created with the option to generate the farm certificate automatically, call the Add-SBHost cmdlet with the following parameters. Execute the cmdlet on all new farm nodes:

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database that you created in step 4.

    • RunAsPassword: SecureString that contains the password of the account under which the Service Bus for Windows Server processes run.

    • EnableFirewallRules: Set to true if the firewall rules of the host should be updated to allow for Service Bus data to traverse the firewall. Otherwise, false.

    • CertificateAutogenerationKey: SecureString that contains the passphrase to secure the new farm certificate that this cmdlet created.

How to rename a user domain

The following example renames the user domain domainA to domainB. To restore access to entities and namespaces for the affected users, do the following:

  1. Call the Stop-SBFarm cmdlet on one of the farm nodes.

  2. Call the Rename-SBAuthorizationDomain cmdlet with the following parameters. Execute the cmdlet on one of the farm nodes:

    • Name: Name of the old domain.

    • NewName: Name of the new domain.

  3. Call the Start-SBFarm cmdlet on one of the farm nodes.

How to move a Service Bus farm to a new domain

The following example moves Service Bus for Windows Server farm nodes from domainA to domainB. Any users that are part of domainA are moved to domainB. To move the farm and users to a new domain, do the following:

  1. If you want to use your own certificate, install the farm certificate for the new domain on the Service Bus for Windows Server farm nodes.

  2. Call the Stop-SBFarm cmdlet on one of the farm nodes.

  3. Call the Rename-SBAuthorizationDomain cmdlet with the following parameters. Execute the cmdlet on one of the farm nodes:

    • Name: Name of the old domain.

    • NewName: Name of the new domain.

  4. Call the Remove-SBHost cmdlet on all farm nodes.

  5. Move all server nodes from domainA to domainB and restart the servers.

  6. If you want to use your own certificate, call the Restore-SBFarm cmdlet with the following parameters on one of the farm nodes:

    • GatewayDBConnectionString: Connection string of the existing gateway database.

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database that this cmdlet created.

    • CertificateAutoGenerationKey: SecureString that contains the passphrase to secure the new farm certificate that this cmdlet created.

    If you want to have the Service Bus for Windows Server generate a new farm certificate, call the Restore-SBFarm cmdlet with the following parameters on one of the new farm nodes:

    • GatewayDBConnectionString: Connection string of the existing gateway database.

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database that this cmdlet created.

    • FarmCertificateThumbprint: Thumbprint of the certificate you want to use as the farm certificate.

    • CertificateAutoGenerationKey: SecureString that contains the passphrase to secure the new farm certificate that this cmdlet created.

    The Restore-SBFarm cmdlet creates a new Service Bus for Windows Server farm database. You can delete the old Service Bus for Windows Server farm database.

  7. For each container database, call the Restore-SBMessageContainer cmdlet with the following parameters. Execute this cmdlet on one of the farm machines.

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database that you created in the previous step.

    • ContainerDBConnectionString: Connection string of the container database.

    • ID: ID of the restored message container.

    You can obtain the ID of the restored message container by calling the Get-SBMessageContainer cmdlet on one of the farm nodes. This cmdlet returns the IDs, connection strings, database server names, and database names of all message containers. Choose the ID of the container whose database name matches the name of the original container.

  8. If the Service Bus for Windows Server farm was created with the option to use an existing certificate, call the Add-SBHost cmdlet on the farm node that has been renamed. Execute the cmdlet with the following parameters:

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database that you created in step 6.

    • RunAsPassword: SecureString that contains the password of the account under which the Service Bus for Windows Server processes run.

    • EnableFirewallRules: Set to true if the firewall rules of the host should be updated to allow for Service Bus data to traverse the firewall. Otherwise, false.

    If the Service Bus for Windows Server farm was created with the option to generate the farm certificate automatically, call the Add-SBHost cmdlet with the following parameters. Execute the cmdlet on all new farm nodes:

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database that you created in step 6.

    • RunAsPassword: SecureString that contains the password of the account under which the Service Bus for Windows Server processes run.

    • EnableFirewallRules: Set to true if the firewall rules of the host should be updated to allow for Service Bus data to traverse the firewall. Otherwise, false.

    • CertificateAutogenerationKey: SecureString that contains the passphrase to secure the new farm certificate that this cmdlet created.

  9. All service namespace keys are encrypted with the farm certificate. Issuing a new farm certificate requires you to replace all namespace keys. For each namespace, call the Set-SBNamespace cmdlet with the following parameters. Execute this cmdlet on one of the farm machines.

    • Name: Name of the service namespace.

    • PrimarySymmetricKey: New service namespace key.

How to rename the Service Bus domain

To move the domain that hosts the Service Bus for Windows Server from domainA to domainB, follow the steps listed in the section “How to move a Service Bus farm to a new domain.” This procedure enables the Service Bus for Windows Server farm to operate in the new domain and to restore access for all users that were part of domainA.

How to modify the gateway or container database connection strings

This procedure is useful when SQL databases have been moved, renamed, or their connection string has changed (for example, changing the password for SQL authentication). When the Service Bus cannot connect to its databases, you cannot perform any operations (such as sending or receiving messages) until you restore connectivity to all databases.

To change the Service Bus for Windows Server farm database connection string, follow the steps in How to rename the SQL server computer.

  1. Call the Stop-SBFarm cmdlet to stop all Service Bus for Windows Server services on all hosts.

  2. Restore the Service Bus gateway. This step is required to modify the connection string to the gateway database. Note that this step can generate warnings if connection strings to the Service Bus Message Container databases have changed as well (see the next step).

    Restore-SBGateway -GatewayDBConnectionString "Data Source=<yourServer>\sqlexpress; Integrated Security=False;initial catalog= SBGatewayDatabase; User ID=<sqlUser>;Password=<sqlPassword>;Encrypt=False";    -SBFarmDBConnectionString "Data Source=<yourServer>\sqlexpress; initial catalog= SBManagementDB; Integrated Security=False; User ID=<sqlUser>;Password=<sqlPassword>;Encrypt=False"

  3. Restore the message containers. This step is required to modify the connection string to the message containers. Remember that you can have more than one (For more information, see the Get-SBMessageContainer cmdlet).

    Note

    Run this cmdlet from only one of your hosts.

    Restore-SBMessageContainer -Id 1 -ContainerDBConnectionString "Data Source=<yourServer>\sqlexpress; initial catalog= SBMessageContainer01; Integrated Security=False; User ID=<sqlUser>; Password=<sqlPassword>;Encrypt=False"  -SBFarmDBConnectionString "Data Source=<yourServer>\sqlexpress; initial catalog= SBManagementDB; Integrated Security=False; User ID=<sqlUser>;Password=<sqlPassword>;Encrypt=False"

  4. Update the Service Bus for Windows Server farm by running the following cmdlet from all your hosts. This step is required to update all local settings on each host.

    Update-SBHost –SBFarmDBConnectionString “Password=<sqlPassword>”;

  5. Start the Service Bus for Windows Server farm by calling the Start-SBFarm cmdlet.

How to upgrade the Service Bus farm

To upgrade the Service Bus for Windows Server farm to a new version, do the following:

  1. Call the Remove-SBHost cmdlet on all farm nodes.

  2. Install the new version of Service Bus for Windows Server on all nodes of the farm.

  3. Call the Restore-SBFarm cmdlet with the following parameters. Execute this cmdlet on one of the farm nodes.

    • RunAsAccount: Account under which the Service Bus for Windows Server services run. This account must be the same account that you used for the old farm.

    • GatewayDBConnectionString: Connection string of the existing gateway database.

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database that this cmdlet created.

    • FarmCertificateThumbprint: Thumbprint of the farm certificate of the old Service Bus for Windows Server farm. You can find the farm thumbprint in the Service Bus for Windows Server farm database [Store].[ServiceConfig] table under ConfigName SBEncryptionCertificateThumbprint.

    • MessageBrokerPort: Port used for message broker communication. This port must be the same port that you used for message broker communication in the old farm. If not specified, the default port is used.

    • HttpsPort: Port used for HTTPS communication. This port must be the same port that you used for HTTPS communication in the old farm. If not specified, the default port is used.

    • TCPPort: Port used for TCP communication. This port must be the same port that you used for TCP communication in the old farm. If not specified, the default port is used.

    The Restore-SBFarm cmdlet creates a new Service Bus for Windows Server farm database. You can delete the old Service Bus for Windows Server farm database.

  4. Call the Restore-SBGateway cmdlet on one of the farm nodes with the following parameters:

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database that you created in step 3.

    • GatewayDBConnectionString: Connection string of the restored gateway database.

  5. Call the Add-SBHost cmdlet with the following parameters. Execute this cmdlet on all nodes of the farm.

    • SBFarmDBConnectionString: Connection string of the Service Bus for Windows Server farm database that you created in step 3.

    • RunAsPassword: SecureString that contains the password of the account under which the Service Bus for Windows Server processes run.

    • EnableFirewallRules: Set to true if the firewall rules of the host should be updated to allow for Service Bus data to traverse the firewall. Otherwise, false.

  6. Call the Stop-SBFarm cmdlet on one of the nodes of the farm.

  7. Call the Invoke-SBHostUpgrade cmdlet on all nodes of the farm.

  8. Call the Start-SBFarm cmdlet on one of the nodes of the farm.

How to renew an expired certificate

To replace an expired Service Bus for Windows Server farm certificate with a new certificate, do the following:

  1. To stop all of the Service Bus for Windows Server services on all hosts, call Stop-SBFarm on one of the nodes in the farm.

  2. Install a new certificate on all Service Bus machines.

  3. Call the Set-SBCertificate cmdlet with the following parameters. Run this cmdlet on one of the farm machines.

    • FarmCertificateThumbprint: Thumbprint of the new farm certificate.

    • SkipKeyReEncryption

  4. Call the Update-SBHost cmdlet on all farm nodes.

  5. For each service namespace, call the Set-SBNamespace cmdlet with the following parameters. Run this cmdlet on one of the farm machines.

    • Name: Name of the service namespace.

    • PrimarySymmetricKey:Base64 string that represents a new 256-bit service namespace key. For example, yUUsL9IKJ8G52flv99PZPaS/iRJrxyssVvvb37bc4EE=.

  6. Call the Start-SBFarm cmdlet on one of the farm nodes.

How to renew a certificate that has not expired yet

To replace an active Service Bus for Windows Server farm certificate with a new certificate, do the following:

  1. Call the Stop-SBFarm cmdlet to stop all of the Service Bus for Windows Server services on all hosts. Execute this cmdlet on one of the farm nodes.

  2. Install a new certificate on all Service Bus for Windows Server machines.

  3. Call the Set-SBCertificate cmdlet with the following parameters. Run this cmdlet on one of the farm machines.

    • FarmCertificateThumbprint: Thumbprint of the new farm certificate.

  4. Call the Update-SBHost cmdlet on all farm nodes.

  5. Call the Start-SBFarm cmdlet on one of the farm nodes.

How to change the password of the RunAs account

To change the password of the account under which the Service Bus for Windows Server processes run, do the following:

  1. Call the Stop-SBFarm cmdlet to stop all of the Service Bus for Windows Server services on all hosts. Execute this cmdlet on one of the farm nodes.

  2. On every node of the farm, run the Update-SBHost cmdlet with the following parameter:

    • RunAsPassword: SecureString that contains the new password of the account under which the Service Bus for Windows Server processes run.

  3. Call the Start-SBFarm cmdlet on one of the farm nodes.

How to add or remove a user from the set of namespace managers

To add or remove a user from the set of users that has managing privileges on a service namespace, do the following:

  1. To replace the primary key, call the Set-SBNamespace cmdlet with the following parameters. Run this cmdlet on one of the farm machines.

    • Name: The name of the service namespace for which the set of managed users is to be changed.

    • ManageUsers: List of users that have privileges to manage the specified service namespace.

  2. After the service namespace settings have been updated, it takes up to 30 seconds for the new settings to apply.

How to attach a message container to a Service Bus farm

To attach an existing message container to a Service Bus for Windows Server farm, do the following:

  1. Restore the gateway and container databases from its backup copy using the SQL Restore capabilities as outlined in Restore a Database Backup.

  2. Call the Restore-SBMessageContainer cmdlet with the following parameter. Run this cmdlet on one of the farm machines.

    • ContainerDBConnectionString: Connection string of the container database that is to be attached.

  3. Call the Stop-SBFarm cmdlet to stop all of the Service Bus for Windows Server services on all hosts.

  4. Call the Start-SBFarm cmdlet on one of the farm nodes.

How to change the namespace key

The Service Bus allows a service namespace to have two keys: the primary key and the secondary key. To replace the existing key for a given service namespace and to allow key replacement without service interruption, do the following:

  1. To replace the primary key, call the Set-SBNamespace cmdlet with the following parameters. Run this cmdlet on one of the farm machines.

    • Name: Name of the service namespace whose key is to be changed.

    • PrimarySymmetricKey: New primary key.

  2. To replace the secondary key, call the Set-SBNamespace cmdlet with the following parameters. Run this cmdlet on one of the farm machines.

    • Name: Name of the service namespace whose key is to be changed.

    • SecondarySymmetricKey: New secondary key.

How to change the Service Bus runtime settings (quotas)

The Service Bus enforces quota limitations on some messaging entity settings. You can modify those quotas by using PowerShell cmdlets.

  1. To learn which settings you can modify, run the Get-SBRuntimeSetting cmdlet with no parameters.

  2. To modify one of the Service Bus for Windows Server runtime settings, run the Set-SBRuntimeSetting cmdlet with the following parameters:

    • Name: The name of the setting you want to change.

    • Value: The new value for the setting.

    Depending on the parameter that you change, the cmdlet prompts you to restart the farm. If prompted, execute steps 3 and 4.

  3. Call Stop-SBFarm to stop all of the Service Bus for Windows Server services on all hosts.

  4. Call the Start-SBFarm cmdlet on one of the farm nodes.

How to protect the Service Bus from brute force attacks that attempt to obtain domain passwords

To find out the password of a legitimate Service Bus for Windows Server user, a malicious user launches a brute-force attack against Service Bus by sending a large number of requests to the Service Bus. Each of these malicious requests is issued with a different password.

If the account lockout policy is applied, Active Directory prevents brute force password attacks. Note that the lockout policy is not configured by default. To enable account lockout, follow the steps described in Apply or modify account lockout policy.

How to install the Service Bus on a server not connected to the Internet

You can install the Service Bus for Windows Server on computers that are not connected to the internet. For offline installation mode, do the following:

  1. On a computer that is connected to the internet, install the Web Platform Installer v4.0.

  2. Open a command prompt and navigate to the "%ProgramFiles%\Microsoft\Web Platform Installer\" folder.

  3. Run the following command from the command prompt:

    WebpiCmd.exe /Offline /Products:ServiceBus /Path:c:\WebPICache

    This command creates the “Offline Cache” folder on your computer in the specified path (in this example, the path is C:\WebPICache).

  4. Install the Web Platform Installer v4.0 on the target computer and copy the “Offfline Cache” folder to this computer.

  5. Start Regedit.exe.

  6. Navigate to HKLM\Software\Microsoft\WebPlatformInstaller.

  7. Create a new string entry:

    Type: String

    Name: ProductXMLLocation

    Value: <full path to your newly created offline cache>\feeds\latest\webproductlist.xml

  8. From the Start menu, click All Programs. Click Microsoft Web Platform Installer.

  9. In the top right-hand search box of the Web Platform Installer, type Service Bus.

  10. Click Add, and then on the bottom panel, click Install.

  11. Continue the installation, following the Web Platform Installer instructions.

How to configure Service Bus with SQL Server 2012 High Availability using AlwaysOn

Service Bus for Windows Server supports SQL Server 2012 high availability with AlwaysOn. In the case of an Availability Group (AG), you must ensure that the gateway database (SbGatewayDatabase), the management database (SbManagementDatabase), and all message container databases (SBMessageContainer01, SBMessageContainer02, and so on) are part of the same AG. You can use optional connection features such as MultiSubnetFailover by using the Service Bus PowerShell cmdlets instead of the configuration wizard. Using the cmdlets, pass the necessary connection string to New-SBFarm, Add-SBHost, and New-SBMessageContainer.

For example, a database connection string appears as follows:

Data Source=<YourSQLInstance>;Integrated Security=True

How to configure Service Bus when installed on Windows Azure Infrastructure As A Service (IaaS) VMs

While you can install Service Bus for Windows Server on Windows Azure Virtual Machines as an Infrastructure as a Service (Iaas), several configuration steps are required to enable remote clients connectivity. After installing Service Bus for Windows Server but before you configure it, execute the following command in a command prompt window:

reg add "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment"  /v FabricDataRoot /t REG_SZ /d d:\programdata\winfabdataroot

You can choose any folder location, but the drive letter must be d:\. This is the drive Windows Azure uses as the temp drive.

Because clients can only talk to Windows Azure VMs through public endpoints, you must map the public endpoints to Service Bus internal endpoints. For example:

If the public address of the VM is https://sbsvriaasdc.cloudapp.net, and public ports are mapped as follows:

External (public) -> Service Bus (internal):

8355 -> 9355 (HTTPs port)

8354 -> 9354 (TCP port)

8356 -> 9356 (Brokered messaging port)

8671 -> 5671 (AMQPS port)

8672 -> 5672 (AMQP port)

8359 -> 9359 (RPHttps port)

To configure gateway redirection, on every Service Bus host machine execute the following PowerShell commands:

Update-SBHost -ExternalBrokerPort 8356 -ExternalBrokerUrl https://sbsvriaasdc.cloudapp.net
Stop-SBHost
Start-SBHost

This example returns the external broker address https://sbsvriaasdc.cloudapp.net:8356 to the client in the gateway redirection case, instead of the internal address https://iaasQFDN:9356.

Build Date:

2013-10-18