corda/docs/build/html/corda-configuration-files.html

387 lines
21 KiB
HTML
Raw Normal View History

2016-11-11 11:52:29 +00:00
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>The Corda Configuration File &mdash; R3 Corda latest documentation</title>
<link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
<link rel="top" title="R3 Corda latest documentation" href="index.html"/>
<link rel="next" title="Where to start" href="where-to-start.html"/>
<link rel="prev" title="Node administration" href="node-administration.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> R3 Corda
</a>
<div class="version">
latest
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<br>
<a href="api/index.html">API reference</a>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Overview</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="inthebox.html">What&#8217;s included?</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting-set-up.html">Getting set up</a></li>
<li class="toctree-l1"><a class="reference internal" href="data-model.html">Data model</a></li>
<li class="toctree-l1"><a class="reference internal" href="transaction-data-types.html">Data types</a></li>
<li class="toctree-l1"><a class="reference internal" href="merkle-trees.html">Transaction Tear-offs</a></li>
<li class="toctree-l1"><a class="reference internal" href="consensus.html">Consensus model</a></li>
<li class="toctree-l1"><a class="reference internal" href="messaging.html">Networking and messaging</a></li>
<li class="toctree-l1"><a class="reference internal" href="persistence.html">Persistence</a></li>
<li class="toctree-l1"><a class="reference internal" href="creating-a-cordapp.html">Creating a Cordapp</a></li>
<li class="toctree-l1"><a class="reference internal" href="creating-a-cordapp.html#gradle-plugins-for-cordapps">Gradle Plugins for Cordapps</a></li>
<li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a></li>
<li class="toctree-l1"><a class="reference internal" href="node-administration.html">Node administration</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">The Corda Configuration File</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#configuration-file-location">Configuration File Location</a></li>
<li class="toctree-l2"><a class="reference internal" href="#configuration-file-format">Configuration File Format</a></li>
<li class="toctree-l2"><a class="reference internal" href="#configuration-file-examples">Configuration File Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="#configuration-file-fields">Configuration File Fields</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#rpc-users-file">RPC Users File</a></li>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="where-to-start.html">Where to start</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-contract.html">Writing a contract</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-contract-clauses.html">Writing a contract using clauses</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-test-dsl.html">Writing a contract test</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-clientrpc-api.html">Client RPC API</a></li>
<li class="toctree-l1"><a class="reference internal" href="protocol-state-machines.html">Protocol state machines</a></li>
<li class="toctree-l1"><a class="reference internal" href="oracles.html">Writing oracle services</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-attachments.html">Using attachments</a></li>
<li class="toctree-l1"><a class="reference internal" href="event-scheduling.html">Event scheduling</a></li>
</ul>
<p class="caption"><span class="caption-text">Contracts</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="contract-catalogue.html">Contract catalogue</a></li>
<li class="toctree-l1"><a class="reference internal" href="contract-irs.html">Interest Rate Swaps</a></li>
<li class="toctree-l1"><a class="reference internal" href="initialmarginagreement.html">Initial Margin Agreements</a></li>
</ul>
<p class="caption"><span class="caption-text">Node API</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="clientrpc.html">Client RPC</a></li>
</ul>
<p class="caption"><span class="caption-text">Appendix</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="secure-coding-guidelines.html">Secure coding guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="release-process.html">Release process</a></li>
<li class="toctree-l1"><a class="reference internal" href="release-process.html#steps-to-cut-a-release">Steps to cut a release</a></li>
<li class="toctree-l1"><a class="reference internal" href="release-notes.html">Release notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="network-simulator.html">Network Simulator</a></li>
<li class="toctree-l1"><a class="reference internal" href="node-explorer.html">Node Explorer</a></li>
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">R3 Corda</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li>The Corda Configuration File</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/corda-configuration-files.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="the-corda-configuration-file">
<h1>The Corda Configuration File<a class="headerlink" href="#the-corda-configuration-file" title="Permalink to this headline"></a></h1>
<div class="section" id="configuration-file-location">
<h2>Configuration File Location<a class="headerlink" href="#configuration-file-location" title="Permalink to this headline"></a></h2>
<p>The Corda all-in-one <code class="docutils literal"><span class="pre">corda.jar</span></code> file is generated by the <code class="docutils literal"><span class="pre">gradle</span> <span class="pre">buildCordaJAR</span></code> task and defaults to reading configuration from a <code class="docutils literal"><span class="pre">node.conf</span></code> file in the present working directory.
This behaviour can be overidden using the <code class="docutils literal"><span class="pre">--config-file</span></code> 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 <code class="docutils literal"><span class="pre">--base-directory</span></code> command line option alters the Corda node workspace location and if specified a <code class="docutils literal"><span class="pre">node.conf</span></code> configuration file is then expected in the root of the workspace.</p>
<p>The configuration file templates used for the <code class="docutils literal"><span class="pre">gradle</span> <span class="pre">installTemplateNodes</span></code> task are to be found in the <code class="docutils literal"><span class="pre">/config/dev</span></code> folder. Also note that there is a basic set of defaults loaded from
the built in resource file <code class="docutils literal"><span class="pre">/node/src/main/resources/reference.conf</span></code> of the <code class="docutils literal"><span class="pre">:node</span></code> 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.</p>
</div>
<div class="section" id="configuration-file-format">
<h2>Configuration File Format<a class="headerlink" href="#configuration-file-format" title="Permalink to this headline"></a></h2>
<p>Corda uses the Typesafe configuration library to parse the configuration see the <a class="reference external" href="https://github.com/typesafehub/config/">typesafe config on Github</a> the format of the configuration files can be simple JSON, but for the more powerful substitution features
uses HOCON format see <a class="reference external" href="https://github.com/typesafehub/config/blob/master/HOCON.md">HOCON documents</a></p>
</div>
<div class="section" id="configuration-file-examples">
<h2>Configuration File Examples<a class="headerlink" href="#configuration-file-examples" title="Permalink to this headline"></a></h2>
<p>General node configuration file for hosting the IRSDemo services.</p>
<div class="highlight-text"><div class="highlight"><pre><span></span>basedir : &quot;./nodea&quot;
myLegalName : &quot;Bank A&quot;
nearestCity : &quot;London&quot;
keyStorePassword : &quot;cordacadevpass&quot;
trustStorePassword : &quot;trustpass&quot;
dataSourceProperties : {
dataSourceClassName : org.h2.jdbcx.JdbcDataSource
&quot;dataSource.url&quot; : &quot;jdbc:h2:&quot;${basedir}&quot;/persistence&quot;
&quot;dataSource.user&quot; : sa
&quot;dataSource.password&quot; : &quot;&quot;
}
artemisAddress : &quot;localhost:31337&quot;
webAddress : &quot;localhost:31339&quot;
extraAdvertisedServiceIds: &quot;corda.interest_rates&quot;
networkMapAddress : &quot;localhost:12345&quot;
useHTTPS : false
</pre></div>
</div>
<p>NetworkMapService plus Simple Notary configuration file.</p>
<div class="highlight-text"><div class="highlight"><pre><span></span>basedir : &quot;./nameserver&quot;
myLegalName : &quot;Notary Service&quot;
nearestCity : &quot;London&quot;
keyStorePassword : &quot;cordacadevpass&quot;
trustStorePassword : &quot;trustpass&quot;
artemisAddress : &quot;localhost:12345&quot;
webAddress : &quot;localhost:12346&quot;
extraAdvertisedServiceIds: &quot;&quot;
useHTTPS : false
</pre></div>
</div>
</div>
<div class="section" id="configuration-file-fields">
<h2>Configuration File Fields<a class="headerlink" href="#configuration-file-fields" title="Permalink to this headline"></a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">basedir:</th><td class="field-body"><p class="first">This specifies the node workspace folder either as an absolute path, or relative to the current working directory. It can be overidden by the <code class="docutils literal"><span class="pre">--base-directory</span></code> command line option, in which case the the value in the file is ignored and a <code class="docutils literal"><span class="pre">node.conf</span></code> file is expected in that workspace directory as the configuration source.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">myLegalName:</th><td class="field-body"><p class="first">The legal identity of the node acts as a human readable alias to the node&#8217;s public key and several demos use this to lookup the NodeInfo.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">nearestCity:</th><td class="field-body"><p class="first">The location of the node as used to locate coordinates on the world map when running the network simulator demo. See <a class="reference internal" href="network-simulator.html"><span class="doc">Network Simulator</span></a>.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">keyStorePassword:</th></tr>
<tr class="field-even field"><td>&nbsp;</td><td class="field-body"><p class="first">The password to unlock the KeyStore file (<code class="docutils literal"><span class="pre">&lt;workspace&gt;/certificates/sslkeystore.jks</span></code>) containing the node certificate and private key.</p>
<p>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.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name" colspan="2">trustStorePassword:</th></tr>
<tr class="field-odd field"><td>&nbsp;</td><td class="field-body"><p class="first">The password to unlock the Trust store file (<code class="docutils literal"><span class="pre">&lt;workspace&gt;/certificates/truststore.jks</span></code>) containing the R3 Corda root certificate. This is the non-secret value for the development certificates automatically generated during the first node run.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Longer term these keys will be managed in secure hardware devices.</p>
</div>
</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">dataSourceProperties:</th></tr>
<tr class="field-even field"><td>&nbsp;</td><td class="field-body"><p class="first">This section is used to configure the jdbc connection and database driver used for the nodes persistence. Currently the defaults in <code class="docutils literal"><span class="pre">/node/src/main/resources/reference.conf</span></code> 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.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">artemisAddress:</th><td class="field-body"><p class="first">The host and port on which the node is available for protocol operations over ArtemisMQ.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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.</p>
</div>
</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">messagingServerAddress:</th></tr>
<tr class="field-even field"><td>&nbsp;</td><td class="field-body"><p class="first">The address of the ArtemisMQ broker instance. If not provided the node will run one locally.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">webAddress:</th><td class="field-body"><p class="first">The host and port on which the node is available for web operations.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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 <code class="docutils literal"><span class="pre">/config/dev/corda_dev_ca.cer</span></code> root certificate be installed as a Trusted CA.</p>
</div>
</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">extraAdvertisedServiceIds:</th></tr>
<tr class="field-even field"><td>&nbsp;</td><td class="field-body"><p class="first">A list of ServiceType id strings to be advertised to the NetworkMapService and thus be available when other nodes query the NetworkMapCache for supporting nodes. This can also include plugin services loaded from .jar files in the plugins folder.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name" colspan="2">networkMapAddress:</th></tr>
<tr class="field-odd field"><td>&nbsp;</td><td class="field-body"><p class="first">If <cite>null</cite>, or missing the node is declaring itself as the NetworkMapService host. Otherwise the configuration value is the remote HostAndPort string for the ArtemisMQ service on the hosting node.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">useHTTPS:</th><td class="field-body"><p class="first last">If false the node&#8217;s web server will be plain HTTP. If true the node will use the same certificate and private key from the <code class="docutils literal"><span class="pre">&lt;workspace&gt;/certificates/sslkeystore.jks</span></code> file as the ArtemisMQ port for HTTPS. If HTTPS is enabled then unencrypted HTTP traffic to the node&#8217;s <strong>webAddress</strong> port is not supported.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="rpc-users-file">
<h1>RPC Users File<a class="headerlink" href="#rpc-users-file" title="Permalink to this headline"></a></h1>
<p>Corda also uses the <code class="docutils literal"><span class="pre">rpc-users.properties</span></code> file, found in the base directory, to control access to the RPC subsystem.
This is a Java properties file (details can be found in the <a class="reference external" href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html#load-java.io.Reader-">Javadocs</a>)
which specifies a list of users with their password and list of permissions they&#8217;re enabled for.</p>
<div class="literal-block-wrapper container" id="sample">
<div class="code-block-caption"><span class="caption-text">Sample</span><a class="headerlink" href="#sample" title="Permalink to this code"></a></div>
<div class="highlight-text"><div class="highlight"><pre><span></span>admin=notsecure,ADMIN
user1=letmein,CASH,PAPER
</pre></div>
</div>
</div>
<p>In this example <code class="docutils literal"><span class="pre">user1</span></code> has password <code class="docutils literal"><span class="pre">letmein</span></code> and has permissions for <code class="docutils literal"><span class="pre">CASH</span></code> and <code class="docutils literal"><span class="pre">PAPER</span></code>. The permissions are
free-form strings which can be used by the RPC methods to control access.</p>
<p>If <code class="docutils literal"><span class="pre">rpc-users.properties</span></code> is empty or doesn&#8217;t exist then the RPC subsystem is effectively locked down.</p>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="where-to-start.html" class="btn btn-neutral float-right" title="Where to start" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="node-administration.html" class="btn btn-neutral" title="Node administration" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2016, Distributed Ledger Group, LLC.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'latest',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>