docs/books/user-guide/managing-using-qdmanage.adoc

////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License
////

[id='managing-router']
= Managing {RouterName} Using `qdmanage`

You can use `qdmanage` to view and modify the configuration of a running router at runtime. Specifically, `qdmanage` enables you to create, read, update, and delete the sections and attributes in the router's configuration file without having to restart the router.

[NOTE]
====
The `qdmanage` tool implements the AMQP management specification, which means that you can use it with any standard AMQP-managed endpoint, not just with {RouterName}.
====

== Syntax for Using `qdmanage`

You can use `qdmanage` with the following syntax:

[options="nowrap",subs="+quotes"]
----
$ qdmanage [__CONNECTION_OPTIONS__] __OPERATION__ [__OPTIONS__]
----

This specifies:

* One or more optional `connection_options` to specify the router on which to perform the operation, or to supply security credentials if the router only accepts secure connections.
+
If you do not specify any connection options, `qdmanage` connects to the router listening on localhost and the default AMQP port (5672).
* The `operation` to perform on the router.
* One or more optional `options` to specify a configuration entity on which to perform the operation or how to format the command output.

When you enter a `qdmanage` command, it is executed as an AMQP management operation request, and then the response is returned as command output in JSON format.

For example, the following command executes a query operation on a router, and then returns the response in JSON format:

[options="nowrap"]
----
$ qdmanage query --type listener
[
  {
    "stripAnnotations": "both", 
    "addr": "127.0.0.1", 
    "multiTenant": false, 
    "requireSsl": false, 
    "idleTimeoutSeconds": 16, 
    "saslMechanisms": "ANONYMOUS", 
    "maxFrameSize": 16384, 
    "requireEncryption": false, 
    "host": "0.0.0.0", 
    "cost": 1, 
    "role": "normal", 
    "http": false, 
    "maxSessions": 32768, 
    "authenticatePeer": false, 
    "type": "org.apache.qpid.dispatch.listener", 
    "port": "amqp", 
    "identity": "listener/0.0.0.0:amqp", 
    "name": "listener/0.0.0.0:amqp"
  }
]
----

For more information about `qdmanage`, see the {qdmanageManPageLink}.

== Managing Network Connections

You can use `qdmanage` to view, create, update, and delete listeners and connectors for any router in your router network.

=== Managing Listeners

Listeners define how clients can connect to a router. The following table lists the `qdmanage` commands you can use to perform common operations on listeners.

For more information about the attributes you can use with these commands, see link:{qdrouterdConfManPageUrl}#_listener[listener] in the `qdrouterd.conf` man page.

//tag::qdmanage-connection-options-note[]
[NOTE]
====
The commands in this table demonstrate operations on the local router listening on localhost and the default AMQP port (5672). If you want to perform an operation on a different router in the router network, you must specify the necessary connection options. For more information, see link:{qdmanageManPageUrl}#_connection_options[Connection Options] in the qdmanage man page.
====
//end::qdmanage-connection-options-note[]

[cols="30,70"]
|===
| To... | Use this command...

|View the router’s listeners
a|
[options="nowrap"]
----
qdmanage query --type=listener
----

|View the roles and ports on which the router is listening
a|
[options="nowrap"]
----
qdmanage query role port --type=listener
----

|View the attributes configured for a listener
a|
[options="nowrap",subs="+quotes"]
----
qdmanage read --name=_LISTENER_NAME_
----

|Create a listener
a|
[options="nowrap",subs="+quotes"]
----
qdmanage create --type=listener --_ATTRIBUTE_=_VALUE_ ...
----

|Create multiple listeners
a|
. Enter this command:
+
[options="nowrap"]
----
qdmanage create --stdin 
----
. Configure the listeners using a JSON map:
+
[options="nowrap",subs="+quotes"]
----
[{"type"="listener", "_ATTRIBUTE_":"_VALUE_"...}, {"type"="listener", "_ATTRIBUTE_":"_VALUE_"...}...]
----

These commands use a JSON map to create two listeners.

|Update a listener
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --type=listener --_ATTRIBUTE_=_VALUE_ ...
----

|Update multiple listeners
a|
. Enter this command:
+
[options="nowrap"]
----
qdmanage update --stdin 
----
. Configure the listeners using a JSON map:
+
[options="nowrap",subs="+quotes"]
----
[{"type"="listener", "_ATTRIBUTE_":"_VALUE_"...}, {"type"="listener", "_ATTRIBUTE_":"_VALUE_"...}...]
----

These commands use a JSON map to update two listeners.

|Delete an attribute from a listener
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --type=listener --_ATTRIBUTE_
----

|Delete a listener
a|
[options="nowrap",subs="+quotes"]
----
qdmanage delete --name=_LISTENER_NAME_
----

|===

[id='managing-connectors']
=== Managing Connectors

Connectors define how the router can connect to other endpoints in your messaging network, such as brokers and other routers. The following table lists the `qdmanage` commands you can use to perform common operations on connectors.

For more information about the attributes you can use with these commands, see link:{qdrouterdConfManPageUrl}#_connector[connector] in the `qdrouterd.conf` man page.

// Note about qdmanage connection options.
include::managing-using-qdmanage.adoc[tags=qdmanage-connection-options-note]

[cols="30,70"]
|===
| To... | Use this command...

|View the router’s connectors
a|
[options="nowrap"]
----
qdmanage query --type=connector
----

|View the roles and ports on which the router can connect to other endpoints
a|
[options="nowrap"]
----
qdmanage query role port --type=connector
----

|If the router is connected to a broker, view the alternate URLs on which the router can connect to the broker if the primary connection fails
a|
[options="nowrap",subs="+quotes"]
----
qdmanage query failoverUrls --type=connector --name=CONNECTOR_NAME
----

|View the attributes configured for a connector
a|
[options="nowrap",subs="+quotes"]
----
qdmanage read --name=_CONNECTOR_NAME_
----

|Create a connector
a|
[options="nowrap",subs="+quotes"]
----
qdmanage create --type=connector --_ATTRIBUTE_=_VALUE_ ...
----

|Create multiple connectors
a|
. Enter this command:
+
[options="nowrap"]
----
qdmanage create --stdin 
----
. Configure the connectors using a JSON map:
+
[options="nowrap",subs="+quotes"]
----
[{"type"="connector", "_ATTRIBUTE_":"_VALUE_"...}, {"type"="connector", "_ATTRIBUTE_":"_VALUE_"...}...]
----

These commands use a JSON map to create two connectors.

|Update a connector
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --type=connector --_ATTRIBUTE_=_VALUE_ ...
----

|Update multiple connectors
a|
. Enter this command:
+
[options="nowrap"]
----
qdmanage update --stdin 
----
. Configure the connectors using a JSON map:
+
[options="nowrap",subs="+quotes"]
----
[{"type"="connector", "_ATTRIBUTE_":"_VALUE_"...}, {"type"="connector", "_ATTRIBUTE_":"_VALUE_"...}...]
----

These commands use a JSON map to update two connectors.

|Delete an attribute from a connector
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --type=connector --_ATTRIBUTE_
----

|Delete a connector
a|
[options="nowrap",subs="+quotes"]
----
qdmanage delete --name=_CONNECTOR_NAME_
----

|===

== Managing Security

{RouterName} supports both SSL/TLS and SASL security protocols for encrypting and authenticating incoming and outgoing connections for your routers. You can use `qdmanage` to view, create, update, and delete security policies for any router in your router network.

=== Managing SSL/TLS Encryption and Authentication

{RouterName} supports SSL/TLS for certificate-level encryption and mutual authentication. The following table lists the common `qdmanage` commands you can use to secure incoming and outgoing connections for a router in your router network.

For more information about the attributes you can use with these commands, see link:{qdrouterdConfManPageUrl}#_sslprofile[sslProfile] and link:{qdrouterdConfManPageUrl}#_listener[listener] in the `qdrouterd.conf` man page.

// Note about qdmanage connection options.
include::managing-using-qdmanage.adoc[tags=qdmanage-connection-options-note]

[cols="30,70"]
|===
| To... | Use this command...

|View the router’s SSL/TLS configuration
a|
[options="nowrap"]
----
qdmanage query --type=sslProfile
----

|Set up SSL/TLS for the router
a|
[options="nowrap",subs="+quotes"]
----
qdmanage create --type=sslProfile --name=_NAME_ --_ATTRIBUTE_=_VALUE_ ...
----

|Add SSL/TLS encryption to an incoming connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_LISTENER_NAME_ --sslProfile=_NAME_ --requireSsl=yes
----

|Change SSL/TLS encryption on an incoming connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_LISTENER_NAME_ --_ATTRIBUTE_=_VALUE_ ...
----

|Add SSL/TLS client authentication to an incoming connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_LISTENER_NAME_ --authenticatePeer=yes
----

|Remove SSL/TLS client authentication from an incoming connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_LISTENER_NAME_ --authenticatePeer=no
----

|Add SSL/TLS client authentication to an outgoing connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_CONNECTOR_NAME_ --sslProfile=_NAME_
----

|Remove SSL/TLS client authentication from an outgoing connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_CONNECTOR_NAME_ --sslProfile
----

|Delete an SSL profile
a|
[options="nowrap",subs="+quotes"]
----
qdmanage delete --name=_SSL_PROFILE_NAME_
----

|===

=== Managing SASL Encryption and Authentication

{RouterName} supports SASL for authentication and payload encryption. The following table lists the common `qdmanage` commands you can use to secure incoming and outgoing connections for a router in your router network.

For more information about the attributes you can use with these commands, see link:{qdrouterdConfManPageUrl}#_router[router] and link:{qdrouterdConfManPageUrl}#_listener[listener] in the `qdrouterd.conf` man page.

// Note about qdmanage connection options.
include::managing-using-qdmanage.adoc[tags=qdmanage-connection-options-note]

[cols="30,70"]
|===
| To... | Use this command...

|Set up SASL for the router
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --type=router --saslConfigDir=_PATH_ --saslConfigName=_NAME_
----

|Add SASL authentication to an incoming connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_LISTENER_NAME_ --authenticatePeer=yes --saslMechanisms=_MECHANISMS_
----

|Change SASL mechanisms for an incoming connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_LISTENER_NAME_ --saslMechanisms=_MECHANISMS_
----

|Add SASL authentication to an outgoing connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_CONNECTOR_NAME_ --saslMechanisms=_MECHANISMS_ --saslUsername=_USERNAME_ --saslPassword=_PASSWORD_
----

|Change SASL mechanisms for an outgoing connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_CONNECTOR_NAME_ --saslMechanisms=_MECHANISMS_
----

|Add SASL payload encryption to an incoming connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_LISTENER_NAME_ --requireEncryption=yes --saslMechanisms=_MECHANISMS_
----

|Change SASL mechanisms for an incoming connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_LISTENER_NAME_ --saslMechanisms=_MECHANISMS_
----

|Remove SASL payload encryption from an incoming connection
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_LISTENER_NAME_ --requireEncryption=no --saslMechanisms
----

|Delete a SASL configuration
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --type=router --saslConfigDir --saslConfigName
----

|===

== Managing Routing

{RouterName} supports both message routing and link routing for distributing messages between senders and receivers. You can use `qdmanage` to view how addresses and link routes are configured in your environment, and define how a router should distribute messages.

=== Managing Message Routing

Message routing involves configuring addresses to define how {RouterName} should distribute messages. The following table lists the common `qdmanage` commands you can use to configure addresses for a router in your router network.

For more information about the attributes you can use with these commands, see link:{qdrouterdConfManPageUrl}#_address[address] and link:{qdrouterdConfManPageUrl}#_autolink[autolink] in the `qdrouterd.conf` man page.

// Note about qdmanage connection options.
include::managing-using-qdmanage.adoc[tags=qdmanage-connection-options-note]

[cols="30,70"]
|===
| To... | Use this command...

|View addresses
a|
[options="nowrap"]
----
qdmanage query --type=address
----

[options="nowrap",subs="+quotes"]
----
qdmanage read --name=_ADDRESS_NAME_
----

|View address distribution patterns
a|
[options="nowrap"]
----
qdmanage query prefix distribution --type=address
----

|View waypoints to broker queues
a|
[options="nowrap"]
----
qdmanage query prefix --type=address --waypoint=yes
----

|View autolinks
a|
[options="nowrap"]
----
qdmanage query --type=autolink
----

|Set a distribution pattern for an address
a|
[options="nowrap",subs="+quotes"]
----
qdmanage create --type=address --prefix=_ADDRESS_PREFIX_ --distribution=_DISTRIBUTION_PATTERN_ ...
----

|Set distribution patterns for multiple addresses
a|
. Enter this command:
+
[options="nowrap",subs="+quotes"]
----
qdmanage create --stdin
----

. Configure the addresses using a JSON map:
+
[options="nowrap",subs="+quotes"]
----
[{"type":"address", "prefix":"_ADDRESS_PREFIX_", "distribution":"_DISTRIBUTION_PATTERN_", "_ATTRIBUTE_":"_VALUE_", ...}, {"type":"address", "prefix":"_ADDRESS_PREFIX_", "distribution":"_DISTRIBUTION_PATTERN_", "_ATTRIBUTE_":"_VALUE_", ...} ...]
----

These commands configure two addresses.

|Connect an address to a broker queue
a|
. Enter this command:
+
[options="nowrap"]
----
qdmanage create --stdin
----

. Create an address waypoint, an incoming autolink, and an outgoing autolink:
+
[options="nowrap",subs="+quotes"]
----
[{"type":"address", "prefix":"_ADDRESS_PREFIX_", "waypoint":"yes"}, {"type":"autolink", "addr":"_ADDRESS_NAME_", "connection":"_CONNECTOR/LISTENER_NAME_", "direction":"in"}, {"type":"autolink", "addr":"_ADDRESS_NAME_", "connection":"_CONNECTOR/LISTENER_NAME_", "direction":"out"}]
----

|Update an address configuration
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_ADDRESS_NAME_ --_ATTRIBUTE_=_VALUE_ ...
----

|Update an autolink
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_AUTOLINK_NAME_ --_ATTRIBUTE_=_VALUE_ ...
----

|Delete an address configuration
a|
[options="nowrap",subs="+quotes"]
----
qdmanage delete --name=_ADDRESS_NAME_
----

|Delete an autolink
a|
[options="nowrap",subs="+quotes"]
----
qdmanage delete --name=_AUTOLINK_NAME_
----

|===

=== Managing Link Routing

A link route is a chain of links between a sender and receiver that provides a private messaging path. The following table lists the common `qdmanage` commands you can use to view, create, update, and delete link routes.

For more information about the attributes you can use with these commands, see the link:{qdrouterdConfManPageUrl}#_linkroute[linkRoute] in the `qdrouterd.conf` man page.

// Note about qdmanage connection options.
include::managing-using-qdmanage.adoc[tags=qdmanage-connection-options-note]

[cols="30,70"]
|===
| To... | Use this command...

|View link routes
a|
[options="nowrap"]
----
qdmanage query --type=linkRoute
----

[options="nowrap",subs="+quotes"]
----
qdmanage read --name=_LINK_ROUTE_NAME_
----

|Create a link route
a|
. Enter this command:
+
[options="nowrap"]
----
qdmanage create --stdin
----

. Create an incoming and outgoing link route:
+
[options="nowrap",subs="+quotes"]
----
[{"type":"linkRoute", "prefix":"_ADDRESS_PREFIX_", "connection":"_CONNECTOR/LISTENER_NAME_", "direction":"in", ...}, {"type":"linkRoute", "prefix":"_ADDRESS_PREFIX_", "connection":"_CONNECTOR/LISTENER_NAME_", "direction":"out", ...}]
----

|Update a link route
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --name=_LINK_ROUTE_NAME_ --_ATTRIBUTE_=_VALUE_ ...
----

|Delete a link route
a|
[options="nowrap",subs="+quotes"]
----
qdmanage delete --name=_INCOMING_LINK_ROUTE_NAME_
qdmanage delete --name=_OUTGOING_LINK_ROUTE_NAME_
----

|===

== Managing Logging

{RouterName} logs are broken into different categories called logging modules. Each module provides important information about a particular aspect of a router. The following table lists the common `qdmanage` commands you can use to view and change the configuration of a logging module.

For more information about the attributes you can use with these commands, see link:{qdrouterdConfManPageUrl}#_log[log] in the `qdrouterd.conf` man page.

// Note about qdmanage connection options.
include::managing-using-qdmanage.adoc[tags=qdmanage-connection-options-note]

[cols="30,70"]
|===
| To... | Use this command...

|View the logging configuration
a|
[options="nowrap",subs="+quotes"]
----
qdmanage query --type=log
----

|View the logging configuration for a logging module
a|
[options="nowrap",subs="+quotes"]
----
qdmanage read --type=log --name=log/_LOGGING_MODULE_NAME_
----

|Set the default logging configuration
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --type=log --name=log/DEFAULT enable=_LOGGING_LEVEL_ includeTimestamp=yes _ATTRIBUTE_=_VALUE_
----

|Enable logging for a logging module
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --type=log --name=log/_LOGGING_MODULE_NAME_ enable=_LOGGING_LEVEL_ _ATTRIBUTE_=_VALUE_ ...
----

|Change the logging configuration for a logging module
a|
[options="nowrap",subs="+quotes"]
----
qdmanage update --type=log --name=log/_LOGGING_MODULE_NAME_ _ATTRIBUTE_=_VALUE_ ...
----

|===