Hosting a Splinter Node

Choosing a Hosting Environment

Currently, Splinter is packaged as Docker images hosted on Docker Hub. This means Splinter can be deployed anywhere a Docker image can run. Most examples will focus on Docker Compose.

Starting with 0.5.1 Splinter can also be installed using apt. Details can be found on the 0.5 releases page and Installing Splinter on Ubuntu.

Hosting a Splinter Node

Detailed information about planning your Splinter deployment can be found in Planning a Splinter Deployment how-to document. This section summarizes some especially important information.

Network Configuration

Other nodes must be able to connect to your node on port 8044. Applications and CLIs used to manage Splinter will connect to the Splinter REST API on port 8080.

While it is technically possible to run the Splinter daemon without port 8044 open, it is not recommended. If the daemon cannot accept incoming connections, it will not be able to receive circuit management requests from new peers. Also, if an existing peer has disconnected, the peer will try to reestablish a connection to splinterd behind the firewall, which will be unsuccessful.

If running behind a firewall without an open port is absolutely necessary, peers can be explicitly set with the splinterd --peer option on startup or with the splinter configuration setting peers = [ ]. This will cause splinterd to try to establish a connection with another Splinter node, whether there is a shared circuit defined or not, and assumes that the other node will accept incoming connections.

Persistent Volumes

Due to the ephemeral nature of Docker containers, any data not explicitly persisted to a volume outside the container will be lost when the container is restarted or stopped. Persisting application data will depend on the design of the application running on Splinter, but all deployments will need to persist splinterd’s data directory, /var/lib/splinter. Splinter’s directories are described in the next section.

Important splinterd Directories

/etc/splinter/: Default location for the Splinter configuration directory. Note: If $SPLINTER_HOME is set, the default location is $SPLINTER_HOME/etc/.

/etc/splinter/certs/: Default location for the TLS certificate directory, which stores CA certificates and the associated keys. Note: If SPLINTER_HOME is set, the default location is $SPLINTER_HOME/certs/.

/etc/splinter/keys/: Default location for splinterd keys generated with splinter keygen --system.

/var/lib/splinter/: Default location for the Splinter state directory, which stores the circuit state SQLITE database (unless --database is set). Note: If $SPLINTER_HOME is set, the default location is $SPLINTER_HOME/data/.

Logging

Currently, splinterd only logs to stdout and stderr. Logging levels can be increased by starting splinterd with -v for INFO logging, -vv for DEBUG logging or -vvv for TRACE. Future versions will have configurable file logging and ability to change the log level without needing to restart splinterd.

Splinter Keys

There are two common types of keys used with Splinter.

Keys for splinterd (generated by running splinter keygen --system) used in a challenge authorization.

User keys are used for signing transactions in applications and smart contracts that run on Splinter.

Splinter Registry

A Splinter registry is used to locate Splinter nodes for the purpose of creating circuits. Registries can be local, remote, or both. For the differences between the two types of registries, instructions for configuring a registry, and recommendations, see the Splinter Registry page.

Security Concerns

REST API

See the Ports and REST API Connections section of the “Security Considerations” document for details about REST API security.

Certificates

In order to run splinterd and create circuits over TLS, you’ll need to provide valid X.509 certificates and the associated private keys. Any splinter node you will be creating circuits with will need to trust the CA that signs your certificates.

splinterd uses both a client and a server certificate for TLS connections.

• The generated server certificate should have the Extended Key Usage OID for Server Authentication (1.3.6.1.5.5.7.3.1).

• The generated client certificate should have the Extended Key Usage OID for Client Authentication (1.3.6.1.5.5.7.3.2).

For development or non-production uses, Splinter can be run in “insecure” mode with self-signed certificates. For the instructions on generating these certificates and enabling insecure mode, see Generating Insecure Certificates for Development.

Authorization

When Splinter nodes connect, they must go through a “handshake” to verify the identity of the other node. Challenge Authorization requires a node’s ID to be tied to a public key/private key pair and a node must prove they have access to that key by signing a random nonce, providing the resulting signature and their public key.

For development or non-production uses, trust authorization can be used. Trust authorization takes the identity provided from the node without further verification.

The required authorization type is set in the circuit.

Available Docker Hub Images

Splinter images are published to splintercommunity on Docker Hub.

The Splinter project produces artifacts for multiple branches compiled with different features, which can be confusing at times. This table lists the image tags and explains what each tag means.

Upgrading Splinter

Upgrading Splinter is usually as simple as updating the version number of the Splinter images in your Docker Compose file, then redeploying. However, breaking changes will be introduced from time to time. Comprehensive upgrade instructions for each version can be found in the Upgrading section of the Splinter website.

Troubleshooting

Circuit Creation:

Error message: T["actix-rt:worker:1"] DEBUG [splinter::admin::rest_api::actix::submit] validation failed: 02f953633bafafe622ebdec3d6d5a309cc5dd967793dexample3d2312ed4ccb599 is not registered for the requester node: alpha

This error message suggests that the key provided as the circuit admin key in the circuit proposal isn’t the key listed for this node in the node registry. Look at your Splinter registry file and make sure that the correct key is being used.