diff --git a/.idea/compiler.xml b/.idea/compiler.xml index e1cb19e8be..fbd48220f1 100644 --- a/.idea/compiler.xml +++ b/.idea/compiler.xml @@ -79,6 +79,9 @@ + + + diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index 0e3efe6629..3a2c462a42 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -134,7 +134,7 @@ absolute path to the node's base directory. :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. + checks whether this name matches the name of the certificate of the notary cluster. :raft: If part of a distributed Raft cluster specify this config object, with the following settings: diff --git a/docs/source/network-bootstrapper.rst b/docs/source/network-bootstrapper.rst index e0c3900927..5d28f87d1d 100644 --- a/docs/source/network-bootstrapper.rst +++ b/docs/source/network-bootstrapper.rst @@ -45,8 +45,6 @@ will generate directories containing three nodes: ``notary``, ``partya`` and ``p that comes with the bootstrapper. If a different version of Corda is required then simply place that ``corda.jar`` file alongside the configuration files in the directory. -The directory can also contain CorDapp JARs which will be copied to each node's ``cordapps`` directory. - You can also have the node directories containing their "node.conf" files already laid out. The previous example would be: .. sourcecode:: none @@ -61,33 +59,34 @@ You can also have the node directories containing their "node.conf" files alread Similarly, each node directory may contain its own ``corda.jar``, which the bootstrapper will use instead. -Synchronisation -~~~~~~~~~~~~~~~ +Providing CorDapps to the Network Bootstrapper +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This tool only bootstraps a network. It cannot dynamically update if a new node needs to join the network or if an existing -one has changed something in their node-info, e.g. their P2P address. For this the new node-info file will need to be placed -in the other nodes' ``additional-node-infos`` directory. A simple way to do this is to use `rsync `_. -However, if it's known beforehand the set of nodes that will eventually form part of the network then all the node directories -can be pregenerated in the bootstrap and only started when needed. +If you would like the Network Bootstrapper to include your CorDapps in each generated node, just place them in the directory +alongside the config files. For example, if your directory has this structure: -Running the bootstrapper again on the same network will allow a new node to be added or an existing one to have its updated -node-info re-distributed. However this comes at the expense of having to temporarily collect the node directories back -together again under a common parent directory. +.. sourcecode:: none + + . + ├── notary_node.conf // The notary's node.conf file + ├── partya_node.conf // Party A's node.conf file + ├── partyb_node.conf // Party B's node.conf file + ├── cordapp-a.jar // A cordapp to be installed on all nodes + └── cordapp-b.jar // Another cordapp to be installed on all nodes + +The ``cordapp-a.jar`` and ``cordapp-b.jar`` will be installed in each node directory, and any contracts within them will be +added to the Contract Whitelist (see below). Whitelisting contracts -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- -The CorDapp JARs are also automatically used to create the *Zone whitelist* (see :doc:`api-contract-constraints`) for -the network. +Any CorDapps provided when bootstrapping a network will be scanned for contracts which will be used to create the +*Zone whitelist* (see :doc:`api-contract-constraints`) for the network. .. note:: If you only wish to whitelist the CorDapps but not copy them to each node then run with the ``--no-copy`` flag. The CorDapp JARs will be hashed and scanned for ``Contract`` classes. These contract class implementations will become part of the whitelisted contracts in the network parameters (see ``NetworkParameters.whitelistedContractImplementations`` :doc:`network-map`). -If the network already has a set of network parameters defined (i.e. the node directories all contain the same network-parameters -file) then the new set of contracts will be appended to the current whitelist. - -.. note:: The whitelist can only ever be appended to. Once added a contract implementation can never be removed. By default the bootstrapper will whitelist all the contracts found in all the CorDapp JARs. To prevent certain contracts from being whitelisted, add their fully qualified class name in the ``exclude_whitelist.txt``. These will instead @@ -99,3 +98,151 @@ For example: net.corda.finance.contracts.asset.Cash net.corda.finance.contracts.asset.CommercialPaper + +Modifying a bootstrapped network +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The network bootstrapper is provided as a development tool for setting up Corda networks for development and testing. +There is some limited functionality which can be used to make changes to a network, but for anything more complicated consider +using a :doc:`network-map` server. + +When running the Network Bootstrapper, each ``node-info`` file needs to be gathered together in one directory. If +the nodes are being run on different machines you need to do the following: + +* Copy the node directories from each machine into one directory, on one machine +* Depending on the modification being made (see below for more information), add any new files required to the root directory +* Run the Network Bootstrapper from the root directory +* Copy each individual node's directory back to the original machine + +The network bootstrapper cannot dynamically update the network if an existing node has changed something in their node-info, +e.g. their P2P address. For this the new node-info file will need to be placed in the other nodes' ``additional-node-infos`` directory. +If the nodes are located on different machines, then a utility such as `rsync `_ can be used +so that the nodes can share node-infos. + +Adding a new node to the network +-------------------------------- + +Running the bootstrapper again on the same network will allow a new node to be added and its +node-info distributed to the existing nodes. + +As an example, if we have an existing bootstrapped network, with a Notary and PartyA and we want to add a PartyB, we +can use the network bootstrapper on the following network structure: + +.. sourcecode:: none + + . + ├── notary // existing node directories + │   ├── node.conf + │ ├── network-parameters + │ ├── node-info-notary + │ └── additional-node-infos + │ ├── node-info-notary + │ └── node-info-partya + ├── partya + │   ├── node.conf + │ ├── network-parameters + │ ├── node-info-partya + │ └── additional-node-infos + │ ├── node-info-notary + │ └── node-info-partya + └── partyb_node.conf // the node.conf for the node to be added + +Then run the network bootstrapper again from the root dir: + +``java -jar network-bootstrapper-VERSION.jar --dir `` + +Which will give the following: + +.. sourcecode:: none + + . + ├── notary // the contents of the existing nodes (keys, db's etc...) are unchanged + │   ├── node.conf + │ ├── network-parameters + │ ├── node-info-notary + │ └── additional-node-infos + │ ├── node-info-notary + │ ├── node-info-partya + │ └── node-info-partyb + ├── partya + │   ├── node.conf + │ ├── network-parameters + │ ├── node-info-partya + │ └── additional-node-infos + │ ├── node-info-notary + │ ├── node-info-partya + │ └── node-info-partyb + └── partyb // a new node directory is created for PartyB +    ├── node.conf + ├── network-parameters + ├── node-info-partyb + └── additional-node-infos + ├── node-info-notary + ├── node-info-partya + └── node-info-partyb + +The bootstrapper will generate a directory and the ``node-info`` file for PartyB, and will also make sure a copy of each +nodes' ``node-info`` file is in the ``additional-node-info`` directory of every node. Any other files in the existing nodes, +such a generated keys, will be unaffected. + +.. note:: The bootstrapper is provided for test deployments and can only generate information for nodes collected on + the same machine. If a network needs to be updated using the bootstrapper once deployed, the nodes will need + collecting back together. + +Updating the contract whitelist for bootstrapped networks +--------------------------------------------------------- + +If the network already has a set of network parameters defined (i.e. the node directories all contain the same network-parameters +file) then the bootstrapper can be used to append contracts from new CorDapps to the current whitelist. +For example, with the following pre-generated network: + +.. sourcecode:: none + + . + ├── notary + │   ├── node.conf + │ ├── network-parameters + │ └── cordapps + │ └── cordapp-a.jar + ├── partya + │   ├── node.conf + │ ├── network-parameters + │ └── cordapps + │ └── cordapp-a.jar + ├── partyb + │   ├── node.conf + │ ├── network-parameters + │ └── cordapps + │ └── cordapp-a.jar + └── cordapp-b.jar // The new cordapp to add to the existing nodes + +Then run the network bootstrapper again from the root dir: + +``java -jar network-bootstrapper-VERSION.jar --dir `` + +To give the following: + +.. sourcecode:: none + + . + ├── notary + │   ├── node.conf + │ ├── network-parameters // The contracts from cordapp-b are appended to the whitelist in network-parameters + │ └── cordapps + │ ├── cordapp-a.jar + │ └── cordapp-b.jar // The updated cordapp is placed in the nodes cordapp directory + ├── partya + │   ├── node.conf + │ ├── network-parameters // The contracts from cordapp-b are appended to the whitelist in network-parameters + │ └── cordapps + │ ├── cordapp-a.jar + │ └── cordapp-b.jar // The updated cordapp is placed in the nodes cordapp directory + └── partyb +    ├── node.conf + ├── network-parameters // The contracts from cordapp-b are appended to the whitelist in network-parameters + └── cordapps + ├── cordapp-a.jar + └── cordapp-b.jar // The updated cordapp is placed in the nodes cordapp directory + +.. note:: The whitelist can only ever be appended to. Once added a contract implementation can never be removed. +