Chapter 4. Configuring a router

Each AMQ Interconnect router contains a qdrouterd.conf configuration file. You edit this file to define how the router should operate.

You can configure the following entities:

Essential router properties
Network connections
Security settings (authentication and authorization)
Routing (message routing and link routing)
Logging

4.1. Configuring router properties

By default, AMQ Interconnect operates in standalone mode with a randomly-generated ID. If you want to use this router in a router network, you must change these properties.

Procedure

Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.
In the router section, specify the mode and ID.
This example shows a router configured to operate in interior mode:
```
router {
    mode: interior
    id: Router.A
}
```
mode
Specify one of the following modes:
standalone - Use this mode if the router does not communicate with other routers and is not part of a router network. When operating in this mode, the router only routes messages between directly connected endpoints.
interior - Use this mode if the router is part of a router network and needs to collaborate with other routers.
edge - Use this mode if the router is an edge router that will connect to a network of interior routers.
id
The unique identifier for the router. This ID will also be the container name at the AMQP protocol level.
If necessary, configure any additional properties for the router.
For information about additional attributes, see router in the qdrouterd.conf man page.

4.2. Configuring network connections

AMQ Interconnect connects clients, servers, AMQP services, and other routers through network connections. To connect the router to other messaging endpoints, you configure listeners to accept connections, and connectors to make outbound connections. However, connections are bidirectional - once the connection is established, message traffic flows in both directions.

You can configure the following types of connections:

inter-router: The connection is for another interior router in the network. Inter-router discovery and routing protocols can only be used over inter-router connections.
normal: The connection is for AMQP clients using normal message delivery.
edge: The connection is between an edge router and an interior router.
route-container: The connection is for a broker or other resource that holds known addresses.

4.2.1. Connecting routers

To connect a router to another router in the router network, you configure a connector on one router to create the outbound connection, and a listener on the other router to accept the connection.

Because connections are bidirectional, there should only be one connection between any pair of routers. Once the connection is established, message traffic flows in both directions.

This procedure describes how to connect a router to another router in the router network.

Procedure

Determine the direction of the connection.
Decide which router should be the "connector", and which should be the "listener". The direction of the connection establishment is sometimes arbitrary, but consider the following factors:
IP network boundaries and firewalls
Generally, inter-router connections should always be established from more private to more public. For example, to connect a router in a private IP network to another router in a public location (such as a public cloud provider), the router in the private network must be the "connector" and the router in the public location must be the "listener". This is because the public location cannot reach the private location by TCP/IP without the use of VPNs or other firewall features designed to allow public-to-private access.
Network topology
The topology of the router network may affect the direction in which connections should be established between the routers. For example, a star-topology that has a series of routers connected to one or two central "hub" routers should have "listeners" on the hub and "connectors" on the spokes. That way, new spoke routers may be added without changing the configuration of the hub.
On the router that should create the connection, open the /etc/qpid-dispatch/qdrouterd.conf configuration file and add a connector.
This example creates a connector for an inter-router connection between two interior routers:
```
connector {
    host: 192.0.2.1
    port: 5001
    role: inter-router
    ...
}
```
host
The IP address (IPv4 or IPv6) or hostname on which the router will connect.
port
The port number or symbolic service name on which the router will connect.
role
The role of the connection. If the connection is between two interior routers, specify inter-router. If the connection is between an interior router and an edge router, specify edge.
On the router that should accept the connection establishment, open the /etc/qpid-dispatch/qdrouterd.conf configuration file and verify that an inter-router listener is configured.
This example creates a listener to accept the connection establishment configured in the previous step:
```
listener {
    host: 0.0.0.0
    port: 5001
    role: inter-router
    ...
}
```
host
The IP address (IPv4 or IPv6) or hostname on which the router will listen.
port
The port number or symbolic service name on which the router will listen.
role
The role of the connection. If the connection is between two interior routers, specify inter-router. If the connection is between an interior router and an edge router, specify edge.
If the router should connect to any other routers, repeat this procedure.
Edge routers can only connect to interior routers. They cannot connect to other edge routers.

4.2.2. Listening for client connections

To enable a router to listen for and accept connections from AMQP clients, you configure a listener.

Once the connection is enabled on the router, clients can connect to it using the same methods they use to connect to a broker. From the client’s perspective, the router connection and link establishment are identical to a broker connection and link establishment.

Note

Instead of configuring a listener to listen for connections from the client, you can configure a connector to initiate connections to the client. In this case, the router will use the connector to initiate the connection, but it will not create any links. Links are only created by the peer that accepts the connection.

Procedure

Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.
Configure a listener with the normal role.
```
listener {
    host: primary.example.com
    port: 5672
    role: normal
    failoverUrls: secondary.example.com:20000, tertiary.example.com
    ...
}
```
host
The IP address (IPv4 or IPv6) or hostname on which the router will listen.
port
The port number or symbolic service name on which the router will listen.
role
The role of the connection. Specify normal to indicate that this connection is used for message delivery for AMQP clients.
failoverUrls (optional)
A comma-separated list of backup URLs the client can use to reconnect if the established connection is lost. Each URL must use the following form:
[(amqp|amqps|ws|wss)://](HOST|IP ADDRESS)[:port]
For more information, see Section 4.2.4, “Connection failover”.

4.2.3. Connecting to external AMQP containers

To enable a router to establish a connection to an external AMQP container (such as a message broker), you configure a connector.

Note

Instead of configuring a connector to initiate connections to the AMQP container, you can configure a listener to listen for connections from the AMQP container. However, in this case, the addresses on the AMQP container are available for routing only after the AMQP container has created a connection.

Procedure

Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.
Configure a connector with the route-container role.
This example creates a connector that initiates connections to a broker. The addresses on the broker will be available for routing once the router creates the connection and it is accepted by the broker.
```
connector {
    name: my-broker
    host: 192.0.2.10
    port: 5672
    role: route-container
    ...
}
```
name
The name of the connector. Specify a name that describes the entity to which the router will connect.
host
The IP address (IPv4 or IPv6) or hostname to which the router will connect.
port
The port number or symbolic service name to which the router will connect.
role
The role of the connection. Specify route-container to indicate that this connection is for an AMQP container that holds known addresses.

4.2.4. Connection failover

If a connection between a router and a remote host fails, connection failover enables the connection to be reestablished automatically on an alternate URL.

A router can use connection failover for both incoming and outgoing connections.

Connection failover for outgoing connections

By default, when you configure a connector on a router, the router attempts to maintain an open network transport connection to the configured remote host and port. If the connection cannot be established, the router continually retries until the connection is established. If the connection is established and then fails, the router immediately attempts to reestablish the connection.

When the router establishes a connection to a remote host, the client may provide the router with alternate connection information (sometimes called failover lists) that it can use if the connection is lost. In these cases, rather than attempting to reestablish the connection on the same host, the router will also try the alternate hosts.

Connection failover is particularly useful when the router establishes outgoing connections to a cluster of servers providing the same service.

Connection failover for incoming connections

You can configure a listener on a router to provide a list of failover URLs to be used as backups. If the connection is lost, the client can use these failover URLs to reestablish the connection to the router.

4.3. Securing network connections

You can configure AMQ Interconnect to communicate with clients, routers, and brokers in a secure way by authenticating and encrypting the router’s connections. AMQ Interconnect supports the following security protocols:

SSL/TLS for certificate-based encryption and mutual authentication
SASL for authentication with mechanisms

To secure the router network, you configure SSL/TLS, SASL (or a combination of both) to secure each of the following types of connections:

4.3.1. Securing connections between routers

Connections between interior routers should be secured with SSL/TLS encryption and authentication (also called mutual authentication) to prevent unauthorized routers (or endpoints pretending to be routers) from joining the network.

SSL/TLS mutual authentication requires an X.509 Certificate Authority (CA) with individual certificates generated for each interior router. Connections between the interior routers are encrypted, and the CA authenticates each incoming inter-router connection.

This procedure describes how to secure a connection between two interior routers using SSL/TLS mutual authentication.

Prerequisites

An X.509 Certificate Authority must exist for the interior routers.
A security certificate must be generated for each router and be signed by the CA.
An inter-router connection must exist between the routers.
For more information, see Section 4.2.1, “Connecting routers”.

Procedure

On the router that establishes the connection, do the following:
1. Open the /etc/qpid-dispatch/qdrouterd.conf.
2. If the router does not contain an sslProfile that defines the private keys and certificates for the inter-router network, then add one.
  This sslProfile contains the locations of the private key and certificates that the router uses to authenticate with its peer.
```
sslProfile {
    name: inter-router-tls
    certFile: /etc/qpid-dispatch-certs/inter-router/tls.crt
    privateKeyFile: /etc/qpid-dispatch-certs/inter-router/tls.key
    caCertFile: /etc/qpid-dispatch-certs/inter-router/ca.crt
    ...
}
```
  name
  A unique name that you can use to refer to this sslProfile.
  certFile
  The absolute path to the file containing the public certificate for this router.
  privateKeyFile
  The absolute path to the file containing the private key for this router’s public certificate.
  caCertFile
  The absolute path to the CA certificate that was used to sign the router’s certificate.
3. Configure the inter-router connector for this connection to use the sslProfile that you created.
```
connector {
    host: 192.0.2.1
    port: 5001
    role: inter-router
    sslProfile: inter-router-tls
    ...
}
```
  sslProfile
  The name of the sslProfile that defines the SSL/TLS private keys and certificates for the inter-router network.
On the router that listens for the connection, do the following:
1. Open the /etc/qpid-dispatch/qdrouterd.conf.
2. If the router does not contain an sslProfile that defines the private keys and certificates for the inter-router network, then add one.
3. Configure the inter-router listener for this connection to use SSL/TLS to secure the connection.
```
listener {
    host: 0.0.0.0
    port: 5001
    role: inter-router
    sslProfile: inter_router_tls
    authenticatePeer: yes
    requireSsl: yes
    saslMechanisms: EXTERNAL
    ...
}
```
  sslProfile
  The name of the sslProfile that defines the SSL/TLS private keys and certificates for the inter-router network.
  authenticatePeer
  Specify yes to authenticate the peer interior router’s identity.
  requireSsl
  Specify yes to encrypt the connection with SSL/TLS.
  saslMechanisms
  Specify EXTERNAL to enable X.509 client certificate authentication.

4.3.2. Securing incoming client connections

You can use SSL/TLS and SASL to provide the appropriate level of security for client traffic into the router network. You can use the following methods to secure incoming connections to a router from AMQP clients, external containers, or edge routers:

4.3.2.1. Enabling SSL/TLS encryption

You can use SSL/TLS to encrypt an incoming connection from a client.

Prerequisites

An X.509 Certificate Authority (CA) must exist for the client connections.
A security certificate must be generated and signed by the CA.

Procedure

Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.
If the router does not contain an sslProfile that defines the private keys and certificates for client connections, then add one.
This sslProfile contains the locations of the private key and certificates that the router should use to encrypt connections from clients.
```
sslProfile {
    name: service-tls
    certFile: /etc/qpid-dispatch-certs/normal/tls.crt
    privateKeyFile: /etc/qpid-dispatch-certs/normal/tls.key
    caCertFile: /etc/qpid-dispatch-certs/client-ca/ca.crt
    ...
}
```
name
A unique name that you can use to refer to this sslProfile.
certFile
The absolute path to the file containing the public certificate for this router.
privateKeyFile
The absolute path to the file containing the private key for this router’s public certificate.
caCertFile
The absolute path to the CA certificate that was used to sign the router’s certificate.
Configure the listener for this connection to use SSL/TLS to encrypt the connection.
This example configures a normal listener to encrypt connections from clients.
```
listener {
    host: 0.0.0.0
    port: 5672
    role: normal
    sslProfile: inter_router_tls
    requireSsl: yes
    ...
}
```
sslProfile
The name of the sslProfile that defines the SSL/TLS private keys and certificates for client connections.
requireSsl
Specify true to encrypt the connection with SSL/TLS.

4.3.2.2. Enabling SSL/TLS client authentication

In addition to SSL/TLS encryption, you can also use SSL/TLS to authenticate an incoming connection from a client. With this method, a clients must present its own X.509 certificate to the router, which the router uses to verify the client’s identity.

Prerequisites

SSL/TLS encryption must be configured.
For more information, see Section 4.3.2.1, “Enabling SSL/TLS encryption”.
The client must have an X.509 certificate that it can use to authenticate to the router.

Procedure

Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.
Configure the listener for this connection to use SSL/TLS to authenticate the client.
This example adds SSL/TLS authentication to a normal listener to authenticate incoming connections from a client. The client will only be able to connect to the router by presenting its own X.509 certificate to the router, which the router will use to verify the client’s identity.
```
listener {
    host: 0.0.0.0
    port: 5672
    role: normal
    sslProfile: service-tls
    requireSsl: yes
    authenticatePeer: yes
    saslMechanisms: EXTERNAL
    ...
}
```
authenticatePeer
Specify yes to authenticate the client’s identity.
saslMechanisms
Specify EXTERNAL to enable X.509 client certificate authentication.

4.3.2.3. Enabling user name and password authentication

You can use the SASL PLAIN mechanism to authenticate incoming client connections against a set of user names and passwords. You can use this method by itself, or you can combine it with SSL/TLS encryption.

Prerequisites

A SASL database containing the usernames and passwords exists.
The SASL configuration file is configured.
By default, this file should be /etc/sasl2/qdrouterd.conf.
The cyrus-sasl-plain plugin is installed.
Cyrus SASL uses plugins to support specific SASL mechanisms. Before you can use a particular SASL mechanism, the relevant plugin must be installed.
To see a list of Cyrus SASL plugins in Red Hat Enterprise Linux, use the yum search cyrus-sasl command. To install a Cyrus SASL plugin, use the yum install PLUGIN command.

Procedure

Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.
In the router section, specify the path to the SASL configuration file.
```
router {
    mode: interior
    id: Router.A
    saslConfigDir: /etc/sasl2/
}
```
saslConfigDir
The absolute path to the SASL configuration file that contains the path to the SASL database that stores the user names and passwords.
Configure the listener for this connection to authenticate clients using SASL PLAIN.
This example configures basic user name and password authentication for a listener. In this case, no SSL/TLS encryption is being used.
```
listener {
    host: 0.0.0.0
    port: 5672
    authenticatePeer: yes
    saslMechanisms: PLAIN
    }
```

4.3.2.4. Integrating with Kerberos

If you have implemented Kerberos in your environment, you can use it with the GSSAPI SASL mechanism to authenticate incoming connections.

Prerequisites

A Kerberos infrastructure must be deployed in your environment.
In the Kerberos environment, a service principal of amqp/<hostname>@<realm> must be configured.
This is the service principal that AMQ Interconnect uses.
The cyrus-sasl-gssapi package must be installed on each client and the router host machine.

Procedure

On the router’s host machine, open the /etc/sasl2/qdrouterd.conf configuration file.

This example shows a /etc/sasl2/qdrouterd.conf configuration file:

pwcheck_method: auxprop
auxprop_plugin: sasldb
sasldb_path: qdrouterd.sasldb
keytab: /etc/krb5.keytab
mech_list: ANONYMOUS DIGEST-MD5 EXTERNAL PLAIN GSSAPI

Verify the following:
- The mech_list attribute contains the GSSAPI mechanism.
- The keytab attribute points to the location of the keytab file.
Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.
In the router section, specify the path to the SASL configuration file.
```
router {
    mode: interior
    id: Router.A
    saslConfigDir: /etc/sasl2/
}
```
saslConfigDir
The absolute path to the SASL configuration file that contains the path to the SASL database.
For each incoming connection using Kerberos for authentication, set the listener to use the GSSAPI mechanism.
```
listener {
    host: 0.0.0.0
    port: 5672
    authenticatePeer: yes
    saslMechanisms: GSSAPI
    }
```

4.3.3. Securing outgoing connections

If a router is configured to create connections to external AMQP containers (such as message brokers), you can configure the connections to use the appropriate level of security.

You can configure a router to create outgoing connections using:

4.3.3.1. Connecting using one-way SSL/TLS authentication

You can connect to an external AMQP container (such as a broker) using one-way SSL/TLS. With this method, the router validates the external AMQP container’s server certificate to verify its identity.

Procedure

Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.
If the router does not contain an sslProfile that defines a certificate that can be used to validate the external AMQP container’s identity, then add one.
```
sslProfile {
    name: broker-tls
    caCertFile: /etc/qpid-dispatch-certs/ca.crt
    ...
}
```
name
A unique name that you can use to refer to this sslProfile.
caCertFile
The absolute path to the CA certificate used to verify the external AMQP container’s identity.
Configure the connector for this connection to use SSL/TLS to validate the server certificate received by the broker during the SSL handshake.
This example configures a connector to a broker. When the router connects to the broker, it will use the CA certificate defined in the broker-tls sslProfile to validate the server certificate received from the broker.
```
connector {
    host: 192.0.2.1
    port: 5672
    role: route-container
    sslProfile: broker-tls
    ...
}
```
sslProfile
The name of the sslProfile that defines the certificate to use to validate the external AMQP container’s identity.

4.3.3.2. Connecting using mutual SSL/TLS authentication

You can connect to an external AMQP container (such as a broker) using mutual SSL/TLS authentication. With this method, the router, acting as a client, provides a certificate to the external AMQP container so that it can verify the router’s identity.

Prerequisites

An X.509 Certificate Authority (CA) must exist for the router.
A security certificate must be generated for the router and be signed by the CA.

Procedure

Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.
If the router does not contain an sslProfile that defines the private keys and certificates to connect to the external AMQP container, then add one.
This sslProfile contains the locations of the private key and certificates that the router should use to authenticate with its peer.
```
sslProfile {
    name: broker-tls
    certFile: /etc/qpid-dispatch-certs/tls.crt
    privateKeyFile: /etc/qpid-dispatch-certs/tls.key
    caCertFile: /etc/qpid-dispatch-certs/ca.crt
    ...
}
```
name
A unique name that you can use to refer to this sslProfile.
certFile
The absolute path to the file containing the public certificate for this router.
privateKeyFile
The absolute path to the file containing the private key for this router’s public certificate.
caCertFile
The absolute path to the CA certificate that was used to sign the router’s certificate.
Configure the connector for this connection to use the sslProfile that you created.
```
connector {
    host: 192.0.2.1
    port: 5672
    role: route-container
    sslProfile: broker-tls
    saslMechanisms: EXTERNAL
    ...
}
```
sslProfile
The name of the sslProfile that defines the SSL/TLS private keys and certificates for the inter-router network.

4.3.3.3. Connecting using user name and password authentication

You can use the SASL PLAIN mechanism to connect to an external AMQP container that requires a user name and password. You can use this method by itself, or you can combine it with SSL/TLS encryption.

Prerequisites

The cyrus-sasl-plain plugin is installed.
Cyrus SASL uses plugins to support specific SASL mechanisms. Before you can use a particular SASL mechanism, the relevant plugin must be installed.
To see a list of Cyrus SASL plugins in Red Hat Enterprise Linux, use the yum search cyrus-sasl command. To install a Cyrus SASL plugin, use the yum install PLUGIN command.

Procedure

Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.

Configure the connector for this connection to provide user name and password credentials to the external AMQP container.

connector {
    host: 192.0.2.1
    port: 5672
    role: route-container
    saslMechanisms: PLAIN
    saslUsername: user
    saslPassword: password
    }

4.4. Authorizing Access to Messaging Resources

You can configure policies to secure messaging resources in your messaging environment. Policies ensure that only authorized users can access messaging endpoints through the router network, and that the resources on those endpoints are used in an authorized way.

AMQ Interconnect provides the following types of policies:

Global policies: Settings for the router. A global policy defines the maximum number of incoming user connections for the router (across all messaging endpoints), and defines how the router should use vhost policies.
Vhost policies: Connection and AMQP resource limits for a messaging endpoint (called an AMQP virtual host, or vhost). A vhost policy defines what a client can access on a messaging endpoint over a particular connection.

The resource limits defined in global and vhost policies are applied to user connections only. The limits do not affect inter-router connections or router connections that are outbound to waypoints.

4.4.1. How AMQ Interconnect Enforces Connection and Resource Limits

AMQ Interconnect uses policies to determine whether to permit a connection, and if it is permitted, to apply the appropriate resource limits.

When a client creates a connection to the router, the router first determines whether to allow or deny the connection. This decision is based on the following criteria:

Whether the connection will exceed the router’s global connection limit (defined in the global policy)
Whether the connection will exceed the vhost’s connection limits (defined in the vhost policy that matches the host to which the connection is directed)

If the connection is allowed, the router assigns the user (the authenticated user name from the connection) to a user group, and enforces the user group’s resource limits for the lifetime of the connection.

4.4.2. Setting Global Connection Limits

You can set the incoming connection limit for the router. This limit defines the total number of concurrent client connections that can be open for this router.

Procedure

In the router configuration file, add a policy section and set the maxConnections.
```
policy {
    maxConnections: 10000
}
```
maxConnections
This limit is always enforced, even if no other policy settings have been defined. The limit is applied to all incoming connections regardless of remote host, authenticated user, or targeted vhost. The default (and the maximum) value is 65535.

4.4.3. Setting Connection and Resource Limits for Messaging Endpoints

You can define the connection limit and AMQP resource limits for a messaging endpoint by configuring a vhost policy. Vhost policies define what resources clients are permitted to access on a messaging endpoint over a particular connection.

Note

A vhost is typically the name of the host to which the client connection is directed. For example, if a client application opens a connection to the amqp://mybroker.example.com:5672/queue01 URL, the vhost would be mybroker.example.com.

You can create vhost policies using either of the following methods:

4.4.3.1. Enabling Vhost Policies

You must enable the router to use vhost policies before you can create the policies.

Procedure

In the router configuration file, add a policy section if one does not exist, and enable vhost policies for the router.
```
policy {
    ...
    enableVhostPolicy: true
    enableVhostNamePatterns: true | false
    defaultVhost: $default
}
```
enableVhostPolicy
Enables the router to enforce the connection denials and resource limits defined in the configured vhost policies. The default is false, which means that the router will not enforce any vhost policies.
enableVhostNamePatterns
Enables pattern matching for vhost hostnames. If set to true, you can use wildcards to specify a range of hostnames for a vhost. If set to false, vhost hostnames are treated as literal strings. This means that you must specify the exact hostname for each vhost. The default is false.
defaultVhost
The name of the default vhost policy, which is applied to any connection for which a vhost policy has not been configured. The default is $default. If defaultVhost is not defined, then default vhost processing is disabled.

4.4.3.2. Configuring Vhost Policies in the Router Configuration File

You can configure vhost policies in the router configuration file by configuring vhost entities. However, if multiple routers in your router network should be configured with the same vhost configuration, you will need to add the vhost configuration to each router’s configuration file.

Prerequisites

Vhost policies must be enabled for the router. For more information, see Section 4.4.3.1, “Enabling Vhost Policies”.

Procedure

Add a vhost section and define the connection limits for the messaging endpoint.
The connection limits apply to all users that are connected to the vhost. These limits control the number of users that can be connected simultaneously to the vhost.
```
vhost {
    hostname: example.com
    maxConnections: 10000
    maxConnectionsPerUser: 100
    maxConnectionsPerHost: 100
    allowUnknownUser: true
    ...
}
```
hostname
The literal hostname of the vhost (the messaging endpoint) or a pattern that matches the vhost hostname. This vhost policy will be applied to any client connection that is directed to the hostname that you specify. This name must be unique; you can only have one vhost policy per hostname.
If enableVhostNamePatterns is set to true, you can use wildcards to specify a pattern that matches a range of hostnames. For more information, see Section 4.4.3.5, “Pattern Matching for Vhost Policy Hostnames”.
maxConnections
The global maximum number of concurrent client connections allowed for this vhost. The default is 65535.
maxConnectionsPerUser
The maximum number of concurrent client connections allowed for any user. The default is 65535.
maxConnectionsPerHost
The maximum number of concurrent client connections allowed for any remote host (the host from which the client is connecting). The default is 65535.
allowUnknownUser
Whether unknown users (users who are not members of a defined user group) are allowed to connect to the vhost. Unknown users are assigned to the $default user group and receive $default settings. The default is false, which means that unknown users are not allowed.
In the vhost section, beneath the connection settings that you added, add a groups entity to define the resource limits.
You define resource limits by user group. A user group specifies the messaging resources the members of the group are allowed to access.
Example 4.1. User Groups in a Vhost Policy
This example shows three user groups: admin, developers, and $default:
```
vhost {
    ...
    groups: {
        admin: {
            users: admin1, admin2
            remoteHosts: 127.0.0.1, ::1
            sources: *
            targets: *
        }
        developers: {
            users: dev1, dev2, dev3
            remoteHosts: *
            sources: myqueue1, myqueue2
            targets: myqueue1, myqueue2
        }
        $default: {
            remoteHosts: *
            allowDynamicSource: true,
            allowAdminStatusUpdate: true,
            sources: myqueue1, myqueue2
            targets: myqueue1, myqueue2
        }
    }
}
```
users
A list of authenticated users for this user group. Use commas to separate multiple users. A user may belong to only one vhost user group.
remoteHosts
A list of remote hosts from which the users may connect. A host can be a hostname, IP address, or IP address range. Use commas to separate multiple hosts. To allow access from all remote hosts, specify a wildcard *. To deny access from all remote hosts, leave this attribute blank.
allowDynamicSource
If true, connections from users in this group are permitted to attach receivers to dynamic sources. This permits creation of listners to temporary addresses or termporary queues. If false, use of dynamic sources is forbidden.
allowAdminStatusUpdate
If true, connections from users in this group are permitted to modify the adminStatus of connections. This permits termination of sender or receiver connections. If false, the users of this group are prohibited from terminating any connections. Inter-router connections can never be terminated by any user under any circumstance. Defaults to true, no policy required.
allowWaypointLinks
If true, connections from users in this group are permitted to attach links using waypoint capabilities. This allows endpoints to act as waypoints (i.e. brokers) without the need for configuring auto-links. If false, use of waypoint capabilities is forbidden.
allowDynamicLinkRoutes
If true, connections from users in this group may dynamically create connection-scoped link route destinations. This allows endpoints to act as link route destinations (i.e. brokers) without the need for configuring link-routes. If false, creation of dynamic link route destintations is forbidden.
allowFallbackLinks
If true, connections from users in this group are permitted to attach links using fallback-link capabilities. This allows endpoints to act as fallback destinations (and sources) for addresses that have fallback enabled. If false, use of fallback-link capabilities is forbidden.
sources | sourcePattern
A list of AMQP source addresses from which users in this group may receive messages.
Use sources to specify one or more literal addresses. To specify multiple addresses, use a comma-separated list. To prevent users in this group from receiving messages from any addresses, leave this attribute blank. To allow access to an address specific to a particular user, specify the ${user} token. For more information, see Section 4.4.3.6, “Methods for Specifying Vhost Policy Source and Target Addresses”.
Alternatively, you can use sourcePattern to match one or more addresses that correspond to a pattern. A pattern is a sequence of words delimited by either a . or / character. You can use wildcard characters to represent a word. The * character matches exactly one word, and the # character matches any sequence of zero or more words.
To specify multiple address ranges, use a comma-separated list of address patterns. For more information, see Router Address Pattern Matching. To allow access to address ranges that are specific to a particular user, specify the ${user} token. For more information, see Section 4.4.3.6, “Methods for Specifying Vhost Policy Source and Target Addresses”.
targets | targetPattern
A list of AMQP target addresses from which users in this group may send messages. You can specify multiple AMQP addresses and use user name substitution and address patterns the same way as with source addresses.
If necessary, add any advanced user group settings to the vhost user groups.
The advanced user group settings enable you to define resource limits based on the AMQP connection open, session begin, and link attach phases of the connection. For more information, see vhost in the qdrouterd.conf man page.

4.4.3.3. Configuring Resource Limits for Outgoing Connections

If the router establishes an outgoing connection to an external AMQP container (such as a client or broker), you can restrict the resources that the external container can access on the router by configuring a connector vhost policy.

The resource limits that are defined in a connector vhost policy are applied to links that are initiated by the external AMQP container. The connector vhost policy does not restrict links that the router creates.

A connector vhost policy can only be applied to a connector with a normal or route-container role. You cannot apply connector vhost policies to connectors that have inter-router or edge roles.

Prerequisites

Vhost policies are enabled for the router. For more information, see Section 4.4.3.1, “Enabling Vhost Policies”.

Procedure

In the router’s configuration file, add a vhost section with a $connector user group.
```
vhost {
    hostname: my-connector-policy
    groups: {
        $connector: {
            sources: *
            targets: *
            maxSenders: 5
            maxReceivers: 10
            allowAnonymousSender: true
            allowWaypointLinks: true
        }
    }
}
```
hostname
A unique name to identify the connector vhost policy. This name does not represent an actual hostname; therefore, choose a name that will not conflict with an actual vhost hostname.
$connector
Identifies this vhost policy as a connector vhost policy.
Apply the connector vhost policy to the connector that establishes the connection to the external AMQP container.
The following example applies the connector vhost policy that was configured in the previous step:
```
connector {
    host: 192.0.2.10
    port: 5672
    role: normal
    policyVhost: my-connector-policy
}
```

4.4.3.4. Configuring Vhost Policies as JSON Files

As an alternative to using the router configuration file, you can configure vhost policies in JSON files. If you have multiple routers that need to share the same vhost configuration, you can put the vhost configuration JSON files in a location accessible to each router, and then configure the routers to apply the vhost policies defined in these JSON files.

Prerequisites

Vhost policies must be enabled for the router. For more information, see Section 4.4.3.1, “Enabling Vhost Policies”.

Procedure

In the router configuration file, specify the directory where you want to store the vhost policy definition JSON files.
```
policy {
    ...
    policyDir: DIRECTORY_PATH
}
```
policyDir
The absolute path to the directory that holds vhost policy definition files in JSON format. The router processes all of the vhost policies in each JSON file that is in this directory.

In the vhost policy definition directory, create a JSON file for each vhost policy.

Example 4.2. Vhost Policy Definition JSON File

[
    ["vhost", {
        "hostname": "example.com",
        "maxConnections": 10000,
        "maxConnectionsPerUser": 100,
        "maxConnectionsPerHost": 100,
        "allowUnknownUser": true,
        "groups": {
            "admin": {
                "users": ["admin1", "admin2"],
                "remoteHosts": ["127.0.0.1", "::1"],
                "sources": "*",
                "targets": "*"
            },
            "developers": {
                "users": ["dev1", "dev2", "dev3"],
                "remoteHosts": "*",
                "sources": ["myqueue1", "myqueue2"],
                "targets": ["myqueue1", "myqueue2"]
            },
            "$default": {
                "remoteHosts": "*",
                "allowDynamicSource": true,
                "sources": ["myqueue1", "myqueue2"],
                "targets": ["myqueue1", "myqueue2"]
            }
        }
    }]
]

For more information about these attributes, see Section 4.4.3.2, “Configuring Vhost Policies in the Router Configuration File”.

4.4.3.5. Pattern Matching for Vhost Policy Hostnames

In a vhost policy, vhost hostnames can be either literal hostnames or patterns that cover a range of hostnames.

A hostname pattern is a sequence of words with one or more of the following wildcard characters:

* represents exactly one word
# represents zero or more words

The following table shows some examples of hostname patterns:

This pattern…	Matches…	But not…
`*.example.com`	`www.example.com`	`example.comsrv2.www.example.com`
`#.example.com`	`example.comwww.example.coma.b.c.d.example.com`	`myhost.com`
`www.*.test.example.com`	`www.a.test.example.com`	`www.test.example.comwww.a.b.c.test.example.com`
`www.#.test.example.com`	`www.test.example.comwww.a.test.example.comwww.a.b.c.test.example.com`	`test.example.com`

Vhost hostname pattern matching applies the following precedence rules:

Policy pattern	Precedence
Exact match	High
*	Medium
#	Low

Note

AMQ Interconnect does not permit you to create vhost hostname patterns that conflict with existing patterns. This includes patterns that can be reduced to be the same as an existing pattern. For example, you would not be able to create the #.#.#.#.com pattern if #.com already exists.

4.4.3.6. Methods for Specifying Vhost Policy Source and Target Addresses

If you want to allow or deny access to multiple addresses on a vhost, there are several methods you can use to match multiple addresses without having to specify each address individually.

The following table describes the methods you can use to specify multiple source and target addresses for a vhost:

To…	Do this…
Allow all users in the user group to access all source or target addresses on the vhost	Use a `` wildcard character. Example 4.3. Receive from Any Address* sources: *
Prevent all users in the user group from accessing all source or target addresses on the vhost	Do not specify a value. Example 4.4. Prohibit Message Transfers to All Addresses targets:
Allow access to some resources specific to each user	Use the `${user}` username substitution token. You can use this token with `source`, `target`, `sourcePattern`, and `targetPattern`. Note You can only specify the `${user}` token once in an AMQP address name or pattern. If there are multiple tokens in an address, only the leftmost token will be substituted. Example 4.5. Receive from a User-Specific Address This definition allows the users in the user group to receive messages from any address that meets any of the following rules: Starts with the prefix `tmp_` and ends with the user name Starts with the prefix `temp` followed by any additional characters Starts with the user name, is followed by `-home-`, and ends with any additional characters sources: tmp_${user}, temp, ${user}-home- Example 4.6. User-Specific Address Patterns This definition allows the users in the user group to receive messages from any address that meets any of the following rules: Starts with the prefix `tmp` and ends with the user name Starts with the prefix `temp` followed by zero or more additional characters Starts with the user name, is followed by `home`, and ends with one or more additional characters sourcePattern: tmp.${user}, temp/#, ${user}.home/* Note In an address pattern (`sourcePattern` or `targetPattern`), the username substitution token must be either the first or last token in the pattern. The token must also be alone within its delimited field, which means that it cannot be concatenated with literal text prefixes or suffixes.

4.4.3.7. Vhost Policy Examples

These examples demonstrate how to use vhost policies to authorize access to messaging resources.

Example 4.7. Defining Basic Resource Limits for a Messaging Endpoint

In this example, a vhost policy defines resource limits for clients connecting to the example.com host.

[
    ["vhost", {
        "hostname": "example.com",  1
        "maxConnectionsPerUser": 10,  2
        "allowUnknownUser": true,  3
        "groups": {
            "admin": {
                "users": ["admin1", "admin2"],  4
                "remoteHosts": ["127.0.0.1", "::1"],  5
                "sources": "*",  6
                "targets": "*"  7
            },
            "$default": {
                "remoteHosts": "*",  8
                "sources": ["news*", "sports*" "chat*"],  9
                "targets": "chat*"  10
            }
        }
    }]
]

1: The rules defined in this vhost policy will be applied to any user connecting to example.com.
2: Each user can open up to 10 connections to the vhost.
3: Any user can connect to this vhost. Users that are not part of the admin group are assigned to the $default group.
4: If the admin1 or admin2 user connects to the vhost, they are assigned to the admin user group.
5: Users in the admin user group must connect from localhost. If the admin user attempts to connect from any other host, the connection will be denied.
6: Users in the admin user group can receive from any address offered by the vhost.
7: Users in the admin user group can send to any address offered by the vhost.
8: Any non-admin user is permitted to connect from any host.
9: Non-admin users are permitted to receive messages from any addresses that start with the news, sports, or chat prefixes.
10: Non-admin users are permitted to send messages to any addresses that start with the chat prefix.

Example 4.8. Limiting Memory Consumption

By using the advanced vhost policy attributes, you can control how much system buffer memory a user connection can potentially consume.

In this example, a stock trading site provides services for stock traders. However, the site must also accept high-capacity, automated data feeds from stock exchanges. To prevent trading activity from consuming memory needed for the feeds, a larger amount of system buffer memory is allotted to the feeds than to the traders.

This example uses the maxSessions and maxSessionWindow attributes to set the buffer memory consumption limits for each AMQP session. These settings are passed directly to the AMQP connection and session negotiations, and do not require any processing cycles on the router.

This example does not show the vhost policy settings that are unrelated to buffer allocation.

[
    ["vhost", {
        "hostname": "traders.com",  1
        "groups": {
            "traders": {
                "users": ["trader1", "trader2"],  2
                "maxFrameSize": 10000,
                "maxSessionWindow": 5000000,  3
                "maxSessions": 1  4
            },
            "feeds": {
                "users": ["nyse-feed", "nasdaq-feed"],  5
                "maxFrameSize": 60000,
                "maxSessionWindow": 1200000000,  6
                "maxSessions": 3  7
            }
        }
    }]
]

1: The rules defined in this vhost policy will be applied to any user connecting to traders.com.
2: The traders group includes trader1, trader2, and any other user defined in the list.
3: At most, 5,000,000 bytes of data can be in flight on each session.
4: Only one session per connection is allowed.
5: The feeds group includes two users.
6: At most, 1,200,000,000 bytes of data can be in flight on each session.
7: Up to three sessions per connection are allowed.

Select Your Language

Language:

Language:

Chapter 4. Configuring a router

4.1. Configuring router properties

4.2. Configuring network connections

4.2.1. Connecting routers

4.2.2. Listening for client connections

4.2.3. Connecting to external AMQP containers

4.2.4. Connection failover

4.3. Securing network connections

4.3.1. Securing connections between routers

4.3.2. Securing incoming client connections

4.3.2.1. Enabling SSL/TLS encryption

4.3.2.2. Enabling SSL/TLS client authentication

4.3.2.3. Enabling user name and password authentication

4.3.2.4. Integrating with Kerberos

4.3.3. Securing outgoing connections

4.3.3.1. Connecting using one-way SSL/TLS authentication

4.3.3.2. Connecting using mutual SSL/TLS authentication

4.3.3.3. Connecting using user name and password authentication

4.4. Authorizing Access to Messaging Resources

4.4.1. How AMQ Interconnect Enforces Connection and Resource Limits

4.4.2. Setting Global Connection Limits

4.4.3. Setting Connection and Resource Limits for Messaging Endpoints

4.4.3.1. Enabling Vhost Policies

4.4.3.2. Configuring Vhost Policies in the Router Configuration File

4.4.3.3. Configuring Resource Limits for Outgoing Connections

4.4.3.4. Configuring Vhost Policies as JSON Files

4.4.3.5. Pattern Matching for Vhost Policy Hostnames

4.4.3.6. Methods for Specifying Vhost Policy Source and Target Addresses

4.4.3.7. Vhost Policy Examples

Quick Links

Help

Site Info

Related Sites

About

Red Hat legal and privacy links

Red Hat legal and privacy links

Language:

Language and Page Formatting Options

Language:

Chapter 4. Configuring a router

4.1. Configuring router properties

4.2. Configuring network connections

4.2.1. Connecting routers

4.2.2. Listening for client connections

4.2.3. Connecting to external AMQP containers

4.2.4. Connection failover

4.3. Securing network connections

4.3.1. Securing connections between routers

4.3.2. Securing incoming client connections

4.3.2.1. Enabling SSL/TLS encryption

4.3.2.2. Enabling SSL/TLS client authentication

4.3.2.3. Enabling user name and password authentication

4.3.2.4. Integrating with Kerberos

4.3.3. Securing outgoing connections

4.3.3.1. Connecting using one-way SSL/TLS authentication

4.3.3.2. Connecting using mutual SSL/TLS authentication

4.3.3.3. Connecting using user name and password authentication

4.4. Authorizing Access to Messaging Resources

4.4.1. How AMQ Interconnect Enforces Connection and Resource Limits

4.4.2. Setting Global Connection Limits

4.4.3. Setting Connection and Resource Limits for Messaging Endpoints

4.4.3.1. Enabling Vhost Policies

4.4.3.2. Configuring Vhost Policies in the Router Configuration File

4.4.3.3. Configuring Resource Limits for Outgoing Connections

4.4.3.4. Configuring Vhost Policies as JSON Files

4.4.3.5. Pattern Matching for Vhost Policy Hostnames

4.4.3.6. Methods for Specifying Vhost Policy Source and Target Addresses

4.4.3.7. Vhost Policy Examples

Quick Links

Help

Site Info

Related Sites

Systems Status

About

Red Hat legal and privacy links

Red Hat legal and privacy links