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

Node configuration

File location

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

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

Format

The Corda configuration file uses the HOCON format which is superset of JSON. It has several features which makes it very useful as a configuration format. Please visit their page for further details.

Examples

General node configuration file for hosting the IRSDemo services.

example-code/src/main/resources/example-node.conf

Simple Notary configuration file.

myLegalName : "O=Notary Service,OU=corda,L=London,C=GB" keyStorePassword : "cordacadevpass" trustStorePassword : "trustpass" p2pAddress : "localhost:12345" rpcAddress : "localhost:12346" webAddress : "localhost:12347" notary : { validating : false } useHTTPS : false devMode : true // Certificate signing service will be hosted by R3 in the near future. //certificateSigningService : "https://testnet.certificate.corda.net"

Fields

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

myLegalName

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

keyStorePassword

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

Note

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

trustStorePassword

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

Note

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

dataSourceProperties

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

messagingServerAddress

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

p2pAddress

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

Note

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

rpcAddress

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

webAddress

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

Note

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

Note

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

notary

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

validating

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

raft

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

nodeAddress

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

clusterAddresses

List of Raft cluster member addresses used to join the cluster. At least one of the specified

members must be active and be able to communicate with the cluster leader for joining. If empty, a new cluster will be bootstrapped.

bftSMaRt

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

replicaId

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

clusterAddresses

List of all BFT-SMaRt cluster member addresses.

custom

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

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

networkMapService

If null, or missing the node is declaring itself as the NetworkMapService host. Otherwise this is a config object with the details of the network map service:

address

Host and port string of the ArtemisMQ broker hosting the network map node

legalName

Legal name of the node. This is required as part of the TLS host verification process. The node will reject the connection to the network map service if it provides a TLS common name which doesn't match with this value.

minimumPlatformVersion

Used by the node if it's running the network map service to enforce a minimum version requirement on registrations - any node on a Platform Version lower than this value will have their registration rejected. Defaults to 1 if absent.

useHTTPS

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

rpcUsers

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

username

Username consisting only of word characters (a-z, A-Z, 0-9 and _)

password

The password

permissions

A list of permission strings which RPC methods can use to control access

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

devMode

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

detectPublicIp

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

certificateSigningService

Certificate Signing Server address. It is used by the certificate signing request utility to obtain SSL certificate. (See permissioning for more information.)

jvmArgs

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

systemProperties

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

jarDirs

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

relay

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

relayHost

Hostname of the relay machine

remoteInboundPort

A port on the relay machine that accepts incoming TCP connections. Traffic will be forwarded from this port to the local port specified in p2pAddress.

username

Username for establishing a SSH connection with the relay.

privateKeyFile

Path to the private key file for SSH authentication. The private key must not have a passphrase.

publicKeyFile

Path to the public key file for SSH authentication.

sshPort

Port to be used for SSH connection, default 22.