corda/docs/source/corda-configuration-file.rst

Node configuration
==================

File location
-------------

The Corda all-in-one ``corda.jar`` file is generated by the ``gradle buildCordaJAR`` task and defaults to reading configuration
from a ``node.conf`` file in the present working directory. This behaviour can be overidden using the ``--config-file``
command line option to target configuration files with different names, or different file location (relative paths are
relative to the current working directory). Also, the ``--base-directory`` command line option alters the Corda node
workspace location and if specified a ``node.conf`` configuration file is then expected in the root of the workspace.

The configuration file templates used for the ``gradle deployNodes`` task are to be found in the ``/config/dev`` folder.
Also note that there is a basic set of defaults loaded from the built in resource file ``/node/src/main/resources/reference.conf``
of the ``:node`` gradle module. All properties in this can be overidden in the file configuration and for rarely changed
properties this defaulting allows the property to be excluded from the configuration file.

Format
------

The Corda configuration file uses the HOCON format which is superset of JSON. It has several features which makes it
very useful as a configuration format. Please visit their `page <https://github.com/typesafehub/config/blob/master/HOCON.md>`_
for further details.

Examples
--------

General node configuration file for hosting the IRSDemo services.

.. literalinclude:: example-code/src/main/resources/example-node.conf
    :language: javascript

Simple Notary configuration file.

.. parsed-literal::

    myLegalName : "O=Notary Service,OU=corda,L=London,C=GB"
    keyStorePassword : "cordacadevpass"
    trustStorePassword : "trustpass"
    p2pAddress : "localhost:12345"
    rpcAddress : "localhost:12346"
    webAddress : "localhost:12347"
    notary : {
        validating : false
    }
    useHTTPS : false
    devMode : true
    compatibilityZoneURL : "https://cz.corda.net"

Fields
------

The available config fields are listed below. ``baseDirectory`` is available as a substitution value, containing the absolute
path to the node's base directory.

:myLegalName: The legal identity of the node acts as a human readable alias to the node's public key and several demos use
    this to lookup the NodeInfo.

:keyStorePassword: The password to unlock the KeyStore file (``<workspace>/certificates/sslkeystore.jks``) containing the
    node certificate and private key.

    .. note:: This is the non-secret value for the development certificates automatically generated during the first node run.
        Longer term these keys will be managed in secure hardware devices.

:trustStorePassword: The password to unlock the Trust store file (``<workspace>/certificates/truststore.jks``) containing
    the Corda network root certificate. This is the non-secret value for the development certificates automatically
    generated during the first node run.

    .. note:: Longer term these keys will be managed in secure hardware devices.

:dataSourceProperties: This section is used to configure the jdbc connection and database driver used for the nodes persistence.
    Currently the defaults in ``/node/src/main/resources/reference.conf`` are as shown in the first example. This is currently
    the only configuration that has been tested, although in the future full support for other storage layers will be validated.

:messagingServerAddress: The address of the ArtemisMQ broker instance. If not provided the node will run one locally.

:p2pAddress: The host and port on which the node is available for protocol operations over ArtemisMQ.

    .. note:: In practice the ArtemisMQ messaging services bind to all local addresses on the specified port. However,
        note that the host is the included as the advertised entry in the NetworkMapService. As a result the value listed
        here must be externally accessible when running nodes across a cluster of machines. If the provided host is unreachable,
        the node will try to auto-discover its public one.

:rpcAddress: The address of the RPC system on which RPC requests can be made to the node. If not provided then the node will run without RPC.

:webAddress: The host and port on which the webserver will listen if it is started. This is not used by the node itself.

    .. note:: If HTTPS is enabled then the browser security checks will require that the accessing url host name is one
        of either the machine name, fully qualified machine name, or server IP address to line up with the Subject Alternative
        Names contained within the development certificates. This is addition to requiring the ``/config/dev/corda_dev_ca.cer``
        root certificate be installed as a Trusted CA.

    .. note:: The driver will not automatically create a webserver instance, but the Cordformation will. If this field
              is present the web server will start.

:notary: Optional configuration object which if present configures the node to run as a notary. If part of a Raft or BFT SMaRt
    cluster then specify ``raft`` or ``bftSMaRt`` respectively as described below. If a single node notary then omit both.

        :validating: Boolean to determine whether the notary is a validating or non-validating one.

        :raft: If part of a distributed Raft cluster specify this config object, with the following settings:

                :nodeAddress: The host and port to which to bind the embedded Raft server. Note that the Raft cluster uses a
                    separate transport layer for communication that does not integrate with ArtemisMQ messaging services.

                :clusterAddresses: List of Raft cluster member addresses used to join the cluster. At least one of the specified
                    members must be active and be able to communicate with the cluster leader for joining. If empty, a new
                    cluster will be bootstrapped.

        :bftSMaRt: If part of a distributed BFT-SMaRt cluster specify this config object, with the following settings:

                :replicaId: The zero-based index of the current replica. All replicas must specify a unique replica id.

                :clusterAddresses: List of all BFT-SMaRt cluster member addresses.

        :custom: If `true`, will load and install a notary service from a CorDapp. See :doc:`tutorial-custom-notary`.

    Only one of ``raft``, ``bftSMaRt`` or ``custom`` configuration values may be specified.

:useHTTPS: If false the node's web server will be plain HTTP. If true the node will use the same certificate and private
    key from the ``<workspace>/certificates/sslkeystore.jks`` file as the ArtemisMQ port for HTTPS. If HTTPS is enabled
    then unencrypted HTTP traffic to the node's **webAddress** port is not supported.

:rpcUsers: A list of users who are authorised to access the RPC system. Each user in the list is a config object with the
    following fields:

        :username: Username consisting only of word characters (a-z, A-Z, 0-9 and _)
        :password: The password
        :permissions: A list of permission strings which RPC methods can use to control access

    If this field is absent or an empty list then RPC is effectively locked down. Alternatively, if it contains the string
    ``ALL`` then the user is permitted to use *any* RPC method. This value is intended for administrator users and for developers.

:devMode: This flag sets the node to run in development mode. On startup, if the keystore ``<workspace>/certificates/sslkeystore.jks``
    does not exist, a developer keystore will be used if ``devMode`` is true. The node will exit if ``devMode`` is false
    and the keystore does not exist. ``devMode`` also turns on background checking of flow checkpoints to shake out any
    bugs in the checkpointing process.

:detectPublicIp: This flag toggles the auto IP detection behaviour, it is enabled by default. On startup the node will
    attempt to discover its externally visible IP address first by looking for any public addresses on its network
    interfaces, and then by sending an IP discovery request to the network map service. Set to ``false`` to disable.

:compatibilityZoneURL: The root address of Corda compatibility zone network management services, it is used by the Corda node to register with the network and
    obtain Corda node certificate, (See :doc:`permissioning` for more information.) and also used by the node to obtain network map information.

:jvmArgs: An optional list of JVM args, as strings, which replace those inherited from the command line when launching via ``corda.jar``
    only. e.g. ``jvmArgs = [ "-Xmx220m", "-Xms220m", "-XX:+UseG1GC" ]``

:systemProperties: An optional map of additional system properties to be set when launching via ``corda.jar`` only.  Keys and values
    of the map should be strings. e.g. ``systemProperties = { visualvm.display.name = FooBar }``

:jarDirs: An optional list of file system directories containing JARs to include in the classpath when launching via ``corda.jar`` only.
    Each should be a string.  Only the JARs in the directories are added, not the directories themselves.  This is useful
    for including JDBC drivers and the like. e.g. ``jarDirs = [ 'lib' ]``

:sshd: If provided, node will start internal SSH server which will provide a management shell. It uses the same credentials
        and permissions as RPC subsystem. It has one required parameter.

            :port: - the port to start SSH server on

:relay: If provided, the node will attempt to tunnel inbound connections via an external relay. The relay's address will be
    advertised to the network map service instead of the provided ``p2pAddress``.

        :relayHost: Hostname of the relay machine
        :remoteInboundPort: A port on the relay machine that accepts incoming TCP connections. Traffic will be forwarded
            from this port to the local port specified in ``p2pAddress``.
        :username: Username for establishing a SSH connection with the relay.
        :privateKeyFile: Path to the private key file for SSH authentication. The private key must not have a passphrase.
        :publicKeyFile: Path to the public key file for SSH authentication.
        :sshPort: Port to be used for SSH connection, default ``22``.