From 718d4b3630c1daf97b595da5fcc9e2f281546a0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Fri, 28 Dec 2018 17:19:07 +0000 Subject: [PATCH 01/21] Reorder Ops docs - reorder Ops docs page to make it easier to follow - reorder content of node.conf fields - fix docker-image hierarchy --- docs/source/corda-configuration-file.rst | 304 ++++++++++++----------- docs/source/corda-nodes-index.rst | 15 +- docs/source/docker-image.rst | 2 +- docs/source/node-naming.rst | 58 +++++ docs/source/node-structure.rst | 70 +----- node/src/main/resources/reference.conf | 32 ++- 6 files changed, 243 insertions(+), 238 deletions(-) create mode 100644 docs/source/node-naming.rst diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index 3f15b19fbd..1439544580 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -3,20 +3,6 @@ Configuring a node .. contents:: -File location -------------- -When starting a node, the ``corda.jar`` file defaults to reading the node's configuration from a ``node.conf`` file in -the directory from which the command to launch Corda is executed. There are two command-line options to override this -behaviour: - -* The ``--config-file`` command line option allows you to specify a configuration file with a different name, or at - different file location. Paths are relative to the current working directory - -* The ``--base-directory`` command line option allows you to specify the node's workspace location. A ``node.conf`` - configuration file is then expected in the root of this workspace - -If you specify both command line arguments at the same time, the node will fail to start. - Format ------ The Corda configuration file uses the HOCON format which is a superset of JSON. Please visit @@ -34,46 +20,44 @@ would be not overwritten by the property `dataSourceProperties.dataSourceClassNa By default the node will fail to start in presence of unknown property keys. To alter this behaviour, program line argument ``on-unknown-config-keys`` can be set to ``IGNORE``. Default is ``FAIL`` if unspecified. -Defaults --------- -A set of default configuration options are loaded from the built-in resource file ``/node/src/main/resources/reference.conf``. -This file can be found in the ``:node`` gradle module of the `Corda repository `_. Any -options you do not specify in your own ``node.conf`` file will use these defaults. - -Here are the contents of the ``reference.conf`` file: - -.. literalinclude:: ../../node/src/main/resources/reference.conf - :language: javascript - Fields ------ .. note:: All fields can be used with placeholders for environment variables. For example: ``${NODE_TRUST_STORE_PASSWORD}`` would be replaced by the contents of environment variable ``NODE_TRUST_STORE_PASSWORD``. See: `Hiding Sensitive Data`_ -The available config fields are listed below. +The available config fields are listed below in alphabetic order. -:myLegalName: The legal identity of the node. This acts as a human-readable alias to the node's public key and can be used with - the network map to look up the node's info. This is the name that is used in the node's certificates (either when requesting them - from the doorman, or when auto-generating them in dev mode). At runtime, Corda checks whether this name matches the - name in the node's certificates. +:additionalP2PAddresses: An array of additional host:port values, which will be included in the advertised NodeInfo in the network map in addition to the ``p2pAddress``. + Nodes can use this configuration option to advertise HA endpoints and aliases to external parties. If not specified the default value is an empty list. -:keyStorePassword: The password to unlock the KeyStore file (``/certificates/sslkeystore.jks``) containing the - node certificate and private key. +:attachmentContentCacheSizeMegaBytes: Optionally specify how much memory should be used to cache attachment contents in memory. + Otherwise defaults to 10MB - .. 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. +:attachmentCacheBound: Optionally specify how many attachments should be cached locally. Note that this includes only the key and + metadata, the content is cached separately and can be loaded lazily. Defaults to 1024. -:trustStorePassword: The password to unlock the Trust store file (``/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. +: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. Cannot be + set at the same time as the ``networkServices`` option. - .. note:: Longer term these keys will be managed in secure hardware devices. +.. _corda_configuration_file_signer_blacklist: + +:cordappSignerKeyFingerprintBlacklist: List of public keys fingerprints (SHA-256 of public key hash) not allowed as Cordapp JARs signers. + Node will not load Cordapps signed by those keys. + The option takes effect only in production mode and defaults to Corda development keys (``["56CA54E803CB87C8472EBD3FBC6A2F1876E814CEEBF74860BD46997F40729367", + "83088052AF16700457AE2C978A7D8AC38DD6A7C713539D00B897CD03A5E5D31D"]``), in development mode any key is allowed to sign Cordpapp JARs. :crlCheckSoftFail: This is a boolean flag that when enabled (i.e. `true` value is set) the certificate revocation list (CRL) checking will use the soft fail mode. The soft fail mode allows the revocation check to succeed if the revocation status cannot be determined because of a network error. 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. +:custom: Set custom command line attributes (e.g. Java system properties) on the node process via the capsule launcher + + :jvmArgs: A list of JVM arguments to apply to the node process. This removes any defaults specified from ``corda.jar``, but can be + overriden from the command line. See :ref:`setting_jvm_args` for examples and details on the precedence of the different + approaches to settings arguments. + .. _databaseConfiguration: :database: Database configuration: @@ -95,27 +79,36 @@ The available config fields are listed below. 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. -:h2Port: Deprecated. Use ``h2Settings`` instead. +:detectPublicIp: This flag toggles the auto IP detection behaviour, it is disabled by default. If enabled, 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 ``true`` to enable. -:h2Settings: Sets the H2 JDBC server host and port. See :doc:`node-database-access-h2`. For non-localhost address the database passowrd needs to be set in ``dataSourceProperties``. +:devMode: This flag sets the node to run in development mode. On startup, if the keystore ``/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. + Also, if ``devMode`` is true, Hibernate will try to automatically create the schema required by Corda + or update an existing schema in the SQL database; if ``devMode`` is false, Hibernate will simply validate the existing schema, + failing on node start if the schema is either not present or not compatible. + If no value is specified in the node config file, the node will attempt to detect if it's running on a developer machine and set ``devMode=true`` in that case. + This value can be overridden from the command line using the ``--dev-mode`` option. -:messagingServerAddress: The address of the ArtemisMQ broker instance. If not provided the node will run one locally. +:devModeOptions: Allows modification of certain ``devMode`` features -:messagingServerExternal: If ``messagingServerAddress`` is specified the default assumption is that the artemis broker is running externally. - Setting this to ``false`` overrides this behaviour and runs the artemis internally to the node, but bound to the address specified in ``messagingServerAddress``. - This allows the address and port advertised in ``p2pAddress`` to differ from the local binding, - especially if there is external remapping by firewalls, load balancers , or routing rules. Note that ``detectPublicIp`` should be set to ``false`` to ensure - that no translation of the ``p2pAddress`` occurs before it is sent to the network map. + :allowCompatibilityZone: Allows a node configured to operate in development mode to connect to a compatibility zone. -:p2pAddress: The host and port on which the node is available for protocol operations over ArtemisMQ. + .. note:: This is an unsupported configuration. - .. 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 network map. 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. - -:additionalP2PAddresses: An array of additional host:port values, which will be included in the advertised NodeInfo in the network map in addition to the ``p2pAddress``. - Nodes can use this configuration option to advertise HA endpoints and aliases to external parties. If not specified the default value is an empty list. +:emailAddress: email address responsible for node administration, used by Compatibility Zone administrator. + +:extraNetworkMapKeys: An optional list of private network map UUIDs. Your node will fetch the public network and private network maps based on + these keys. Private network UUID should be provided by network operator and lets you see nodes not visible on public network. + + .. note:: This is temporary feature for onboarding network participants that limits their visibility for privacy reasons. + +:flowMonitorPeriodMillis: ``Duration`` of the period suspended flows waiting for IO are logged. Default value is ``60 seconds``. + +:flowMonitorSuspensionLoggingThresholdMillis: Threshold ``Duration`` suspended flows waiting for IO need to exceed before they are logged. Default value is ``60 seconds``. :flowTimeout: When a flow implementing the ``TimedFlow`` interface and setting the ``isTimeoutEnabled`` flag does not complete within a defined elapsed time, it is restarted from the initial checkpoint. Currently only used for notarisation requests with clustered @@ -128,6 +121,83 @@ The available config fields are listed below. constant. :backoffBase: The base of the exponential backoff, `t_{wait} = timeout * backoffBase^{retryCount}`. +:h2Port: Deprecated. Use ``h2Settings`` instead. + +:h2Settings: Sets the H2 JDBC server host and port. See :doc:`node-database-access-h2`. For non-localhost address the database passowrd needs to be set in ``dataSourceProperties``. + +: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 = [ '${baseDirectory}/lib' ]`` (Note that you have to use the ``baseDirectory`` + substitution value when pointing to a relative path) + +:jmxMonitoringHttpPort: If set, will enable JMX metrics reporting via the Jolokia HTTP/JSON agent on the corresponding port. + Default Jolokia access url is http://127.0.0.1:port/jolokia/ + +:jmxReporterType: Provides an option for registering an alternative JMX reporter. Available options are ``JOLOKIA`` and ``NEW_RELIC``. If no value is provided, ``JOLOKIA`` will be used. + + .. note:: The Jolokia configuration is provided by default. The New Relic configuration leverages the Dropwizard_ NewRelicReporter solution. See `Introduction to New Relic for Java`_ for details on how to get started and how to install the New Relic Java agent. + + .. _Dropwizard: https://metrics.dropwizard.io/3.2.3/manual/third-party.html + .. _Introduction to New Relic for Java: https://docs.newrelic.com/docs/agents/java-agent/getting-started/introduction-new-relic-java + +:keyStorePassword: The password to unlock the KeyStore file (``/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. + +:lazyBridgeStart: PLACEHOLDER + +:messagingServerAddress: The address of the ArtemisMQ broker instance. If not provided the node will run one locally. + +:messagingServerExternal: If ``messagingServerAddress`` is specified the default assumption is that the artemis broker is running externally. + Setting this to ``false`` overrides this behaviour and runs the artemis internally to the node, but bound to the address specified in ``messagingServerAddress``. + This allows the address and port advertised in ``p2pAddress`` to differ from the local binding, + especially if there is external remapping by firewalls, load balancers , or routing rules. Note that ``detectPublicIp`` should be set to ``false`` to ensure + that no translation of the ``p2pAddress`` occurs before it is sent to the network map. + +:myLegalName: The legal identity of the node. This acts as a human-readable alias to the node's public key and can be used with + the network map to look up the node's info. This is the name that is used in the node's certificates (either when requesting them + from the doorman, or when auto-generating them in dev mode). At runtime, Corda checks whether this name matches the + name in the node's certificates. + +:notary: Optional configuration object which if present configures the node to run as a notary. + + :validating: Boolean to determine whether the notary is a validating or non-validating one. + + :serviceLegalName: If the node is part of a distributed cluster, specify the legal name of the cluster. At runtime, Corda + checks whether this name matches the name of the certificate of the notary cluster. + + :className: The fully qualified class name of the notary service to run. The class is expected to be loaded from + a notary CorDapp. Defaults to run the ``SimpleNotaryService``, which is built in. + + :extraConfig: an optional configuration block for providing notary implementation-specific values. + +:networkParameterAcceptanceSettings: Optional settings for managing the network parameter auto-acceptance behaviour. If not provided then the defined defaults below are used. + + :autoAcceptEnabled: This flag toggles auto accepting of network parameter changes. If a network operator issues a network parameter change which modifies only + auto-acceptable options and this behaviour is enabled then the changes will be accepted without any manual intervention from the node operator. See + :doc:`network-map` for more information on the update process and current auto-acceptable parameters. Set to ``false`` to disable. Defaults to true. + + :excludedAutoAcceptableParameters: List of auto-acceptable parameter names to explicitly exclude from auto-accepting. Allows a node operator to control the behaviour at a + more granular level. Defaults to an empty list. + +:networkServices: If the Corda compatibility zone services, both network map and registration (doorman), are not running on the same endpoint + and thus have different URLs then this option should be used in place of the ``compatibilityZoneURL`` setting. + + :doormanURL: Root address of the network registration service. + :networkMapURL: Root address of the network map service. + :pnm: Optional UUID of the private network operating within the compatibility zone this node should be joinging. + + .. note:: Only one of ``compatibilityZoneURL`` or ``networkServices`` should be used. + +: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 network map. 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: (Deprecated) 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. This is now deprecated in favour of the ``rpcSettings`` block. :rpcSettings: Options for the RPC server exposed by the Node. @@ -148,21 +218,6 @@ The available config fields are listed below. and truststore that can be used to secure the RPC connection. You can use this if you have no special requirements. -:security: Contains various nested fields controlling user authentication/authorization, in particular for RPC accesses. See - :doc:`clientrpc` for details. - -:notary: Optional configuration object which if present configures the node to run as a notary. - - :validating: Boolean to determine whether the notary is a validating or non-validating one. - - :serviceLegalName: If the node is part of a distributed cluster, specify the legal name of the cluster. At runtime, Corda - checks whether this name matches the name of the certificate of the notary cluster. - - :className: The fully qualified class name of the notary service to run. The class is expected to be loaded from - a notary CorDapp. Defaults to run the ``SimpleNotaryService``, which is built in. - - :extraConfig: an optional configuration block for providing notary implementation-specific values. - :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: @@ -173,68 +228,19 @@ The available config fields are listed below. contains the string ``ALL``, the user can start any flow via RPC. This value is intended for administrator users and for development. -:devMode: This flag sets the node to run in development mode. On startup, if the keystore ``/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. - Also, if ``devMode`` is true, Hibernate will try to automatically create the schema required by Corda - or update an existing schema in the SQL database; if ``devMode`` is false, Hibernate will simply validate the existing schema, - failing on node start if the schema is either not present or not compatible. - If no value is specified in the node config file, the node will attempt to detect if it's running on a developer machine and set ``devMode=true`` in that case. - This value can be overridden from the command line using the ``--dev-mode`` option. - -:detectPublicIp: This flag toggles the auto IP detection behaviour, it is disabled by default. If enabled, 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 ``true`` to enable. - -: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. Cannot be - set at the same time as the ``networkServices`` option. - -:networkServices: If the Corda compatibility zone services, both network map and registration (doorman), are not running on the same endpoint - and thus have different URLs then this option should be used in place of the ``compatibilityZoneURL`` setting. - - :doormanURL: Root address of the network registration service. - :networkMapURL: Root address of the network map service. - :pnm: Optional UUID of the private network operating within the compatibility zone this node should be joinging. - - .. note:: Only one of ``compatibilityZoneURL`` or ``networkServices`` should be used. - -:devModeOptions: Allows modification of certain ``devMode`` features - - :allowCompatibilityZone: Allows a node configured to operate in development mode to connect to a compatibility zone. - - .. note:: This is an unsupported configuration. - -: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 = [ '${baseDirectory}/lib' ]`` (Note that you have to use the ``baseDirectory`` - substitution value when pointing to a relative path) +:security: Contains various nested fields controlling user authentication/authorization, in particular for RPC accesses. See + :doc:`clientrpc` for details. :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 e.g. ``sshd { port = 2222 }``. -:jmxMonitoringHttpPort: If set, will enable JMX metrics reporting via the Jolokia HTTP/JSON agent on the corresponding port. - Default Jolokia access url is http://127.0.0.1:port/jolokia/ +: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 }`` :transactionCacheSizeMegaBytes: Optionally specify how much memory should be used for caching of ledger transactions in memory. Otherwise defaults to 8MB plus 5% of all heap memory above 300MB. -:attachmentContentCacheSizeMegaBytes: Optionally specify how much memory should be used to cache attachment contents in memory. - Otherwise defaults to 10MB - -:attachmentCacheBound: Optionally specify how many attachments should be cached locally. Note that this includes only the key and - metadata, the content is cached separately and can be loaded lazily. Defaults to 1024. - -:extraNetworkMapKeys: An optional list of private network map UUIDs. Your node will fetch the public network and private network maps based on - these keys. Private network UUID should be provided by network operator and lets you see nodes not visible on public network. - - .. note:: This is temporary feature for onboarding network participants that limits their visibility for privacy reasons. - :tlsCertCrlDistPoint: CRL distribution point (i.e. URL) for the TLS certificate. Default value is NULL, which indicates no CRL availability for the TLS certificate. .. note:: This needs to be set if crlCheckSoftFail is false (i.e. strict CRL checking is on). @@ -244,38 +250,26 @@ The available config fields are listed below. .. note:: If this parameter is set then `tlsCertCrlDistPoint` needs to be set as well. -:flowMonitorPeriodMillis: ``Duration`` of the period suspended flows waiting for IO are logged. Default value is ``60 seconds``. +:trustStorePassword: The password to unlock the Trust store file (``/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. -:flowMonitorSuspensionLoggingThresholdMillis: Threshold ``Duration`` suspended flows waiting for IO need to exceed before they are logged. Default value is ``60 seconds``. + .. note:: Longer term these keys will be managed in secure hardware devices. -:jmxReporterType: Provides an option for registering an alternative JMX reporter. Available options are ``JOLOKIA`` and ``NEW_RELIC``. If no value is provided, ``JOLOKIA`` will be used. +:useTestClock: PLACEHOLDER - .. note:: The Jolokia configuration is provided by default. The New Relic configuration leverages the Dropwizard_ NewRelicReporter solution. See `Introduction to New Relic for Java`_ for details on how to get started and how to install the New Relic Java agent. +:verfierType: PLACEHOLDER - .. _Dropwizard: https://metrics.dropwizard.io/3.2.3/manual/third-party.html - .. _Introduction to New Relic for Java: https://docs.newrelic.com/docs/agents/java-agent/getting-started/introduction-new-relic-java +Defaults +-------- +A set of default configuration options are loaded from the built-in resource file ``/node/src/main/resources/reference.conf``. +This file can be found in the ``:node`` gradle module of the `Corda repository `_. Any +options you do not specify in your own ``node.conf`` file will use these defaults. -.. _corda_configuration_file_signer_blacklist: +Here are the contents of the ``reference.conf`` file: -:cordappSignerKeyFingerprintBlacklist: List of public keys fingerprints (SHA-256 of public key hash) not allowed as Cordapp JARs signers. - Node will not load Cordapps signed by those keys. - The option takes effect only in production mode and defaults to Corda development keys (``["56CA54E803CB87C8472EBD3FBC6A2F1876E814CEEBF74860BD46997F40729367", - "83088052AF16700457AE2C978A7D8AC38DD6A7C713539D00B897CD03A5E5D31D"]``), in development mode any key is allowed to sign Cordpapp JARs. - -:networkParameterAcceptanceSettings: Optional settings for managing the network parameter auto-acceptance behaviour. If not provided then the defined defaults below are used. - - :autoAcceptEnabled: This flag toggles auto accepting of network parameter changes. If a network operator issues a network parameter change which modifies only - auto-acceptable options and this behaviour is enabled then the changes will be accepted without any manual intervention from the node operator. See - :doc:`network-map` for more information on the update process and current auto-acceptable parameters. Set to ``false`` to disable. Defaults to true. - - :excludedAutoAcceptableParameters: List of auto-acceptable parameter names to explicitly exclude from auto-accepting. Allows a node operator to control the behaviour at a - more granular level. Defaults to an empty list. - -:custom: Set custom command line attributes (e.g. Java system properties) on the node process via the capsule launcher - - :jvmArgs: A list of JVM arguments to apply to the node process. This removes any defaults specified from ``corda.jar``, but can be - overriden from the command line. See :ref:`setting_jvm_args` for examples and details on the precedence of the different - approaches to settings arguments. +.. literalinclude:: ../../node/src/main/resources/reference.conf + :language: javascript Examples -------- @@ -308,6 +302,20 @@ Configuring a node where the Corda Compatibility Zone's registration and Network .. literalinclude:: example-code/src/main/resources/example-node-with-networkservices.conf +File location +------------- +When starting a node, the ``corda.jar`` file defaults to reading the node's configuration from a ``node.conf`` file in +the directory from which the command to launch Corda is executed. There are two command-line options to override this +behaviour: + +* The ``--config-file`` command line option allows you to specify a configuration file with a different name, or at + different file location. Paths are relative to the current working directory + +* The ``--base-directory`` command line option allows you to specify the node's workspace location. A ``node.conf`` + configuration file is then expected in the root of this workspace + +If you specify both command line arguments at the same time, the node will fail to start. + Fields override --------------- JVM options or environmental variables prefixed with ``corda.`` can override ``node.conf`` fields. diff --git a/docs/source/corda-nodes-index.rst b/docs/source/corda-nodes-index.rst index 62530ee277..670f99aa23 100644 --- a/docs/source/corda-nodes-index.rst +++ b/docs/source/corda-nodes-index.rst @@ -5,13 +5,14 @@ Nodes :maxdepth: 1 node-structure - generating-a-node - docker-image - running-a-node - deploying-a-node + node-naming corda-configuration-file - clientrpc - shell + node-administration + deploying-a-node + docker-image node-database node-database-access-h2 - node-administration \ No newline at end of file + shell + clientrpc + generating-a-node + running-a-node diff --git a/docs/source/docker-image.rst b/docs/source/docker-image.rst index 4b866a376f..cce9a875af 100644 --- a/docs/source/docker-image.rst +++ b/docs/source/docker-image.rst @@ -62,7 +62,7 @@ As the node within the container starts up, it will place it's own nodeInfo into Generating Configs and Certificates -=================================== +----------------------------------- It is possible to utilize the image to automatically generate a sensible minimal configuration for joining an existing Corda network. diff --git a/docs/source/node-naming.rst b/docs/source/node-naming.rst new file mode 100644 index 0000000000..bdea524a8e --- /dev/null +++ b/docs/source/node-naming.rst @@ -0,0 +1,58 @@ +Node naming +=========== +A node's name must be a valid X.500 distinguished name. In order to be compatible with other implementations +(particularly TLS implementations), we constrain the allowed X.500 name attribute types to a subset of the minimum +supported set for X.509 certificates (specified in RFC 3280), plus the locality attribute: + +* Organization (O) +* State (ST) +* Locality (L) +* Country (C) +* Organizational-unit (OU) +* Common name (CN) + +Note that the serial number is intentionally excluded from Corda certificates in order to minimise scope for uncertainty in +the distinguished name format. The distinguished name qualifier has been removed due to technical issues; consideration was +given to "Corda" as qualifier, however the qualifier needs to reflect the Corda compatibility zone, not the technology involved. +There may be many Corda namespaces, but only one R3 namespace on Corda. The ordering of attributes is important. + +``State`` should be avoided unless required to differentiate from other ``localities`` with the same or similar names at the +country level. For example, London (GB) would not need a ``state``, but St Ives would (there are two, one in Cornwall, one +in Cambridgeshire). As legal entities in Corda are likely to be located in major cities, this attribute is not expected to be +present in the majority of names, but is an option for the cases which require it. + +The name must also obey the following constraints: + +* The ``organisation``, ``locality`` and ``country`` attributes are present + + * The ``state``, ``organisational-unit`` and ``common name`` attributes are optional + +* The fields of the name have the following maximum character lengths: + + * Common name: 64 + * Organisation: 128 + * Organisation unit: 64 + * Locality: 64 + * State: 64 + +* The ``country`` attribute is a valid `ISO 3166-1` two letter code in upper-case + +* The ``organisation`` field of the name obeys the following constraints: + * Has at least two letters + * Does not include the following characters: ``,`` , ``"``, ``\`` + * Is in NFKC normalization form + * Does not contain the null character + * Only the latin, common and inherited unicode scripts are supported + * No double-spacing + +This is to avoid right-to-left issues, debugging issues when we can't pronounce names over the phone, and +character confusability attacks. + +.. note:: The network operator of a Corda Network may put additional constraints on node naming in place. + +External identifiers +^^^^^^^^^^^^^^^^^^^^ +Mappings to external identifiers such as Companies House nos., LEI, BIC, etc. should be stored in custom X.509 +certificate extensions. These values may change for operational reasons, without the identity they're associated with +necessarily changing, and their inclusion in the distinguished name would cause significant logistical complications. +The OID and format for these extensions will be described in a further specification. diff --git a/docs/source/node-structure.rst b/docs/source/node-structure.rst index 371f258ae7..e36ee785b5 100644 --- a/docs/source/node-structure.rst +++ b/docs/source/node-structure.rst @@ -1,9 +1,9 @@ -Node structure +Node folder structure ============== .. contents:: -A Corda node has the following structure: +A folder with Corda node files has the following structure: .. sourcecode:: none @@ -12,11 +12,11 @@ A Corda node has the following structure: ├── artemis // Stores buffered P2P messages ├── brokers // Stores buffered RPC messages ├── certificates // The node's certificates - ├── corda-webserver.jar // The built-in node webserver - ├── corda.jar // The core Corda libraries + ├── corda-webserver.jar // The built-in node webserver (DEPRECATED) + ├── corda.jar // The core Corda libraries (JAR with actually Corda node) ├── cordapps // The CorDapp JARs installed on the node ├── drivers // Contains a Jolokia driver used to export JMX metrics, the node loads any additional JAR files from this directory at startup. - ├── logs // The node logs + ├── logs // The node's logs ├── network-parameters // The network parameters automatically downloaded from the network map server ├── node.conf // The node's configuration files ├── persistence.mv.db // The node's database @@ -40,63 +40,3 @@ If no password is configured, it defaults to ``cordacadevpass``. To learn more, see :doc:`permissioning`. -.. _node_naming: - -Node naming ------------ -A node's name must be a valid X.500 distinguished name. In order to be compatible with other implementations -(particularly TLS implementations), we constrain the allowed X.500 name attribute types to a subset of the minimum -supported set for X.509 certificates (specified in RFC 3280), plus the locality attribute: - -* Organization (O) -* State (ST) -* Locality (L) -* Country (C) -* Organizational-unit (OU) -* Common name (CN) - -Note that the serial number is intentionally excluded in order to minimise scope for uncertainty in the distinguished name format. -The distinguished name qualifier has been removed due to technical issues; consideration was given to "Corda" as qualifier, -however the qualifier needs to reflect the compatibility zone, not the technology involved. There may be many Corda namespaces, -but only one R3 namespace on Corda. The ordering of attributes is important. - -``State`` should be avoided unless required to differentiate from other ``localities`` with the same or similar names at the -country level. For example, London (GB) would not need a ``state``, but St Ives would (there are two, one in Cornwall, one -in Cambridgeshire). As legal entities in Corda are likely to be located in major cities, this attribute is not expected to be -present in the majority of names, but is an option for the cases which require it. - -The name must also obey the following constraints: - -* The ``organisation``, ``locality`` and ``country`` attributes are present - - * The ``state``, ``organisational-unit`` and ``common name`` attributes are optional - -* The fields of the name have the following maximum character lengths: - - * Common name: 64 - * Organisation: 128 - * Organisation unit: 64 - * Locality: 64 - * State: 64 - -* The ``country`` attribute is a valid ISO 3166-1 two letter code in upper-case - -* The ``organisation`` field of the name obeys the following constraints: - * Has at least two letters - * Does not include the following characters: ``,`` , ``"``, ``\`` - * Is in NFKC normalization form - * Does not contain the null character - * Only the latin, common and inherited unicode scripts are supported - * No double-spacing - -This is to avoid right-to-left issues, debugging issues when we can't pronounce names over the phone, and -character confusability attacks. - -.. note:: The network operator of a Corda Network may put additional constraints on node naming in place. - -External identifiers -^^^^^^^^^^^^^^^^^^^^ -Mappings to external identifiers such as Companies House nos., LEI, BIC, etc. should be stored in custom X.509 -certificate extensions. These values may change for operational reasons, without the identity they're associated with -necessarily changing, and their inclusion in the distinguished name would cause significant logistical complications. -The OID and format for these extensions will be described in a further specification. diff --git a/node/src/main/resources/reference.conf b/node/src/main/resources/reference.conf index a09a38df1d..02539aef51 100644 --- a/node/src/main/resources/reference.conf +++ b/node/src/main/resources/reference.conf @@ -1,30 +1,28 @@ -emailAddress = "admin@company.com" -keyStorePassword = "cordacadevpass" -trustStorePassword = "trustpass" -crlCheckSoftFail = true -lazyBridgeStart = true additionalP2PAddresses = [] +crlCheckSoftFail = true +database = { + transactionIsolationLevel = "REPEATABLE_READ" + exportHibernateJMXStatistics = "false" +} dataSourceProperties = { dataSourceClassName = org.h2.jdbcx.JdbcDataSource dataSource.url = "jdbc:h2:file:"${baseDirectory}"/persistence;DB_CLOSE_ON_EXIT=FALSE;WRITE_DELAY=0;LOCK_TIMEOUT=10000" dataSource.user = sa dataSource.password = "" } -database = { - transactionIsolationLevel = "REPEATABLE_READ" - exportHibernateJMXStatistics = "false" -} - -useTestClock = false -verifierType = InMemory -rpcSettings = { - useSsl = false - standAloneBroker = false -} +emailAddress = "admin@company.com" flowTimeout { timeout = 30 seconds maxRestartCount = 6 backoffBase = 1.8 } jmxReporterType = JOLOKIA - +keyStorePassword = "cordacadevpass" +lazyBridgeStart = true +rpcSettings = { + useSsl = false + standAloneBroker = false +} +trustStorePassword = "trustpass" +useTestClock = false +verifierType = InMemory From 3020741da26f30c46cc8f7065743c5e2825dfdea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Wed, 2 Jan 2019 16:03:30 +0000 Subject: [PATCH 02/21] Reformat docs + examples for node.conf - add default value for every parameter - reformat text to have consistent format of one sentence per line (in sources) - reformat examples to be consistent and use '=' as key:value separator --- docs/source/corda-configuration-file.rst | 483 ++++++++++++------ .../example-node-with-networkservices.conf | 36 +- .../src/main/resources/example-node.conf | 30 +- .../src/main/resources/example-verifier.conf | 6 +- 4 files changed, 354 insertions(+), 201 deletions(-) diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index 1439544580..0e0ad7836e 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -27,244 +27,389 @@ Fields The available config fields are listed below in alphabetic order. -:additionalP2PAddresses: An array of additional host:port values, which will be included in the advertised NodeInfo in the network map in addition to the ``p2pAddress``. - Nodes can use this configuration option to advertise HA endpoints and aliases to external parties. If not specified the default value is an empty list. +:additionalP2PAddresses: + An array of additional host:port values, which will be included in the advertised NodeInfo in the network map in addition to the ``p2pAddress``. + Nodes can use this configuration option to advertise HA endpoints and aliases to external parties. + *Default:* an empty list. -:attachmentContentCacheSizeMegaBytes: Optionally specify how much memory should be used to cache attachment contents in memory. - Otherwise defaults to 10MB +:attachmentContentCacheSizeMegaBytes: + Optionally specify how much memory should be used to cache attachment contents in memory. + *Default:* 10MB -:attachmentCacheBound: Optionally specify how many attachments should be cached locally. Note that this includes only the key and - metadata, the content is cached separately and can be loaded lazily. Defaults to 1024. +:attachmentCacheBound: + Optionally specify how many attachments should be cached locally. Note that this includes only the key and metadata, the content is cached separately and can be loaded lazily. + *Default:* 1024 -: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. Cannot be - set at the same time as the ``networkServices`` option. +: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. + Cannot be set at the same time as the ``networkServices`` option. + *Important:* old config value, please use networkServices + *Default:* not define .. _corda_configuration_file_signer_blacklist: -:cordappSignerKeyFingerprintBlacklist: List of public keys fingerprints (SHA-256 of public key hash) not allowed as Cordapp JARs signers. - Node will not load Cordapps signed by those keys. - The option takes effect only in production mode and defaults to Corda development keys (``["56CA54E803CB87C8472EBD3FBC6A2F1876E814CEEBF74860BD46997F40729367", - "83088052AF16700457AE2C978A7D8AC38DD6A7C713539D00B897CD03A5E5D31D"]``), in development mode any key is allowed to sign Cordpapp JARs. +:cordappSignerKeyFingerprintBlacklist: + List of public keys fingerprints (SHA-256 of public key hash) not allowed as Cordapp JARs signers. + Node will not load Cordapps signed by those keys. + The option takes effect only in production mode and defaults to Corda development keys (``["56CA54E803CB87C8472EBD3FBC6A2F1876E814CEEBF74860BD46997F40729367", "83088052AF16700457AE2C978A7D8AC38DD6A7C713539D00B897CD03A5E5D31D"]``), in development mode any key is allowed to sign Cordpapp JARs. + *Default:* not define -:crlCheckSoftFail: This is a boolean flag that when enabled (i.e. `true` value is set) the certificate revocation list (CRL) checking will use the soft fail mode. - The soft fail mode allows the revocation check to succeed if the revocation status cannot be determined because of a network error. - 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. +:crlCheckSoftFail: + This is a boolean flag that when enabled (i.e. `true` value is set) the certificate revocation list (CRL) checking will use the soft fail mode. + The soft fail mode allows the revocation check to succeed if the revocation status cannot be determined because of a network error. + 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. + *Default:* true -:custom: Set custom command line attributes (e.g. Java system properties) on the node process via the capsule launcher +:custom: + Set custom command line attributes (e.g. Java system properties) on the node process via the capsule launcher - :jvmArgs: A list of JVM arguments to apply to the node process. This removes any defaults specified from ``corda.jar``, but can be - overriden from the command line. See :ref:`setting_jvm_args` for examples and details on the precedence of the different - approaches to settings arguments. + :jvmArgs: + A list of JVM arguments to apply to the node process. This removes any defaults specified from ``corda.jar``, but can be overridden from the command line. + See :ref:`setting_jvm_args` for examples and details on the precedence of the different approaches to settings arguments. + *Default:* not define .. _databaseConfiguration: -:database: Database configuration: +:database: + Database configuration: - :transactionIsolationLevel: Transaction isolation level as defined by the ``TRANSACTION_`` constants in - ``java.sql.Connection``, but without the ``TRANSACTION_`` prefix. Defaults to ``REPEATABLE_READ``. - :exportHibernateJMXStatistics: Whether to export Hibernate JMX statistics (caution: expensive run-time overhead) + :transactionIsolationLevel: + Transaction isolation level as defined by the ``TRANSACTION_`` constants in ``java.sql.Connection``, but without the ``TRANSACTION_`` prefix. + *Default*: ``REPEATABLE_READ`` - :initialiseSchema: Boolean on whether to update database schema at startup (or create when node starts for the first time). - Defaults to ``true``. If set to ``false`` on startup, the node will validate if it's running against the compatible database schema. + :exportHibernateJMXStatistics: + Whether to export Hibernate JMX statistics + *Caution:* expensive run-time overhead + *Default:* false - :initialiseAppSchema: The property allows to override (downgrade) ``database.initialiseSchema`` for the Hibernate - DDL generation for CorDapp schemas. ``UPDATE`` performs an update of CorDapp schemas, while ``VALID`` only verifies - their integrity and ``NONE`` performs no check. By default (if the property is not specified) CorDapp schemas - creation is controlled by ``initialiseSchema``. When ``initialiseSchema`` is set to false then ``initialiseAppSchema`` - may be set as ``VALID`` or ``NONE`` only. + :initialiseSchema: + Boolean on whether to update database schema at startup (or create when node starts for the first time). + If set to ``false`` on startup, the node will validate if it's running against the compatible database schema. + *Default* ``true`` -: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. + :initialiseAppSchema: + The property allows to override (downgrade) ``database.initialiseSchema`` for the Hibernate DDL generation for CorDapp schemas. + ``UPDATE`` performs an update of CorDapp schemas, while ``VALID`` only verifies their integrity and ``NONE`` performs no check. + When ``initialiseSchema`` is set to false then ``initialiseAppSchema`` may be set as ``VALID`` or ``NONE`` only. + *Default:* CorDapp schemas creation is controlled ``initialiseSchema``. -:detectPublicIp: This flag toggles the auto IP detection behaviour, it is disabled by default. If enabled, 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 ``true`` to enable. +:dataSourceProperties: + This section is used to configure the jdbc connection and database driver used for the nodes persistence. + This is currently the only configuration that has been tested, although in the future full support for other storage layers will be validated. + Currently the defaults in ``/node/src/main/resources/reference.conf`` are as shown in the first example. + *Default*: ``` dataSourceClassName = org.h2.jdbcx.JdbcDataSource + dataSource.url = "jdbc:h2:file:"${baseDirectory}"/persistence;DB_CLOSE_ON_EXIT=FALSE;WRITE_DELAY=0;LOCK_TIMEOUT=10000" + dataSource.user = sa + dataSource.password = ""``` -:devMode: This flag sets the node to run in development mode. On startup, if the keystore ``/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. - Also, if ``devMode`` is true, Hibernate will try to automatically create the schema required by Corda - or update an existing schema in the SQL database; if ``devMode`` is false, Hibernate will simply validate the existing schema, - failing on node start if the schema is either not present or not compatible. +:detectPublicIp: + This flag toggles the auto IP detection behaviour. + If enabled, 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 ``true`` to enable. + *Default*: false + +:devMode: + This flag sets the node to run in development mode. + On startup, if the keystore ``/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. + Also, if ``devMode`` is true, Hibernate will try to automatically create the schema required by Corda or update an existing schema in the SQL database; if ``devMode`` is false, Hibernate will simply validate the existing schema, failing on node start if the schema is either not present or not compatible. If no value is specified in the node config file, the node will attempt to detect if it's running on a developer machine and set ``devMode=true`` in that case. This value can be overridden from the command line using the ``--dev-mode`` option. + *Default:* Corda will try to establish based on OS environment -:devModeOptions: Allows modification of certain ``devMode`` features - - :allowCompatibilityZone: Allows a node configured to operate in development mode to connect to a compatibility zone. +:devModeOptions: + Allows modification of certain ``devMode`` features + :allowCompatibilityZone: + Allows a node configured to operate in development mode to connect to a compatibility zone. + *Default:* not define .. note:: This is an unsupported configuration. -:emailAddress: email address responsible for node administration, used by Compatibility Zone administrator. +:emailAddress: + email address responsible for node administration, used by Compatibility Zone administrator. + *Default:* company@example.com + .. note:: Very important to provide sensible value in production evironment -:extraNetworkMapKeys: An optional list of private network map UUIDs. Your node will fetch the public network and private network maps based on - these keys. Private network UUID should be provided by network operator and lets you see nodes not visible on public network. +:extraNetworkMapKeys: + An optional list of private network map UUIDs. Your node will fetch the public network and private network maps based on these keys. + Private network UUID should be provided by network operator and lets you see nodes not visible on public network. + *Default:* not define - .. note:: This is temporary feature for onboarding network participants that limits their visibility for privacy reasons. + .. note:: This is temporary feature for onboarding network participants that limits their visibility for privacy reasons. -:flowMonitorPeriodMillis: ``Duration`` of the period suspended flows waiting for IO are logged. Default value is ``60 seconds``. +:flowMonitorPeriodMillis: + ``Duration`` of the period suspended flows waiting for IO are logged. + *Default:* ``60 seconds`` -:flowMonitorSuspensionLoggingThresholdMillis: Threshold ``Duration`` suspended flows waiting for IO need to exceed before they are logged. Default value is ``60 seconds``. +:flowMonitorSuspensionLoggingThresholdMillis: + Threshold ``Duration`` suspended flows waiting for IO need to exceed before they are logged. + *Default:* ``60 seconds`` -:flowTimeout: When a flow implementing the ``TimedFlow`` interface and setting the ``isTimeoutEnabled`` flag does not complete within a - defined elapsed time, it is restarted from the initial checkpoint. Currently only used for notarisation requests with clustered - notaries: if a notary cluster member dies while processing a notarisation request, the client flow eventually times out and gets - restarted. On restart the request is resent to a different notary cluster member in a round-robin fashion. Note that the flow will - keep retrying forever. +:flowTimeout: + When a flow implementing the ``TimedFlow`` interface and setting the ``isTimeoutEnabled`` flag does not complete within a defined elapsed time, it is restarted from the initial checkpoint. + Currently only used for notarisation requests with clustered notaries: if a notary cluster member dies while processing a notarisation request, the client flow eventually times out and gets restarted. + On restart the request is resent to a different notary cluster member in a round-robin fashion. Note that the flow will keep retrying forever. - :timeout: The initial flow timeout period, e.g. `30 seconds`. - :maxRestartCount: The number of retries the back-off time keeps growing for. For subsequent retries, the timeout value will remain - constant. - :backoffBase: The base of the exponential backoff, `t_{wait} = timeout * backoffBase^{retryCount}`. + :timeout: + The initial flow timeout period. + *Default:* `30 seconds` + :maxRestartCount: + The number of retries the back-off time keeps growing for. + For subsequent retries, the timeout value will remain constant. + *Default:* 6 + :backoffBase: + The base of the exponential backoff, `t_{wait} = timeout * backoffBase^{retryCount}` + *Default*: 1.8 -:h2Port: Deprecated. Use ``h2Settings`` instead. +:h2Port: + Defines port for h2 DB. + .. note:: Depracated please use h2Setting instead -:h2Settings: Sets the H2 JDBC server host and port. See :doc:`node-database-access-h2`. For non-localhost address the database passowrd needs to be set in ``dataSourceProperties``. +:h2Settings: + Sets the H2 JDBC server host and port. + See :doc:`node-database-access-h2`. + For non-localhost address the database password needs to be set in ``dataSourceProperties``. + *Default:* ??? -: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 = [ '${baseDirectory}/lib' ]`` (Note that you have to use the ``baseDirectory`` - substitution value when pointing to a relative path) +: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 = [ '${baseDirectory}/lib' ]``. + (Note that you have to use the ``baseDirectory`` substitution value when pointing to a relative path). + *Default:* not define -:jmxMonitoringHttpPort: If set, will enable JMX metrics reporting via the Jolokia HTTP/JSON agent on the corresponding port. +:jmxMonitoringHttpPort: + If set, will enable JMX metrics reporting via the Jolokia HTTP/JSON agent on the corresponding port. Default Jolokia access url is http://127.0.0.1:port/jolokia/ + *Default:* ??? -:jmxReporterType: Provides an option for registering an alternative JMX reporter. Available options are ``JOLOKIA`` and ``NEW_RELIC``. If no value is provided, ``JOLOKIA`` will be used. +:jmxReporterType: + Provides an option for registering an alternative JMX reporter. + Available options are ``JOLOKIA`` and ``NEW_RELIC``. + *Default:* ``JOLOKIA`` - .. note:: The Jolokia configuration is provided by default. The New Relic configuration leverages the Dropwizard_ NewRelicReporter solution. See `Introduction to New Relic for Java`_ for details on how to get started and how to install the New Relic Java agent. + .. note:: The Jolokia configuration is provided by default. + The New Relic configuration leverages the Dropwizard_ NewRelicReporter solution. + See `Introduction to New Relic for Java`_ for details on how to get started and how to install the New Relic Java agent. - .. _Dropwizard: https://metrics.dropwizard.io/3.2.3/manual/third-party.html - .. _Introduction to New Relic for Java: https://docs.newrelic.com/docs/agents/java-agent/getting-started/introduction-new-relic-java + .. _Dropwizard: https://metrics.dropwizard.io/3.2.3/manual/third-party.html + .. _Introduction to New Relic for Java: https://docs.newrelic.com/docs/agents/java-agent/getting-started/introduction-new-relic-java -:keyStorePassword: The password to unlock the KeyStore file (``/certificates/sslkeystore.jks``) containing the - node certificate and private key. +:keyStorePassword: + The password to unlock the KeyStore file (``/certificates/sslkeystore.jks``) containing the node certificate and private key. + *Default*: cordacadevpass .. 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. -:lazyBridgeStart: PLACEHOLDER +:lazyBridgeStart: + Internal option. + Please do not change. + *Default*: true -:messagingServerAddress: The address of the ArtemisMQ broker instance. If not provided the node will run one locally. +:messagingServerAddress: + The address of the ArtemisMQ broker instance. + If not provided the node will run one locally. + Default: not define -:messagingServerExternal: If ``messagingServerAddress`` is specified the default assumption is that the artemis broker is running externally. +:messagingServerExternal: + If ``messagingServerAddress`` is specified the default assumption is that the artemis broker is running externally. Setting this to ``false`` overrides this behaviour and runs the artemis internally to the node, but bound to the address specified in ``messagingServerAddress``. - This allows the address and port advertised in ``p2pAddress`` to differ from the local binding, - especially if there is external remapping by firewalls, load balancers , or routing rules. Note that ``detectPublicIp`` should be set to ``false`` to ensure - that no translation of the ``p2pAddress`` occurs before it is sent to the network map. + This allows the address and port advertised in ``p2pAddress`` to differ from the local binding, especially if there is external remapping by firewalls, load balancers , or routing rules. Note that ``detectPublicIp`` should be set to ``false`` to ensure that no translation of the ``p2pAddress`` occurs before it is sent to the network map. + *Default*: not define -:myLegalName: The legal identity of the node. This acts as a human-readable alias to the node's public key and can be used with - the network map to look up the node's info. This is the name that is used in the node's certificates (either when requesting them - from the doorman, or when auto-generating them in dev mode). At runtime, Corda checks whether this name matches the - name in the node's certificates. +:myLegalName: + The legal identity of the node. + This acts as a human-readable alias to the node's public key and can be used with the network map to look up the node's info. + This is the name that is used in the node's certificates (either when requesting them from the doorman, or when auto-generating them in dev mode). + At runtime, Corda checks whether this name matches the name in the node's certificates. + *Default*: not define -:notary: Optional configuration object which if present configures the node to run as a notary. +:notary: + Optional configuration object which if present configures the node to run as a notary. - :validating: Boolean to determine whether the notary is a validating or non-validating one. + :validating: + Boolean to determine whether the notary is a validating or non-validating one. + *Default*: false - :serviceLegalName: If the node is part of a distributed cluster, specify the legal name of the cluster. At runtime, Corda - checks whether this name matches the name of the certificate of the notary cluster. + :serviceLegalName: + If the node is part of a distributed cluster, specify the legal name of the cluster. + At runtime, Corda checks whether this name matches the name of the certificate of the notary cluster. + *Default:* not define - :className: The fully qualified class name of the notary service to run. The class is expected to be loaded from - a notary CorDapp. Defaults to run the ``SimpleNotaryService``, which is built in. + :className: + The fully qualified class name of the notary service to run. + The class is expected to be loaded from a notary CorDapp. + *Default:* ``SimpleNotaryService`` (which is built in). - :extraConfig: an optional configuration block for providing notary implementation-specific values. + :extraConfig: + an optional configuration block for providing notary implementation-specific values. + *Default:* not define -:networkParameterAcceptanceSettings: Optional settings for managing the network parameter auto-acceptance behaviour. If not provided then the defined defaults below are used. +:networkParameterAcceptanceSettings: + Optional settings for managing the network parameter auto-acceptance behaviour. + If not provided then the defined defaults below are used. - :autoAcceptEnabled: This flag toggles auto accepting of network parameter changes. If a network operator issues a network parameter change which modifies only - auto-acceptable options and this behaviour is enabled then the changes will be accepted without any manual intervention from the node operator. See - :doc:`network-map` for more information on the update process and current auto-acceptable parameters. Set to ``false`` to disable. Defaults to true. + :autoAcceptEnabled: + This flag toggles auto accepting of network parameter changes. + If a network operator issues a network parameter change which modifies only auto-acceptable options and this behaviour is enabled then the changes will be accepted without any manual intervention from the node operator. + See :doc:`network-map` for more information on the update process and current auto-acceptable parameters. + Set to ``false`` to disable. + *Default:* true - :excludedAutoAcceptableParameters: List of auto-acceptable parameter names to explicitly exclude from auto-accepting. Allows a node operator to control the behaviour at a - more granular level. Defaults to an empty list. + :excludedAutoAcceptableParameters: + List of auto-acceptable parameter names to explicitly exclude from auto-accepting. + Allows a node operator to control the behaviour at a more granular level. + *Default:* empty list -:networkServices: If the Corda compatibility zone services, both network map and registration (doorman), are not running on the same endpoint +:networkServices: + If the Corda compatibility zone services, both network map and registration (doorman), are not running on the same endpoint and thus have different URLs then this option should be used in place of the ``compatibilityZoneURL`` setting. - :doormanURL: Root address of the network registration service. - :networkMapURL: Root address of the network map service. - :pnm: Optional UUID of the private network operating within the compatibility zone this node should be joinging. + :doormanURL: + Root address of the network registration service. + *Default:* not define + + :networkMapURL: + Root address of the network map service. + *Default:* not define + + :pnm: + Optional UUID of the private network operating within the compatibility zone this node should be joining. + *Default:* not define .. note:: Only one of ``compatibilityZoneURL`` or ``networkServices`` should be used. -:p2pAddress: The host and port on which the node is available for protocol operations over ArtemisMQ. +:p2pAddress: + The host and port on which the node is available for protocol operations over ArtemisMQ. + *Default:* not define .. 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 network map. 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. + note that the host is the included as the advertised entry in the network map. + 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: (Deprecated) 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. This is now deprecated in favour of the ``rpcSettings`` block. +: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. + *Default*: not define + .. note:: Depracated. Use rpcSettings instead. -:rpcSettings: Options for the RPC server exposed by the Node. +:rpcSettings: + Options for the RPC server exposed by the Node. - :address: host and port for the RPC server binding. - :adminAddress: host and port for the RPC admin binding (this is the endpoint that the node process will connect to). - :standAloneBroker: (optional) boolean, indicates whether the node will connect to a standalone broker for RPC, defaulted to ``false``. - :useSsl: (optional) boolean, indicates whether or not the node should require clients to use SSL for RPC connections, defaulted to ``false``. - :ssl: (mandatory if ``useSsl=true``) SSL settings for the RPC server. + :address: + host and port for the RPC server binding. + *Default:* not define - :keyStorePath: Absolute path to the key store containing the RPC SSL certificate. - :keyStorePassword: Password for the key store. + :adminAddress: + host and port for the RPC admin binding (this is the endpoint that the node process will connect to). + *Default*: not define + :standAloneBroker: + boolean, indicates whether the node will connect to a standalone broker for RPC. + *Default:* ``false`` + + :useSsl: + boolean, indicates whether or not the node should require clients to use SSL for RPC connections. + *Default:* ``false`` + :ssl: + (mandatory if ``useSsl=true``) SSL settings for the RPC server. + + :keyStorePath: + Absolute path to the key store containing the RPC SSL certificate. + *Default:* not define + + :keyStorePassword: + Password for the key store. + *Default*: not define .. note:: The RPC SSL certificate is used by RPC clients to authenticate the connection. The Node operator must provide RPC clients with a truststore containing the certificate they can trust. We advise Node operators to not use the P2P keystore for RPC. - The node can be run with the "generate-rpc-ssl-settings" command, which generates a secure keystore - and truststore that can be used to secure the RPC connection. You can use this if you have no special requirements. + The node can be run with the "generate-rpc-ssl-settings" command, which generates a secure keystore and truststore that can be used to secure the RPC connection. + You can use this if you have no special requirements. -: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: +: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 permissions for starting flows via RPC. To give the user the permission to start the flow - ``foo.bar.FlowClass``, add the string ``StartFlow.foo.bar.FlowClass`` to the list. If the list - contains the string ``ALL``, the user can start any flow via RPC. This value is intended for administrator - users and for development. + :username: + Username consisting only of word characters (a-z, A-Z, 0-9 and _) + *Default:* not define + :password: + The password + *Default:* not define -:security: Contains various nested fields controlling user authentication/authorization, in particular for RPC accesses. See - :doc:`clientrpc` for details. + :permissions: + A list of permissions for starting flows via RPC. + To give the user the permission to start the flow ``foo.bar.FlowClass``, add the string ``StartFlow.foo.bar.FlowClass`` to the list. + If the list contains the string ``ALL``, the user can start any flow via RPC. + This value is intended for administrator users and for development. + *Default*: not define -: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. +:security: + Contains various nested fields controlling user authentication/authorization, in particular for RPC accesses. + See :doc:`clientrpc` for details. - :port: The port to start SSH server on e.g. ``sshd { port = 2222 }``. +: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. -: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 }`` + :port: + The port to start SSH server on e.g. ``sshd { port = 2222 }``. + *Default:* not define -:transactionCacheSizeMegaBytes: Optionally specify how much memory should be used for caching of ledger transactions in memory. - Otherwise defaults to 8MB plus 5% of all heap memory above 300MB. +: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 }`` + *Default:* not define -:tlsCertCrlDistPoint: CRL distribution point (i.e. URL) for the TLS certificate. Default value is NULL, which indicates no CRL availability for the TLS certificate. +:transactionCacheSizeMegaBytes: + Optionally specify how much memory should be used for caching of ledger transactions in memory. + *Default:* 8 MB plus 5% of all heap memory above 300MB. - .. note:: This needs to be set if crlCheckSoftFail is false (i.e. strict CRL checking is on). +:tlsCertCrlDistPoint: + CRL distribution point (i.e. URL) for the TLS certificate. + Default value is NULL, which indicates no CRL availability for the TLS certificate. + *Default*: not define -:tlsCertCrlIssuer: CRL issuer (given in the X500 name format) for the TLS certificate. Default value is NULL, - which indicates that the issuer of the TLS certificate is also the issuer of the CRL. + .. note:: This needs to be set if crlCheckSoftFail is false (i.e. strict CRL checking is on). + +:tlsCertCrlIssuer: + CRL issuer (given in the X500 name format) for the TLS certificate. + Default value is NULL, which indicates that the issuer of the TLS certificate is also the issuer of the CRL. + *Default*: not define .. note:: If this parameter is set then `tlsCertCrlDistPoint` needs to be set as well. -:trustStorePassword: The password to unlock the Trust store file (``/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. +:trustStorePassword: + The password to unlock the Trust store file (``/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. + *Default:* trustpass .. note:: Longer term these keys will be managed in secure hardware devices. -:useTestClock: PLACEHOLDER +:useTestClock: + Internal option. + Please do not change. + *Default:* false -:verfierType: PLACEHOLDER -Defaults +:verfierType: + Internal option. + Please do not change. + *Default:* InMemory + +Refrence.conf -------- A set of default configuration options are loaded from the built-in resource file ``/node/src/main/resources/reference.conf``. -This file can be found in the ``:node`` gradle module of the `Corda repository `_. Any -options you do not specify in your own ``node.conf`` file will use these defaults. +This file can be found in the ``:node`` gradle module of the `Corda repository `_. +Any options you do not specify in your own ``node.conf`` file will use these defaults. Here are the contents of the ``reference.conf`` file: @@ -282,21 +427,24 @@ Simple notary configuration file: .. parsed-literal:: - myLegalName : "O=Notary Service,OU=corda,L=London,C=GB" - keyStorePassword : "cordacadevpass" - trustStorePassword : "trustpass" - p2pAddress : "localhost:12345" - rpcSettings = { + myLegalName = "O=Notary Service,OU=corda,L=London,C=GB" + keyStorePassword = "cordacadevpass" + trustStorePassword = "trustpass" + p2pAddress = "localhost:12345" + rpcSettings { useSsl = false standAloneBroker = false - address : "my-corda-node:10003" - adminAddress : "my-corda-node:10004" + address = "my-corda-node:10003" + adminAddress = "my-corda-node:10004" } - notary : { - validating : false + notary { + validating = false + } + devMode = false + networkServices { + doormanURL = "https://cz.example.com" + networkMapURL = "https://cz.example.com" } - devMode : false - compatibilityZoneURL : "https://cz.corda.net" Configuring a node where the Corda Compatibility Zone's registration and Network Map services exist on different URLs @@ -304,15 +452,14 @@ Configuring a node where the Corda Compatibility Zone's registration and Network File location ------------- -When starting a node, the ``corda.jar`` file defaults to reading the node's configuration from a ``node.conf`` file in -the directory from which the command to launch Corda is executed. There are two command-line options to override this -behaviour: +When starting a node, the ``corda.jar`` file defaults to reading the node's configuration from a ``node.conf`` file in the directory from which the command to launch Corda is executed. +There are two command-line options to override this behaviour: -* The ``--config-file`` command line option allows you to specify a configuration file with a different name, or at - different file location. Paths are relative to the current working directory +* The ``--config-file`` command line option allows you to specify a configuration file with a different name, or at different file location. + Paths are relative to the current working directory -* The ``--base-directory`` command line option allows you to specify the node's workspace location. A ``node.conf`` - configuration file is then expected in the root of this workspace +* The ``--base-directory`` command line option allows you to specify the node's workspace location. + A ``node.conf`` configuration file is then expected in the root of this workspace If you specify both command line arguments at the same time, the node will fail to start. @@ -361,7 +508,10 @@ Take a simple node config that wishes to protect the node cryptographic stores: trustStorePassword : ${TRUST_PASS} p2pAddress : "localhost:12345" devMode : false - compatibilityZoneURL : "https://cz.corda.net" + networkServices { + doormanURL = "https://cz.example.com" + networkMapURL = "https://cz.example.com" + } By delegating to a password store, and using `command substitution` it is possible to ensure that sensitive passwords never appear in plain text. The below examples are of loading Corda with the KEY_PASS and TRUST_PASS variables read from a program named ``corporatePasswordStore``. @@ -374,6 +524,9 @@ Bash KEY_PASS=$(corporatePasswordStore --cordaKeyStorePassword) TRUST_PASS=$(corporatePasswordStore --cordaTrustStorePassword) java -jar corda.jar +.. warning:: If this approach is taken, the passwords will appear in the shell history. + + Windows PowerShell ~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/example-code/src/main/resources/example-node-with-networkservices.conf b/docs/source/example-code/src/main/resources/example-node-with-networkservices.conf index 61ddf736d1..cf91614e2c 100644 --- a/docs/source/example-code/src/main/resources/example-node-with-networkservices.conf +++ b/docs/source/example-code/src/main/resources/example-node-with-networkservices.conf @@ -1,25 +1,25 @@ -myLegalName : "O=Bank A,L=London,C=GB" -keyStorePassword : "cordacadevpass" -trustStorePassword : "trustpass" -crlCheckSoftFail: true -dataSourceProperties : { - dataSourceClassName : org.h2.jdbcx.JdbcDataSource - dataSource.url : "jdbc:h2:file:"${baseDirectory}"/persistence" - dataSource.user : sa - dataSource.password : "" +myLegalName = "O=Bank A,L=London,C=GB" +keyStorePassword = "cordacadevpass" +trustStorePassword = "trustpass" +crlCheckSoftFail = true +dataSourceProperties { + dataSourceClassName = org.h2.jdbcx.JdbcDataSource + dataSource.url = "jdbc:h2:file:"${baseDirectory}"/persistence" + dataSource.user = sa + dataSource.password = "" } -p2pAddress : "my-corda-node:10002" -rpcSettings = { +p2pAddress = "my-corda-node:10002" +rpcSettings { useSsl = false standAloneBroker = false - address : "my-corda-node:10003" - adminAddress : "my-corda-node:10004" + address = "my-corda-node:10003" + adminAddress = "my-corda-node:10004" } -rpcUsers : [ +rpcUsers = [ { username=user1, password=letmein, permissions=[ StartFlow.net.corda.protocols.CashProtocol ] } ] -devMode : false -networkServices : { - doormanURL = "https://registration.corda.net" - networkMapURL = "https://cz.corda.net" +devMode = false +networkServices { + doormanURL = "https://registration.example.com" + networkMapURL = "https://cz.example.com" } diff --git a/docs/source/example-code/src/main/resources/example-node.conf b/docs/source/example-code/src/main/resources/example-node.conf index 918b574d84..39083999a7 100644 --- a/docs/source/example-code/src/main/resources/example-node.conf +++ b/docs/source/example-code/src/main/resources/example-node.conf @@ -1,21 +1,21 @@ -myLegalName : "O=Bank A,L=London,C=GB" -keyStorePassword : "cordacadevpass" -trustStorePassword : "trustpass" -crlCheckSoftFail: true -dataSourceProperties : { - dataSourceClassName : org.h2.jdbcx.JdbcDataSource - dataSource.url : "jdbc:h2:file:"${baseDirectory}"/persistence" - dataSource.user : sa - dataSource.password : "" +myLegalName = "O=Bank A,L=London,C=GB" +keyStorePassword = "cordacadevpass" +trustStorePassword = "trustpass" +crlCheckSoftFail = true +dataSourceProperties { + dataSourceClassName = org.h2.jdbcx.JdbcDataSource + dataSource.url = "jdbc:h2:file:"${baseDirectory}"/persistence" + dataSource.user = sa + dataSource.password = "" } -p2pAddress : "my-corda-node:10002" -rpcSettings = { +p2pAddress = "my-corda-node:10002" +rpcSettings { useSsl = false standAloneBroker = false - address : "my-corda-node:10003" - adminAddress : "my-corda-node:10004" + address = "my-corda-node:10003" + adminAddress = "my-corda-node:10004" } -rpcUsers : [ +rpcUsers = [ { username=user1, password=letmein, permissions=[ StartFlow.net.corda.protocols.CashProtocol ] } ] -devMode : true +devMode = true diff --git a/docs/source/example-code/src/main/resources/example-verifier.conf b/docs/source/example-code/src/main/resources/example-verifier.conf index 2799cb60de..456f5cc613 100644 --- a/docs/source/example-code/src/main/resources/example-verifier.conf +++ b/docs/source/example-code/src/main/resources/example-verifier.conf @@ -1,3 +1,3 @@ -nodeHostAndPort: "my-corda-node:10002" -keyStorePassword : "cordacadevpass" -trustStorePassword : "trustpass" \ No newline at end of file +nodeHostAndPort = "my-corda-node:10002" +keyStorePassword = "cordacadevpass" +trustStorePassword = "trustpass" From cc91ddf3c8551c34a6538f4b6ebd1e131ee38505 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Mon, 7 Jan 2019 15:04:53 +0000 Subject: [PATCH 03/21] Adjustment to config values --- docs/source/corda-configuration-file.rst | 78 +++++++++++++++++++++--- 1 file changed, 70 insertions(+), 8 deletions(-) diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index 0e0ad7836e..d34fef21ea 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -30,20 +30,25 @@ The available config fields are listed below in alphabetic order. :additionalP2PAddresses: An array of additional host:port values, which will be included in the advertised NodeInfo in the network map in addition to the ``p2pAddress``. Nodes can use this configuration option to advertise HA endpoints and aliases to external parties. - *Default:* an empty list. + + *Default:* empty list + :attachmentContentCacheSizeMegaBytes: Optionally specify how much memory should be used to cache attachment contents in memory. + *Default:* 10MB :attachmentCacheBound: Optionally specify how many attachments should be cached locally. Note that this includes only the key and metadata, the content is cached separately and can be loaded lazily. + *Default:* 1024 :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. Cannot be set at the same time as the ``networkServices`` option. *Important:* old config value, please use networkServices + *Default:* not define .. _corda_configuration_file_signer_blacklist: @@ -52,12 +57,14 @@ The available config fields are listed below in alphabetic order. List of public keys fingerprints (SHA-256 of public key hash) not allowed as Cordapp JARs signers. Node will not load Cordapps signed by those keys. The option takes effect only in production mode and defaults to Corda development keys (``["56CA54E803CB87C8472EBD3FBC6A2F1876E814CEEBF74860BD46997F40729367", "83088052AF16700457AE2C978A7D8AC38DD6A7C713539D00B897CD03A5E5D31D"]``), in development mode any key is allowed to sign Cordpapp JARs. + *Default:* not define :crlCheckSoftFail: This is a boolean flag that when enabled (i.e. `true` value is set) the certificate revocation list (CRL) checking will use the soft fail mode. The soft fail mode allows the revocation check to succeed if the revocation status cannot be determined because of a network error. 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. + *Default:* true :custom: @@ -66,6 +73,7 @@ The available config fields are listed below in alphabetic order. :jvmArgs: A list of JVM arguments to apply to the node process. This removes any defaults specified from ``corda.jar``, but can be overridden from the command line. See :ref:`setting_jvm_args` for examples and details on the precedence of the different approaches to settings arguments. + *Default:* not define .. _databaseConfiguration: @@ -75,28 +83,33 @@ The available config fields are listed below in alphabetic order. :transactionIsolationLevel: Transaction isolation level as defined by the ``TRANSACTION_`` constants in ``java.sql.Connection``, but without the ``TRANSACTION_`` prefix. + *Default*: ``REPEATABLE_READ`` :exportHibernateJMXStatistics: Whether to export Hibernate JMX statistics *Caution:* expensive run-time overhead + *Default:* false :initialiseSchema: Boolean on whether to update database schema at startup (or create when node starts for the first time). If set to ``false`` on startup, the node will validate if it's running against the compatible database schema. + *Default* ``true`` :initialiseAppSchema: The property allows to override (downgrade) ``database.initialiseSchema`` for the Hibernate DDL generation for CorDapp schemas. ``UPDATE`` performs an update of CorDapp schemas, while ``VALID`` only verifies their integrity and ``NONE`` performs no check. When ``initialiseSchema`` is set to false then ``initialiseAppSchema`` may be set as ``VALID`` or ``NONE`` only. + *Default:* CorDapp schemas creation is controlled ``initialiseSchema``. :dataSourceProperties: This section is used to configure the jdbc connection and database driver used for the nodes persistence. This is currently the only configuration that has been tested, although in the future full support for other storage layers will be validated. - Currently the defaults in ``/node/src/main/resources/reference.conf`` are as shown in the first example. + Currently the defaults in ``/node/src/main/resources/reference.conf`` are as shown in the reference.conf below. + *Default*: ``` dataSourceClassName = org.h2.jdbcx.JdbcDataSource dataSource.url = "jdbc:h2:file:"${baseDirectory}"/persistence;DB_CLOSE_ON_EXIT=FALSE;WRITE_DELAY=0;LOCK_TIMEOUT=10000" dataSource.user = sa @@ -106,6 +119,7 @@ The available config fields are listed below in alphabetic order. This flag toggles the auto IP detection behaviour. If enabled, 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 ``true`` to enable. + *Default*: false :devMode: @@ -117,34 +131,40 @@ The available config fields are listed below in alphabetic order. Also, if ``devMode`` is true, Hibernate will try to automatically create the schema required by Corda or update an existing schema in the SQL database; if ``devMode`` is false, Hibernate will simply validate the existing schema, failing on node start if the schema is either not present or not compatible. If no value is specified in the node config file, the node will attempt to detect if it's running on a developer machine and set ``devMode=true`` in that case. This value can be overridden from the command line using the ``--dev-mode`` option. + *Default:* Corda will try to establish based on OS environment :devModeOptions: Allows modification of certain ``devMode`` features - :allowCompatibilityZone: + :allowCompatibilityZone: Allows a node configured to operate in development mode to connect to a compatibility zone. + *Default:* not define + .. note:: This is an unsupported configuration. :emailAddress: email address responsible for node administration, used by Compatibility Zone administrator. + *Default:* company@example.com - .. note:: Very important to provide sensible value in production evironment :extraNetworkMapKeys: An optional list of private network map UUIDs. Your node will fetch the public network and private network maps based on these keys. Private network UUID should be provided by network operator and lets you see nodes not visible on public network. + *Default:* not define .. note:: This is temporary feature for onboarding network participants that limits their visibility for privacy reasons. :flowMonitorPeriodMillis: ``Duration`` of the period suspended flows waiting for IO are logged. + *Default:* ``60 seconds`` :flowMonitorSuspensionLoggingThresholdMillis: Threshold ``Duration`` suspended flows waiting for IO need to exceed before they are logged. + *Default:* ``60 seconds`` :flowTimeout: @@ -154,23 +174,28 @@ The available config fields are listed below in alphabetic order. :timeout: The initial flow timeout period. + *Default:* `30 seconds` :maxRestartCount: The number of retries the back-off time keeps growing for. For subsequent retries, the timeout value will remain constant. + *Default:* 6 :backoffBase: The base of the exponential backoff, `t_{wait} = timeout * backoffBase^{retryCount}` + *Default*: 1.8 :h2Port: Defines port for h2 DB. + .. note:: Depracated please use h2Setting instead :h2Settings: Sets the H2 JDBC server host and port. See :doc:`node-database-access-h2`. For non-localhost address the database password needs to be set in ``dataSourceProperties``. + *Default:* ??? :jarDirs: @@ -179,16 +204,19 @@ The available config fields are listed below in alphabetic order. 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 = [ '${baseDirectory}/lib' ]``. (Note that you have to use the ``baseDirectory`` substitution value when pointing to a relative path). + *Default:* not define :jmxMonitoringHttpPort: If set, will enable JMX metrics reporting via the Jolokia HTTP/JSON agent on the corresponding port. Default Jolokia access url is http://127.0.0.1:port/jolokia/ + *Default:* ??? :jmxReporterType: Provides an option for registering an alternative JMX reporter. Available options are ``JOLOKIA`` and ``NEW_RELIC``. + *Default:* ``JOLOKIA`` .. note:: The Jolokia configuration is provided by default. @@ -200,6 +228,7 @@ The available config fields are listed below in alphabetic order. :keyStorePassword: The password to unlock the KeyStore file (``/certificates/sslkeystore.jks``) containing the node certificate and private key. + *Default*: cordacadevpass .. note:: This is the non-secret value for the development certificates automatically generated during the first node run. @@ -208,17 +237,20 @@ The available config fields are listed below in alphabetic order. :lazyBridgeStart: Internal option. Please do not change. + *Default*: true :messagingServerAddress: The address of the ArtemisMQ broker instance. If not provided the node will run one locally. - Default: not define + + *Default:* not define :messagingServerExternal: If ``messagingServerAddress`` is specified the default assumption is that the artemis broker is running externally. Setting this to ``false`` overrides this behaviour and runs the artemis internally to the node, but bound to the address specified in ``messagingServerAddress``. This allows the address and port advertised in ``p2pAddress`` to differ from the local binding, especially if there is external remapping by firewalls, load balancers , or routing rules. Note that ``detectPublicIp`` should be set to ``false`` to ensure that no translation of the ``p2pAddress`` occurs before it is sent to the network map. + *Default*: not define :myLegalName: @@ -226,6 +258,7 @@ The available config fields are listed below in alphabetic order. This acts as a human-readable alias to the node's public key and can be used with the network map to look up the node's info. This is the name that is used in the node's certificates (either when requesting them from the doorman, or when auto-generating them in dev mode). At runtime, Corda checks whether this name matches the name in the node's certificates. + *Default*: not define :notary: @@ -233,20 +266,24 @@ The available config fields are listed below in alphabetic order. :validating: Boolean to determine whether the notary is a validating or non-validating one. + *Default*: false :serviceLegalName: If the node is part of a distributed cluster, specify the legal name of the cluster. At runtime, Corda checks whether this name matches the name of the certificate of the notary cluster. + *Default:* not define :className: The fully qualified class name of the notary service to run. The class is expected to be loaded from a notary CorDapp. + *Default:* ``SimpleNotaryService`` (which is built in). :extraConfig: an optional configuration block for providing notary implementation-specific values. + *Default:* not define :networkParameterAcceptanceSettings: @@ -258,11 +295,13 @@ The available config fields are listed below in alphabetic order. If a network operator issues a network parameter change which modifies only auto-acceptable options and this behaviour is enabled then the changes will be accepted without any manual intervention from the node operator. See :doc:`network-map` for more information on the update process and current auto-acceptable parameters. Set to ``false`` to disable. + *Default:* true :excludedAutoAcceptableParameters: List of auto-acceptable parameter names to explicitly exclude from auto-accepting. Allows a node operator to control the behaviour at a more granular level. + *Default:* empty list :networkServices: @@ -271,20 +310,24 @@ The available config fields are listed below in alphabetic order. :doormanURL: Root address of the network registration service. + *Default:* not define :networkMapURL: Root address of the network map service. + *Default:* not define :pnm: Optional UUID of the private network operating within the compatibility zone this node should be joining. + *Default:* not define .. note:: Only one of ``compatibilityZoneURL`` or ``networkServices`` should be used. :p2pAddress: The host and port on which the node is available for protocol operations over ArtemisMQ. + *Default:* not define .. note:: In practice the ArtemisMQ messaging services bind to all local addresses on the specified port. However, @@ -295,6 +338,7 @@ The available config fields are listed below in alphabetic order. :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. + *Default*: not define .. note:: Depracated. Use rpcSettings instead. @@ -303,27 +347,34 @@ The available config fields are listed below in alphabetic order. :address: host and port for the RPC server binding. + *Default:* not define :adminAddress: host and port for the RPC admin binding (this is the endpoint that the node process will connect to). + *Default*: not define + :standAloneBroker: boolean, indicates whether the node will connect to a standalone broker for RPC. + *Default:* ``false`` :useSsl: boolean, indicates whether or not the node should require clients to use SSL for RPC connections. + *Default:* ``false`` :ssl: (mandatory if ``useSsl=true``) SSL settings for the RPC server. :keyStorePath: Absolute path to the key store containing the RPC SSL certificate. + *Default:* not define :keyStorePassword: Password for the key store. + *Default*: not define .. note:: The RPC SSL certificate is used by RPC clients to authenticate the connection. @@ -339,9 +390,11 @@ The available config fields are listed below in alphabetic order. :username: Username consisting only of word characters (a-z, A-Z, 0-9 and _) + *Default:* not define :password: The password + *Default:* not define :permissions: @@ -349,6 +402,7 @@ The available config fields are listed below in alphabetic order. To give the user the permission to start the flow ``foo.bar.FlowClass``, add the string ``StartFlow.foo.bar.FlowClass`` to the list. If the list contains the string ``ALL``, the user can start any flow via RPC. This value is intended for administrator users and for development. + *Default*: not define :security: @@ -362,34 +416,40 @@ The available config fields are listed below in alphabetic order. :port: The port to start SSH server on e.g. ``sshd { port = 2222 }``. + *Default:* not define :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 }`` + *Default:* not define :transactionCacheSizeMegaBytes: Optionally specify how much memory should be used for caching of ledger transactions in memory. + *Default:* 8 MB plus 5% of all heap memory above 300MB. :tlsCertCrlDistPoint: CRL distribution point (i.e. URL) for the TLS certificate. Default value is NULL, which indicates no CRL availability for the TLS certificate. - *Default*: not define + + *Default*: NULL .. note:: This needs to be set if crlCheckSoftFail is false (i.e. strict CRL checking is on). :tlsCertCrlIssuer: CRL issuer (given in the X500 name format) for the TLS certificate. Default value is NULL, which indicates that the issuer of the TLS certificate is also the issuer of the CRL. - *Default*: not define - .. note:: If this parameter is set then `tlsCertCrlDistPoint` needs to be set as well. + *Default*: NULL + + .. note:: If this parameter is set then `tlsCertCrlDistPoint` needs to be set as well. :trustStorePassword: The password to unlock the Trust store file (``/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. + *Default:* trustpass .. note:: Longer term these keys will be managed in secure hardware devices. @@ -397,12 +457,14 @@ The available config fields are listed below in alphabetic order. :useTestClock: Internal option. Please do not change. + *Default:* false :verfierType: Internal option. Please do not change. + *Default:* InMemory Refrence.conf From 29a17d9de49557aeb1195265b48bda9ae2e01fa8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Tue, 8 Jan 2019 13:49:29 +0000 Subject: [PATCH 04/21] Refactor fields + other file ajustment - finish fixing fields format in node configuration - rename few chapters - adjust hyperlink --- docs/source/corda-configuration-file.rst | 882 +++++++++++------------ docs/source/deploying-a-node.rst | 43 +- docs/source/node-administration.rst | 70 ++ docs/source/node-naming.rst | 2 + docs/source/node-structure.rst | 4 +- 5 files changed, 513 insertions(+), 488 deletions(-) diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index d34fef21ea..15584f59bb 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -1,474 +1,517 @@ -Configuring a node +Node configuration ================== .. contents:: -Format ------- +Config file location +-------------------- +When starting a node, the ``corda.jar`` file defaults to reading the node's configuration from a ``node.conf`` file in the directory from which the command to launch Corda is executed. +There are two command-line options to override this behaviour: + +* The ``--config-file`` command line option allows you to specify a configuration file with a different name, or at different file location. + Paths are relative to the current working directory + +* The ``--base-directory`` command line option allows you to specify the node's workspace location. + A ``node.conf`` configuration file is then expected in the root of this workspace + +If you specify both command line arguments at the same time, the node will fail to start. + +Config file format +------------------ The Corda configuration file uses the HOCON format which is a superset of JSON. Please visit ``_ for further details. Please do NOT use double quotes (``"``) in configuration keys. -Node setup will log `Config files should not contain \" in property names. Please fix: [key]` as an error -when it finds double quotes around keys. -This prevents configuration errors when mixing keys containing ``.`` wrapped with double quotes and without them -e.g.: -The property `"dataSourceProperties.dataSourceClassName" = "val"` in ``reference.conf`` -would be not overwritten by the property `dataSourceProperties.dataSourceClassName = "val2"` in ``node.conf``. +Node setup will log ``Config files should not contain \" in property names. Please fix: [key]`` as an error when it finds double quotes around keys. +This prevents configuration errors when mixing keys containing ``.`` wrapped with double quotes and without them e.g.: The property ``"dataSourceProperties.dataSourceClassName" = "val"`` in *reference.conf* (see: Reference.conf_) would be not overwritten by the property ``dataSourceProperties.dataSourceClassName = "val2"`` in *node.conf*. -By default the node will fail to start in presence of unknown property keys. To alter this behaviour, program line argument -``on-unknown-config-keys`` can be set to ``IGNORE``. Default is ``FAIL`` if unspecified. +By default the node will fail to start in presence of unknown property keys. +To alter this behaviour, program line argument ``on-unknown-config-keys`` can be set to ``IGNORE`` (default is ``FAIL``). -Fields ------- +How to overwrite values from node.conf +-------------------------------------- -.. note:: All fields can be used with placeholders for environment variables. For example: ``${NODE_TRUST_STORE_PASSWORD}`` would be replaced by the contents of environment variable ``NODE_TRUST_STORE_PASSWORD``. See: `Hiding Sensitive Data`_ +Enviroment variables + All fields can be used with placeholders for environment variables. + For example: ``${NODE_TRUST_STORE_PASSWORD}`` would be replaced by the contents of environment variable ``NODE_TRUST_STORE_PASSWORD``. + See: :ref:`hiding-sensitive-data` section in "Node administration" chapter. -The available config fields are listed below in alphabetic order. +JVM options + JVM options or environmental variables prefixed with ``corda.`` can override ``node.conf`` fields. + Provided system properties can also set values for absent fields in ``node.conf``. + This is an example of adding/overriding the keyStore password : -:additionalP2PAddresses: - An array of additional host:port values, which will be included in the advertised NodeInfo in the network map in addition to the ``p2pAddress``. - Nodes can use this configuration option to advertise HA endpoints and aliases to external parties. + .. sourcecode:: shell - *Default:* empty list + java -Dcorda.rpcSettings.ssl.keyStorePassword=mypassword -jar node.jar + +Config file fields +------------------ + +.. note :: The available config fields are listed below in alphabetic order. + +additionalP2PAddresses + An array of additional host:port values, which will be included in the advertised NodeInfo in the network map in addition to the ``p2pAddress``. + Nodes can use this configuration option to advertise HA endpoints and aliases to external parties. + + *Default:* empty list -:attachmentContentCacheSizeMegaBytes: - Optionally specify how much memory should be used to cache attachment contents in memory. +attachmentContentCacheSizeMegaBytes + Optionally specify how much memory should be used to cache attachment contents in memory. - *Default:* 10MB + *Default:* 10MB -:attachmentCacheBound: - Optionally specify how many attachments should be cached locally. Note that this includes only the key and metadata, the content is cached separately and can be loaded lazily. +attachmentCacheBound + Optionally specify how many attachments should be cached locally. Note that this includes only the key and metadata, the content is cached separately and can be loaded lazily. - *Default:* 1024 + *Default:* 1024 -: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. - Cannot be set at the same time as the ``networkServices`` option. - *Important:* old config value, please use networkServices +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. + Cannot be set at the same time as the ``networkServices`` option. - *Default:* not define + *Important:* old config value, please use networkServices + + *Default:* not define .. _corda_configuration_file_signer_blacklist: -:cordappSignerKeyFingerprintBlacklist: - List of public keys fingerprints (SHA-256 of public key hash) not allowed as Cordapp JARs signers. - Node will not load Cordapps signed by those keys. - The option takes effect only in production mode and defaults to Corda development keys (``["56CA54E803CB87C8472EBD3FBC6A2F1876E814CEEBF74860BD46997F40729367", "83088052AF16700457AE2C978A7D8AC38DD6A7C713539D00B897CD03A5E5D31D"]``), in development mode any key is allowed to sign Cordpapp JARs. +cordappSignerKeyFingerprintBlacklist + List of public keys fingerprints (SHA-256 of public key hash) not allowed as Cordapp JARs signers. + Node will not load Cordapps signed by those keys. + The option takes effect only in production mode and defaults to Corda development keys (``["56CA54E803CB87C8472EBD3FBC6A2F1876E814CEEBF74860BD46997F40729367", "83088052AF16700457AE2C978A7D8AC38DD6A7C713539D00B897CD03A5E5D31D"]``), in development mode any key is allowed to sign Cordpapp JARs. - *Default:* not define + *Default:* not define -:crlCheckSoftFail: - This is a boolean flag that when enabled (i.e. `true` value is set) the certificate revocation list (CRL) checking will use the soft fail mode. - The soft fail mode allows the revocation check to succeed if the revocation status cannot be determined because of a network error. - 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. +crlCheckSoftFail + This is a boolean flag that when enabled (i.e. `true` value is set) the certificate revocation list (CRL) checking will use the soft fail mode. + The soft fail mode allows the revocation check to succeed if the revocation status cannot be determined because of a network error. + 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. - *Default:* true + *Default:* true -:custom: - Set custom command line attributes (e.g. Java system properties) on the node process via the capsule launcher +custom + Set custom command line attributes (e.g. Java system properties) on the node process via the capsule launcher - :jvmArgs: - A list of JVM arguments to apply to the node process. This removes any defaults specified from ``corda.jar``, but can be overridden from the command line. - See :ref:`setting_jvm_args` for examples and details on the precedence of the different approaches to settings arguments. + jvmArgs: + A list of JVM arguments to apply to the node process. This removes any defaults specified from ``corda.jar``, but can be overridden from the command line. + See :ref:`setting_jvm_args` for examples and details on the precedence of the different approaches to settings arguments. - *Default:* not define + *Default:* not define .. _databaseConfiguration: -:database: - Database configuration: +database + Database configuration - :transactionIsolationLevel: - Transaction isolation level as defined by the ``TRANSACTION_`` constants in ``java.sql.Connection``, but without the ``TRANSACTION_`` prefix. + transactionIsolationLevel: + Transaction isolation level as defined by the ``TRANSACTION_`` constants in ``java.sql.Connection``, but without the ``TRANSACTION_`` prefix. - *Default*: ``REPEATABLE_READ`` + *Default:* ``REPEATABLE_READ`` - :exportHibernateJMXStatistics: - Whether to export Hibernate JMX statistics - *Caution:* expensive run-time overhead + exportHibernateJMXStatistics: + Whether to export Hibernate JMX statistics + *Caution:* expensive run-time overhead - *Default:* false + *Default:* false - :initialiseSchema: - Boolean on whether to update database schema at startup (or create when node starts for the first time). - If set to ``false`` on startup, the node will validate if it's running against the compatible database schema. + initialiseSchema + Boolean on whether to update database schema at startup (or create when node starts for the first time). + If set to ``false`` on startup, the node will validate if it's running against the compatible database schema. - *Default* ``true`` + *Default:* true - :initialiseAppSchema: - The property allows to override (downgrade) ``database.initialiseSchema`` for the Hibernate DDL generation for CorDapp schemas. - ``UPDATE`` performs an update of CorDapp schemas, while ``VALID`` only verifies their integrity and ``NONE`` performs no check. - When ``initialiseSchema`` is set to false then ``initialiseAppSchema`` may be set as ``VALID`` or ``NONE`` only. + initialiseAppSchema + The property allows to override (downgrade) ``database.initialiseSchema`` for the Hibernate DDL generation for CorDapp schemas. + ``UPDATE`` performs an update of CorDapp schemas, while ``VALID`` only verifies their integrity and ``NONE`` performs no check. + When ``initialiseSchema`` is set to false then ``initialiseAppSchema`` may be set as ``VALID`` or ``NONE`` only. - *Default:* CorDapp schemas creation is controlled ``initialiseSchema``. + *Default:* CorDapp schemas creation is controlled with ``initialiseSchema``. -:dataSourceProperties: - This section is used to configure the jdbc connection and database driver used for the nodes persistence. - This is currently the only configuration that has been tested, although in the future full support for other storage layers will be validated. - Currently the defaults in ``/node/src/main/resources/reference.conf`` are as shown in the reference.conf below. +dataSourceProperties + This section is used to configure the jdbc connection and database driver used for the nodes persistence. + This is currently the only configuration that has been tested, although in the future full support for other storage layers will be validated. + Currently the defaults in ``/node/src/main/resources/reference.conf`` are as shown in the Reference.conf_ below. - *Default*: ``` dataSourceClassName = org.h2.jdbcx.JdbcDataSource + *Default:* + + .. sourcecode:: kotlin + + dataSourceClassName = org.h2.jdbcx.JdbcDataSource dataSource.url = "jdbc:h2:file:"${baseDirectory}"/persistence;DB_CLOSE_ON_EXIT=FALSE;WRITE_DELAY=0;LOCK_TIMEOUT=10000" dataSource.user = sa dataSource.password = ""``` -:detectPublicIp: - This flag toggles the auto IP detection behaviour. - If enabled, 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 ``true`` to enable. +detectPublicIp + This flag toggles the auto IP detection behaviour. + If enabled, 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 ``true`` to enable. - *Default*: false + *Default:* false -:devMode: - This flag sets the node to run in development mode. - On startup, if the keystore ``/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. - Also, if ``devMode`` is true, Hibernate will try to automatically create the schema required by Corda or update an existing schema in the SQL database; if ``devMode`` is false, Hibernate will simply validate the existing schema, failing on node start if the schema is either not present or not compatible. - If no value is specified in the node config file, the node will attempt to detect if it's running on a developer machine and set ``devMode=true`` in that case. - This value can be overridden from the command line using the ``--dev-mode`` option. +devMode + This flag sets the node to run in development mode. + On startup, if the keystore ``/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. + Also, if ``devMode`` is true, Hibernate will try to automatically create the schema required by Corda or update an existing schema in the SQL database; if ``devMode`` is false, Hibernate will simply validate the existing schema, failing on node start if the schema is either not present or not compatible. + If no value is specified in the node config file, the node will attempt to detect if it's running on a developer machine and set ``devMode=true`` in that case. + This value can be overridden from the command line using the ``--dev-mode`` option. - *Default:* Corda will try to establish based on OS environment + *Default:* Corda will try to establish based on OS environment -:devModeOptions: - Allows modification of certain ``devMode`` features +devModeOptions + Allows modification of certain ``devMode`` features - :allowCompatibilityZone: - Allows a node configured to operate in development mode to connect to a compatibility zone. + *Important:* This is an unsupported configuration. - *Default:* not define - - .. note:: This is an unsupported configuration. - -:emailAddress: - email address responsible for node administration, used by Compatibility Zone administrator. - - *Default:* company@example.com - -:extraNetworkMapKeys: - An optional list of private network map UUIDs. Your node will fetch the public network and private network maps based on these keys. - Private network UUID should be provided by network operator and lets you see nodes not visible on public network. + allowCompatibilityZone + Allows a node configured to operate in development mode to connect to a compatibility zone. *Default:* not define - .. note:: This is temporary feature for onboarding network participants that limits their visibility for privacy reasons. -:flowMonitorPeriodMillis: - ``Duration`` of the period suspended flows waiting for IO are logged. +emailAddress + email address responsible for node administration, used by Compatibility Zone administrator. - *Default:* ``60 seconds`` + *Default:* company@example.com -:flowMonitorSuspensionLoggingThresholdMillis: - Threshold ``Duration`` suspended flows waiting for IO need to exceed before they are logged. +extraNetworkMapKeys + An optional list of private network map UUIDs. Your node will fetch the public network and private network maps based on these keys. + Private network UUID should be provided by network operator and lets you see nodes not visible on public network. - *Default:* ``60 seconds`` + *Important:* This is temporary feature for onboarding network participants that limits their visibility for privacy reasons. -:flowTimeout: - When a flow implementing the ``TimedFlow`` interface and setting the ``isTimeoutEnabled`` flag does not complete within a defined elapsed time, it is restarted from the initial checkpoint. - Currently only used for notarisation requests with clustered notaries: if a notary cluster member dies while processing a notarisation request, the client flow eventually times out and gets restarted. - On restart the request is resent to a different notary cluster member in a round-robin fashion. Note that the flow will keep retrying forever. + *Default:* not define - :timeout: - The initial flow timeout period. - *Default:* `30 seconds` - :maxRestartCount: - The number of retries the back-off time keeps growing for. - For subsequent retries, the timeout value will remain constant. +flowMonitorPeriodMillis + Duration of the period suspended flows waiting for IO are logged. - *Default:* 6 - :backoffBase: - The base of the exponential backoff, `t_{wait} = timeout * backoffBase^{retryCount}` + *Default:* 60 seconds - *Default*: 1.8 +flowMonitorSuspensionLoggingThresholdMillis + Threshold duration suspended flows waiting for IO need to exceed before they are logged. -:h2Port: - Defines port for h2 DB. + *Default:* 60 seconds - .. note:: Depracated please use h2Setting instead +flowTimeout + When a flow implementing the ``TimedFlow`` interface and setting the ``isTimeoutEnabled`` flag does not complete within a defined elapsed time, it is restarted from the initial checkpoint. + Currently only used for notarisation requests with clustered notaries: if a notary cluster member dies while processing a notarisation request, the client flow eventually times out and gets restarted. + On restart the request is resent to a different notary cluster member in a round-robin fashion. Note that the flow will keep retrying forever. -:h2Settings: - Sets the H2 JDBC server host and port. - See :doc:`node-database-access-h2`. - For non-localhost address the database password needs to be set in ``dataSourceProperties``. + timeout + The initial flow timeout period. - *Default:* ??? + *Default:* 30 seconds -: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 = [ '${baseDirectory}/lib' ]``. - (Note that you have to use the ``baseDirectory`` substitution value when pointing to a relative path). + maxRestartCount + The number of retries the back-off time keeps growing for. + For subsequent retries, the timeout value will remain constant. - *Default:* not define + *Default:* 6 -:jmxMonitoringHttpPort: - If set, will enable JMX metrics reporting via the Jolokia HTTP/JSON agent on the corresponding port. - Default Jolokia access url is http://127.0.0.1:port/jolokia/ + backoffBase + The base of the exponential backoff, `t_{wait} = timeout * backoffBase^{retryCount}` - *Default:* ??? + *Default:* 1.8 -:jmxReporterType: - Provides an option for registering an alternative JMX reporter. - Available options are ``JOLOKIA`` and ``NEW_RELIC``. +h2Port + Defines port for h2 DB. - *Default:* ``JOLOKIA`` + *Important:* Deprecated please use h2Setting instead - .. note:: The Jolokia configuration is provided by default. - The New Relic configuration leverages the Dropwizard_ NewRelicReporter solution. - See `Introduction to New Relic for Java`_ for details on how to get started and how to install the New Relic Java agent. +h2Settings + Sets the H2 JDBC server host and port. + See :doc:`node-database-access-h2`. + For non-localhost address the database password needs to be set in ``dataSourceProperties``. - .. _Dropwizard: https://metrics.dropwizard.io/3.2.3/manual/third-party.html - .. _Introduction to New Relic for Java: https://docs.newrelic.com/docs/agents/java-agent/getting-started/introduction-new-relic-java + *Default:* ??? -:keyStorePassword: - The password to unlock the KeyStore file (``/certificates/sslkeystore.jks``) containing the node certificate and private key. +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 = [ '${baseDirectory}/lib' ]``. + (Note that you have to use the ``baseDirectory`` substitution value when pointing to a relative path). - *Default*: cordacadevpass + *Default:* not define - .. 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. +jmxMonitoringHttpPort + If set, will enable JMX metrics reporting via the Jolokia HTTP/JSON agent on the corresponding port. + Default Jolokia access url is http://127.0.0.1:port/jolokia/ -:lazyBridgeStart: - Internal option. - Please do not change. + *Default:* ??? - *Default*: true +jmxReporterType + Provides an option for registering an alternative JMX reporter. + Available options are ``JOLOKIA`` and ``NEW_RELIC``. -:messagingServerAddress: - The address of the ArtemisMQ broker instance. - If not provided the node will run one locally. - - *Default:* not define + The Jolokia configuration is provided by default. + The New Relic configuration leverages the Dropwizard_ NewRelicReporter solution. + See `Introduction to New Relic for Java`_ for details on how to get started and how to install the New Relic Java agent. -:messagingServerExternal: - If ``messagingServerAddress`` is specified the default assumption is that the artemis broker is running externally. - Setting this to ``false`` overrides this behaviour and runs the artemis internally to the node, but bound to the address specified in ``messagingServerAddress``. - This allows the address and port advertised in ``p2pAddress`` to differ from the local binding, especially if there is external remapping by firewalls, load balancers , or routing rules. Note that ``detectPublicIp`` should be set to ``false`` to ensure that no translation of the ``p2pAddress`` occurs before it is sent to the network map. + *Default:* ``JOLOKIA`` - *Default*: not define + .. _Dropwizard: https://metrics.dropwizard.io/3.2.3/manual/third-party.html + .. _Introduction to New Relic for Java: https://docs.newrelic.com/docs/agents/java-agent/getting-started/introduction-new-relic-java -:myLegalName: - The legal identity of the node. - This acts as a human-readable alias to the node's public key and can be used with the network map to look up the node's info. - This is the name that is used in the node's certificates (either when requesting them from the doorman, or when auto-generating them in dev mode). - At runtime, Corda checks whether this name matches the name in the node's certificates. +keyStorePassword + The password to unlock the KeyStore file (``/certificates/sslkeystore.jks``) containing the node certificate and private key. - *Default*: not define + *Important:* 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. -:notary: - Optional configuration object which if present configures the node to run as a notary. + *Default:* cordacadevpass - :validating: - Boolean to determine whether the notary is a validating or non-validating one. +lazyBridgeStart + Internal option. - *Default*: false + *Important:* Please do not change. - :serviceLegalName: - If the node is part of a distributed cluster, specify the legal name of the cluster. - At runtime, Corda checks whether this name matches the name of the certificate of the notary cluster. + *Default:* true - *Default:* not define +messagingServerAddress + The address of the ArtemisMQ broker instance. + If not provided the node will run one locally. - :className: - The fully qualified class name of the notary service to run. - The class is expected to be loaded from a notary CorDapp. + *Default:* not define - *Default:* ``SimpleNotaryService`` (which is built in). +messagingServerExternal + If ``messagingServerAddress`` is specified the default assumption is that the artemis broker is running externally. + Setting this to ``false`` overrides this behaviour and runs the artemis internally to the node, but bound to the address specified in ``messagingServerAddress``. + This allows the address and port advertised in ``p2pAddress`` to differ from the local binding, especially if there is external remapping by firewalls, load balancers , or routing rules. Note that ``detectPublicIp`` should be set to ``false`` to ensure that no translation of the ``p2pAddress`` occurs before it is sent to the network map. - :extraConfig: - an optional configuration block for providing notary implementation-specific values. + *Default:* not define - *Default:* not define +myLegalName + The legal identity of the node. + This acts as a human-readable alias to the node's public key and can be used with the network map to look up the node's info. + This is the name that is used in the node's certificates (either when requesting them from the doorman, or when auto-generating them in dev mode). + At runtime, Corda checks whether this name matches the name in the node's certificates. + For more details please read :ref:`node-naming` chapter. -:networkParameterAcceptanceSettings: - Optional settings for managing the network parameter auto-acceptance behaviour. - If not provided then the defined defaults below are used. + *Default:* not define - :autoAcceptEnabled: - This flag toggles auto accepting of network parameter changes. - If a network operator issues a network parameter change which modifies only auto-acceptable options and this behaviour is enabled then the changes will be accepted without any manual intervention from the node operator. - See :doc:`network-map` for more information on the update process and current auto-acceptable parameters. - Set to ``false`` to disable. +notary + Optional configuration object which if present configures the node to run as a notary. - *Default:* true - - :excludedAutoAcceptableParameters: - List of auto-acceptable parameter names to explicitly exclude from auto-accepting. - Allows a node operator to control the behaviour at a more granular level. - - *Default:* empty list - -:networkServices: - If the Corda compatibility zone services, both network map and registration (doorman), are not running on the same endpoint - and thus have different URLs then this option should be used in place of the ``compatibilityZoneURL`` setting. - - :doormanURL: - Root address of the network registration service. - - *Default:* not define - - :networkMapURL: - Root address of the network map service. - - *Default:* not define - - :pnm: - Optional UUID of the private network operating within the compatibility zone this node should be joining. - - *Default:* not define - - .. note:: Only one of ``compatibilityZoneURL`` or ``networkServices`` should be used. - -:p2pAddress: - The host and port on which the node is available for protocol operations over ArtemisMQ. - - *Default:* not define - - .. 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 network map. - 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. - - *Default*: not define - .. note:: Depracated. Use rpcSettings instead. - -:rpcSettings: - Options for the RPC server exposed by the Node. - - :address: - host and port for the RPC server binding. - - *Default:* not define - - :adminAddress: - host and port for the RPC admin binding (this is the endpoint that the node process will connect to). - - *Default*: not define - - :standAloneBroker: - boolean, indicates whether the node will connect to a standalone broker for RPC. - - *Default:* ``false`` - - :useSsl: - boolean, indicates whether or not the node should require clients to use SSL for RPC connections. - - *Default:* ``false`` - :ssl: - (mandatory if ``useSsl=true``) SSL settings for the RPC server. - - :keyStorePath: - Absolute path to the key store containing the RPC SSL certificate. - - *Default:* not define - - :keyStorePassword: - Password for the key store. - - *Default*: not define - - .. note:: The RPC SSL certificate is used by RPC clients to authenticate the connection. - The Node operator must provide RPC clients with a truststore containing the certificate they can trust. - We advise Node operators to not use the P2P keystore for RPC. - The node can be run with the "generate-rpc-ssl-settings" command, which generates a secure keystore and truststore that can be used to secure the RPC connection. - You can use this if you have no special requirements. - - -: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 _) - - *Default:* not define - :password: - The password - - *Default:* not define - - :permissions: - A list of permissions for starting flows via RPC. - To give the user the permission to start the flow ``foo.bar.FlowClass``, add the string ``StartFlow.foo.bar.FlowClass`` to the list. - If the list contains the string ``ALL``, the user can start any flow via RPC. - This value is intended for administrator users and for development. - - *Default*: not define - -:security: - Contains various nested fields controlling user authentication/authorization, in particular for RPC accesses. - See :doc:`clientrpc` for details. - -: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 e.g. ``sshd { port = 2222 }``. - - *Default:* not define - -: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 }`` - - *Default:* not define - -:transactionCacheSizeMegaBytes: - Optionally specify how much memory should be used for caching of ledger transactions in memory. - - *Default:* 8 MB plus 5% of all heap memory above 300MB. - -:tlsCertCrlDistPoint: - CRL distribution point (i.e. URL) for the TLS certificate. - Default value is NULL, which indicates no CRL availability for the TLS certificate. - - *Default*: NULL - - .. note:: This needs to be set if crlCheckSoftFail is false (i.e. strict CRL checking is on). - -:tlsCertCrlIssuer: - CRL issuer (given in the X500 name format) for the TLS certificate. - Default value is NULL, which indicates that the issuer of the TLS certificate is also the issuer of the CRL. - - *Default*: NULL - - .. note:: If this parameter is set then `tlsCertCrlDistPoint` needs to be set as well. - -:trustStorePassword: - The password to unlock the Trust store file (``/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. - - *Default:* trustpass - - .. note:: Longer term these keys will be managed in secure hardware devices. - -:useTestClock: - Internal option. - Please do not change. + validating + Boolean to determine whether the notary is a validating or non-validating one. *Default:* false + serviceLegalName + If the node is part of a distributed cluster, specify the legal name of the cluster. + At runtime, Corda checks whether this name matches the name of the certificate of the notary cluster. -:verfierType: - Internal option. - Please do not change. + *Default:* not define - *Default:* InMemory + className + The fully qualified class name of the notary service to run. + The class is expected to be loaded from a notary CorDapp. -Refrence.conf --------- + *Default:* ``SimpleNotaryService`` (which is built in). + + extraConfig + an optional configuration block for providing notary implementation-specific values. + + *Default:* not define + +networkParameterAcceptanceSettings + Optional settings for managing the network parameter auto-acceptance behaviour. + If not provided then the defined defaults below are used. + + autoAcceptEnabled + This flag toggles auto accepting of network parameter changes. + If a network operator issues a network parameter change which modifies only auto-acceptable options and this behaviour is enabled then the changes will be accepted without any manual intervention from the node operator. + See :doc:`network-map` for more information on the update process and current auto-acceptable parameters. + Set to ``false`` to disable. + + *Default:* true + + excludedAutoAcceptableParameters + List of auto-acceptable parameter names to explicitly exclude from auto-accepting. + Allows a node operator to control the behaviour at a more granular level. + + *Default:* empty list + +networkServices + If the Corda compatibility zone services, both network map and registration (doorman), are not running on the same endpoint + and thus have different URLs then this option should be used in place of the ``compatibilityZoneURL`` setting. + + *Important:* Only one of ``compatibilityZoneURL`` or ``networkServices`` should be used. + + doormanURL + Root address of the network registration service. + + *Default:* not define + + networkMapURL + Root address of the network map service. + + *Default:* not define + + pnm + Optional UUID of the private network operating within the compatibility zone this node should be joining. + + *Default:* not define + + +p2pAddress + The host and port on which the node is available for protocol operations over ArtemisMQ. + + 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 network map. + 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. + + *Default:* not define + +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. + + *Important:* Deprecated. Use rpcSettings instead. + + *Default:* not define + +rpcSettings + Options for the RPC server exposed by the Node. + + *Important:* The RPC SSL certificate is used by RPC clients to authenticate the connection. + The Node operator must provide RPC clients with a truststore containing the certificate they can trust. + We advise Node operators to not use the P2P keystore for RPC. + The node can be run with the "generate-rpc-ssl-settings" command, which generates a secure keystore and truststore that can be used to secure the RPC connection. + You can use this if you have no special requirements. + + address + host and port for the RPC server binding. + + *Default:* not define + + adminAddress + host and port for the RPC admin binding (this is the endpoint that the node process will connect to). + + *Default:* not define + + standAloneBroker + boolean, indicates whether the node will connect to a standalone broker for RPC. + + *Default:* false + + useSsl + boolean, indicates whether or not the node should require clients to use SSL for RPC connections. + + *Default:* ``false`` + + ssl + (mandatory if ``useSsl=true``) SSL settings for the RPC server. + + keyStorePath + Absolute path to the key store containing the RPC SSL certificate. + + *Default:* not define + + keyStorePassword + Password for the key store. + + *Default:* not define + +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 _) + + *Default:* not define + + password + The password + + *Default:* not define + + permissions + A list of permissions for starting flows via RPC. + To give the user the permission to start the flow ``foo.bar.FlowClass``, add the string ``StartFlow.foo.bar.FlowClass`` to the list. + If the list contains the string ``ALL``, the user can start any flow via RPC. + This value is intended for administrator users and for development. + + *Default:* not define + +security + Contains various nested fields controlling user authentication/authorization, in particular for RPC accesses. + See :doc:`clientrpc` for details. + +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 e.g. ``sshd { port = 2222 }``. + + *Default:* not define + +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 }`` + + *Default:* not define + +transactionCacheSizeMegaBytes + Optionally specify how much memory should be used for caching of ledger transactions in memory. + + *Default:* 8 MB plus 5% of all heap memory above 300MB. + +tlsCertCrlDistPoint + CRL distribution point (i.e. URL) for the TLS certificate. + Default value is NULL, which indicates no CRL availability for the TLS certificate. + + *Important:* This needs to be set if crlCheckSoftFail is false (i.e. strict CRL checking is on). + + *Default:* NULL + + +tlsCertCrlIssuer + CRL issuer (given in the X500 name format) for the TLS certificate. + Default value is NULL, which indicates that the issuer of the TLS certificate is also the issuer of the CRL. + + *Important:* If this parameter is set then `tlsCertCrlDistPoint` needs to be set as well. + + *Default:* NULL + + +trustStorePassword + The password to unlock the Trust store file (``/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. + + *Important:* Longer term these keys will be managed in secure hardware devices. ??? (Is it for OS?) + + *Default:* trustpass + + +useTestClock + Internal option. + + *Important:* Please do not change. + + *Default:* false + + +verfierType + Internal option. + + *Important:* Please do not change. + + *Default:* InMemory + +Reference.conf +-------------- A set of default configuration options are loaded from the built-in resource file ``/node/src/main/resources/reference.conf``. This file can be found in the ``:node`` gradle module of the `Corda repository `_. Any options you do not specify in your own ``node.conf`` file will use these defaults. @@ -476,16 +519,19 @@ Any options you do not specify in your own ``node.conf`` file will use these def Here are the contents of the ``reference.conf`` file: .. literalinclude:: ../../node/src/main/resources/reference.conf - :language: javascript -Examples --------- -General node configuration file for hosting the IRSDemo services: +Configuration examples +---------------------- + +Node configuration hosting the IRSDemo services +```````````````````````````````````````````````````````````````` +General node configuration file for hosting the IRSDemo services .. literalinclude:: example-code/src/main/resources/example-node.conf -Simple notary configuration file: +Simple notary configuration file +````````````````````````````````` .. parsed-literal:: @@ -508,101 +554,11 @@ Simple notary configuration file: networkMapURL = "https://cz.example.com" } +Node configuration with diffrent URL for NetworkMap and Doorman +``````````````````````````````````````````````````````````````` + Configuring a node where the Corda Compatibility Zone's registration and Network Map services exist on different URLs .. literalinclude:: example-code/src/main/resources/example-node-with-networkservices.conf -File location -------------- -When starting a node, the ``corda.jar`` file defaults to reading the node's configuration from a ``node.conf`` file in the directory from which the command to launch Corda is executed. -There are two command-line options to override this behaviour: - -* The ``--config-file`` command line option allows you to specify a configuration file with a different name, or at different file location. - Paths are relative to the current working directory - -* The ``--base-directory`` command line option allows you to specify the node's workspace location. - A ``node.conf`` configuration file is then expected in the root of this workspace - -If you specify both command line arguments at the same time, the node will fail to start. - -Fields override ---------------- -JVM options or environmental variables prefixed with ``corda.`` can override ``node.conf`` fields. -Provided system properties can also set values for absent fields in ``node.conf``. - -This is an example of adding/overriding the keyStore password : - -.. sourcecode:: shell - - java -Dcorda.rpcSettings.ssl.keyStorePassword=mypassword -jar node.jar - -CRL configuration ------------------ -The Corda Network provides an endpoint serving an empty certificate revocation list for the TLS-level certificates. -This is intended for deployments that do not provide a CRL infrastructure but still require a strict CRL mode checking. -In such a case use the following URL in `tlsCertCrlDistPoint` option configuration: - - .. sourcecode:: kotlin - - "https://crl.cordaconnect.org/cordatls.crl" - -Together with the above configuration `tlsCertCrlIssuer` option needs to be set to the following value: - - .. sourcecode:: kotlin - - "C=US, L=New York, O=R3 HoldCo LLC, OU=Corda, CN=Corda Root CA" - -This set-up ensures that the TLS-level certificates are embedded with the CRL distribution point referencing the CRL issued by R3. -In cases where a proprietary CRL infrastructure is provided those values need to be changed accordingly. - -.. _corda-configuration-hiding-sensitive-data: - -Hiding sensitive data ---------------------- -A frequent requirement is that configuration files must not expose passwords to unauthorised readers. By leveraging environment variables, it is possible to hide passwords and other similar fields. - -Take a simple node config that wishes to protect the node cryptographic stores: - -.. parsed-literal:: - - myLegalName : "O=PasswordProtectedNode,OU=corda,L=London,C=GB" - keyStorePassword : ${KEY_PASS} - trustStorePassword : ${TRUST_PASS} - p2pAddress : "localhost:12345" - devMode : false - networkServices { - doormanURL = "https://cz.example.com" - networkMapURL = "https://cz.example.com" - } - -By delegating to a password store, and using `command substitution` it is possible to ensure that sensitive passwords never appear in plain text. -The below examples are of loading Corda with the KEY_PASS and TRUST_PASS variables read from a program named ``corporatePasswordStore``. - - -Bash -~~~~ - -.. sourcecode:: shell - - KEY_PASS=$(corporatePasswordStore --cordaKeyStorePassword) TRUST_PASS=$(corporatePasswordStore --cordaTrustStorePassword) java -jar corda.jar - -.. warning:: If this approach is taken, the passwords will appear in the shell history. - - -Windows PowerShell -~~~~~~~~~~~~~~~~~~ - -.. sourcecode:: shell - - $env:KEY_PASS=$(corporatePasswordStore --cordaKeyStorePassword); $env:TRUST_PASS=$(corporatePasswordStore --cordaTrustStorePassword); java -jar corda.jar - - -For launching on Windows without PowerShell, it is not possible to perform command substitution, and so the variables must be specified manually, for example: - -.. sourcecode:: shell - - SET KEY_PASS=mypassword & SET TRUST_PASS=mypassword & java -jar corda.jar - -.. warning:: If this approach is taken, the passwords will appear in the windows command prompt history. - diff --git a/docs/source/deploying-a-node.rst b/docs/source/deploying-a-node.rst index 611c63707e..f48fd54041 100644 --- a/docs/source/deploying-a-node.rst +++ b/docs/source/deploying-a-node.rst @@ -1,5 +1,5 @@ -Deploying a node -================ +Node deployment to server +========================= .. contents:: @@ -36,18 +36,18 @@ handling, and ensures the Corda service is run at boot. 6. Save the below as ``/opt/corda/node.conf``. See :doc:`corda-configuration-file` for a description of these options:: - p2pAddress : "example.com:10002" + p2pAddress = "example.com:10002" rpcSettings { address: "example.com:10003" adminAddress: "example.com:10004" } - h2port : 11000 - emailAddress : "you@example.com" - myLegalName : "O=Bank of Breakfast Tea, L=London, C=GB" - keyStorePassword : "cordacadevpass" - trustStorePassword : "trustpass" - devMode : false - rpcUsers=[ + h2port = 11000 + emailAddress = "you@example.com" + myLegalName = "O=Bank of Breakfast Tea, L=London, C=GB" + keyStorePassword = "cordacadevpass" + trustStorePassword = "trustpass" + devMode = false + rpcUsers= [ { user=corda password=portal_password @@ -116,8 +116,6 @@ handling, and ensures the Corda service is run at boot. * Make sure the service description is informative - particularly if you plan to run multiple nodes. * Change the username to the user account you want to use to run Corda. **We recommend that this user account is not root** - * Set the maximum amount of memory available to the Corda process by changing the ``-Xmx2048m`` parameter in - the config file * **SystemD**: Make sure the ``corda.service`` file is owned by root with the correct permissions: * ``sudo chown root:root /etc/systemd/system/corda.service`` @@ -205,18 +203,18 @@ at boot, and means the Corda service stays running with no users connected to th 3. Save the below as ``C:\Corda\node.conf``. See :doc:`corda-configuration-file` for a description of these options:: - p2pAddress : "example.com:10002" + p2pAddress = "example.com:10002" rpcSettings { - address: "example.com:10003" - adminAddress: "example.com:10004" + address = "example.com:10003" + adminAddress = "example.com:10004" } - h2port : 11000 - emailAddress: "you@example.com" - myLegalName : "O=Bank of Breakfast Tea, L=London, C=GB" - keyStorePassword : "cordacadevpass" - trustStorePassword : "trustpass" - devMode : false - rpcUsers=[ + h2port = 11000 + emailAddress = "you@example.com" + myLegalName = "O=Bank of Breakfast Tea, L=London, C=GB" + keyStorePassword = "cordacadevpass" + trustStorePassword = "trustpass" + devMode = false + rpcUsers = [ { user=corda password=portal_password @@ -225,6 +223,7 @@ at boot, and means the Corda service stays running with no users connected to th ] } ] + custom { jvmArgs = [ '-Xmx2048m', '-XX:+UseG1GC' ] } 4. Make the following changes to ``C:\Corda\node.conf``: diff --git a/docs/source/node-administration.rst b/docs/source/node-administration.rst index b5bacfad67..36aebd4615 100644 --- a/docs/source/node-administration.rst +++ b/docs/source/node-administration.rst @@ -1,6 +1,76 @@ Node administration =================== +CRL configuration +----------------- +The Corda Network provides an endpoint serving an empty certificate revocation list for the TLS-level certificates. +This is intended for deployments that do not provide a CRL infrastructure but still require a strict CRL mode checking. +In such a case use the following URL in `tlsCertCrlDistPoint` option configuration: + + .. sourcecode:: kotlin + + "https://crl.cordaconnect.org/cordatls.crl" + +Together with the above configuration `tlsCertCrlIssuer` option needs to be set to the following value: + + .. sourcecode:: kotlin + + "C=US, L=New York, O=R3 HoldCo LLC, OU=Corda, CN=Corda Root CA" + +This set-up ensures that the TLS-level certificates are embedded with the CRL distribution point referencing the CRL issued by R3. +In cases where a proprietary CRL infrastructure is provided those values need to be changed accordingly. + +.. _hiding-sensitive-data: + +Hiding sensitive data +--------------------- +A frequent requirement is that configuration files must not expose passwords to unauthorised readers. By leveraging environment variables, it is possible to hide passwords and other similar fields. + +Take a simple node config that wishes to protect the node cryptographic stores: + +.. parsed-literal:: + + myLegalName : "O=PasswordProtectedNode,OU=corda,L=London,C=GB" + keyStorePassword : ${KEY_PASS} + trustStorePassword : ${TRUST_PASS} + p2pAddress : "localhost:12345" + devMode : false + networkServices { + doormanURL = "https://cz.example.com" + networkMapURL = "https://cz.example.com" + } + +By delegating to a password store, and using `command substitution` it is possible to ensure that sensitive passwords never appear in plain text. +The below examples are of loading Corda with the KEY_PASS and TRUST_PASS variables read from a program named ``corporatePasswordStore``. + + +Bash +~~~~ + +.. sourcecode:: shell + + KEY_PASS=$(corporatePasswordStore --cordaKeyStorePassword) TRUST_PASS=$(corporatePasswordStore --cordaTrustStorePassword) java -jar corda.jar + +.. warning:: If this approach is taken, the passwords will appear in the shell history. + + +Windows PowerShell +~~~~~~~~~~~~~~~~~~ + +.. sourcecode:: shell + + $env:KEY_PASS=$(corporatePasswordStore --cordaKeyStorePassword); $env:TRUST_PASS=$(corporatePasswordStore --cordaTrustStorePassword); java -jar corda.jar + + +For launching on Windows without PowerShell, it is not possible to perform command substitution, and so the variables must be specified manually, for example: + +.. sourcecode:: shell + + SET KEY_PASS=mypassword & SET TRUST_PASS=mypassword & java -jar corda.jar + +.. warning:: If this approach is taken, the passwords will appear in the windows command prompt history. + + Logging ------- diff --git a/docs/source/node-naming.rst b/docs/source/node-naming.rst index bdea524a8e..fc3d15bf4e 100644 --- a/docs/source/node-naming.rst +++ b/docs/source/node-naming.rst @@ -1,3 +1,5 @@ +.. _node-naming: + Node naming =========== A node's name must be a valid X.500 distinguished name. In order to be compatible with other implementations diff --git a/docs/source/node-structure.rst b/docs/source/node-structure.rst index e36ee785b5..235d6573a6 100644 --- a/docs/source/node-structure.rst +++ b/docs/source/node-structure.rst @@ -1,7 +1,5 @@ Node folder structure -============== - -.. contents:: +===================== A folder with Corda node files has the following structure: From 4eb711413497b61f062ed532cd4ca6d0a21d6c46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Tue, 8 Jan 2019 14:09:55 +0000 Subject: [PATCH 05/21] Adjust deployment notes - update to new config --- docs/source/deploying-a-node.rst | 41 ++++++++++---------------------- 1 file changed, 13 insertions(+), 28 deletions(-) diff --git a/docs/source/deploying-a-node.rst b/docs/source/deploying-a-node.rst index f48fd54041..ca38256098 100644 --- a/docs/source/deploying-a-node.rst +++ b/docs/source/deploying-a-node.rst @@ -14,7 +14,7 @@ handling, and ensures the Corda service is run at boot. **Prerequisites**: - * Oracle Java 8. The supported versions are listed in :doc:`getting-set-up` + * Supported Java 8. The supported versions are listed in :doc:`getting-set-up` 1. As root/sys admin user - add a system user which will be used to run Corda: @@ -66,13 +66,8 @@ handling, and ensures the Corda service is run at boot. * Change the ports if necessary, for example if you are running multiple nodes on one server (see below). * Enter an email address which will be used as an administrative contact during the registration process. This is only visible to the permissioning service. - * Enter your node's desired legal name. This will be used during the issuance of your certificate and should rarely - change as it should represent the legal identity of your node. - - * Organization (``O=``) should be a unique and meaningful identifier (e.g. Bank of Breakfast Tea) - * Location (``L=``) is your nearest city - * Country (``C=``) is the `ISO 3166-1 alpha-2 code `_ - * Change the RPC username and password. + * Enter your node's desired legal name (see :ref:`node-naming` for more details). + * Setup RPC users (*optional*). .. note:: Ubuntu 16.04 and most current Linux distributions use SystemD, so if you are running one of these distributions follow the steps marked **SystemD**. @@ -190,7 +185,7 @@ at boot, and means the Corda service stays running with no users connected to th **Prerequisites**: - * Oracle Java 8. The supported versions are listed in :doc:`getting-set-up` + * Supported Java 8. The supported versions are listed in :doc:`getting-set-up` 1. Create a Corda directory and download the Corda jar. Replace ``VERSION_NUMBER`` with the desired version. Here's an example using PowerShell:: @@ -214,16 +209,13 @@ at boot, and means the Corda service stays running with no users connected to th keyStorePassword = "cordacadevpass" trustStorePassword = "trustpass" devMode = false - rpcUsers = [ - { - user=corda - password=portal_password - permissions=[ - ALL - ] - } - ] - custom { jvmArgs = [ '-Xmx2048m', '-XX:+UseG1GC' ] } + rpcSettings { + useSsl = false + standAloneBroker = false + address = "example.com:10003" + adminAddress = "example.com:10004" + } + custom { jvmArgs = [ '-Xmx2048m', '-XX:+UseG1GC' ] } 4. Make the following changes to ``C:\Corda\node.conf``: @@ -233,13 +225,8 @@ at boot, and means the Corda service stays running with no users connected to th * Change the ports if necessary, for example if you are running multiple nodes on one server (see below). * Enter an email address which will be used as an administrative contact during the registration process. This is only visible to the permissioning service. - * Enter your node's desired legal name. This will be used during the issuance of your certificate and should rarely - change as it should represent the legal identity of your node. - - * Organization (``O=``) should be a unique and meaningful identifier (e.g. Bank of Breakfast Tea) - * Location (``L=``) is your nearest city - * Country (``C=``) is the `ISO 3166-1 alpha-2 code `_ - * Change the RPC username and password. + * Enter your node's desired legal name (see :ref:`node-naming` for more details). + * Setup RPC users (*optional*). 5. Copy the required Java keystores to the node. See :doc:`permissioning` @@ -253,7 +240,6 @@ at boot, and means the Corda service stays running with no users connected to th nssm install cordanode1 C:\ProgramData\Oracle\Java\javapath\java.exe nssm set cordanode1 AppDirectory C:\Corda - nssm set cordanode1 AppParameters "-Xmx2048m -jar corda.jar --config-file=C:\corda\node.conf" nssm set cordanode1 AppStdout C:\Corda\service.log nssm set cordanode1 AppStderr C:\Corda\service.log nssm set cordanode1 Description Corda Node - Bank of Breakfast Tea @@ -263,7 +249,6 @@ at boot, and means the Corda service stays running with no users connected to th 9. Modify the batch file: * If you are installing multiple nodes, use a different service name (``cordanode1``) for each node - * Set the amount of Java heap memory available to this node by modifying the -Xmx argument * Set an informative description 10. Provision the required certificates to your node. Contact the network permissioning service or see From 78a758364ec72a4ce18e1812b4a9dec80caf9217 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Tue, 8 Jan 2019 15:20:17 +0000 Subject: [PATCH 06/21] Move commandline to own chapter - move commandline section to separate file - remove old way of passing Java options --- docs/source/corda-nodes-index.rst | 1 + docs/source/node-commandline.rst | 49 ++++++++++++++++++++++++++ docs/source/running-a-node.rst | 57 ------------------------------- 3 files changed, 50 insertions(+), 57 deletions(-) create mode 100644 docs/source/node-commandline.rst diff --git a/docs/source/corda-nodes-index.rst b/docs/source/corda-nodes-index.rst index 670f99aa23..fd7fe167d7 100644 --- a/docs/source/corda-nodes-index.rst +++ b/docs/source/corda-nodes-index.rst @@ -9,6 +9,7 @@ Nodes corda-configuration-file node-administration deploying-a-node + node-commandline docker-image node-database node-database-access-h2 diff --git a/docs/source/node-commandline.rst b/docs/source/node-commandline.rst new file mode 100644 index 0000000000..c390db6489 --- /dev/null +++ b/docs/source/node-commandline.rst @@ -0,0 +1,49 @@ +Node Command-line options +==================== + +The node can optionally be started with the following command-line options: + +* ``--base-directory``, ``-b``: The node working directory where all the files are kept (default: ``.``). +* ``--config-file``, ``-f``: The path to the config file. Defaults to ``node.conf``. +* ``--dev-mode``, ``-d``: Runs the node in development mode. Unsafe in production. Defaults to true on MacOS and desktop versions of Windows. False otherwise. +* ``--no-local-shell``, ``-n``: Do not start the embedded shell locally. +* ``--on-unknown-config-keys <[FAIL,INFO]>``: How to behave on unknown node configuration. Defaults to FAIL. +* ``--sshd``: Enables SSH server for node administration. +* ``--sshd-port``: Sets the port for the SSH server. If not supplied and SSH server is enabled, the port defaults to 2222. +* ``--verbose``, ``--log-to-console``, ``-v``: If set, prints logging to the console as well as to a file. +* ``--logging-level=``: Enable logging at this level and higher. Possible values: ERROR, WARN, INFO, DEBUG, TRACE. Default: INFO. +* ``--help``, ``-h``: Show this help message and exit. +* ``--version``, ``-V``: Print version information and exit. + +Sub-commands +------------ + +``clear-network-cache``: Clears local copy of network map, on node startup it will be restored from server or file system. + +``initial-registration``: Starts initial node registration with the compatibility zone to obtain a certificate from the Doorman. + +Parameters: + +* ``--network-root-truststore``, ``-t`` **required**: Network root trust store obtained from network operator. +* ``--network-root-truststore-password``, ``-p``: Network root trust store password obtained from network operator. + +``generate-node-info``: Performs the node start-up tasks necessary to generate the nodeInfo file, saves it to disk, then exits. + +``generate-rpc-ssl-settings``: Generates the SSL keystore and truststore for a secure RPC connection. + +``install-shell-extensions``: Install ``corda`` alias and auto completion for bash and zsh. See :doc:`cli-application-shell-extensions` for more info. + + +``validate-configuration``: Validates the actual configuration without starting the node. + +.. _enabling-remote-debugging: + +Enabling remote debugging +------------------------- +To enable remote debugging of the node, run the node with the following JVM arguments: + +``java -Dcapsule.jvm.args="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005" -jar corda.jar`` + +This will allow you to attach a debugger to your node on port 5005. + + diff --git a/docs/source/running-a-node.rst b/docs/source/running-a-node.rst index 2e30354bd5..67695d5fc7 100644 --- a/docs/source/running-a-node.rst +++ b/docs/source/running-a-node.rst @@ -26,15 +26,6 @@ By default, the node will look for a configuration file called ``node.conf`` and in the current working directory. You can override the configuration file and workspace paths on the command line (e.g. ``./corda.jar --config-file=test.conf --base-directory=/opt/corda/nodes/test``). -You can increase the amount of Java heap memory available to the node using the ``-Xmx`` command line argument. For -example, the following would run the node with a heap size of 2048MB: - -.. code-block:: shell - - java -Xmx2048m -jar corda.jar - -You should do this if you receive an ``OutOfMemoryError`` exception when interacting with the node. - Optionally run the node's webserver as well by opening a terminal window in the node's folder and running: .. code-block:: shell @@ -77,54 +68,6 @@ anything set earlier. :Command line flag: You can set JVM args on the command line that apply to the launcher process and the node process as in the example above. This will override any value for the same flag set any other way, but will leave any other JVM arguments alone. - -Command-line options -~~~~~~~~~~~~~~~~~~~~ -The node can optionally be started with the following command-line options: - -* ``--base-directory``, ``-b``: The node working directory where all the files are kept (default: ``.``). -* ``--config-file``, ``-f``: The path to the config file. Defaults to ``node.conf``. -* ``--dev-mode``, ``-d``: Runs the node in development mode. Unsafe in production. Defaults to true on MacOS and desktop versions of Windows. False otherwise. -* ``--no-local-shell``, ``-n``: Do not start the embedded shell locally. -* ``--on-unknown-config-keys <[FAIL,INFO]>``: How to behave on unknown node configuration. Defaults to FAIL. -* ``--sshd``: Enables SSH server for node administration. -* ``--sshd-port``: Sets the port for the SSH server. If not supplied and SSH server is enabled, the port defaults to 2222. -* ``--verbose``, ``--log-to-console``, ``-v``: If set, prints logging to the console as well as to a file. -* ``--logging-level=``: Enable logging at this level and higher. Possible values: ERROR, WARN, INFO, DEBUG, TRACE. Default: INFO. -* ``--help``, ``-h``: Show this help message and exit. -* ``--version``, ``-V``: Print version information and exit. - -Sub-commands -^^^^^^^^^^^^ - -``clear-network-cache``: Clears local copy of network map, on node startup it will be restored from server or file system. - -``initial-registration``: Starts initial node registration with the compatibility zone to obtain a certificate from the Doorman. - -Parameters: - -* ``--network-root-truststore``, ``-t`` **required**: Network root trust store obtained from network operator. -* ``--network-root-truststore-password``, ``-p``: Network root trust store password obtained from network operator. - -``generate-node-info``: Performs the node start-up tasks necessary to generate the nodeInfo file, saves it to disk, then exits. - -``generate-rpc-ssl-settings``: Generates the SSL keystore and truststore for a secure RPC connection. - -``install-shell-extensions``: Install ``corda`` alias and auto completion for bash and zsh. See :doc:`cli-application-shell-extensions` for more info. - - -``validate-configuration``: Validates the actual configuration without starting the node. - -.. _enabling-remote-debugging: - -Enabling remote debugging -~~~~~~~~~~~~~~~~~~~~~~~~~ -To enable remote debugging of the node, run the node with the following JVM arguments: - -``java -Dcapsule.jvm.args="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005" -jar corda.jar`` - -This will allow you to attach a debugger to your node on port 5005. - Starting all nodes at once on a local machine from the command line ------------------------------------------------------------------- From e9f00204f94c0334be66a8a9caea5809536259f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Tue, 8 Jan 2019 15:28:21 +0000 Subject: [PATCH 07/21] Small fixes --- docs/source/corda-nodes-index.rst | 2 +- docs/source/node-commandline.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/corda-nodes-index.rst b/docs/source/corda-nodes-index.rst index fd7fe167d7..45d9f0fd03 100644 --- a/docs/source/corda-nodes-index.rst +++ b/docs/source/corda-nodes-index.rst @@ -7,9 +7,9 @@ Nodes node-structure node-naming corda-configuration-file + node-commandline node-administration deploying-a-node - node-commandline docker-image node-database node-database-access-h2 diff --git a/docs/source/node-commandline.rst b/docs/source/node-commandline.rst index c390db6489..41910a9cad 100644 --- a/docs/source/node-commandline.rst +++ b/docs/source/node-commandline.rst @@ -1,4 +1,4 @@ -Node Command-line options +Node command-line options ==================== The node can optionally be started with the following command-line options: From 6fc80604bf7f18f7b9b445a89b86d36071dd1128 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Tue, 8 Jan 2019 15:52:24 +0000 Subject: [PATCH 08/21] Move docker in menu --- docs/source/corda-nodes-index.rst | 1 - docs/source/docker.rst | 7 +++++++ docs/source/index.rst | 3 ++- 3 files changed, 9 insertions(+), 2 deletions(-) create mode 100644 docs/source/docker.rst diff --git a/docs/source/corda-nodes-index.rst b/docs/source/corda-nodes-index.rst index 45d9f0fd03..a3c888565d 100644 --- a/docs/source/corda-nodes-index.rst +++ b/docs/source/corda-nodes-index.rst @@ -10,7 +10,6 @@ Nodes node-commandline node-administration deploying-a-node - docker-image node-database node-database-access-h2 shell diff --git a/docs/source/docker.rst b/docs/source/docker.rst new file mode 100644 index 0000000000..3315b5cb57 --- /dev/null +++ b/docs/source/docker.rst @@ -0,0 +1,7 @@ +Docker +===== + +.. toctree:: + :maxdepth: 1 + + docker-image diff --git a/docs/source/index.rst b/docs/source/index.rst index b0602c9293..a0b17c7890 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -55,6 +55,7 @@ We look forward to seeing what you can do with Corda! corda-nodes-index.rst corda-networks-index.rst + docker.rst azure-vm.rst aws-vm.rst loadtesting.rst @@ -95,7 +96,7 @@ We look forward to seeing what you can do with Corda! :caption: Participate :maxdepth: 2 :if_tag: htmlmode - + contributing-index.rst corda-repo-layout.rst deterministic-modules.rst From 628c336abddd256698a64a3c8870b4f93c204bb8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Tue, 8 Jan 2019 16:44:41 +0000 Subject: [PATCH 09/21] First round of comments --- docs/source/corda-configuration-file.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index 15584f59bb..a3d3d707f6 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -3,20 +3,20 @@ Node configuration .. contents:: -Config file location +Configuration file location -------------------- When starting a node, the ``corda.jar`` file defaults to reading the node's configuration from a ``node.conf`` file in the directory from which the command to launch Corda is executed. There are two command-line options to override this behaviour: -* The ``--config-file`` command line option allows you to specify a configuration file with a different name, or at different file location. +* The ``--config-file`` command line option allows you to specify a configuration file with a different name, or in a different file location. Paths are relative to the current working directory * The ``--base-directory`` command line option allows you to specify the node's workspace location. - A ``node.conf`` configuration file is then expected in the root of this workspace + A ``node.conf`` configuration file is then expected in the root of this workspace. If you specify both command line arguments at the same time, the node will fail to start. -Config file format +Configuration file format ------------------ The Corda configuration file uses the HOCON format which is a superset of JSON. Please visit ``_ for further details. @@ -46,7 +46,7 @@ JVM options java -Dcorda.rpcSettings.ssl.keyStorePassword=mypassword -jar node.jar -Config file fields +Configuration file fields ------------------ .. note :: The available config fields are listed below in alphabetic order. @@ -490,8 +490,6 @@ trustStorePassword The password to unlock the Trust store file (``/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. - *Important:* Longer term these keys will be managed in secure hardware devices. ??? (Is it for OS?) - *Default:* trustpass From 4e0a54faea94e700b3dbb01d2b069eb8d68ff67a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Thu, 10 Jan 2019 10:10:10 +0000 Subject: [PATCH 10/21] Further minor changes --- docs/source/deploying-a-node.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/deploying-a-node.rst b/docs/source/deploying-a-node.rst index ca38256098..f1502510e5 100644 --- a/docs/source/deploying-a-node.rst +++ b/docs/source/deploying-a-node.rst @@ -1,5 +1,5 @@ -Node deployment to server -========================= +Deploying a node to a server +============================ .. contents:: @@ -14,7 +14,7 @@ handling, and ensures the Corda service is run at boot. **Prerequisites**: - * Supported Java 8. The supported versions are listed in :doc:`getting-set-up` + * A supported Java distribution. The supported versions are listed in :doc:`getting-set-up` 1. As root/sys admin user - add a system user which will be used to run Corda: @@ -67,7 +67,7 @@ handling, and ensures the Corda service is run at boot. * Enter an email address which will be used as an administrative contact during the registration process. This is only visible to the permissioning service. * Enter your node's desired legal name (see :ref:`node-naming` for more details). - * Setup RPC users (*optional*). + * If required, add RPC users .. note:: Ubuntu 16.04 and most current Linux distributions use SystemD, so if you are running one of these distributions follow the steps marked **SystemD**. @@ -185,7 +185,7 @@ at boot, and means the Corda service stays running with no users connected to th **Prerequisites**: - * Supported Java 8. The supported versions are listed in :doc:`getting-set-up` + * A supported Java distribution. The supported versions are listed in :doc:`getting-set-up` 1. Create a Corda directory and download the Corda jar. Replace ``VERSION_NUMBER`` with the desired version. Here's an example using PowerShell:: @@ -226,7 +226,7 @@ at boot, and means the Corda service stays running with no users connected to th * Enter an email address which will be used as an administrative contact during the registration process. This is only visible to the permissioning service. * Enter your node's desired legal name (see :ref:`node-naming` for more details). - * Setup RPC users (*optional*). + * If required, add RPC users 5. Copy the required Java keystores to the node. See :doc:`permissioning` From 3a742ca04a90c0e5d3c3dd9370fa513409797814 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Thu, 10 Jan 2019 10:51:01 +0000 Subject: [PATCH 11/21] Fix 'not define' --- docs/source/corda-configuration-file.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index a3d3d707f6..b72af87557 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -74,7 +74,7 @@ compatibilityZoneURL *Important:* old config value, please use networkServices - *Default:* not define + *Default:* not defined .. _corda_configuration_file_signer_blacklist: @@ -83,7 +83,7 @@ cordappSignerKeyFingerprintBlacklist Node will not load Cordapps signed by those keys. The option takes effect only in production mode and defaults to Corda development keys (``["56CA54E803CB87C8472EBD3FBC6A2F1876E814CEEBF74860BD46997F40729367", "83088052AF16700457AE2C978A7D8AC38DD6A7C713539D00B897CD03A5E5D31D"]``), in development mode any key is allowed to sign Cordpapp JARs. - *Default:* not define + *Default:* not defined crlCheckSoftFail This is a boolean flag that when enabled (i.e. `true` value is set) the certificate revocation list (CRL) checking will use the soft fail mode. @@ -99,7 +99,7 @@ custom A list of JVM arguments to apply to the node process. This removes any defaults specified from ``corda.jar``, but can be overridden from the command line. See :ref:`setting_jvm_args` for examples and details on the precedence of the different approaches to settings arguments. - *Default:* not define + *Default:* not defined .. _databaseConfiguration: @@ -171,7 +171,7 @@ devModeOptions allowCompatibilityZone Allows a node configured to operate in development mode to connect to a compatibility zone. - *Default:* not define + *Default:* not defined emailAddress @@ -185,7 +185,7 @@ extraNetworkMapKeys *Important:* This is temporary feature for onboarding network participants that limits their visibility for privacy reasons. - *Default:* not define + *Default:* not defined flowMonitorPeriodMillis @@ -238,7 +238,7 @@ jarDirs This is useful for including JDBC drivers and the like. e.g. ``jarDirs = [ '${baseDirectory}/lib' ]``. (Note that you have to use the ``baseDirectory`` substitution value when pointing to a relative path). - *Default:* not define + *Default:* not defined jmxMonitoringHttpPort If set, will enable JMX metrics reporting via the Jolokia HTTP/JSON agent on the corresponding port. @@ -278,14 +278,14 @@ messagingServerAddress The address of the ArtemisMQ broker instance. If not provided the node will run one locally. - *Default:* not define + *Default:* not defined messagingServerExternal If ``messagingServerAddress`` is specified the default assumption is that the artemis broker is running externally. Setting this to ``false`` overrides this behaviour and runs the artemis internally to the node, but bound to the address specified in ``messagingServerAddress``. This allows the address and port advertised in ``p2pAddress`` to differ from the local binding, especially if there is external remapping by firewalls, load balancers , or routing rules. Note that ``detectPublicIp`` should be set to ``false`` to ensure that no translation of the ``p2pAddress`` occurs before it is sent to the network map. - *Default:* not define + *Default:* not defined myLegalName The legal identity of the node. @@ -294,7 +294,7 @@ myLegalName At runtime, Corda checks whether this name matches the name in the node's certificates. For more details please read :ref:`node-naming` chapter. - *Default:* not define + *Default:* not defined notary Optional configuration object which if present configures the node to run as a notary. @@ -308,7 +308,7 @@ notary If the node is part of a distributed cluster, specify the legal name of the cluster. At runtime, Corda checks whether this name matches the name of the certificate of the notary cluster. - *Default:* not define + *Default:* not defined className The fully qualified class name of the notary service to run. From bf4d7b1848dac55fea0cf2f0e7dbea3013a82846 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Thu, 10 Jan 2019 11:16:35 +0000 Subject: [PATCH 12/21] More 'not define' - my Vim misbehaved and I had to run substitute again --- docs/source/corda-configuration-file.rst | 38 ++++++++++++------------ 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index b72af87557..284aa4131d 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -4,7 +4,7 @@ Node configuration .. contents:: Configuration file location --------------------- +--------------------------- When starting a node, the ``corda.jar`` file defaults to reading the node's configuration from a ``node.conf`` file in the directory from which the command to launch Corda is executed. There are two command-line options to override this behaviour: @@ -17,7 +17,7 @@ There are two command-line options to override this behaviour: If you specify both command line arguments at the same time, the node will fail to start. Configuration file format ------------------- +------------------------- The Corda configuration file uses the HOCON format which is a superset of JSON. Please visit ``_ for further details. @@ -47,7 +47,7 @@ JVM options java -Dcorda.rpcSettings.ssl.keyStorePassword=mypassword -jar node.jar Configuration file fields ------------------- +------------------------- .. note :: The available config fields are listed below in alphabetic order. @@ -244,7 +244,7 @@ jmxMonitoringHttpPort If set, will enable JMX metrics reporting via the Jolokia HTTP/JSON agent on the corresponding port. Default Jolokia access url is http://127.0.0.1:port/jolokia/ - *Default:* ??? + *Default:* not defined jmxReporterType Provides an option for registering an alternative JMX reporter. @@ -319,7 +319,7 @@ notary extraConfig an optional configuration block for providing notary implementation-specific values. - *Default:* not define + *Default:* not defined networkParameterAcceptanceSettings Optional settings for managing the network parameter auto-acceptance behaviour. @@ -348,17 +348,17 @@ networkServices doormanURL Root address of the network registration service. - *Default:* not define + *Default:* not defined networkMapURL Root address of the network map service. - *Default:* not define + *Default:* not defined pnm Optional UUID of the private network operating within the compatibility zone this node should be joining. - *Default:* not define + *Default:* not defined p2pAddress @@ -369,7 +369,7 @@ p2pAddress 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. - *Default:* not define + *Default:* not defined rpcAddress The address of the RPC system on which RPC requests can be made to the node. @@ -377,7 +377,7 @@ rpcAddress *Important:* Deprecated. Use rpcSettings instead. - *Default:* not define + *Default:* not defined rpcSettings Options for the RPC server exposed by the Node. @@ -391,12 +391,12 @@ rpcSettings address host and port for the RPC server binding. - *Default:* not define + *Default:* not defined adminAddress host and port for the RPC admin binding (this is the endpoint that the node process will connect to). - *Default:* not define + *Default:* not defined standAloneBroker boolean, indicates whether the node will connect to a standalone broker for RPC. @@ -414,12 +414,12 @@ rpcSettings keyStorePath Absolute path to the key store containing the RPC SSL certificate. - *Default:* not define + *Default:* not defined keyStorePassword Password for the key store. - *Default:* not define + *Default:* not defined rpcUsers A list of users who are authorised to access the RPC system. @@ -428,12 +428,12 @@ rpcUsers username Username consisting only of word characters (a-z, A-Z, 0-9 and _) - *Default:* not define + *Default:* not defined password The password - *Default:* not define + *Default:* not defined permissions A list of permissions for starting flows via RPC. @@ -441,7 +441,7 @@ rpcUsers If the list contains the string ``ALL``, the user can start any flow via RPC. This value is intended for administrator users and for development. - *Default:* not define + *Default:* not defined security Contains various nested fields controlling user authentication/authorization, in particular for RPC accesses. @@ -455,13 +455,13 @@ sshd port The port to start SSH server on e.g. ``sshd { port = 2222 }``. - *Default:* not define + *Default:* not defined 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 }`` - *Default:* not define + *Default:* not defined transactionCacheSizeMegaBytes Optionally specify how much memory should be used for caching of ledger transactions in memory. From 0624e4eb1de74df6be55aa635f7855b9b5afa4d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Thu, 10 Jan 2019 15:27:09 +0000 Subject: [PATCH 13/21] Adjust 'important' to be bold --- docs/source/corda-configuration-file.rst | 30 ++++++++++++------------ 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index 284aa4131d..598598fbb5 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -72,7 +72,7 @@ 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. Cannot be set at the same time as the ``networkServices`` option. - *Important:* old config value, please use networkServices + **Important: old config value, please use networkServices** *Default:* not defined @@ -166,7 +166,7 @@ devMode devModeOptions Allows modification of certain ``devMode`` features - *Important:* This is an unsupported configuration. + **Important: This is an unsupported configuration.** allowCompatibilityZone Allows a node configured to operate in development mode to connect to a compatibility zone. @@ -183,7 +183,7 @@ extraNetworkMapKeys An optional list of private network map UUIDs. Your node will fetch the public network and private network maps based on these keys. Private network UUID should be provided by network operator and lets you see nodes not visible on public network. - *Important:* This is temporary feature for onboarding network participants that limits their visibility for privacy reasons. + **Important: This is temporary feature for onboarding network participants that limits their visibility for privacy reasons.** *Default:* not defined @@ -222,7 +222,7 @@ flowTimeout h2Port Defines port for h2 DB. - *Important:* Deprecated please use h2Setting instead + **Important: Deprecated please use h2Setting instead** h2Settings Sets the H2 JDBC server host and port. @@ -262,15 +262,15 @@ jmxReporterType keyStorePassword The password to unlock the KeyStore file (``/certificates/sslkeystore.jks``) containing the node certificate and private key. - *Important:* 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. + **Important: 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.** *Default:* cordacadevpass lazyBridgeStart Internal option. - *Important:* Please do not change. + **Important: Please do not change.** *Default:* true @@ -343,7 +343,7 @@ networkServices If the Corda compatibility zone services, both network map and registration (doorman), are not running on the same endpoint and thus have different URLs then this option should be used in place of the ``compatibilityZoneURL`` setting. - *Important:* Only one of ``compatibilityZoneURL`` or ``networkServices`` should be used. + **Important: Only one of ``compatibilityZoneURL`` or ``networkServices`` should be used.** doormanURL Root address of the network registration service. @@ -375,18 +375,18 @@ 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. - *Important:* Deprecated. Use rpcSettings instead. + **Important: Deprecated. Use rpcSettings instead.** *Default:* not defined rpcSettings Options for the RPC server exposed by the Node. - *Important:* The RPC SSL certificate is used by RPC clients to authenticate the connection. + **Important: The RPC SSL certificate is used by RPC clients to authenticate the connection. The Node operator must provide RPC clients with a truststore containing the certificate they can trust. We advise Node operators to not use the P2P keystore for RPC. The node can be run with the "generate-rpc-ssl-settings" command, which generates a secure keystore and truststore that can be used to secure the RPC connection. - You can use this if you have no special requirements. + You can use this if you have no special requirements.** address host and port for the RPC server binding. @@ -472,7 +472,7 @@ tlsCertCrlDistPoint CRL distribution point (i.e. URL) for the TLS certificate. Default value is NULL, which indicates no CRL availability for the TLS certificate. - *Important:* This needs to be set if crlCheckSoftFail is false (i.e. strict CRL checking is on). + **Important: This needs to be set if crlCheckSoftFail is false (i.e. strict CRL checking is on).** *Default:* NULL @@ -481,7 +481,7 @@ tlsCertCrlIssuer CRL issuer (given in the X500 name format) for the TLS certificate. Default value is NULL, which indicates that the issuer of the TLS certificate is also the issuer of the CRL. - *Important:* If this parameter is set then `tlsCertCrlDistPoint` needs to be set as well. + **Important: If this parameter is set then `tlsCertCrlDistPoint` needs to be set as well.** *Default:* NULL @@ -496,7 +496,7 @@ trustStorePassword useTestClock Internal option. - *Important:* Please do not change. + **Important: Please do not change.** *Default:* false @@ -504,7 +504,7 @@ useTestClock verfierType Internal option. - *Important:* Please do not change. + **Important: Please do not change.** *Default:* InMemory From 819405bd74dea31d0c7b4f70d5660e240cefd644 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Thu, 10 Jan 2019 15:49:06 +0000 Subject: [PATCH 14/21] Fix one important block --- docs/source/corda-configuration-file.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index 598598fbb5..cc5093f2a1 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -382,11 +382,7 @@ rpcAddress rpcSettings Options for the RPC server exposed by the Node. - **Important: The RPC SSL certificate is used by RPC clients to authenticate the connection. - The Node operator must provide RPC clients with a truststore containing the certificate they can trust. - We advise Node operators to not use the P2P keystore for RPC. - The node can be run with the "generate-rpc-ssl-settings" command, which generates a secure keystore and truststore that can be used to secure the RPC connection. - You can use this if you have no special requirements.** + **Important: The RPC SSL certificate is used by RPC clients to authenticate the connection. The Node operator must provide RPC clients with a truststore containing the certificate they can trust. We advise Node operators to not use the P2P keystore for RPC. The node can be run with the "generate-rpc-ssl-settings" command, which generates a secure keystore and truststore that can be used to secure the RPC connection. You can use this if you have no special requirements.** address host and port for the RPC server binding. From d4178eeccac5a351e238d43f8b7d69d20ddfdbe8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Fri, 11 Jan 2019 16:06:09 +0000 Subject: [PATCH 15/21] Adjust titles in docker - capitalization should be better --- docs/source/docker-image.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/docker-image.rst b/docs/source/docker-image.rst index cce9a875af..88dd96863b 100644 --- a/docs/source/docker-image.rst +++ b/docs/source/docker-image.rst @@ -1,7 +1,7 @@ Official Corda Docker Image =========================== -Running a Node connected to a Compatibility Zone in Docker +Running a node connected to a Compatibility Zone in Docker ---------------------------------------------------------- .. note:: Requirements: A valid node.conf and a valid set of certificates - (signed by the CZ) @@ -33,7 +33,7 @@ If using the H2 database 5. Persistence - the folder to hold the H2 database files must be mounted at location ``/opt/corda/persistence`` -Running a Node connected to a Bootstrapped Network +Running a node connected to a Bootstrapped Network -------------------------------------------------- .. note:: Requirements: A valid node.conf, a valid set of certificates, and an existing network-parameters file @@ -61,7 +61,7 @@ There is a new mount ``/home/user/sharedFolder/node-infos:/opt/corda/additional- As the node within the container starts up, it will place it's own nodeInfo into this directory. This will allow other nodes also using this folder to see this new node. -Generating Configs and Certificates +Generating configs and certificates ----------------------------------- It is possible to utilize the image to automatically generate a sensible minimal configuration for joining an existing Corda network. @@ -107,7 +107,7 @@ It is now possible to start the node using the generated config and certificates corda/corda-4.0-snapshot:latest -Joining An Existing Compatibility Zone +Joining an existing Compatibility Zone -------------------------------------- .. note:: Requirements: A Compatibility Zone, the Zone Trust Root and authorisation to join said Zone. From b4b1d7d020c494bbac3a54921ca7dfe51349c979 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Mon, 14 Jan 2019 09:56:13 +0000 Subject: [PATCH 16/21] Move CRL to Corda Network - not sure if that the best place. CRL is is Corda Network specific, but current text sound the Corda Network specific. --- docs/source/corda-network/index.md | 21 +++++++++++++++++++++ docs/source/node-administration.rst | 19 ------------------- 2 files changed, 21 insertions(+), 19 deletions(-) diff --git a/docs/source/corda-network/index.md b/docs/source/corda-network/index.md index beee40efd5..e8621d03c7 100644 --- a/docs/source/corda-network/index.md +++ b/docs/source/corda-network/index.md @@ -57,3 +57,24 @@ Support ------- The Support Service is provided to Participants and Business Network Operators to manage / resolve inquiries and incidents relating to the Doorman, Network Map Service and Notary Service, and any other relevant services. + +CRL configuration +----------------- +The Corda Network provides an endpoint serving an empty certificate revocation list for the TLS-level certificates. +This is intended for deployments that do not provide a CRL infrastructure but still require a strict CRL mode checking. +In such a case use the following URL in `tlsCertCrlDistPoint` option configuration: + + .. sourcecode:: kotlin + + "https://crl.cordaconnect.org/cordatls.crl" + +Together with the above configuration `tlsCertCrlIssuer` option needs to be set to the following value: + + .. sourcecode:: kotlin + + "C=US, L=New York, O=R3 HoldCo LLC, OU=Corda, CN=Corda Root CA" + +This set-up ensures that the TLS-level certificates are embedded with the CRL distribution point referencing the CRL issued by R3. +In cases where a proprietary CRL infrastructure is provided those values need to be changed accordingly. + + diff --git a/docs/source/node-administration.rst b/docs/source/node-administration.rst index 36aebd4615..2bcf295dce 100644 --- a/docs/source/node-administration.rst +++ b/docs/source/node-administration.rst @@ -1,25 +1,6 @@ Node administration =================== -CRL configuration ------------------ -The Corda Network provides an endpoint serving an empty certificate revocation list for the TLS-level certificates. -This is intended for deployments that do not provide a CRL infrastructure but still require a strict CRL mode checking. -In such a case use the following URL in `tlsCertCrlDistPoint` option configuration: - - .. sourcecode:: kotlin - - "https://crl.cordaconnect.org/cordatls.crl" - -Together with the above configuration `tlsCertCrlIssuer` option needs to be set to the following value: - - .. sourcecode:: kotlin - - "C=US, L=New York, O=R3 HoldCo LLC, OU=Corda, CN=Corda Root CA" - -This set-up ensures that the TLS-level certificates are embedded with the CRL distribution point referencing the CRL issued by R3. -In cases where a proprietary CRL infrastructure is provided those values need to be changed accordingly. - .. _hiding-sensitive-data: Hiding sensitive data From d55c527b3b6386e72cb2d5f8b2d1d80f22d62f41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Mon, 14 Jan 2019 10:07:51 +0000 Subject: [PATCH 17/21] More fixes --- docs/source/corda-network/index.md | 13 ++-- docs/source/node-administration.rst | 97 +++++++++++++++-------------- docs/source/node-naming.rst | 4 +- 3 files changed, 55 insertions(+), 59 deletions(-) diff --git a/docs/source/corda-network/index.md b/docs/source/corda-network/index.md index e8621d03c7..cd7c94edfb 100644 --- a/docs/source/corda-network/index.md +++ b/docs/source/corda-network/index.md @@ -62,17 +62,12 @@ CRL configuration ----------------- The Corda Network provides an endpoint serving an empty certificate revocation list for the TLS-level certificates. This is intended for deployments that do not provide a CRL infrastructure but still require a strict CRL mode checking. -In such a case use the following URL in `tlsCertCrlDistPoint` option configuration: +In order to use this, add the following to your configuration file: - .. sourcecode:: kotlin + .. parsed-literal:: - "https://crl.cordaconnect.org/cordatls.crl" - -Together with the above configuration `tlsCertCrlIssuer` option needs to be set to the following value: - - .. sourcecode:: kotlin - - "C=US, L=New York, O=R3 HoldCo LLC, OU=Corda, CN=Corda Root CA" + tlsCertCrlDistPoint = "https://crl.cordaconnect.org/cordatls.crl" + tlsCertCrlIssuer = "C=US, L=New York, O=R3 HoldCo LLC, OU=Corda, CN=Corda Root CA" This set-up ensures that the TLS-level certificates are embedded with the CRL distribution point referencing the CRL issued by R3. In cases where a proprietary CRL infrastructure is provided those values need to be changed accordingly. diff --git a/docs/source/node-administration.rst b/docs/source/node-administration.rst index 2bcf295dce..392510e07e 100644 --- a/docs/source/node-administration.rst +++ b/docs/source/node-administration.rst @@ -3,54 +3,6 @@ Node administration .. _hiding-sensitive-data: -Hiding sensitive data ---------------------- -A frequent requirement is that configuration files must not expose passwords to unauthorised readers. By leveraging environment variables, it is possible to hide passwords and other similar fields. - -Take a simple node config that wishes to protect the node cryptographic stores: - -.. parsed-literal:: - - myLegalName : "O=PasswordProtectedNode,OU=corda,L=London,C=GB" - keyStorePassword : ${KEY_PASS} - trustStorePassword : ${TRUST_PASS} - p2pAddress : "localhost:12345" - devMode : false - networkServices { - doormanURL = "https://cz.example.com" - networkMapURL = "https://cz.example.com" - } - -By delegating to a password store, and using `command substitution` it is possible to ensure that sensitive passwords never appear in plain text. -The below examples are of loading Corda with the KEY_PASS and TRUST_PASS variables read from a program named ``corporatePasswordStore``. - - -Bash -~~~~ - -.. sourcecode:: shell - - KEY_PASS=$(corporatePasswordStore --cordaKeyStorePassword) TRUST_PASS=$(corporatePasswordStore --cordaTrustStorePassword) java -jar corda.jar - -.. warning:: If this approach is taken, the passwords will appear in the shell history. - - -Windows PowerShell -~~~~~~~~~~~~~~~~~~ - -.. sourcecode:: shell - - $env:KEY_PASS=$(corporatePasswordStore --cordaKeyStorePassword); $env:TRUST_PASS=$(corporatePasswordStore --cordaTrustStorePassword); java -jar corda.jar - - -For launching on Windows without PowerShell, it is not possible to perform command substitution, and so the variables must be specified manually, for example: - -.. sourcecode:: shell - - SET KEY_PASS=mypassword & SET TRUST_PASS=mypassword & java -jar corda.jar - -.. warning:: If this approach is taken, the passwords will appear in the windows command prompt history. - Logging ------- @@ -202,6 +154,55 @@ The example command above would give a 1 gigabyte Java heap. .. note:: Unfortunately the JVM does not let you limit the total memory usage of Java program, just the heap size. +Hiding sensitive data +--------------------- +A frequent requirement is that configuration files must not expose passwords to unauthorised readers. By leveraging environment variables, it is possible to hide passwords and other similar fields. + +Take a simple node config that wishes to protect the node cryptographic stores: + +.. parsed-literal:: + + myLegalName = "O=PasswordProtectedNode,OU=corda,L=London,C=GB" + keyStorePassword = ${KEY_PASS} + trustStorePassword = ${TRUST_PASS} + p2pAddress = "localhost:12345" + devMode = false + networkServices { + doormanURL = "https://cz.example.com" + networkMapURL = "https://cz.example.com" + } + +By delegating to a password store, and using `command substitution` it is possible to ensure that sensitive passwords never appear in plain text. +The below examples are of loading Corda with the KEY_PASS and TRUST_PASS variables read from a program named ``corporatePasswordStore``. + + +Bash +~~~~ + +.. sourcecode:: shell + + KEY_PASS=$(corporatePasswordStore --cordaKeyStorePassword) TRUST_PASS=$(corporatePasswordStore --cordaTrustStorePassword) java -jar corda.jar + +.. warning:: If this approach is taken, the passwords will appear in the shell history. + + +Windows PowerShell +~~~~~~~~~~~~~~~~~~ + +.. sourcecode:: shell + + $env:KEY_PASS=$(corporatePasswordStore --cordaKeyStorePassword); $env:TRUST_PASS=$(corporatePasswordStore --cordaTrustStorePassword); java -jar corda.jar + + +For launching on Windows without PowerShell, it is not possible to perform command substitution, and so the variables must be specified manually, for example: + +.. sourcecode:: shell + + SET KEY_PASS=mypassword & SET TRUST_PASS=mypassword & java -jar corda.jar + +.. warning:: If this approach is taken, the passwords will appear in the windows command prompt history. + + Backup recommendations ---------------------- diff --git a/docs/source/node-naming.rst b/docs/source/node-naming.rst index fc3d15bf4e..a25522b86a 100644 --- a/docs/source/node-naming.rst +++ b/docs/source/node-naming.rst @@ -1,7 +1,7 @@ .. _node-naming: -Node naming -=========== +Node identity +============= A node's name must be a valid X.500 distinguished name. In order to be compatible with other implementations (particularly TLS implementations), we constrain the allowed X.500 name attribute types to a subset of the minimum supported set for X.509 certificates (specified in RFC 3280), plus the locality attribute: From a2d4df19187581e749b894732067866b19312e28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Mon, 14 Jan 2019 10:55:39 +0000 Subject: [PATCH 18/21] Another file adjusted --- docs/source/corda-network/index.md | 4 ++-- docs/source/node-structure.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/corda-network/index.md b/docs/source/corda-network/index.md index cd7c94edfb..d020d9099f 100644 --- a/docs/source/corda-network/index.md +++ b/docs/source/corda-network/index.md @@ -60,8 +60,8 @@ relating to the Doorman, Network Map Service and Notary Service, and any other r CRL configuration ----------------- -The Corda Network provides an endpoint serving an empty certificate revocation list for the TLS-level certificates. -This is intended for deployments that do not provide a CRL infrastructure but still require a strict CRL mode checking. +The Corda Network provides an endpoint serving an empty certificate revocation list for TLS-level certificates. +This is intended for deployments that do not provide a CRL infrastructure but still require strict CRL mode checking. In order to use this, add the following to your configuration file: .. parsed-literal:: diff --git a/docs/source/node-structure.rst b/docs/source/node-structure.rst index 235d6573a6..d44f9c89dd 100644 --- a/docs/source/node-structure.rst +++ b/docs/source/node-structure.rst @@ -1,7 +1,7 @@ Node folder structure ===================== -A folder with Corda node files has the following structure: +A folder containing a Corda node files has the following structure: .. sourcecode:: none @@ -11,7 +11,7 @@ A folder with Corda node files has the following structure: ├── brokers // Stores buffered RPC messages ├── certificates // The node's certificates ├── corda-webserver.jar // The built-in node webserver (DEPRECATED) - ├── corda.jar // The core Corda libraries (JAR with actually Corda node) + ├── corda.jar // The core Corda libraries (This is the actual Corda node implementation) ├── cordapps // The CorDapp JARs installed on the node ├── drivers // Contains a Jolokia driver used to export JMX metrics, the node loads any additional JAR files from this directory at startup. ├── logs // The node's logs From 1b41c517fc645356648d95557ff994f87bf6198b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Mon, 14 Jan 2019 15:19:09 +0000 Subject: [PATCH 19/21] Apply further changes suggested in review --- docs/source/corda-configuration-file.rst | 61 +++++++++++++----------- 1 file changed, 32 insertions(+), 29 deletions(-) diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index cc5093f2a1..4b74f1026b 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -23,17 +23,16 @@ The Corda configuration file uses the HOCON format which is a superset of JSON. Please do NOT use double quotes (``"``) in configuration keys. -Node setup will log ``Config files should not contain \" in property names. Please fix: [key]`` as an error when it finds double quotes around keys. +Node setup will log ``Config files should not contain " in property names. Please fix: [key]`` as an error when it finds double quotes around keys. This prevents configuration errors when mixing keys containing ``.`` wrapped with double quotes and without them e.g.: The property ``"dataSourceProperties.dataSourceClassName" = "val"`` in *reference.conf* (see: Reference.conf_) would be not overwritten by the property ``dataSourceProperties.dataSourceClassName = "val2"`` in *node.conf*. By default the node will fail to start in presence of unknown property keys. -To alter this behaviour, program line argument ``on-unknown-config-keys`` can be set to ``IGNORE`` (default is ``FAIL``). +To alter this behaviour, the ``on-unknown-config-keys`` command-line argument can be set to ``IGNORE`` (default is ``FAIL``). -How to overwrite values from node.conf --------------------------------------- +Overriding values from node.conf +-------------------------------- -Enviroment variables - All fields can be used with placeholders for environment variables. +Environment variables For example: ``${NODE_TRUST_STORE_PASSWORD}`` would be replaced by the contents of environment variable ``NODE_TRUST_STORE_PASSWORD``. See: :ref:`hiding-sensitive-data` section in "Node administration" chapter. @@ -49,7 +48,7 @@ JVM options Configuration file fields ------------------------- -.. note :: The available config fields are listed below in alphabetic order. +.. note :: The available configuration fields are listed below in alphabetic order. additionalP2PAddresses An array of additional host:port values, which will be included in the advertised NodeInfo in the network map in addition to the ``p2pAddress``. @@ -68,27 +67,28 @@ attachmentCacheBound *Default:* 1024 -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. - Cannot be set at the same time as the ``networkServices`` option. - **Important: old config value, please use networkServices** +compatibilityZoneURL (deprecated) + The root address of the Corda compatibility zone network management services, it is used by the Corda node to register with the network and obtain a Corda node certificate, (See :doc:`permissioning` for more information.) and also is used by the node to obtain network map information. + Cannot be set at the same time as the :ref:`networkServices ` option. + + **Important: old configuration value, please use networkServices** *Default:* not defined .. _corda_configuration_file_signer_blacklist: cordappSignerKeyFingerprintBlacklist - List of public keys fingerprints (SHA-256 of public key hash) not allowed as Cordapp JARs signers. - Node will not load Cordapps signed by those keys. + List of the public keys fingerprints (SHA-256 of public key hash) not allowed as Cordapp JARs signers. + The node will not load Cordapps signed by those keys. The option takes effect only in production mode and defaults to Corda development keys (``["56CA54E803CB87C8472EBD3FBC6A2F1876E814CEEBF74860BD46997F40729367", "83088052AF16700457AE2C978A7D8AC38DD6A7C713539D00B897CD03A5E5D31D"]``), in development mode any key is allowed to sign Cordpapp JARs. *Default:* not defined crlCheckSoftFail - This is a boolean flag that when enabled (i.e. `true` value is set) the certificate revocation list (CRL) checking will use the soft fail mode. + This is a boolean flag that when enabled (i.e. ``true`` value is set) causes the certificate revocation list (CRL) checking will use the soft fail mode. The soft fail mode allows the revocation check to succeed if the revocation status cannot be determined because of a network error. - 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. + If this parameter is set to ``false`` rigorous CRL checking takes place, involving 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. *Default:* true @@ -112,21 +112,22 @@ database *Default:* ``REPEATABLE_READ`` exportHibernateJMXStatistics: - Whether to export Hibernate JMX statistics - *Caution:* expensive run-time overhead + Whether to export Hibernate JMX statistics. + + **Caution: enabling this option causes expensive run-time overhead** *Default:* false initialiseSchema - Boolean on whether to update database schema at startup (or create when node starts for the first time). - If set to ``false`` on startup, the node will validate if it's running against the compatible database schema. + Boolean which indicates whether to update the database schema at startup (or create the schema when node starts for the first time). + If set to ``false`` on startup, the node will validate if it's running against a compatible database schema. *Default:* true initialiseAppSchema - The property allows to override (downgrade) ``database.initialiseSchema`` for the Hibernate DDL generation for CorDapp schemas. + The property allows to override ``database.initialiseSchema`` for the Hibernate DDL generation for CorDapp schemas. ``UPDATE`` performs an update of CorDapp schemas, while ``VALID`` only verifies their integrity and ``NONE`` performs no check. - When ``initialiseSchema`` is set to false then ``initialiseAppSchema`` may be set as ``VALID`` or ``NONE`` only. + When ``initialiseSchema`` is set to ``false``, then ``initialiseAppSchema`` may be set as ``VALID`` or ``NONE`` only. *Default:* CorDapp schemas creation is controlled with ``initialiseSchema``. @@ -137,7 +138,7 @@ dataSourceProperties *Default:* - .. sourcecode:: kotlin + .. parsed-literal:: dataSourceClassName = org.h2.jdbcx.JdbcDataSource dataSource.url = "jdbc:h2:file:"${baseDirectory}"/persistence;DB_CLOSE_ON_EXIT=FALSE;WRITE_DELAY=0;LOCK_TIMEOUT=10000" @@ -158,7 +159,7 @@ devMode 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. Also, if ``devMode`` is true, Hibernate will try to automatically create the schema required by Corda or update an existing schema in the SQL database; if ``devMode`` is false, Hibernate will simply validate the existing schema, failing on node start if the schema is either not present or not compatible. - If no value is specified in the node config file, the node will attempt to detect if it's running on a developer machine and set ``devMode=true`` in that case. + If no value is specified in the node configuration file, the node will attempt to detect if it's running on a developer machine and set ``devMode=true`` in that case. This value can be overridden from the command line using the ``--dev-mode`` option. *Default:* Corda will try to establish based on OS environment @@ -175,7 +176,7 @@ devModeOptions emailAddress - email address responsible for node administration, used by Compatibility Zone administrator. + The email address responsible for node administration, used by the Compatibility Zone administrator. *Default:* company@example.com @@ -183,7 +184,7 @@ extraNetworkMapKeys An optional list of private network map UUIDs. Your node will fetch the public network and private network maps based on these keys. Private network UUID should be provided by network operator and lets you see nodes not visible on public network. - **Important: This is temporary feature for onboarding network participants that limits their visibility for privacy reasons.** + **Important: This is a temporary feature for onboarding network participants that limits their visibility for privacy reasons.** *Default:* not defined @@ -229,7 +230,7 @@ h2Settings See :doc:`node-database-access-h2`. For non-localhost address the database password needs to be set in ``dataSourceProperties``. - *Default:* ??? + *Default:* NULL jarDirs An optional list of file system directories containing JARs to include in the classpath when launching via ``corda.jar`` only. @@ -244,7 +245,7 @@ jmxMonitoringHttpPort If set, will enable JMX metrics reporting via the Jolokia HTTP/JSON agent on the corresponding port. Default Jolokia access url is http://127.0.0.1:port/jolokia/ - *Default:* not defined + *Default:* not defined jmxReporterType Provides an option for registering an alternative JMX reporter. @@ -339,6 +340,8 @@ networkParameterAcceptanceSettings *Default:* empty list +.. _corda_configuratation_file_networkServices: + networkServices If the Corda compatibility zone services, both network map and registration (doorman), are not running on the same endpoint and thus have different URLs then this option should be used in place of the ``compatibilityZoneURL`` setting. @@ -402,7 +405,7 @@ rpcSettings useSsl boolean, indicates whether or not the node should require clients to use SSL for RPC connections. - *Default:* ``false`` + *Default:* false ssl (mandatory if ``useSsl=true``) SSL settings for the RPC server. @@ -419,7 +422,7 @@ rpcSettings 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: + Each user in the list is a configuration object with the following fields: username Username consisting only of word characters (a-z, A-Z, 0-9 and _) From 75ebc2b26ede43bd7668a7e555c89f5b7fb34550 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Mon, 14 Jan 2019 15:28:36 +0000 Subject: [PATCH 20/21] Address few more comments --- docs/source/corda-configuration-file.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index 4b74f1026b..3053f2652f 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -24,7 +24,7 @@ The Corda configuration file uses the HOCON format which is a superset of JSON. Please do NOT use double quotes (``"``) in configuration keys. Node setup will log ``Config files should not contain " in property names. Please fix: [key]`` as an error when it finds double quotes around keys. -This prevents configuration errors when mixing keys containing ``.`` wrapped with double quotes and without them e.g.: The property ``"dataSourceProperties.dataSourceClassName" = "val"`` in *reference.conf* (see: Reference.conf_) would be not overwritten by the property ``dataSourceProperties.dataSourceClassName = "val2"`` in *node.conf*. +This prevents configuration errors when mixing keys containing ``.`` wrapped with double quotes and without them e.g.: The property ``"dataSourceProperties.dataSourceClassName" = "val"`` in :ref:`reference.conf` would be not overwritten by the property ``dataSourceProperties.dataSourceClassName = "val2"`` in *node.conf*. By default the node will fail to start in presence of unknown property keys. To alter this behaviour, the ``on-unknown-config-keys`` command-line argument can be set to ``IGNORE`` (default is ``FAIL``). @@ -33,8 +33,7 @@ Overriding values from node.conf -------------------------------- Environment variables - For example: ``${NODE_TRUST_STORE_PASSWORD}`` would be replaced by the contents of environment variable ``NODE_TRUST_STORE_PASSWORD``. - See: :ref:`hiding-sensitive-data` section in "Node administration" chapter. + For example: ``${NODE_TRUST_STORE_PASSWORD}`` would be replaced by the contents of environment variable ``NODE_TRUST_STORE_PASSWORD`` (see: :ref:`hiding-sensitive-data` section). JVM options JVM options or environmental variables prefixed with ``corda.`` can override ``node.conf`` fields. @@ -129,7 +128,7 @@ database ``UPDATE`` performs an update of CorDapp schemas, while ``VALID`` only verifies their integrity and ``NONE`` performs no check. When ``initialiseSchema`` is set to ``false``, then ``initialiseAppSchema`` may be set as ``VALID`` or ``NONE`` only. - *Default:* CorDapp schemas creation is controlled with ``initialiseSchema``. + *Default:* CorDapp schema creation is controlled with ``initialiseSchema``. dataSourceProperties This section is used to configure the jdbc connection and database driver used for the nodes persistence. @@ -220,7 +219,7 @@ flowTimeout *Default:* 1.8 -h2Port +h2Port (deprecated) Defines port for h2 DB. **Important: Deprecated please use h2Setting instead** @@ -374,7 +373,7 @@ p2pAddress *Default:* not defined -rpcAddress +rpcAddress (deprecated) 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. From 27d29c731f1415781c5a1a13ffdb9dc5c0cc25cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wawrzyniec=20Niewodnicza=C5=84ski?= Date: Mon, 14 Jan 2019 16:12:51 +0000 Subject: [PATCH 21/21] More internal links --- docs/source/corda-configuration-file.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index 3053f2652f..4215b0dd67 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -50,7 +50,7 @@ Configuration file fields .. note :: The available configuration fields are listed below in alphabetic order. additionalP2PAddresses - An array of additional host:port values, which will be included in the advertised NodeInfo in the network map in addition to the ``p2pAddress``. + An array of additional host:port values, which will be included in the advertised NodeInfo in the network map in addition to the :ref:`p2pAddress `. Nodes can use this configuration option to advertise HA endpoints and aliases to external parties. *Default:* empty list @@ -339,7 +339,7 @@ networkParameterAcceptanceSettings *Default:* empty list -.. _corda_configuratation_file_networkServices: +.. _corda_configuration_file_networkServices: networkServices If the Corda compatibility zone services, both network map and registration (doorman), are not running on the same endpoint @@ -362,6 +362,7 @@ networkServices *Default:* not defined +.. _corda_configuration_file_p2pAddress: p2pAddress The host and port on which the node is available for protocol operations over ArtemisMQ.