corda/docs/source/shell.rst

391 lines
15 KiB
ReStructuredText
Raw Normal View History

.. highlight:: kotlin
.. raw:: html
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script>
Shell
=====
2017-12-21 16:57:03 +00:00
.. contents::
The Corda shell is an embedded or standalone command line that allows an administrator to control and monitor a node. It is based on
2017-12-21 16:57:03 +00:00
the `CRaSH`_ shell and supports many of the same features. These features include:
2017-12-21 16:57:03 +00:00
* Invoking any of the node's RPC methods
* Viewing a dashboard of threads, heap usage, VM properties
* Uploading and downloading attachments
* Issuing SQL queries to the underlying database
* Viewing JMX metrics and monitoring exports
* UNIX style pipes for both text and objects, an ``egrep`` command and a command for working with columnular data
* Shutting the node down.
Permissions
-----------
When accessing the shell (embedded, standalone, via SSH) RPC permissions are required. This is because the shell actually communicates
with the node using RPC calls.
* Watching flows (``flow watch``) requires ``InvokeRpc.stateMachinesFeed``
* Starting flows requires ``InvokeRpc.startTrackedFlowDynamic``, ``InvokeRpc.registeredFlows`` and ``InvokeRpc.wellKnownPartyFromX500Name``, as well as a
permission for the flow being started
2017-12-21 16:57:03 +00:00
The shell via the local terminal
--------------------------------
In development mode, the shell will display in the node's terminal window.
The shell connects to the node as 'shell' user with password 'shell' which is only available in dev mode.
It may be disabled by passing the ``--no-local-shell`` flag when running the node.
2017-12-21 16:57:03 +00:00
The shell via SSH
-----------------
The shell is also accessible via SSH.
2017-12-21 16:57:03 +00:00
Enabling SSH access
*******************
2017-12-21 16:57:03 +00:00
By default, the SSH server is *disabled*. To enable it, a port must be configured in the node's ``node.conf`` file:
.. code:: bash
sshd {
port = 2222
}
2017-12-21 16:57:03 +00:00
Authentication
**************
Users log in to shell via SSH using the same credentials as for RPC.
No RPC permissions are required to allow the connection and log in.
2017-12-21 16:57:03 +00:00
The host key is loaded from the ``<node root directory>/sshkey/hostkey.pem`` file. If this file does not exist, it is
generated automatically. In development mode, the seed may be specified to give the same results on the same computer
in order to avoid host-checking errors.
2017-12-21 16:57:03 +00:00
Connecting to the shell
***********************
2017-12-21 16:57:03 +00:00
Linux and MacOS
^^^^^^^^^^^^^^^
2017-12-21 16:57:03 +00:00
Run the following command from the terminal:
2017-12-21 16:57:03 +00:00
.. code:: bash
2017-12-21 16:57:03 +00:00
ssh -p [portNumber] [host] -l [user]
2017-12-21 16:57:03 +00:00
Where:
2017-12-21 16:57:03 +00:00
* ``[portNumber]`` is the port number specified in the ``node.conf`` file
* ``[host]`` is the node's host (e.g. ``localhost`` if running the node locally)
* ``[user]`` is the RPC username
2017-12-21 16:57:03 +00:00
The RPC password will be requested after a connection is established.
.. note:: In development mode, restarting a node frequently may cause the host key to be regenerated. SSH usually saves
2017-12-21 16:57:03 +00:00
trusted hosts and will refuse to connect in case of a change. This check can be disabled using the
``-o StrictHostKeyChecking=no`` flag. This option should never be used in production environment!
2017-12-21 16:57:03 +00:00
Windows
^^^^^^^
2017-12-21 16:57:03 +00:00
Windows does not provide a built-in SSH tool. An alternative such as PuTTY should be used.
The standalone shell
--------------------
The standalone shell is a standalone application interacting with a Corda node via RPC calls.
RPC node permissions are necessary for authentication and authorisation.
Certain operations, such as starting flows, require access to CordApps jars.
Starting the standalone shell
*****************************
Run the following command from the terminal:
Linux and MacOS
^^^^^^^^^^^^^^^
.. code:: bash
./shell [--config-file PATH | --cordpass-directory PATH --commands-directory PATH --host HOST --port PORT
--user USER --password PASSWORD --sshd-port PORT --sshd-hostkey-directory PATH --keystore-password PASSWORD
--keystore-file FILE --truststore-password PASSWORD --truststore-file FILE | --help]
Windows
^^^^^^^
.. code:: bash
shell.bat [--config-file PATH | --cordpass-directory PATH --commands-directory PATH --host HOST --port PORT
--user USER --password PASSWORD --sshd-port PORT --sshd-hostkey-directory PATH --keystore-password PASSWORD
--keystore-file FILE --truststore-password PASSWORD --truststore-file FILE | --help]
Where:
* ``config-file`` is the path to config file, used instead of providing the rest of command line options
* ``cordpass-directory`` is the directory containing Cordapps jars, Cordapps are require when starting flows
* ``commands-directory`` is the directory with additional CrAsH shell commands
* ``host`` is the Corda node's host
* ``port`` is the Corda node's port, specified in the ``node.conf`` file
* ``user`` is the RPC username, if not provided it will be requested at startup
* ``password`` is the RPC user password, if not provided it will be requested at startup
* ``sshd-port`` instructs the standalone shell app to start SSH server on the given port, optional
* ``sshd-hostkey-directory`` is the directory containing hostkey.pem file for SSH server
* ``keystore-password`` the password to unlock the KeyStore file containing the standalone shell certificate and private key, optional, unencrypted RPC connection without SSL will be used if the option is not provided
* ``keystore-file`` is the path to the KeyStore file
* ``truststore-password`` the password to unlock the TrustStore file containing the Corda node certificate, optional, unencrypted RPC connection without SSL will be used if the option is not provided
* ``truststore-file`` is the path to the TrustStore file
* ``help`` prints Shell help
The format of ``config-file``:
.. code:: bash
node {
addresses {
rpc {
host : "localhost"
port : 10006
}
}
}
shell {
workDir : /path/to/dir
}
extensions {
cordapps {
path : /path/to/cordapps/dir
}
sshd {
enabled : "false"
port : 2223
}
}
ssl {
keystore {
path: "/path/to/keystore"
type: "JKS"
password: password
}
trustore {
path: "/path/to/trusttore"
type: "JKS"
password: password
}
}
user : demo
password : demo
Standalone Shell via SSH
------------------------
The standalone shell can embed an SSH server which redirects interactions via RPC calls to the Corda node.
To run SSH server use ``--sshd-port`` option when starting standalone shell or ``extensions.sshd`` entry in the configuration file.
For connection to SSH refer to `Connecting to the shell`_.
Certain operations (like starting Flows) will require Shell's ``--cordpass-directory`` to be configured correctly (see `Starting the standalone shell`_).
2017-12-21 16:57:03 +00:00
Interacting with the node via the shell
---------------------------------------
The shell interacts with the node by issuing RPCs (remote procedure calls). You make an RPC from the shell by typing
``run`` followed by the name of the desired RPC method. For example, you'd see a list of the registered flows on your
node by running:
``run registeredFlows``
Some RPCs return a stream of events that will be shown on screen until you press Ctrl-C.
You can find a list of the available RPC methods
`here <https://docs.corda.net/api/kotlin/corda/net.corda.core.messaging/-corda-r-p-c-ops/index.html>`_.
Shutting down the node
**********************
You can shut the node down via shell:
* ``gracefulShutdown`` will put node into draining mode, and shut down when there are no flows running
* ``shutdown`` will shut the node down immediately
2017-12-21 16:57:03 +00:00
Flow commands
*************
The shell also has special commands for working with flows:
* ``flow list`` lists the flows available on the node
* ``flow watch`` shows all the flows currently running on the node with result (or error) information
* ``flow start`` starts a flow. The ``flow start`` command takes the name of a flow class, or
*any unambiguous substring* thereof, as well as the data to be passed to the flow constructor. If there are several
matches for a given substring, the possible matches will be printed out. If a flow has multiple constructors then the
names and types of the arguments will be used to try and automatically determine which one to use. If the match
against available constructors is unclear, the reasons each available constructor failed to match will be printed
out. In the case of an ambiguous match, the first applicable constructor will be used
Parameter syntax
****************
Parameters are passed to RPC or flow commands using a syntax called `Yaml`_ (yet another markup language), a
simple JSON-like language. The key features of Yaml are:
* Parameters are separated by commas
* Each parameter is specified as a ``key: value`` pair
* There **MUST** to be a space after the colon, otherwise you'll get a syntax error
* Strings do not need to be surrounded by quotes unless they contain commas, colons or embedded quotes
* Class names must be fully-qualified (e.g. ``java.lang.String``)
.. note:: If your CorDapp is written in Java, named arguments won't work unless you compiled the node using the
``-parameters`` argument to javac. See :doc:`generating-a-node` for how to specify it via Gradle.
Creating an instance of a class
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2017-12-21 16:57:03 +00:00
Class instances are created using curly-bracket syntax. For example, if we have a ``Campaign`` class with the following
constructor:
``data class Campaign(val name: String, val target: Int)``
Then we could create an instance of this class to pass as a parameter as follows:
``newCampaign: { name: Roger, target: 1000 }``
Where ``newCampaign`` is a parameter of type ``Campaign``.
Mappings from strings to types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In addition to the types already supported by Jackson, several parameter types can automatically be mapped from strings.
We cover the most common types here.
2017-12-21 16:57:03 +00:00
Amount
~~~~~~
A parameter of type ``Amount<Currency>`` can be written as either:
* A dollar ($), pound (£) or euro (€) symbol followed by the amount as a decimal
* The amount as a decimal followed by the ISO currency code (e.g. "100.12 CHF")
SecureHash
~~~~~~~~~~
A parameter of type ``SecureHash`` can be written as a hexadecimal string: ``F69A7626ACC27042FEEAE187E6BFF4CE666E6F318DC2B32BE9FAF87DF687930C``
OpaqueBytes and SerializedBytes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A parameter of type ``OpaqueBytes`` can be provided as a string in Base64.
PublicKey and CompositeKey
~~~~~~~~~~~~~~~~~~~~~~~~~~
A parameter of type ``PublicKey`` can be written as a Base58 string of its encoded format: ``GfHq2tTVk9z4eXgyQXzegw6wNsZfHcDhfw8oTt6fCHySFGp3g7XHPAyc2o6D``.
``net.corda.core.utilities.EncodingUtils.toBase58String`` will convert a ``PublicKey`` to this string format.
2017-12-21 16:57:03 +00:00
Party
~~~~~
A parameter of type ``Party`` can be written in several ways:
* By using the full name: ``"O=Monogram Bank,L=Sao Paulo,C=GB"``
2017-12-21 16:57:03 +00:00
* By specifying the organisation name only: ``"Monogram Bank"``
* By specifying any other non-ambiguous part of the name: ``"Sao Paulo"`` (if only one network node is located in Sao
Paulo)
* By specifying the public key (see above)
NodeInfo
~~~~~~~~
A parameter of type ``NodeInfo`` can be written in terms of one of its identities (see ``Party`` above)
AnonymousParty
~~~~~~~~~~~~~~
A parameter of type ``AnonymousParty`` can be written in terms of its ``PublicKey`` (see above)
NetworkHostAndPort
~~~~~~~~~~~~~~~~~~
A parameter of type ``NetworkHostAndPort`` can be written as a "host:port" string: ``"localhost:1010"``
2017-12-21 16:57:03 +00:00
Instant and Date
~~~~~~~~~~~~~~~~
A parameter of ``Instant`` and ``Date`` can be written as an ISO-8601 string: ``"2017-12-22T00:00:00Z"``
2017-12-21 16:57:03 +00:00
Examples
^^^^^^^^
Starting a flow
~~~~~~~~~~~~~~~
We would start the ``CashIssue`` flow as follows:
``flow start CashIssueFlow amount: $1000, issuerBankPartyRef: 1234, notary: "O=Controller, L=London, C=GB"``
2017-12-21 16:57:03 +00:00
This breaks down as follows:
* ``flow start`` is a shell command for starting a flow
* ``CashIssue`` is the flow we want to start
* Each ``name: value`` pair after that is a flow constructor argument
This command invokes the following ``CashIssue`` constructor:
.. container:: codeset
.. sourcecode:: kotlin
class CashIssueFlow(val amount: Amount<Currency>,
val issueRef: OpaqueBytes,
val recipient: Party,
val notary: Party) : AbstractCashFlow(progressTracker)
2017-12-21 16:57:03 +00:00
Querying the vault
~~~~~~~~~~~~~~~~~~
2017-12-21 16:57:03 +00:00
We would query the vault for ``IOUState`` states as follows:
2017-12-21 16:57:03 +00:00
``run vaultQuery contractStateType: com.template.IOUState``
2017-12-21 16:57:03 +00:00
This breaks down as follows:
2017-12-21 16:57:03 +00:00
* ``run`` is a shell command for making an RPC call
* ``vaultQuery`` is the RPC call we want to make
* ``contractStateType: com.template.IOUState`` is the fully-qualified name of the state type we are querying for
Merge release-v1 onto master (mostly documentation changes) (#1797) * Updated corda release version to 1.0.0.RC2 (#1641) * Fixed Simm Valuation Demo Test and enable serializabe java 8 lambdas. (#1655) * [CORDA-624] Node Explorer on Issuing cash throws MissingContractAttachements exception (#1656) (cherry picked from commit 27fea4d) * BIGINT fix for H2 coin selection. (#1658) * BIGINT fix for H2 coin selection. * Review feedback * CORDA-637 Node Explorer shows Network Map Service in Cash Issue dropdown (#1665) * [CORDA-637] Node Explorer shows Network Map Service in Cash Issue dropdown * add TODO to remove the hack * Declare this internal message string as "const". (#1676) * Merge "A variety of small fixes" into the 1.0 release branch (#1673) * Minor: improve javadocs in NodeInfo * Minor: use package descriptions in Kotlin build of api docs too, not just javadocs. * RPC: make RPCConnection non-internal, as it's a core API. Move docs around so they're on public API not internal API. * Add an IntelliJ scope that covers the currently supported Corda API. This is useful when used in combination with the "Highlight public declarations with missing KDoc" inspection. * Ironic: upgrade the version of the Gradle plugin that checks for upgraded versions of things. It had broken due being incompatible with the new versions of Gradle itself. * Docs: flesh out javadocs on ServiceHub * Docs: add @suppress to a few things that were polluting the Dokka docs. * Docs: mention RPC access in NodeInfo javadoc * IRS Fixes to bring UI closer to declared financial types (#1662) * Made problematic CordaRPCClient c'tor private (with internal bridge methods) and added correct c'tors for public use. (#1653) initialiseSerialization param has also been removed. * Fixing flow snapshot feature (#1685) * Fix validating notary flow to handle notary change transactions properly. (#1687) Add a notary change test for checking longer chains involving both regular and notary change transactions. * Unification of VaultQuery And VaultService APIs (into single VaultService interface) to simplify node bootstrapping and usability. (#1677) (#1688) * Identity documentation (#1620) * Sketch initial identity docs * Restructure confidential identity docs to better fit structure * Split confidential identities into API and concepts * Further expansion on basic identity conceptS * Merge Party type into api-identity.rst * Address feedback on written content * Rework inline code with literalinclude * Start addressing feedback from Richard * Clarify use of "counterparty" * Address comments on key concepts * Correct back to US english * Clarify distribution/publishing of identities * Update changelog around confidential identities * CORDA-642 Notary demo documentation fixes (#1682) * Notary demo documentation fixes. * One of the tables is prefixed. * CORDA-641: A temporary fix for contract upgrade transactions (#1700) * A temporary fix for contract upgrade transactions: during LedgerTransaction verification run the right logic based on whether it contains the UpgradeCommand. * Move ContractUpgradeFlowTest away from createSomeNodes() * Remove assembleBareTx as it's not used * Update corda version tag to 1.0.0-RC3 (#1705) * Hide SerializationContext from public API on TransactionBuilder (#1707) * Hide SerializationContext from public API on TransactionBuilder (cherry picked from commit 6ff7b7e) * Hide SerializationContext from public API on TransactionBuilder (cherry picked from commit 6ff7b7e) * Address feedback on confidential identities docs (#1701) * Address minor comments on confidential identities docs * Expand on implementation details of confidential identities * Cleanup * Clarify details of the data blob in the swap identites flow * Add that certificate path is not made public for confidential identities * FlowSession docs (#1693) * FlowSession docs (#1660) * FlowSession docs * PR comments * Milder example flow name * Fixes bugs with contract constraints (#1696) * Added schedulable flows to cordapp scanning Fixed a bug where the core flows are included in every cordapp. Added a test to prove the scheduled flows are loaded correctly. Added scheduled flow support to cordapp. Renabled broken test. Fixed test to prove cordapps aren't retreived from network. Review fixes. Fixed a test issue caused by gradle having slightly different paths to IntelliJ * Fixed test for real this time. * Consistent use of CordaException and CordaRuntimeException (#1710) * Custom exceptions in corda, should either derive from an appropriate closely related java exception, or CordaException, or CordaRuntimeException. They should not inherit just from Exception, or RuntimeException. Handle PR comments Add nicer constructors to CordaException and CordaRuntimeException * Fix ambiguous defaulted constructor * Add @suppress (#1725) * Git-ignore Node Explorer config. (#1709) * add message warning windows users they might need to manually kill explorer demo nodes started by gradle (#1717) (#1726) * Misc documentation fixes (#1694) (cherry picked from commit 592896f) * Document -parameters compiler arg for Java CorDapps. (#1712) * Correct non-anonymous two party trade flow (#1731) * Parameterize TwoPartyTradeFlowTests to confirm deanonymised functionality works. * Correct handling of counterparty using well known identity in TWoPartyTradeFlow * CORDA-594 - SIMM Demo doc update (#1723) (#1735) * CORDA-594 - SIMM Demo doc update For V1 write a series of JSON / curl commands a user can follow to run the demo * Review Comments * Updated the rationale behind as to why SIMM was introduced. * typo * Cordapps now have a name field. (#1664) Corrected cordapp name generation. Added changelog entry. * Small API fixes against M16 (#1737) * Move CompositeSignaturesWithKeys into net.corda.core.crypto package. (cherry picked from commit 8f29562) * Rename and move CordaPluginRegistry to reflect its real purpose now. Simplify serialization code a bit. (cherry picked from commit e2ecd3a) * Docs: docsite improvements * Remove discussion of webserver from 'writing a cordapp' page. * Fixup some flow docs. * Add a couple more package descriptions. (cherry picked from commit 2aedc43) * Review comments (cherry picked from commit ba1d007) * Review comments - always apply default whitelist and no longer load it via ServiceLoader (cherry picked from commit 7d4d7bb) * Added wording about renaming services resource file * Update corda version tag to 1.0.0-RC4 (#1734) * Update corda version tag to 1.0.0-RC3 * Update corda version tag to 1.0.0-RC4 * Update build.gradle * V1 tests and fixes for the ContractConstraints work (#1739) * V1 tests and fixes for the ContractConstraints work * More fixes. * Added a contract constraints section to the key concepts doc. (#1704) Documentation for contract constraints. Added to index. Review fixes round 1. More review fixes. Review fixes. Explained package contents. review fixes. Addressed RGB's final review comments. Updated source code type to 'java' * Fixes dead links. (#1749) * Update gradle plugins version to 1.0.0 (#1753) * Update Readme (#1756) * Update Readme Minor tweaks to Readme -- consistent capitalisation and more descriptive list of features (also reordered to put the important things first) * Copied master readme. * Update Readme Minor tweaks to Readme -- consistent capitalisation and more descriptive list of features (also reordered to put the important things first) * Fixes .rst formatting. (#1751) * Updates tutorials. (#1649) * Updates tutorials. * Addresses review comments. * Tutorial refresh for v1.0 and moving of code into separate files. (#1758) * Moves code sections in tutorials to code files. * Removes wallet references. * Updates repo layout doc. * Removes remaining cordapp-tutorial references, replaced with cordapp-example. * Fixes broken link. * Misc docs fixes. * Refreshes the ServiceHub and rpc ops api pages. * Updates the cheat sheet. * Updates cookbooks. * Refreshes the running-a-notary tutorial. * Updates flow-testing tutorial * Updates tear-offs tutorial. * Refreshes integration-testing tutorial. * Updates to contract tutorial and accompanying code to bring inline with V1 release. * Refreshes contract-upgrade tutorial. * Fixed broken code sample in "writing a contract" and updated contracts dsl. * Added contract ref to java code. Fixed broken rst markup. * Updates transaction-building tutorial. * Updates the client-rpc and flow-state-machines tutorials. * Updates the oracles tutorial. * Amended country in X500 names from "UK" to "GB" * Update FlowCookbook.kt * Amended cheatsheet. Minor update on contract upgrades tutoraial. * Added `extraCordappPackagesToScan` to node driver. * Changes to match new function signature. * Update to reflect change in location of cash contract name. * CORDA-670: Correct scanned packages in network visualiser (#1763) * Add CorDapp dependency of IRS to network visualiser * Set CorDapp directories * Checking out the latest milestone will no longer be required. (#1761) * Updated documentation indices (#1754) * Update documentation indices. * Reference a moveable tag for V1 docs. Remove redundant warning text. * Reverted proposed usage of new docs release tag * Minor: print a deprecation warning when the web server starts. (#1767) * Release and upgrade notes for V1.0 (#1736) * Release and upgrade notes for V1.0 * Update changelog.rst * Update changelog.rst * Formatting. * Incorporating review feedback from KB and MN. * "guarantee" instead of "promise" * Updated with final review comments from KB and RGB. * Updated upgrade notes to describe migration from removed CordaPluginRegistry. * Minor clarification. * Minor updates following final RGB feedback. * Kat's further pedantic feedback * Minor changes following feedback from KB. * Incorporating review feedback from MH. * killed 'patent-pending' * Made the visualiser into a regular JVM module - not a CorDapp. (#1771) * Docs: more package descriptions and take non-stabilised APIs out of the docs build. (#1775) * Update corda version tag to 1.0.0 * Updated release notes to fix minor typos (#1779) Fixed bold type on simplified annotation driven scanning bullet and added bold type to module name bullets * Fixed drop down.. probably. (#1780) * fixed formatting for release notes. (#1782) * Improve API page wording (#1784) * Removed "unreleased" sections from the release notes and change log. * Merge remote-tracking branch 'origin/release-V1' into colljos-merge-v1-docs # Conflicts: # build.gradle # client/jfx/src/main/kotlin/net/corda/client/jfx/model/NodeMonitorModel.kt # client/rpc/src/main/kotlin/net/corda/client/rpc/CordaRPCClient.kt # client/rpc/src/main/kotlin/net/corda/client/rpc/PermissionException.kt # constants.properties # core/src/main/kotlin/net/corda/core/flows/FlowSession.kt # core/src/test/kotlin/net/corda/core/contracts/DummyContractV2Tests.kt # core/src/test/kotlin/net/corda/core/flows/ContractUpgradeFlowTest.kt # docs/source/api-flows.rst # docs/source/api-index.rst # docs/source/changelog.rst # docs/source/example-code/src/main/java/net/corda/docs/java/tutorial/testdsl/CommercialPaperTest.java # docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt # docs/source/example-code/src/main/kotlin/net/corda/docs/tutorial/contract/TutorialContract.kt # docs/source/example-code/src/main/kotlin/net/corda/docs/tutorial/testdsl/TutorialTestDSL.kt # docs/source/hello-world-state.rst # docs/source/key-concepts-contract-constraints.rst # docs/source/serialization.rst # docs/source/tut-two-party-flow.rst # docs/source/tutorial-tear-offs.rst # node-api/src/main/kotlin/net/corda/nodeapi/internal/serialization/CordaClassResolver.kt # node-api/src/test/java/net/corda/nodeapi/internal/serialization/ForbiddenLambdaSerializationTests.java # node-api/src/test/java/net/corda/nodeapi/internal/serialization/LambdaCheckpointSerializationTest.java # node/src/integration-test/kotlin/net/corda/node/services/AttachmentLoadingTests.kt # node/src/integration-test/kotlin/net/corda/services/messaging/MQSecurityTest.kt # node/src/main/kotlin/net/corda/node/internal/NodeStartup.kt # node/src/test/kotlin/net/corda/node/internal/cordapp/CordappLoaderTest.kt # node/src/test/kotlin/net/corda/node/services/NotaryChangeTests.kt # samples/attachment-demo/src/main/kotlin/net/corda/attachmentdemo/AttachmentDemo.kt # samples/trader-demo/src/main/kotlin/net/corda/traderdemo/TraderDemo.kt # testing/node-driver/src/integration-test/kotlin/net/corda/testing/FlowStackSnapshotTest.kt # testing/node-driver/src/main/kotlin/net/corda/testing/driver/Driver.kt # testing/node-driver/src/main/kotlin/net/corda/testing/node/MockNode.kt # webserver/src/main/kotlin/net/corda/webserver/internal/NodeWebServer.kt
2017-10-03 16:32:11 +00:00
2017-12-21 16:57:03 +00:00
Attachments
***********
2017-12-21 16:57:03 +00:00
The shell can be used to upload and download attachments from the node. To learn more, see the tutorial
":doc:`tutorial-attachments`".
2017-12-21 16:57:03 +00:00
Getting help
************
2017-12-21 16:57:03 +00:00
You can type ``help`` in the shell to list the available commands, and ``man`` to get interactive help on many
commands. You can also pass the ``--help`` or ``-h`` flags to a command to get info about what switches it supports.
Commands may have subcommands, in the same style as ``git``. In that case, running the command by itself will
list the supported subcommands.
Extending the shell
-------------------
2017-12-21 16:57:03 +00:00
The shell can be extended using commands written in either Java or `Groovy`_ (a Java-compatible scripting language).
These commands have full access to the node's internal APIs and thus can be used to achieve almost anything.
2017-12-21 16:57:03 +00:00
A full tutorial on how to write such commands is out of scope for this documentation. To learn more, please refer to
the `CRaSH`_ documentation. New commands are placed in the ``shell-commands`` subdirectory in the node directory. Edits
to existing commands will be used automatically, but currently commands added after the node has started won't be
automatically detected. Commands must have names all in lower-case with either a ``.java`` or ``.groovy`` extension.
.. warning:: Commands written in Groovy ignore Java security checks, so have unrestricted access to node and JVM
internals regardless of any sandboxing that may be in place. Don't allow untrusted users to edit files in the
shell-commands directory!
Limitations
-----------
The shell will be enhanced over time. The currently known limitations include:
2018-03-20 08:14:33 +00:00
* Flows cannot be run unless they override the progress tracker
* If a command requires an argument of an abstract type, the command cannot be run because the concrete subclass to use cannot be specified using the YAML syntax
2017-12-21 16:57:03 +00:00
* There is no command completion for flows or RPCs
* Command history is not preserved across restarts
* The ``jdbc`` command requires you to explicitly log into the database first
* Commands placed in the ``shell-commands`` directory are only noticed after the node is restarted
* The ``jul`` command advertises access to logs, but it doesn't work with the logging framework we're using
.. _Yaml: http://www.yaml.org/spec/1.2/spec.html
.. _Groovy: http://groovy-lang.org/
.. _CRaSH: http://www.crashub.org/