Merge pull request #1104 from chenette/New-config-file-doc

Document config files in new "Configuring Sawtooth" section

docs/source/architecture/validator_network.rst

@@ -288,6 +288,8 @@ role.
 In the future, RoleType will include other roles such as CLIENT, STATE_DELTA,
 and TP.
 
+.. _Authorization_Types:
+
 Authorization Types
 -------------------
 Presented here are the two authorization types that will be implemented

docs/source/sysadmin_guide.rst

@@ -8,7 +8,7 @@ System Administrator's Guide
 
    sysadmin_guide/installation
    sysadmin_guide/systemd
-   sysadmin_guide/log_configuration
+   sysadmin_guide/configuring_sawtooth
    sysadmin_guide/rest_auth_proxy
    sysadmin_guide/permissioning
    sysadmin_guide/configure_sgx

docs/source/sysadmin_guide/configuring_sawtooth.rst

@@ -0,0 +1,38 @@
+********************
+Configuring Sawtooth
+********************
+
+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`.
+
+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.
+
+.. Note::
+
+  Sawtooth also includes a deprecated set of configuration files in
+  ``/etc/default``. These files have the same name as the component they
+  configure and contain the command-line arguments passed when the service
+  is started.
+
+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`.
+
+The following sections describe each component's configuration file.
+
+.. toctree::
+   :maxdepth: 1
+
+   configuring_sawtooth/validator_configuration_file
+   configuring_sawtooth/rest_api_configuration_file
+   configuring_sawtooth/poet_sgx_enclave_configuration_file
+   configuring_sawtooth/path_configuration_file
+   log_configuration

docs/source/sysadmin_guide/configuring_sawtooth/path_configuration_file.rst

@@ -0,0 +1,62 @@
+-----------------------
+Path Configuration File
+-----------------------
+
+.. Important::
+
+  Changing the path settings in this file is usually unnecessary.
+  For non-standard directory paths, use the ``SAWTOOTH_HOME`` environment
+  variable instead of this configuration file.
+
+The ``path.toml`` configuration changes the Sawtooth ``data_dir`` directory.
+This file should be used only when installing on an operating system
+distribution where the  default paths are not appropriate. For example, some
+Unix-based operating systems do not use ``/var/lib``, so it would be appropriate
+to use this file to set ``data_dir`` to the natural operating system default
+path for application data.
+
+This file configures the following settings:
+
+- ``key_dir`` = `path`
+
+  Directory path to use when loading key files
+
+- ``data_dir`` = `path`
+
+  Directory path for storing data files such as the block store
+
+- ``log_dir`` = `path`
+
+  Directory path to use to write log files
+  (by default, an error log and a debug log; see :doc:`../log_configuration`).
+
+- ``policy_dir`` = `path`
+
+  Directory path for storing policies
+
+The default directory paths depend on whether the ``SAWTOOTH_HOME`` environment
+variable is set. When ``SAWTOOTH_HOME`` is set, the default paths are:
+
+- ``key_dir`` = ``SAWTOOTH_HOME/keys/``
+- ``data_dir`` = ``SAWTOOTH_HOME/data/``
+- ``log_dir`` = ``SAWTOOTH_HOME/logs/``
+- ``policy_dir`` = ``SAWTOOTH_HOME/policy/``
+
+For example, if ``SAWTOOTH_HOME`` is set to ``/tmp/testing``, the default path
+for ``data_dir`` is ``/tmp/testing/data/``.
+
+When ``SAWTOOTH_HOME`` is not set, the operating system defaults are used.
+On Linux, the default path settings are:
+
+- ``key_dir`` = ``/etc/sawtooth/keys``
+- ``data_dir`` = ``/var/lib/sawtooth``
+- ``log_dir`` = ``/var/log/sawtooth``
+- ``policy_dir`` = ``/etc/sawtooth/policy``
+
+Sawtooth also uses ``config_dir`` to determine the directory path containing the
+configuration files. Note that this directory is fixed; it cannot be changed in
+the ``path.toml`` configuration file.
+
+- If ``SAWTOOTH_HOME`` is set, ``conf_dir`` = ``SAWTOOTH_HOME/etc/``
+
+- If ``SAWTOOTH_HOME`` is not set, ``conf_dir`` = ``/etc/sawtooth``

docs/source/sysadmin_guide/configuring_sawtooth/poet_sgx_enclave_configuration_file.rst

@@ -0,0 +1,51 @@
+-----------------------------------
+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
+in the configuration file.
+
+An example configuration file is in
+``/sawtooth-core/consensus/poet/sgx/packaging/poet_enclave_sgx.toml.example``.
+To create a PoET SGX enclave configuration file, copy the example file to the
+config directory and name it ``poet_enclave_sgx.toml``. Then edit the file to
+change the example configuration options as necessary for your system.
+
+.. Note::
+
+  See :doc:`../configure_sgx` for an example of changing settings in
+  ``poet_enclave_sgx.toml`` when configuring Sawtooth with the SGX
+  implementation of PoET.
+
+The ``poet_enclave_sgx.toml`` configuration file has the following options:
+
+- ``spid`` = '`string`'
+
+  Specifies the Service Provider ID (SPID), which is linked to the key pair used
+  to authenticate with the attestation service. Default: none. The SPID value
+  is a 32-digit hex string tied to the enclave implementation; for example:
+
+  .. code-block:: none
+
+    spid = 'DEADBEEF00000000DEADBEEF00000000'
+
+- ``ias_url`` = '`URL`'
+
+  Specifies the URL of the Intel Attestation Service (IAS) server. Default:
+  none. Note that the URL shown in ``poet_enclave_sgx.toml.example`` is an
+  example server for debug enclaves only:
+
+  .. code-block:: none
+
+    ias_url = 'https://test-as.sgx.trustedservices.intel.com:443'
+
+- ``spid_cert_file`` = '`/full/path/to/certificate.pem`'
+
+  Identifies the PEM-encoded certificate file that was submitted to Intel in
+  order to obtain a SPID. Default: none. Specify the full path to the
+  certificate file.

docs/source/sysadmin_guide/configuring_sawtooth/rest_api_configuration_file.rst

@@ -0,0 +1,63 @@
+---------------------------
+REST API Configuration File
+---------------------------
+
+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
+in the configuration file.
+
+An example configuration file is in
+``/sawtooth-core/rest_api/packaging/rest_api.toml.example``.
+To create a REST API configuration file, copy the example file to the config
+directory and name it ``rest_api.toml``. Then edit the file to change the
+example configuration options as necessary for your system.
+
+The ``rest_api.toml`` configuration file has the following options:
+
+- ``bind`` = ["`HOST:PORT`"]
+
+  Sets the port and host for the REST API to run on.
+  Default: ``127.0.0.1:8080``. For example:
+
+  .. code-block:: none
+
+    bind = ["127.0.0.1:8080"]
+
+- ``connect`` = "`URL`"
+
+  Identifies the URL of a running validator. Default: ``tcp://localhost:4004``.
+  For example:
+
+  .. code-block:: none
+
+    connect = "tcp://localhost:4004"
+
+- ``timeout`` = `value`
+
+  Specifies the time, in seconds, to wait for a validator response.
+  Default: 300. For example:
+
+  .. code-block:: none
+
+    timeout = 900
+
+- ``opentsdb_url`` = "`value`"
+
+  Sets the host and port for Open TSDB database (used for metrics).
+
+- ``opentsdb_db`` = "`name`"
+
+  Sets the name of the Open TSDB database. Default: none.
+
+- ``opentsdb_username`` = `username`
+
+  Sets the username for the Open TSDB database. Default: none.
+
+- ``opentsdb_password`` = `password`
+
+  Sets the password for the Open TSDB database. Default: none.