> For the complete documentation index, see [llms.txt](https://docs.parallels.com/landing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parallels.com/landing/ras-admin-guide/parallels-ras-21-administrators-guide/ras-multi-tenant-architecture/deploying-tenant-broker-and-tenants/deploying-a-tenant/join-a-tenant-to-tenant-broker.md).

# Join a Tenant to Tenant Broker

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

{% hint style="info" %}
**Note:** A Tenant is a Site in a separately deployed Parallels RAS Farm. When you join a Tenant to Tenant Broker, you join a Site. When you want to join the whole Farm, you do it one Site at a time. Of course, if you have just one Site in a Farm (and have no plans to create more sites), you are essentially joining the whole Farm.
{% endhint %}

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**](/landing/ras-admin-guide/parallels-ras-21-administrators-guide/ras-multi-tenant-architecture/deploying-tenant-broker-and-tenants/deploying-a-tenant/joining-with-a-secret-key.md).

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**](/landing/ras-admin-guide/parallels-ras-21-administrators-guide/ras-multi-tenant-architecture/deploying-tenant-broker-and-tenants/deploying-a-tenant/assign-a-public-domain-address.md).
   * **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**](/landing/ras-admin-guide/parallels-ras-21-administrators-guide/common-management-tasks/licensing.md) 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**](/landing/ras-admin-guide/parallels-ras-21-administrators-guide/ras-multi-tenant-architecture/managing-tenants/tenant-configuration.md).
   * **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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.parallels.com/landing/ras-admin-guide/parallels-ras-21-administrators-guide/ras-multi-tenant-architecture/deploying-tenant-broker-and-tenants/deploying-a-tenant/join-a-tenant-to-tenant-broker.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.