Update + edit Config File topics in Sys Admin Guide

- Change title to clarify that this is reference info
- Rewrite intro for clarity and style
- Add links to config procedures in the sysadmin guide
- Clarify that the log and path config files are "non-component" files
  and reorg to put them after the component files
- Change title and edit the log config file topic for clarity and style

Signed-off-by: Anne Chenette <chenette@bitwise.io>

docs/source/sysadmin_guide/configuring_sawtooth.rst

@@ -1,25 +1,42 @@
-********************
-Configuring Sawtooth
-********************
+***********************************
+About Sawtooth Configuration Files
+***********************************
 
 Each Sawtooth component, such as the validator or the REST API, has an optional
-configuration file that controls the component's behavior. You can also specify
-configuration options on the command line when starting the component. For more
-information, see :doc:`/cli`.
+configuration file that controls the component's behavior. These configuration
+files provide an alternative to specifying Sawtooth command options when
+starting a component.
+
+.. note::
+
+   Using configuration files is an example of `off-chain configuration`.
+   Changes are made on the local system only. For more information, see
+   :doc:`configuring_permissions`.
 
 When a Sawtooth component starts, it looks for a
-`TOML <https://github.com/toml-lang/toml>`_ configuration file in the config
-directory (``config_dir``). By default, configuration files are stored in
-``/etc/sawtooth``; see :doc:`configuring_sawtooth/path_configuration_file` for
-more information on the config directory location.
+`TOML-format <https://github.com/toml-lang/toml>`_ configuration file in the
+config directory, ``/etc/sawtooth/`` (by default).
+
+By default (when Sawtooth is installed), no configuration files are created.
+However, Sawtooth includes example configuration files that can be customized
+for your system. See :doc:`off_chain_settings` for this procedure.
+
+.. important::
+
+   After changing a configuration file for a component, you must restart that
+   component in order to load the changes.
 
-In addition, the Sawtooth log output can be configured with a log config file
-in `TOML <https://github.com/toml-lang/toml>`_ or `YAML <http://yaml.org>`_
-format. By default, Sawtooth stores error and debug log messages
-for each component in the log directory. For more information,
-see :doc:`log_configuration`.
+Sawtooth also supports several non-component configuration files:
+
+* The :doc:`log_configuration` allows you to configure the log output for each
+  component.
+
+* The :doc:`configuring_sawtooth/path_configuration_file` controls the location
+  of Sawtooth directories, such as the configuration directory (``config_dir``)
+  and log directory (``log_dir``). This file also lets you set an optional
+  ``$SAWTOOTH_HOME`` environment variable to change the base location of
+  Sawtooth files and directories.
 
-The following sections describe each component's configuration file.
 
 .. toctree::
    :maxdepth: 1
@@ -28,11 +45,11 @@ The following sections describe each component's configuration file.
    configuring_sawtooth/rest_api_configuration_file
    configuring_sawtooth/cli_configuration
    configuring_sawtooth/poet_sgx_enclave_configuration_file
-   configuring_sawtooth/path_configuration_file
    configuring_sawtooth/identity_tp_configuration
    configuring_sawtooth/settings_tp_configuration
    configuring_sawtooth/xo_tp_configuration
    log_configuration
+   configuring_sawtooth/path_configuration_file
 
 .. Licensed under Creative Commons Attribution 4.0 International License
 .. https://creativecommons.org/licenses/by/4.0/

docs/source/sysadmin_guide/configuring_sawtooth/cli_configuration.rst

@@ -8,14 +8,14 @@ file to set the URL of the REST API once, rather than entering the ``--url``
 option for each subcommand.
 
 If the config directory contains a file named ``cli.toml``, the
-configuration settings are applied when the ``sawtooth`` command is
-run. (By default, the config directory is /etc/sawtooth/; see
-:doc:`path_configuration_file` for more information.)
+configuration settings are applied when the ``sawtooth`` command is run.
 Specifying command-line options will override the settings in the
 configuration file.
 
-Note: By default, the config directory is /etc/sawtooth/.
-See :doc:`path_configuration_file` for more information.
+.. note::
+
+   By default, the config directory is ``/etc/sawtooth/``.
+   See :doc:`path_configuration_file` for more information.
 
 An example configuration file is in the ``sawtooth-core`` repository at
 ``/sawtooth-core/cli/cli.toml.example``. To create a CLI configuration

docs/source/sysadmin_guide/configuring_sawtooth/identity_tp_configuration.rst

@@ -10,8 +10,10 @@ configuration settings are applied when the transaction processor starts.
 Specifying a command-line option will override the setting in the configuration
 file.
 
-Note: By default, the config directory is /etc/sawtooth/.
-See :doc:`path_configuration_file` for more information.
+.. note::
+
+   By default, the config directory is ``/etc/sawtooth/``.
+   See :doc:`path_configuration_file` for more information.
 
 An example configuration file is in the ``sawtooth-core`` repository at
 ``/sawtooth-core/families/identity/packaging/identity.toml.example``.

docs/source/sysadmin_guide/configuring_sawtooth/poet_sgx_enclave_configuration_file.rst

@@ -5,13 +5,14 @@ PoET SGX Enclave Configuration File
 This configuration file specifies configuration settings for a PoET SGX enclave.
 
 If the config directory contains a file named ``poet_enclave_sgx.toml``, the
-configuration settings are applied when the component starts. (By default, the
-config directory is ``/etc/sawtooth/``; see :doc:`path_configuration_file` for
-more information.) Specifying a command-line option will override the setting
+configuration settings are applied when the component starts.
+Specifying a command-line option will override the setting
 in the configuration file.
 
-Note: By default, the config directory is /etc/sawtooth/.
-See :doc:`path_configuration_file` for more information.
+.. note::
+
+   By default, the config directory is ``/etc/sawtooth/``.
+   See :doc:`path_configuration_file` for more information.
 
 An example configuration file is in the ``sawtooth-core`` repository at
 ``/sawtooth-core/consensus/poet/sgx/packaging/poet_enclave_sgx.toml.example``.

docs/source/sysadmin_guide/configuring_sawtooth/rest_api_configuration_file.rst

@@ -6,13 +6,14 @@ The REST API configuration file specifies network connection settings and an
 optional timeout value.
 
 If the config directory contains a file named ``rest_api.toml``, the
-configuration settings are applied when the REST API starts.  (By default, the
-config directory is ``/etc/sawtooth/``; see :doc:`path_configuration_file` for
-more information.) Specifying a command-line option will override the setting
+configuration settings are applied when the REST API starts.
+Specifying a command-line option will override the setting
 in the configuration file.
 
-Note: By default, the config directory is /etc/sawtooth/.
-See :doc:`path_configuration_file` for more information.
+.. note::
+
+   By default, the config directory is ``/etc/sawtooth/``.
+   See :doc:`path_configuration_file` for more information.
 
 An example configuration file is in the ``sawtooth-core`` repository at
 ``/sawtooth-core/rest_api/packaging/rest_api.toml.example``.

docs/source/sysadmin_guide/configuring_sawtooth/settings_tp_configuration.rst

@@ -10,8 +10,10 @@ configuration settings are applied when the transaction processor starts.
 Specifying a command-line option will override the setting in the configuration
 file.
 
-Note: By default, the config directory is /etc/sawtooth/.
-See :doc:`path_configuration_file` for more information.
+.. note::
+
+   By default, the config directory is ``/etc/sawtooth/``.
+   See :doc:`path_configuration_file` for more information.
 
 An example configuration file is in the ``sawtooth-core`` repository at
 ``/sawtooth-core/families/settings/packaging/settings.toml.example``.

docs/source/sysadmin_guide/configuring_sawtooth/validator_configuration_file.rst

@@ -8,24 +8,24 @@ also contains settings for optional authorization roles and transactor
 permissions.
 
 If the config directory contains a file named ``validator.toml``, the
-configuration settings are applied when the validator starts. (By default, the
-config directory is ``/etc/sawtooth/``; see :doc:`path_configuration_file` for
-more information.) Specifying an option on the command line overrides the
+configuration settings are applied when the validator starts.
+Specifying an option on the command line overrides the
 setting in the configuration file.
 
-Note: By default, the config directory is /etc/sawtooth/.
-See :doc:`path_configuration_file` for more information.
+.. note::
+
+   By default, the config directory is ``/etc/sawtooth/``.
+   See :doc:`path_configuration_file` for more information.
 
 An example configuration file is in ``/etc/sawtooth/validator.toml.example``.
 To create a validator configuration file, copy the example file to the config
 directory and name it ``validator.toml``. Then edit the file to change the
 example configuration options as necessary for your system.
 
-.. Note::
+.. note::
 
-  See :doc:`../configure_sgx` for an example of changing the settings in
-  ``validator.toml`` when configuring Sawtooth with the SGX implementation of
-  PoET.
+  For the procedures that show how to change configuration settings in this
+  file, see :doc:`../off_chain_settings` and :doc:`../configure_sgx`.
 
 The ``validator.toml`` configuration file has the following options:
 
@@ -129,9 +129,12 @@ The ``validator.toml`` configuration file has the following options:
 
 - ``opentsdb_url`` = "`value`"
 
-  Sets the host and port for Open TSDB database (used for metrics).
+  Sets the host and port for an Open TSDB database (used for metrics).
   Default: none.
 
+  For example of using the ``opentsdb_`` settings, see
+  :doc:`../grafana_configuration`.
+
 - ``opentsdb_db`` = "`name`"
 
   Sets the name of the Open TSDB database. Default: none.

docs/source/sysadmin_guide/configuring_sawtooth/xo_tp_configuration.rst

@@ -10,8 +10,10 @@ configuration settings are applied when the transaction processor starts.
 Specifying a command-line option will override the setting in the configuration
 file.
 
-Note: By default, the config directory is /etc/sawtooth/.
-See :doc:`path_configuration_file` for more information.
+.. note::
+
+   By default, the config directory is ``/etc/sawtooth/``.
+   See :doc:`path_configuration_file` for more information.
 
 An example configuration file is in the ``sawtooth-core`` repository at
 ``/sawtooth-core/sdk/examples/xo_python/packaging/xo.toml.example``.

docs/source/sysadmin_guide/log_configuration.rst

@@ -1,42 +1,46 @@
-*****************
-Log Configuration
-*****************
+**********************
+Log Configuration File
+**********************
 
-Overview
-========
-The validator and the Python SDK make it easy to customize the
+The validator and the Python SDK make it easy to customize Sawtooth
 logging output.  This is done by creating a log config file in
 `TOML <https://github.com/toml-lang/toml>`_ or `YAML <http://yaml.org>`_
 format and passing it to the built-in Python logging module.
 
 .. Note::
 
-  Use YAML to configure a remote syslog service. Due to a limitation in
+  You must use YAML to configure a remote syslog service. Due to a limitation in
   the TOML spec, you cannot configure a remote syslog service using TOML.
 
-Log Files
-=========
+About Sawtooth Log Files
+========================
 
-If there is no log configuration file provided, the default is to create an
-error log and a debug log. Theses files will be stored in the log directory
-(``log_dir``) in a location determined by the ``SAWTOOTH_HOME`` environment
-variable. For more information, see
-:doc:`configuring_sawtooth/path_configuration_file`.
+If there is no log configuration file provided, Sawtooth creates an error log
+and a debug log by default. These files are stored in the log directory
+(``log_dir``), which is ``/var/log/sawtooth`` by default. However, the location
+``SAWTOOTH_HOME`` environment variable, if set, can change the default location.
+For more information, see :doc:`configuring_sawtooth/path_configuration_file`.
 
-The names of the validator log files are:
+For Sawtooth core components, such as the validator or REST API, the log file
+names are ``{component}-debug.log`` and ``{component}-error.log``. For example,
+the validator log files are:
 
 - ``validator-debug.log``
 - ``validator-error.log``
 
 For Python transaction processors, the author determines the name of the log
-file. It is highly encouraged that the file names are unique for each running
-processor to avoid naming conflicts.  The example transaction processors
-provided with the SDK uses the following naming convention:
+file. Because a Sawtooth node can run several instances of the same transaction
+processor, it is important to create unique log file names for each running
+transaction processor to avoid naming conflicts.
+
+The example transaction processors included in Sawtooth use the following
+naming convention:
 
 - ``{TPname}-{zmqID}-debug.log``
 - ``{TPname}-{zmqID}-error.log``
 
-Examples:
+For example, an instance of the IntegerKey (``intkey``) transaction processor
+could have the following log files:
 
 -  ``intkey-18670799cbbe4367-debug.log``
 -  ``intkey-18670799cbbe4367-error.log``
@@ -45,12 +49,13 @@ Log Configuration
 =================
 
 To change the default logging behavior of a Sawtooth component, such as the
-validator, put a log configuration file in the config directory (see
+validator or REST API, put a log configuration file in the config directory
+(``/var/log/sawtooth`` by default; see
 :doc:`configuring_sawtooth/path_configuration_file`).
 
-An example log configuration file is at
+Sawtooth provides an example log configuration file in
 ``/etc/sawtooth/log_config.toml.example``. To create a log configuration file,
-copy the example file to ``/etc/sawtooth`` and name it ``log_config.toml``.
+copy the example file to the config directory and name it ``log_config.toml``.
 
 Each transaction processor can define its own config file. The name of
 this file is determined by the author. The transaction processors included in
@@ -61,11 +66,8 @@ the Python SDK use the following naming convention:
 For example, the IntegerKey (``intkey``) log configuration file is
 ``intkey_log_config.toml``.
 
-Examples
-========
-
-Configure a Specific Logger
----------------------------
+Example: Configure a Specific Logger
+====================================
 If the default logs give too much information, you can configure a specific
 logger that will only report on the area of the code you are interested in.
 
@@ -95,9 +97,9 @@ interconnect logs to the directory and file specified.
 The formatter and log level can also be specified to provide the exact
 information you want in your logs.
 
-Rotating File Handler
----------------------
-Below is an example of how to setup rotating logs. This is useful when the logs
+Example: Create a Rotating File Handler
+=======================================
+This example shows how to set up rotating logs. This is useful when the logs
 may grow very large, such as with a long-running network. For example:
 
 .. code-block:: none
@@ -120,10 +122,11 @@ may grow very large, such as with a long-running network. For example:
   handlers = [ "interconnect"]
 
 If one file exceeds the ``maxBytes`` set in the config file, that file will be
-renamed to ``filename.log.1`` and a new ``filename.log`` will be written to.
-This process continues for the number of files plus one set in the
-``backupCount``. After that point, the file that is being written to is rotated.
-The current file being written to is always ``filename.log``.
+renamed to ``filename.log.1`` and logs will be written to a new
+``filename.log``.
+This process continues for the number of files plus one (the value set in
+``backupCount``). After that point, the file being written to is rotated.
+The current log file is always ``filename.log``.
 
 For more Python configuration options, see the Python documentation at
 `<https://docs.python.org/3/library/logging.config.html>`_.