Every Tenant must have a unique public domain address for end users to connect to it through Tenant Broker. Although every Tenant must have a unique public domain address, it is not required for every Tenant to have a unique IP address. Different public domain address can be configured to resolve to the same IP address to reach the Tenant Broker shared Gateways. This way the Tenant Broker is still able to forward traffic to the right tenant based on the hostname requested by an end user.

A public domain address can be chosen a number of different ways. For example, a service provider can register a subdomain (e.g. Tenant1.Service-Provider.com) and assign it to a Tenant. Another approach could be using a private domain address (e.g. RAS.Tenant1.com) and have it routed to RAS Secure Gateways in the Tenant Broker. For testing purposes, you can even use an IP address.

The Public domain address is also a property of a Tenant object in the Tenant Broker console. After joining a Tenant to the Tenant Broker, you must ensure that this property contains the correct address. Otherwise end users will not be able to connect to the Tenant through the Tenant Broker.

To verify (and set if necessary) the Tenant's public domain address:

1. Log in to the Tenant Broker.

2. In the RAS Console, navigate to Farm > Tenants.

3. Right-click a Tenant and choose Properties.

4. In the Properties dialog, verify that the Public domain address field contains the correct address.

In addition to an invitation hash, you can join a Tenant to the Tenant Broker using a secret key. As described earlier, a secret key can be used to join an unlimited number of Tenants to the same Tenant Broker.

To create a secret key:

1. Log in to the Tenant Broker console.

2. In the RAS Console, navigate to Farm > Settings.

3. Select the Tenant broker tab.

4. Select Allow RAS Farms to register in Tenant Broker using a secret key.

5. Optionally, select Do not show billing information to hide billing information in the Licensing category of Tenants joined with secret keys.

6. The secret key is generated automatically. To generate a different key, click Generate.

7. If you want to register Tenants as subdomains, specify the domain part of the hostname in the Domain field. For example, to use "subdomain.domain.com" as a Tenant host name, specify "domain.com".

Once you have the key, you can use it to join one or more Tenants to the Tenant Broker.

To join a Tenant using a secret key:

1. Log in to the Tenant.

2. In the RAS Console, navigate to Farm > Site.

3. Click Tasks > Join Tenant Broker.

4. In the Join Tenant Broker dialog, specify the following:

   • Enter the secret key in the first field from the top. If the Tenant is able to reach the Tenant Broker, the Tenant Broker field will be populated automatically.

   • The Tenant Name field is populated automatically based on the name of the current Site, but you can specify a Tenant name of your choosing. The name you enter will be used in the Tenant Broker to name the corresponding Tenant object.

   • In the Public domain addresses field, you can specify public domain addresses that will be used to access the Tenant. Configuring this is optional. If the Domain field is configured in the Tenant Broker settings (see above), you may enter subdomain only rather then the full domain address.

5. Click Join.

On successful join, you will see a message welcoming you to the Tenant Broker. If the primary Connection Broker in your Tenant Farm can't reach the Tenant Broker, you will see a corresponding error message. Make sure that the Tenant Broker computer is reachable from the machine where you have the primary Connection Broker running.

Overriding the Tenant Broker IP address

The Tenant Broker IP address is detected automatically when you generate a secret key and is embedded into it. If a Tenant can't reach the Tenant Broker using this address, you have the ability to override it as follows:

1. Log in to the Tenant Broker.

2. In the RAS Console, navigate to Farm > Settings and click the Tenant broker tab.

3. Select the Override Tenant Broker address in tenant invitations and secret keys option.

4. Enter the desired IP address in the field provided.

After deploying a Tenant, you need to configure networking between Tenant Broker and Tenant in order to allow the following communications:

• Tenant Connection Broker > Tenant Broker Connection Broker: port 20003

• Tenant Broker Gateway > Tenant Broker Connection Broker: port 20002

• Tenant Broker Gateway > Tenant Connection Broker: port 20002

• Tenant Broker Gateway > Servers hosting published resources: port 3389

These are standard RAS ports, which are also described in the Port reference section.

One other thing that you have to do after you join a Tenant to the Tenant Broker, is set up routing for the incoming traffic from the Internet to shared RAS Secure Gateways or HALB.

After you join a Tenant to the Tenant Broker, you should verify that the procedure was successful.

First, verify the Tenant Broker status in the Tenant console:

1. Log in to the Tenant Farm.

2. In the RAS Console, navigate to Farm > Site and select the Site tab in the right pane.

3. You should see the Tenant Broker section with the Status column, which should say OK. If the status is Not verified, make sure that the Tenant Broker is operational (or contact the Tenant Broker admin if you are not him or her).

You can also see additional Tenant Broker information by right-clicking it and choosing Properties. The information includes the following:

• Name: The Tenant Broker name.

• Primary address: The primary RAS Connection Broker address.

• Secondary address: The secondary RAS Connection Broker address (if available).

You should then verify the Tenant status in the Tenant Broker console:

1. Log in to the Tenant Broker.

2. In the RAS Console, navigate to Farm > Tenants.

3. In the Tenants tab, find the Tenant of interest and examine the Status column, which should say OK if the Tenant is joined properly. For other possible Status column values, see Tenant configuration.

Once the Tenant Farm is operational, you can join one or more sites in it to the Tenant Broker.

There are two ways you can join a Tenant: (1) Using an invitation hash or (2) Using a shared secret key. The difference between the two is as follows:

• Invitation hash. An invitation hash is an automatically generated encrypted string that can be used to join a single Tenant to Tenant Broker. Invitation hash is a property of a Tenant object, which is created in the Tenant Broker console. You email the hash to the Tenant Farm administrator, so they can use it to join the Tenant Broker. Once used, an invitation hash cannot be used again by any other Tenant.

• Shared secret key. A shared secret key is similar to an invitation hash, with one important difference. It can be used to join an unlimited number of Tenants. A Tenant object is not pre-created for a secret key in the Tenant Broker. Instead, the object is created when the key is used to join a Tenant. Because of its unlimited usage capability, only the Tenant Broker admins should have access to a shared secret key. This scenario is useful when there are multiple Tenants, all managed by the same Tenant Broker administrator.

The invitation hash scenario is described below. For the secret key scenario see Joining with a secret key.

First, you need to generate an invitation hash and create a Tenant object on the Tenant Broker side:

1. Log in to the Tenant Broker.

2. In the RAS Console, navigate to Farm > Tenants.

3. Click Tasks > Add.

4. In the Tenant properties dialog, specify the following:

   • Name: Type a Tenant name (this can be any name that you like).

   • Public domain address: If you've already assigned a public domain address to the Tenant, specify it here. If not, you can leave it blank. The address is not required for the Tenant to join the Tenant Broker. However, without the address specified here, end users will not be able to connect to the Tenant, so you will need to come back and fill it in later. For details, see Assign a public domain address.

   • Clients in gateway mode connect to published tenant resources by server IP: When selected, clients will use the Tenant IP address instead of the DNS name. You can use this option when a Tenant farm does not share the same DNS provider as the Tenant Broker farm.

   • Do not show billing information: When selected, billing information is not shown in the Licensing category of the Tenant.

   • Description: Type an optional description.

   • Connection Brokers: This filed is disabled and will be populated automatically when the Tenant joins the Tenant Broker. See more in Tenant configuration.

   • Tenant invitation hash: This is the hash that the admin of the Tenant Farm will need to use to join the Tenant Broker. A hash is generated automatically when you open this dialog. To generate a new hash, click Create new hash.

   • Send via email. You can give the invitation hash to the Tenant admin directly or you can use this button to send it via email. When you click the button, you'll see a dialog where you can enter the recipients and where you can review and modify the email message. By default, the message contains instructions on how to join the Tenant Broker. Please note that SMTP settings must be configured in the RAS Console before you can use the email option. You can configure SMTP first and then return to this screen to complete this step.

5. Click OK to close the Tenant properties dialog. The new Tenant will appear in the Tenants list in the console. At this time, the Tenant is not joined yet. Read on to learn how to join it.

To join the Tenant to the Tenant Broker:

1. Log in to the Tenant Farm.

2. In the RAS console, navigate to Farm > Site. Note that you are joining a Site to the Tenant Broker, not the whole Farm, so if you have more than one Site, you need to join them one by one.

3. Click Tasks > Join Tenant Broker.

4. In the Join Tenant Broker dialog, enter the invitation hash that you obtained from the Tenant Broker in the previous steps (or, if you are an admin of a Tenant Farm, the one your received in the invitation email).

5. Click Join.

On successful join, you will see a message welcoming you to the Tenant Broker. If the primary Connection Broker in your Tenant Farm can't reach the Tenant Broker, you will see a corresponding error message. Make sure that the Tenant Broker computer is reachable from the machine where you have the Tenant's RAS Connection Broker running.

Overriding Tenant Broker IP address

The Tenant Broker IP address is detected automatically when you generate an invitation hash (or a secret key) and is embedded into the hash. If a Tenant can't reach the Tenant Broker using this address, you have the ability to override it as follows:

1. Log in to the Tenant Broker.

2. In the RAS Console, navigate to Farm > Settings and click the Tenant broker tab.

3. Select the Override Tenant Broker address in tenant invitations and secret keys option.

4. Enter the desired IP address in the field provided.

When done, the specified IP address will be used instead of the auto-detected address when generating an invitation hash or secret key. When the hash is used on the Tenant side to join the Tenant Broker, the Tenant will use this address to connect to the Tenant Broker.

Once used on the Tenant side, an invitation hash binds the Tenant Farm to the corresponding Tenant object in the Tenant Broker and the tenancy becomes effective.

A Tenant Farm is deployed just like a traditional Parallels RAS Farm. The only difference is, when installing the Farm, you don't need to install RAS Secure Gateways in it.

To set up a Parallels RAS Farm to be used as a Tenant:

1. Run the Parallels RAS installer.

2. On the Select Installation Type page, select Custom.

3. Click Next.

4. Make sure that the following components are selected for installation:

   • RAS Connection Broker

   • Parallels RAS Console (optional; you can have the RAS Console installed on a different machine)

   Other components are optional. You can install them now or you can install them later if needed.

5. Click Next and follow the onscreen instructions to complete the installation.

The public domain address assigned to a Tenant must have a matching certificate. The Tenant Broker admin must create a certificate for every Tenant in the Tenant Broker console. Shared RAS Secure Gateways must then be configured to use these certificates. Tenant certificates are created and managed in Parallels RAS the same way as other certificates using the Farm > Site > Certificates subcategory. For the complete information about how to create certificates and how to assign them to RAS Secure Gateways and HALB, please see the SSL Certificate Management chapter.

When a user connects to the Tenant's public domain address, a certificate with the common name matching the requested public domain address is selected automatically for every connection. The first available certificate is used which might not be the self-signed (say it was deleted)

If no matching certificate is found, the default self-signed certificate will be used, but the user will see a certificate warning in the web browser.