jbyrne-redhat commented on a change in pull request #516: DISPATCH-1347: Update
doc for setting up and accessing web console
URL: https://github.com/apache/qpid-dispatch/pull/516#discussion_r289306715
##########
File path: docs/books/user-guide/using-console.adoc
##########
@@ -17,110 +17,100 @@ specific language governing permissions and limitations
under the License
////
+[id='using-router-console']
= Using {ConsoleName}
-[[console-overview]]
-== Console Overview
+{ConsoleName} is a web console for monitoring the status and performance of
{RouterName} router networks.
-The console is an HTML based web site that displays information about a qpid
dispatch router network.
+== Setting up access to the web console
-The console requires an HTML web server that can serve static html,
javascript, style sheets, and images.
+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.
-The console only provides limited information about the clients that are
attached to the router network and is therfore more appropriate for
administrators needing to know the layout and health of the router network.
+.Procedure
-[[console-installation]]
-== Console Installation
+. On the router from which you want to access the web console, open the
{RouterConfigFile} configuration file.
-[discrete]
-=== Prerequisites
-
-The following need to be installed before running a console:
-
-* One or more dispatch routers. See the documentation for the dispatch
-router for help in starting a router network.
-* A websockets to tcp proxy.
-* A web server. This can be any server capable of serving static
-html/js/css/image files.
-
-[discrete]
-=== Procedure
-
-To install a websockets to tcp proxy:
+. 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"]
----
-sudo dnf install python-websockify
-websockify localhost:5673 localhost:5672
+listener {
+ host: 0.0.0.0
+ port: 8672
+ role: normal
+ http: true
+ httpRootDir: /usr/share/qpid-dispatch/console
+}
----
+`http`:: Set this attribute to `true` to specify that this `listener` should
accept HTTP connections instead of plain AMQP connections.
-This will start the proxy listening to ws traffic on port 5673 and
-translating it to tcp on port 5672. One of the routers in the network
-needs to have a listener configured on port 5672. That listener's role
-should be 'normal'. For example:
+`httpRootDir`:: Specify the absolute path to the directory that contains the
web console HTML files. The default directory is
`/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
- role: normal
- port: amqp
- saslMechanisms: ANONYMOUS
+ host: 0.0.0.0
+ port: 8672
+ role: normal
+ http: true
+ httpRootDir: /usr/share/qpid-dispatch/console
+ authenticatePeer: yes
+ saslMechanisms: PLAIN
}
----
+--
-[[the-console-files]]
-=== The Console Files
-
-The files for the console are located under the console/stand-alone
-directory in the source tree
-* 'index.html'
-* 'plugin/'
-
-Copy these files to a directory under the the html or webapps directory
-of your web server. For example, for apache tomcat the files should be
-under webapps/dispatch. Then the console is available as
'http://localhost:8080/dispatch'
-
-[[console-operation]]
-== Console Operation
-
-[[logging-in-to-a-router-network]]
-=== Logging into a Router Network
-
-image:console_login.png[image]
+. 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.
-Enter the address of the websockets to tcp proxy that is connected to a router
in the network.
+== Accessing the web console
-The Autostart checkbox, when checked, will automatically log in with the
previous host:port the next time you start the console.
+You can access the web console from a web browser.
-[[overview-page]]
-=== Overview Page
+.Procedure
-image:console_overview.png[image]
+. 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`.
-On the overview page, aggregate information about routers, addresses, and
connections is displayed.
+The {ConsoleName} opens. If you set up user name and password authentication,
the *Connect* tab is displayed.
+--
-[[topology-page]]
-=== Topology Page
+. 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.
-image:console_topology.png[image]
+The syntax for the user name is <user>@<domain>. For example:
`admin@my-domain`.
+--
-This page displays the router network in a graphical form showing how the
routers are connected and information about the individual routers and links.
+== Monitoring the router network using the web console
-[[list-page]]
-=== List Page
+In the web console, you use the tabs to monitor the router network.
-image:console_entity.png[image]
+[cols="30,70"]
+|===
+| This tab... | Provides...
-Displays detailed information about entities such as routers, links,
addresses, memory.
+| `Overview` | Aggregate information about routers, addresses, links,
connections, and logs.
Review comment:
Change to 'aggregated' so that it's not misread as a verb....
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org
For additional commands, e-mail: dev-h...@qpid.apache.org
