From 70374e9724b7b6c696832441c9db39aa3309d1d3 Mon Sep 17 00:00:00 2001 From: Christian Sailer Date: Mon, 2 Jul 2018 15:32:47 +0100 Subject: [PATCH] Node adminstration documentation rewrite (#3484) * Slight rewrite of Node administation to reflect some dev/prod differnces, and clear up some options. --- docs/source/corda-configuration-file.rst | 2 + docs/source/node-administration.rst | 60 +++++++++--------------- docs/source/node-database-access-h2.rst | 27 +++++++++++ 3 files changed, 52 insertions(+), 37 deletions(-) create mode 100644 docs/source/node-database-access-h2.rst diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index 8293a062e2..0e3efe6629 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -72,6 +72,8 @@ absolute path to the node's base directory. If this parameter is set to `false` the rigorous CRL checking takes place, meaning that each certificate in the certificate path being checked needs to have the CRL distribution point extension set and pointing to a URL serving a valid CRL. +.. _databaseConfiguration: + :database: Database configuration: :serverNameTablePrefix: Prefix string to apply to all the database tables. The default is no prefix. diff --git a/docs/source/node-administration.rst b/docs/source/node-administration.rst index 39fe2dcf76..35b32545ad 100644 --- a/docs/source/node-administration.rst +++ b/docs/source/node-administration.rst @@ -1,9 +1,6 @@ Node administration =================== -When a node is running, it exposes an RPC interface that lets you monitor it, upload and download attachments, and so -on. - Logging ------- @@ -59,44 +56,18 @@ Node can be configured to run SSH server. See :doc:`shell` for details. Database access --------------- -The node can be configured to expose its internal database over socket which can be browsed using any tool that can use JDBC drivers. -The JDBC URL is printed during node startup to the log and will typically look like this: +When running a node backed with a H2 database, the node can be configured to expose the database over a socket +(see :doc:`node-database-access-h2`). - ``jdbc:h2:tcp://localhost:31339/node`` - -The username and password can be altered in the :doc:`corda-configuration-file` but default to username "sa" and a blank -password. - -Any database browsing tool that supports JDBC can be used, but if you have IntelliJ Ultimate edition then there is -a tool integrated with your IDE. Just open the database window and add an H2 data source with the above details. -You will now be able to browse the tables and row data within them. - -By default the node will expose its database on the localhost network interface. This behaviour can be -overridden by specifying the full network address (interface and port), using the new h2Settings -syntax in the node configuration: - -.. sourcecode:: groovy - h2Settings { - address: "localhost:12345" - } - -The configuration above will restrict the H2 service to run on localhost. If remote access is required, the address -can be changed to 0.0.0.0. However it is recommended to change the default username and password -before doing so. +Note that in production, exposing the database via the node is not recommended. Monitoring your node -------------------- Like most Java servers, the node can be configured to export various useful metrics and management operations via the industry-standard `JMX infrastructure `_. JMX is a standard API -for registering so-called *MBeans* ... objects whose properties and methods are intended for server management. It does -not require any particular network protocol for export. So this data can be exported from the node in various ways: -some monitoring systems provide a "Java Agent", which is essentially a JVM plugin that finds all the MBeans and sends -them out to a statistics collector over the network. For those systems, follow the instructions provided by the vendor. - -.. warning:: As of Corda M11, Java serialisation in the Corda node has been restricted, meaning MBeans access via the JMX - port will no longer work. Please use java agents instead, you can find details on how to use Jolokia JVM - agent `here `_. +for registering so-called *MBeans* ... objects whose properties and methods are intended for server management. As Java +serialization in the node has been restricted for security reasons, the metrics can only be exported via a Jolokia agent. `Jolokia `_ allows you to access the raw data and operations without connecting to the JMX port directly. Nodes can be configured to export the data over HTTP on the ``/jolokia`` HTTP endpoint, Jolokia defines the JSON and REST @@ -126,7 +97,24 @@ The following JMX statistics are exported: * Corda specific metrics: flow information (total started, finished, in-flight; flow duration by flow type), attachments (count) * Apache Artemis metrics: queue information for P2P and RPC services * JVM statistics: classloading, garbage collection, memory, runtime, threading, operating system -* Hibernate statistics (only when node is started-up in `devMode` due to to expensive run-time costs) + +Notes for production use +++++++++++++++++++++++++ + +When using Jolokia monitoring in production, it is recommended to use a Jolokia agent that reads the metrics from the node +and pushes them to the metrics storage, rather than exposing a port on the production machine/process to the internet. + +Also ensure to have restrictive Jolokia access policy in place for access to production nodes. The Jolokia access is controlled +via a file called ``jolokia-access.xml``. +Several Jolokia policy based security configuration files (``jolokia-access.xml``) are available for dev, test, and prod +environments under ``/config/``. + +Notes for development use ++++++++++++++++++++++++++ + +When running in dev mode, Hibernate statistics are also available via the Jolkia interface. These are disabled otherwise +due to expensive run-time costs. They can be turned on and off explicitly regardless of dev mode via the +``exportHibernateJMXStatistics`` flag on the :ref:`database configuration `. When starting Corda nodes using Cordformation runner (see :doc:`running-a-node`), you should see a startup message similar to the following: **Jolokia: Agent started with URL http://127.0.0.1:7005/jolokia/** @@ -134,8 +122,6 @@ When starting Corda nodes using Cordformation runner (see :doc:`running-a-node`) When starting Corda nodes using the `DriverDSL`, you should see a startup message in the logs similar to the following: **Starting out-of-process Node USA Bank Corp, debug port is not enabled, jolokia monitoring port is 7005 {}** -Several Jolokia policy based security configuration files (``jolokia-access.xml``) are available for dev, test, and prod -environments under ``/config/``. The following diagram illustrates Corda flow metrics visualized using `hawtio `_ : diff --git a/docs/source/node-database-access-h2.rst b/docs/source/node-database-access-h2.rst new file mode 100644 index 0000000000..bbeaf4667b --- /dev/null +++ b/docs/source/node-database-access-h2.rst @@ -0,0 +1,27 @@ +Database access when running H2 +=============================== +When running a node using the H2 database, the node can be configured to expose its internal database over socket which +can be browsed using any tool that can use JDBC drivers. +The JDBC URL is printed during node startup to the log and will typically look like this: + + ``jdbc:h2:tcp://localhost:31339/node`` + +The username and password can be altered in the :doc:`corda-configuration-file` but default to username "sa" and a blank +password. + +Any database browsing tool that supports JDBC can be used, but if you have IntelliJ Ultimate edition then there is +a tool integrated with your IDE. Just open the database window and add an H2 data source with the above details. +You will now be able to browse the tables and row data within them. + +By default the node will expose its database on the localhost network interface. This behaviour can be +overridden by specifying the full network address (interface and port), using the new h2Settings +syntax in the node configuration: + +.. sourcecode:: groovy + h2Settings { + address: "localhost:12345" + } + +The configuration above will restrict the H2 service to run on localhost. If remote access is required, the address +can be changed to 0.0.0.0. However it is recommended to change the default username and password +before doing so.