docs/books/modules/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
////

// This assembly is included in the following assemblies:
//
// book.adoc

[id='managing-using-qdmanage-{context}']
= Managing using `qdmanage`

The `qdmanage` tool is a command-line tool for viewing and modifying the configuration of a running router at runtime.

[NOTE]
====
If you make a change to a router using `qdmanage`, the change takes effect immediately, but is lost if the router is stopped. If you want to make a permanent change to a router's configuration, you must edit the router's `{RouterConfigFile}` configuration file.
====

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"
  }
]
----

.Additional resources

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