Installing Splinter on Ubuntu
In this short tutorial, you’ll install the Splinter daemon, become acquainted with its configuration files, learn how to start and stop splinterd and view logs. At the end of the guide you’ll have a Splinter node ready to create new circuits with other existing nodes.
This document assumes you have an Ubuntu Focal environment with sudo permissions. Instructions focusing on docker can be found at configuring splinter nodes with docker.
Open a terminal window. Download the Splinter repo’s key and add the repository as an apt source.
$ sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys --recv-keys B1DF8C00ACEB5855 $ sudo add-apt-repository "deb [arch=amd64] http://repo.splinter.dev/ubuntu/extraball focal stable"
$ sudo apt install -yq splinter-cli splinter-daemon
splinterdwere installed successfully.
$ splinter --version splinter-cli 0.6.x $ splinterd --version splinterd 0.6.x
splintercommand to generate certificates.
$ sudo splinter cert generate Writing file: /etc/splinter/certs/generated_ca.pem Writing file: /etc/splinter/certs/private/generated_ca.key Writing file: /etc/splinter/certs/client.crt Writing file: /etc/splinter/certs/private/client.key Writing file: /etc/splinter/certs/server.crt Writing file: /etc/splinter/certs/private/server.key
Next, create a
ca.pemfile. Splinterd will not start without at least one valid certificate in the
ca.pemfile. Since we don’t have any peers yet, an example certificate is provided below as a workaround for this guide only. In a real-world scenario, this file should be populated with the contents of the
generated_ca.pemfrom each of your peers. Detailed information about Splinter certificates can be found on the Splinter Certificates page.
$ sudo vi /etc/splinter/certs/ca.pem
Paste the example certificate.
# Example only, do not use in production. -----BEGIN CERTIFICATE----- MIICyTCCAbGgAwIBAgIBADANBgkqhkiG9w0BAQsFADAXMRUwEwYDVQQDDAxnZW5l cmF0ZWRfY2EwHhcNMjEwNjI0MTk0MjM5WhcNMjIwNjI0MTk0MjM5WjAXMRUwEwYD VQQDDAxnZW5lcmF0ZWRfY2EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB AQDgR/Yj6SJbh/VFC76v+JwiB59ehsNsCu4Hp2jVrDEEyi2b5BHsRFDbNbLsjj5t mfQ5sbv34xsIweN+kqZwLL1XcEDFBygx1Aa+kB4ZkzJqu1Amz4D3k8Ak29d1izA4 k5/UHzunUd9klL9DceYVqRYGpN//dqf9PohLZZ76tvGWdnxZlY0mFP1SdsklgG97 zxDjRTjpGfLgJSrmvl3jyf/bqjsKKaKr+Rr+b+zys+hDO+py+M5wQ23VQpeyoTYD 2cVp6yurUyImbg83YPgAfBkHutlGA1ShWdYJNXUckI/bf+HO5wJihJc3PVeES5pT Bv+9gtp/bcRDqQewN1lsJostAgMBAAGjIDAeMA8GA1UdEwEB/wQFMAMBAf8wCwYD VR0PBAQDAgIEMA0GCSqGSIb3DQEBCwUAA4IBAQA02LBE4hO3U/YxQNIlkUmqjQnS VfXk6rxHkAwClukmGtvTocBaIzPCB2ljpFpU0FhXgnWBAwgOY7lt3PIs+WY8Hb1l DAIKNiZO7X7ahqwP8o/MVg60IR7hGeIN51NxU0XIUWfqPP3civQpi6ZicGCOmM3+ CF0s6k3TthiPCyKmadbS/zsf2EVXsLC9MH/hJznxZaWtxn3m0FB288QOR/DXWt0L AReGQk4fuFG7Lx/CU4MSn9ENi3AklWkN7Qrhzn3Q3mjQRpQc7Y4dy+bCjmXSV5e+ 7iHuMfoiAZ4ddwD5EHjbRzyuBaR1rzYdl8vmSVoT5S+nwLVVs1gh5coM24bA -----END CERTIFICATE-----
Save the file and exit.
splinterdgroup read rights.
$ sudo chown root:splinterd /etc/splinter/certs/ca.pem
Initialize the splinter database
In this tutorial we’ll be using SQLite but Splinter also supports Postgres. Click here for more information about configuring Splinter databases.
splinter database migratecommand will create a Splinter database file and populate it with the necessary tables.
$ sudo -u splinterd splinter database migrate Running migrations against SQLite database: /var/lib/splinter/splinter_state.db Successfully applied SQLite migrations
Verify that the db file was created with the correct permissions.
$ sudo -u splinterd ls -al /var/lib/splinter/splinter_state.db -rw-r----- 1 splinterd splinterd 339968 Jun 22 19:25 /var/lib/splinter/splinter_state.db
Create a config file
Copy the example config file into place. Make sure to include the
-pflag or you’ll encounter a
Permission deniederror when starting
$ sudo cp -p /etc/splinter/splinterd.toml.example /etc/splinter/splinterd.toml
Open the new config file in your editor of choice.
$ sudo vi /etc/splinter/splinterd.toml
Find and uncomment the
node_idline. Add a short name to identify your node. It should look similar to the below.
... # Identifier for this node. Must be unique on the network. This value will be # used to initialize a "node_id" file in the Splinter state directory. Once # node_id is created, the value in the configuration below must match the # contents of node_id. If they differ, splinterd will not start. node_id = "coolnewnode" ...
Next, find and uncomment the
registriesline. This file doesn’t exist yet, but we’ll create it in a later step.
... # Splinter Registry file registries = ["file:///etc/splinter/registry.yaml"] ...
Save the file and exit.
Splinter uses public/private keys to sign all transactions that affect shared state. We can easily generate them with the
splinter keygencommand. The key directory and key name default to the user running the command, so your output will look slightly different than below.
$ splinter keygen Writing private key file: /home/username/.cylinder/keys/username.priv writing public key file: /home/username/.cylinder/keys/username.pub
If there will be multiple operators of this node, you may want to write the keys to a shared location that everyone has access to.
$ splinter keygen --key-dir /foo/shared_dir shared_key Writing private key file: /foo/shared_dir/shared_key.priv writing public key file: /foo/shared_dir/shared_key.pub
These keypairs will be used as part of your identity on your Splinter node. It should be treated like a password and backed up securely. If you lose access to this key, you may lose access to data.
The Splinter daemon also requires a public/private key pair to be used for identification when using challenge authorization. The key is stored in the config directory and the key name defaults to
splinterd. Multiple system keys can be generated and all will be added to the daemon.
$ sudo splinter keygen --system --group splinterd Writing private key file: /etc/splinter/keys/splinterd.priv writing public key file: /etc/splinter/keys/splinterd.pub
Configure REST API authorization
The Splinter REST API is secure by default and will not accept any unauthorized requests. Adding a public key to the
allow_keysfile is the quickest way to configure authorization.
$ sudo bash -c "cat /home/username/.cylinder/keys/username.pub > /etc/splinter/allow_keys"
Create a registry file
A Splinter registry (or just “registry”) is a list of nodes that can be browsed (and sometimes directly managed) by an administrator. We’ll walk through creating a registry file containing the infromation for your new node. Later when you’re creating a circuit with another administrator you can provide them with this file to add to their registry.
Copy the example registry file into place. Copy the example registry file into place. Make sure to include the
-pflag or you may encounter and error trying to start
$ sudo cp -p /etc/splinter/registry.yaml.example /etc/splinter/registry.yaml
Display the value of your public key. This will be used by other nodes to verify the identity of your node.
$ cat /home/username/.cylinder/keys/username.pub 02381b606ac2bbe3bd374654cb7cb467ffb0225eb46038a5ec37b43e0c2f085dcb
Make note of this value as we’ll be using it in the next step.
$ sudo vi /etc/splinter/registry.yaml
Delete the existing example registry information and add your node’s information.
- identity: "coolnewnode" # Use the value of node_id in your config file endpoints: # At least one endpoint is required - "tcps://126.96.36.199:8044" # The public address and port where your node will be available. Port 8044 is the default. display_name: "coolnewnode" # Use the value of node_id in your config file keys: # At least one key is required - "000000000000000000000000000000000" # Replace with your public key metadata: # Additional metadata. Can be empty. company: "Cool Corp"
Save the file and exit.
An in-depth walkthrough of the Splinter registry can be found here.
$ sudo systemctl start splinterd
View the logs to see splinterd has started.
$ sudo journalctl -u splinterd
Edit the systemd defaults file (optional)
You can adjust the behavior of splinterd by adding flags or options to the systemd defaults file. A full list of splinterd options and flags can be found here. We’ll increase the logging verbosity as an example.
$ sudo vi /etc/default/splinterd
Uncomment the variable and add flags.
... # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. SPLINTERD_ARGS="-vv"
splinterdso the changes take effect.
$ sudo systemctl restart splinterd
View the logs again.
$ sudo journalctl -u splinterd
Started Splinter Daemon. T[main] DEBUG [splinterd] Loading config toml file: "/etc/splinter/splinterd.toml" T[main] DEBUG [splinterd::transport] Using client certificate file: "/etc/splinter/certs/client.crt" T[main] DEBUG [splinterd::transport] Using client key file: "/etc/splinter/certs/private/client.key" T[main] DEBUG [splinterd::transport] Using server certificate file: "/etc/splinter/certs/server.crt" ...
Error occurred building config object
If you see
error occurred building config object: Permission denied
(os error 13): error when starting splinterd, your config file has incorrect
ERROR [splinterd] Failed to start daemon, error occurred building config object: Permission denied (os error 13): /etc/splinter/splinterd.toml
chown to correct the permissions.
$ ls -al /etc/splinter/splinterd.toml -rw-r----- 1 root root 2104 Jun 22 22:02 /etc/splinter/splinterd.toml $ sudo chown root:splinterd /etc/splinter/splinterd.toml $ ls -al /etc/splinter/splinterd.toml -rw-r----- 1 root splinterd 2104 Jun 22 22:02 /etc/splinter/splinterd.toml
Failed to initialize store factory
Failed to start daemon, unable to start the Splinter daemon: unable to set up storage: Failed to initialize store factory: Database file '/var/lib/splinter/splinter_state.db' does not exist
splinter database migrate to initialize a Splinter database.
Failed to add read-only LocalYamlRegistry
Failed to add read-only LocalYamlRegistry '/etc/splinter/registry.yaml': Failed to open YAML registry file
Permissions on your registry file may be incorrect. Run
chown to correct the
-rw-r----- 1 root root 2104 Jun 22 22:02 /etc/splinter/registry.yaml $ sudo chown root:splinterd /etc/splinter/registry.yaml $ ls -al /etc/splinter/splinterd.toml -rw-r----- 1 root splinterd 2104 Jun 22 22:02 /etc/splinter/registry.yaml