diff --git a/docs/source/network-bootstrapper.rst b/docs/source/network-bootstrapper.rst new file mode 100644 index 0000000000..9b8343b43b --- /dev/null +++ b/docs/source/network-bootstrapper.rst @@ -0,0 +1,246 @@ +Network Bootstrapper +==================== + +Test deployments +~~~~~~~~~~~~~~~~ + +Nodes within a network see each other using the network map. This is a collection of statically signed node-info files, +one for each node. Most production deployments will use a highly available, secure distribution of the network map via HTTP. + +For test deployments where the nodes (at least initially) reside on the same filesystem, these node-info files can be +placed directly in the node's ``additional-node-infos`` directory from where the node will pick them up and store them +in its local network map cache. The node generates its own node-info file on startup. + +In addition to the network map, all the nodes must also use the same set of network parameters. These are a set of constants +which guarantee interoperability between the nodes. The HTTP network map distributes the network parameters which are downloaded +automatically by the nodes. In the absence of this the network parameters must be generated locally. + +For these reasons, test deployments can avail themselves of the network bootstrapper. This is a tool that scans all the +node configurations from a common directory to generate the network parameters file, which is then copied to all the nodes' +directories. It also copies each node's node-info file to every other node so that they can all be visible to each other. + +You can find out more about network maps and network parameters from :doc:`network-map`. + +Bootstrapping a test network +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Corda Network Bootstrapper can be downloaded from `here `_. + +Create a directory containing a node config file, ending in "_node.conf", for each node you want to create. Then run the +following command: + +``java -jar network-bootstrapper-VERSION.jar --dir `` + +For example running the command on a directory containing these files: + +.. 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 + +will generate directories containing three nodes: ``notary``, ``partya`` and ``partyb``. They will each use the ``corda.jar`` +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. + +You can also have the node directories containing their "node.conf" files already laid out. The previous example would be: + +.. sourcecode:: none + + . + ├── notary + │ └── node.conf + ├── partya + │ └── node.conf + └── partyb + └── node.conf + +Similarly, each node directory may contain its own ``corda.jar``, which the bootstrapper will use instead. + +Providing CorDapps to the Network Bootstrapper +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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: + +.. 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 +---------------------- + +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`). + +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 +use the more restrictive ``HashAttachmentConstraint``. + +For example: + +.. sourcecode:: none + + 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. \ No newline at end of file diff --git a/docs/source/setting-up-a-corda-network.rst b/docs/source/setting-up-a-corda-network.rst index 5705e23063..89621ce23c 100644 --- a/docs/source/setting-up-a-corda-network.rst +++ b/docs/source/setting-up-a-corda-network.rst @@ -44,96 +44,14 @@ The most important fields regarding network configuration are: * ``rpcAddress``: The address to which Artemis will bind for RPC calls. * ``webAddress``: The address the webserver should bind. Note that the port must be distinct from that of ``p2pAddress`` and ``rpcAddress`` if they are on the same machine. -Bootstrapping the network -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The nodes see each other using the network map. This is a collection of statically signed node-info files, one for each -node in the network. Most production deployments will use a highly available, secure distribution of the network map via HTTP. - -For test deployments where the nodes (at least initially) reside on the same filesystem, these node-info files can be -placed directly in the node's ``additional-node-infos`` directory from where the node will pick them up and store them -in its local network map cache. The node generates its own node-info file on startup. - -In addition to the network map, all the nodes on a network must use the same set of network parameters. These are a set -of constants which guarantee interoperability between nodes. The HTTP network map distributes the network parameters -which the node downloads automatically. In the absence of this the network parameters must be generated locally. This can -be done with the network bootstrapper. This is a tool that scans all the node configurations from a common directory to -generate the network parameters file which is copied to the nodes' directories. It also copies each node's node-info file -to every other node so that they can all transact with each other. - -The bootstrapper tool can be downloaded from http://downloads.corda.net/network-bootstrapper-corda-X.Y.jar, where ``X`` is the major Corda version and ``Y`` is the minor Corda version. - -To use it, create a directory containing a ``node.conf`` file for each node you want to create. Then run the following command: - -``java -jar network-bootstrapper.jar `` - -For example running the command on a directory containing these files : - -.. sourcecode:: none - - . - ├── notary.conf // The notary's node.conf file - ├── partya.conf // Party A's node.conf file - └── partyb.conf // Party B's node.conf file - -Would generate directories containing three nodes: notary, partya and partyb. - -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 the node folders can be pregenerated in the bootstrap -and only started when needed. - - -Whitelisting Contracts -~~~~~~~~~~~~~~~~~~~~~~ - -If you want to create a *Zone whitelist* (see :doc:`api-contract-constraints`), you can pass in a list of CorDapp jars: - -``java -jar network-bootstrapper.jar ..`` - -The CorDapp jars will be hashed and scanned for ``Contract`` classes. -By default the tool would generate a file named ``whitelist.txt`` containing an entry for each contract with the hash of the jar. - -For example: - -.. sourcecode:: none - - net.corda.finance.contracts.asset.Obligation:decd098666b9657314870e192ced0c3519c2c9d395507a238338f8d003929de8 - net.corda.finance.contracts.asset.Cash:decd098666b9657314870e192ced0c3519c2c9d395507a238338f8d003929de9 - -These will be added to the ``NetworkParameters.whitelistedContractImplementations``. See :doc:`network-map`. - -This means that by default the Network bootstrapper tool will whitelist all contracts found in all passed CorDapps. - -In case there is a ``whitelist.txt`` file in the root dir already, the tool will append the new jar hashes or contracts to it. - -The zone operator will maintain this whitelist file, and, using the tool, will append new versions of CorDapps to it. - -.. warning:: - - The zone operator must ensure that this file is *append only*. - - If the operator removes hashes from the list, all transactions pointing to that version will suddenly fail the constraint verification, and the entire chain is compromised. - - If a contract is removed from the whitelist, then all states created from that moment on will be constrained by the HashAttachmentConstraint. - - Note: In future releases, we will provider a tamper-proof way of maintaining the contract whitelist. - -For fine-grained control of constraints, in case multiple contracts live in the same jar, the tool reads from another file: -``exclude_whitelist.txt``, which contains a list of contracts that should not be whitelisted, and thus default to the very restrictive: -``HashAttachmentConstraint`` - -For example: - -.. sourcecode:: none - - net.corda.finance.contracts.asset.Cash - net.corda.finance.contracts.asset.CommercialPaper - - Starting the nodes ~~~~~~~~~~~~~~~~~~ -You may now start the nodes in any order. You should see a banner, some log lines and eventually ``Node started up and registered``, -indicating that the node is fully started. +You will first need to create the local network by bootstrapping it with the bootstrapper. Details of how to do that +can be found in :doc:`network-bootstrapper`. + +Once that's done you may now start the nodes in any order. You should see a banner, some log lines and eventually +``Node started up and registered``, indicating that the node is fully started. .. TODO: Add a better way of polling for startup. A programmatic way of determining whether a node is up is to check whether it's ``webAddress`` is bound. diff --git a/docs/source/tools-index.rst b/docs/source/tools-index.rst index 18d2fe908d..fbfe4cd680 100644 --- a/docs/source/tools-index.rst +++ b/docs/source/tools-index.rst @@ -5,6 +5,7 @@ Tools :maxdepth: 1 network-builder + network-bootstrapper blob-inspector network-simulator demobench