parameters.md

title
Runtime Parameters

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Runtime Parameters

Overview {#overview}

While much of the configuration for RabbitMQ lives in the configuration file, some things do not mesh well with the use of a configuration file:

• If they need to be the same across all nodes in a cluster
• If they are likely to change at run time

RabbitMQ calls these items parameters. Parameters can be set by invoking rabbitmqctl or through the HTTP API.

There are two kinds of parameters: virtual host-scoped parameters and global parameters. The former, as the name suggests, are tied to a virtual host and consist of a component name, a name and a value.

For example, a dynamic shovel is definened using runtime parameters. It belongs to a virtual host, has a name and its component type is set to "shovel".

Global parameters are not tied to a particular virtual host and they consist of a name and value.

:::important

One important example of parameters usage is policies

:::

Per-virtual host Parameters {#per-vhost}

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 (federation-upstream), 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.

Virtual host-scoped parameters can be set, cleared and listed:

```bash # sets a runtime parameter in a virtual host rabbitmqctl set_parameter [-p vhost]

clears (unsets) a runtime parameter in a virtual host

rabbitmqctl clear_parameter [-p vhost] <component_name>

lists runtime parameters in a virtual host

rabbitmqctl list_parameters [-p vhost]

</TabItem>

<TabItem value="PowerShell" label="PowerShell">
```PowerShell
# sets a runtime parameter in a virtual host
rabbitmqctl.bat set_parameter [-p vhost] <component_name> <name> <value>

# clears (unsets) a runtime parameter in a virtual host
rabbitmqctl.bat clear_parameter [-p vhost] <component_name> <name>

# lists runtime parameters in a virtual host
rabbitmqctl.bat list_parameters [-p vhost]

```ini PUT /api/parameters/{component_name}/{vhost}/{name} DELETE /api/parameters/{component_name}/{vhost}/{name} GET /api/parameters ```

Global Parameters {#global}

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:

```bash # sets a global (virtual-host-independent) runtime parameter rabbitmqctl set_global_parameter

clears (unsets) a global (virtual-host-independent) runtime parameter

rabbitmqctl clear_global_parameter

lists global (virtual-host-independent) runtime parameters

rabbitmqctl list_global_parameters

</TabItem>

<TabItem value="PowerShell" label="PowerShell">
```PowerShell
# sets a global (virtual-host-independent) runtime parameter
rabbitmqctl.bat set_global_parameter <name> <value>

# clears (unsets) a global (virtual-host-independent) runtime parameter
rabbitmqctl.bat clear_global_parameter <name>

# lists global (virtual-host-independent) runtime parameters
rabbitmqctl.bat list_global_parameters

```ini PUT /api/global-parameters/name DELETE /api/global-parameters/name GET /api/global-parameters ```

Since a parameter value is a JSON document, you will usually need to quote it when creating one on the command line with rabbitmqctl. On Unix it is usually easiest to quote the whole document with single quotes, and use double quotes within it. On Windows you will have to escape every double quote. We give examples for both Unix and Windows for this reason.

Parameters reside in the database used by RabbitMQ for definitions of virtual hosts, exchanges, queues, bindings, users and permissions. Parameters are exported along with other object definitions by the management plugin's export feature.

Virtual-scoped parameters are used by the federation and shovel plugins.

Global parameters are used to store various cluster-level metadata, for example, cluster name, cluster tags, as well as internal node metada such as imported definitions hash.

Cluster Name

Cluster name stored using global runtime parameters. It can be updated using a dedicated CLI command.

```bash rabbitmqctl set_cluster_name rabbit@id-3942837 ``` ```PowerShell rabbitmqctl.bat set_cluster_name rabbit@id-3942837 ```

Cluster Tags

Cluster tags are arbitrary key-value pairs that describe a cluster. They can be used by operators to attach deployment-specific information.

Cluster tags are stored in a global parameter named cluster_tags. They can also be preconfigured using rabbitmq.conf:

cluster_tags.series = 4.1.x

cluster_tags.purpose = iot_ingress
cluster_tags.region = ca-central-1
cluster_tags.environment = production

To retrieve a list of tags, list global runtime parametersor fetch a global runtime parameter named cluster_tags, or use rabbitmqadmin v2's snow overviewcommand.

```bash rabbitmqadmin show overview ``` ```bash # lists global (virtual-host-independent) runtime parameters rabbitmqctl list_global_parameters ``` ```PowerShell # lists global (virtual-host-independent) runtime parameters rabbitmqctl.bat list_global_parameters ``` ```ini GET /api/global-parameters

GET /api/global-parameters/cluster_tags

</TabItem>
</Tabs>


## Policies

[Policies](./policies) are now documented in a dedicated guide.

## Operator Policies {#operator-policies}

[Operator policies](./policies#operator-policies) are now documented in the policies guide.