Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document MQTT cert/vhost mapping #310

Merged
merged 3 commits into from
Dec 15, 2016
Merged

Document MQTT cert/vhost mapping #310

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
92bfb96
Document MQTT cert/vhost mapping
acogoluegnes Dec 14, 2016
376eca0
Clarify difference between global/vhost parameters
acogoluegnes Dec 14, 2016
3dc2236
Clarify global/vhost runtime parameters doc
acogoluegnes Dec 14, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions site/mqtt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,8 +189,36 @@ Note that:
* The authenticated user must exist in the configured authentication / authorisation backend(s).
* Clients **must not** supply username and password.

You can optionally specify a virtual host for a client certificate by using the `mqtt_default_vhosts`
[global runtime parameter](/parameters.html). The value of this global parameter must contain a JSON document that
maps certificates' subject's Distinguished Name to their target virtual host. Let's see how to
map 2 certificates, `O=client,CN=guest` and `O=client,CN=rabbit`, to the `vhost1` and `vhost2`
virtual hosts, respectively.

Global parameters can be set up with `rabbitmqctl`:

rabbitmqctl set_global_parameter mqtt_default_vhosts \
'{"O=client,CN=guest": "vhost1", "O=client,CN=rabbit": "vhost2"}'

With `rabbitmqctl`, on Windows:

rabbitmqctl set_global_parameter mqtt_default_vhosts ^
"{""O=client,CN=guest"": ""vhost1"", ""O=client,CN=rabbit"": ""vhost2""}'

And with the HTTP API:

PUT /api/global-parameters/mqtt_default_vhosts
{"value": {"O=client,CN=guest": "vhost1", "O=client,CN=rabbit": "vhost2"}}

Note that:

* If the virtual host for a certificate cannot be found (because the certificate
subject's DN cannot be found in the `mqtt_default_vhosts` global parameter JSON
document or if the global parameter isn't set at all), the virtual host specified
by the `vhost` plugin config option will be used.
* The broker queries the `mqtt_default_vhosts` global parameter value at connection time.
If the value changes, connected clients are not notified or disconnected. They need
to reconnect to switch to a new virtual host.

### <a id="stickiness"/> Session Stickiness (Clean and Non-clean Sessions) and Queue/Subscription TTL

Expand Down
43 changes: 39 additions & 4 deletions site/parameters.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,20 +43,31 @@ limitations under the License.
set by
invoking <a href="man/rabbitmqctl.1.man.html"><code>rabbitmqctl</code></a>
or through <a href="management.html">the management plugin</a>'s HTTP API.
Parameters are scoped per vhost.
There are 2 kinds of parameters: vhost-scoped parameters and global parameters.
Copy link
Member

@michaelklishin michaelklishin Dec 14, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to clearly explain the difference.

Vhost-scoped parameters are tied to a virtual host and consist
of a component name, a name and a value.
Global parameters are not tied to a particular virtual and they consist
of a name and value.
</p>
<p>
One special case of parameters usage is policies, which are used for specifying
optional arguments for groups of queues and exchanges, as well as plugins such
as Federation and Shovel.
as Federation and Shovel. Policies are vhost-scoped.
</p>
</doc:section>

<doc:section name="parameter-management">
<doc:heading>Parameter Management</doc:heading>

<p>
Parameters can be set, cleared and listed:
As stated above, there are vhost-scoped parameters and global parameters.
An example of vhost-scoped
parameter is a federation upstream: it targets a component
(<code>federation-upstream</code>), it has a name that identifies
it, it's tied to a virtual host (federation links will target
some resources of this virtual host), and its value defines connection
parameters to an upstream broker.
Vhost-scoped parameters can be set, cleared and listed:
</p>
<table>
<tr>
Expand All @@ -76,6 +87,29 @@ limitations under the License.
</td>
</tr>
</table>
<p>
Global parameters is the other kind of parameters.
An example of a global parameter is the name of the cluster.
Global parameters can be set, cleared and listed:
</p>
<table>
<tr>
<th>rabbitmqctl</th>
<td>
<code>rabbitmqctl set_global_parameter <i>name</i> <i>value</i></code><br/>
<code>rabbitmqctl clear_global_parameter <i>name</i></code><br/>
<code>rabbitmqctl list_global_parameters</code>
</td>
</tr>
<tr>
<th>HTTP API</th>
<td>
<code>PUT /api/global-parameters/<i>name</i></code><br/>
<code>DELETE /api/global-parameters/<i>name</i></code><br/>
<code>GET /api/global-parameters</code><br/>
</td>
</tr>
</table>
<p>
Since a parameter value is a JSON document, you will usually
need to quote it when creating one on the command line
Expand All @@ -92,7 +126,8 @@ limitations under the License.
definitions by the management plugin's export feature.
</p>
<p>
Parameters are used by the federation and shovel plugins.
Vhost-scoped parameters are used by the federation and shovel plugins.
Global parameters are used by the MQTT plugin.
</p>
</doc:section>

Expand Down