mirror of
https://github.com/corda/corda.git
synced 2024-12-19 21:17:58 +00:00
CORDA-1712 - Make documentation clearer for Network Bootstrapper (#3504)
This commit is contained in:
Anthony Keenan
Michele Sollecito
parent
d481c55b82
commit
857ed1897a
3
.idea/compiler.xml
generated
3
.idea/compiler.xml
generated
@ -79,6 +79,9 @@
|
||||
<module name="example-code_integrationTest" target="1.8" />
|
||||
<module name="example-code_main" target="1.8" />
|
||||
<module name="example-code_test" target="1.8" />
|
||||
<module name="experimental-behave_behave" target="1.8" />
|
||||
<module name="experimental-behave_main" target="1.8" />
|
||||
<module name="experimental-behave_test" target="1.8" />
|
||||
<module name="experimental-kryo-hook_main" target="1.8" />
|
||||
<module name="experimental-kryo-hook_test" target="1.8" />
|
||||
<module name="experimental_main" target="1.8" />
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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 <https://en.wikipedia.org/wiki/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 <https://en.wikipedia.org/wiki/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 <nodes-root-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 <nodes-root-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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user