docs/books/modules/user-guide/using-console.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='using-router-console']
= Using {ConsoleName}

{ConsoleName} is a web console for monitoring the status and performance of {RouterName} router networks.

include::{FragmentDir}/fragment-console-prereq.adoc[]

== Setting up access to the web console

Before you can access the web console, you must configure a `listener` to accept HTTP connections for the web console and serve the console files.

.Procedure

. On the router from which you want to access the web console, open the {RouterConfigFile} configuration file.

. Add a `listener` to serve the console.
+
--
This example creates a `listener` that clients can use to access the web console:

[options="nowrap",subs="+quotes"]
----
listener {
    host: 0.0.0.0
    port: 8672
    role: normal
    http: true
    httpRootDir: /usr/share/qpid-dispatch/console
}
----
`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 client traffic.

`http`:: Set this attribute to `true` to specify that this `listener` should accept HTTP connections instead of plain AMQP connections.

`httpRootDir`:: Specify the absolute path to the directory that contains the web console HTML files. The default directory is the stand-alone console installation directory, usually `/usr/share/qpid-dispatch/console`.
--

. If you want to secure access to the console, secure the `listener`.
+
--
For more information, see xref:securing-incoming-client-connections-{context}[]. This example adds basic user name and password authentication using SASL PLAIN:

[options="nowrap",subs="+quotes"]
----
listener {
    host: 0.0.0.0
    port: 8672
    role: normal
    http: true
    httpRootDir: /usr/share/qpid-dispatch/console
    authenticatePeer: yes
    saslMechanisms: PLAIN
}
----
--

. If you want to set up access to the web console from any other router in the router network, repeat this procedure for each router.

== Accessing the web console

You can access the web console from a web browser.

.Procedure

. In a web browser, navigate to the web console URL.
+
--
The web console URL is the <host>:<port> from the `listener` that you created to serve the web console. For example: `localhost:8672`.

The {ConsoleName} opens. If you set up user name and password authentication, the *Connect* tab is displayed.
--

. If necessary, log in to the web console.
+
--
If you set up user name and password authentication, enter your user name and password to access the web console.

The syntax for the user name is <__user__>@<__domain__>. For example: `admin@my-domain`.
--

== Monitoring the router network using the web console

In the web console, you use the tabs to monitor the router network.

[cols="30,70"]
|===
| This tab... | Provides...

| `Overview` | Aggregated information about routers, addresses, links, connections, and logs.

| `Entities` | Detailed information about each AMQP management entity for each router in the router network. Some of the attributes have charts that you can add to the `Charts` tab.

| `Topology` | A graphical view of the router network, including routers, clients, and brokers. The topology shows how the routers are connected, and how messages are flowing through the network.

| `Charts` | Graphs of the information selected on the `Entities` tab.

| `Message Flow` | A chord diagram showing the real-time message flow by address.

| `Schema` | The management schema that controls each of the routers in the router network.

|===

== Closing a connection

If a consumer is processing messages too slowly, or has stopped processing messages without settling its deliveries, you can close the connection. When you close the connection, the "stuck" deliveries are released (meaning they are not delivered to any consumers).

.Procedure

. Identify any connections with slow or stuck consumers.
.. Navigate to menu:Overview[Connections].
.. Click a connection, and then click *Links*.
+
The *Rate*, *Delayed 10 sec*, and *Delayed 1 sec* columns indicate if there are any slow or stuck consumers on the connection.

. Click btn:[Close] to close the connection.