Managing Farms and Nodes
Applies To: Service Bus for Windows Server 1.1
The cmdlets described in this section create or delete farms and the nodes they contain.
Creating a New Service Bus for Windows Server Farm
The New-SBFarm cmdlet creates a new farm of Service Bus for Windows Server nodes. To create a farm with auto-generated certificates use the following format:
New-SBFarm [-AdminGroup <String>] [-GatewayDBConnectionString <String>] [-HttpsPort <Int32>]
[-InternalPortRangeStart <Int32>] [-MessageBrokerPort <Int32>] [-MessageContainerDBConnectionString <String>]
[-RunAsAccount <String>] [-TcpPort <Int32>] -CertificateAutoGenerationKey <SecureString> -SBFarmDBConnectionString <String>
To create a farm with custom certificates use the following format:
New-SBFarm [-AdminGroup <String>] [-EncryptionCertificateThumbprint <String>] [-GatewayDBConnectionString
<String>] [-HttpsPort <Int32>] [-InternalPortRangeStart <Int32>] [-MessageBrokerPort <Int32>]
[-MessageContainerDBConnectionString <String>] [-RunAsAccount <String>] [-TcpPort <Int32>]
-FarmCertificateThumbprint <String> -SBFarmDBConnectionString <String>
If an error occurs or you are forced to reboot during farm creation, the farm management database that is created may be left in a corrupt state. In that case, when you try to join a farm the process may display an error indicating that the machine you are trying to add to the farm is not a part of any farm. When you encounter such an error, you must drop the farm management database and recreate it before you can join any new nodes to the farm.
The following table describes the options for this cmdlet.
Option |
Effect |
|---|---|
–SBFarmDBConnectionString <connectionstring> |
Represents a connection string of the configuration database. |
-Admingroup <adgroup> |
Specifies the user group whose members receive administrative access to the databases in the farm.Defaults to the BuiltIn\Administrators group on the machine. |
-CertificateAutoGenerationKey <SecureString>] |
Specifies the key that the installer uses to generate the new services SSL certificate to secure communications between the services and their clients. |
-MessageContainerDBConnectionString <connstring> |
Specifies the connection string for the database instance used as the container database. |
-MessageBrokerPort <portno> |
Specifies the port that will be used for the message broker communication. The default value is 9356. |
-HttpsPort <portno> |
Specifies the port that will be used for the https communication. The default value is 9355. |
-InternalPortRangeStart <portrange> |
Specifies the range of ports that the Service Bus for Windows Server nodes use to communicate with one another. The portrange parameter is a single port number that represents the first of a range of six consecutive ports. |
-GatewayDBConnectionString <connstring> |
Specifies the connection string for the database instance used as the gateway database. The gateway database manages and load balances incoming requests. |
-TCPPort <portno> |
Specifies the port that the Service Bus for Windows Server nodes use to communicate with each other. The default value is 9354. |
-EncryptionCertificateThumbprint <string> |
The certificate that is used for securing the SQL connection strings. If not provided, it will take the value of the SslCertificate. Represents the encryption certificate. |
-FarmCertificateThumbprint <string> |
The certificate that is used for securing the certificate. Do not provide this certificate if you are providing CertificateAutoGenerationKey for auto-generation of certificates. |
Adding a New Node to a Farm
The Add-SBHost cmdlet adds a node to an existing farm. The Add-SBHost cmdlet has the following format:
Add-SBHost [-CertificateAutogenerationKey <SecureString>] [-ExternalBrokerPort <Int32>] [-ExternalBrokerUrl <Uri>] -EnableFirewallRules <Boolean> -RunAsPassword <SecureString> -SBFarmDBConnectionString <String>
The following table describes the options for this cmdlet.
Option |
Effect |
|---|---|
–SBFarmDBConnectionString <connectionstring> |
Specifies the connection string for the SQL Server instance being added as the farm management database. |
-RunAsPassword <SecureString> |
Specifies the password for the user account under which services are running on the farm. If all the machines in a farm share the same service account and the security policy requires the service account password to be changed at regular intervals, you must perform specific actions on each machine in the farm to be able to continue adding and removing nodes in the farm. See the section titled Handling Farm Password Changes2 for this procedure. |
-CertificateAutoGenerationKey <SecureString>] |
Specifies the key that the farm uses to secure the auto generated certificates. |
-EnableFirewallRules <Boolean> |
If true, firewall rules will be enabled on the host. |
-ExternalBrokerPort <Int32> |
Represents the port that the Service Bus for Windows Server uses for ExternalBroker communication. |
-ExternalBrokerUrl <Uri> |
Specifies a case-sensitive ExternalBroker URI. |
The installation program auto generates the following certificates based on your selections when it adds the node to the farm:
Certificate Type |
Name |
Issuer |
|---|---|---|
CA |
AppServerGeneratedSBCA |
|
FarmCertificate |
AppServerGeneratedSBCA |
AppServerGeneratedSBCA |
Removing a Node from a Farm
The Remove-SBHost cmdlet removes a node from an existing farm. If the farm is in a stopped state when you run this cmdlet, there may be some errors or warnings. You can ignore the errors and warnings and run Start-SBFarm after Remove-SBHost for the changes to take effect. If the farm is in a running state, running Start-SBFarm is not required.
This cmdlet has the following format:
Remove-SBHost [-SBFarmDBConnectionString <string>] [-HostName <string>] [<CommonParameters>]
The following table describes the options for this cmdlet.
Option |
Effect |
|---|---|
–SBFarmDBConnectionString<connectionstring> |
Specifies the connection string for the SQL Server instance being removed from the farm. If you do not provide this parameter the cmdlet finds the connection string in the registry. |
-HostName<String> |
Name of the host to be removed. If you do not provide this parameter the host on which the cmdlet is executed will be removed. Note You must to provide a HostName in case the host is no longer available and you wish to clean up the farm configuration. |
If you want to rename a machine that belongs to a farm, you must use this cmdlet to remove it from the farm before you rename it, then add it back to the farm using the Add-SBHost cmdlet. If this cmdlet encounters a timeout error, you can still try to run the Add-SBHost cmdlet to try to add it back to the farm. If Add-SBHost succeeds, you can ignore the earlier timeout error.
When you leave a farm, the uninstaller leaves any certificates that you installed on the machine. If you want to remove those certificates, you must remove them manually.
When reducing the farm to single computer farm, you must remove all the computers from the farm. Then you must add back the computer that you want to be part of the farm.