The DCP Standalone Worker is Copyright © 2017-2020 Kings Distributed Systems, All Rights Reserved.
This document is Copyright © 2020 Kings Distributed Systems, All Rights Reserved.
You may not distribute this document, the DCP Standalone Worker, nor any accompanying software nor documentation in any form without the express written consent of Kings Distributed Systems.
Note: Kings Distributed Systems intends to release this software product as an Open Source project at some point in the future.
The DCP Standalone Worker is an application which allows your computer to participate as a Worker (computing node) in the Distributed.Computer via DCP, the Distributed Compute Protocol.
The application resides on your host, and contacts the Distributed.Computer scheduler to request work. This work is then computed in a secure sandbox, the results are sent back to the scheduler, and DCC (Distributed Compute Credits) are deposited in the Bank account corresponding to the Worker’s identity, based on the amount of work completed.
| Date | Author | Change |
|---|---|---|
| Jan 16 2020 | Wes Garland | Initial release for CENGN |
| Jan 10 2020 | Jack Troughton | Initial draft |
The latest version of this document is available online at https://docs.distributed.computer/worker/readme.html
This product is unreleased.
The DCP Standalone Worker uses an Ethereum v3 keystore file to represent the Bank account where DCCs will be deposited as they are earned.
By default, the worker looks for this file as /opt/dcp/.dcp/default.keystore; this can be overridden on the command-line. During installation, an Ethereum v3 keystore corresponding to an unused Bank account will be created for you if one doesn’t already existing at that location.
If you already have an account on the Distributed.Computer, you can download a keystore for your Bank account from the Wallet page at https://portal.distributed.computer/#Accounts.
If you are a managing a large deployment and wish to have all earned DCC deposited into a single Bank account, we suggest creating a new Bank account on the Distributed.Computer web portal with an empty passphrase, downloading this keystore file, and copying it to each host in your deployment. Once the workers are working, funds can be moved from the deposit account into another account for safe-keeping.
The use of the linux text mode DCP worker requires node.js version 10 to be installed. We recommend installing the latest version of node.js version 10 LTS: at the time this document was written that is version 10.18.
In order to install this software, you will need to have administrator privileges on the system; if you don’t have administrative privileges, please consult your system administrator.
Here is a short summary of how to install node.js version 10; if you run into problems we recommend visiting http://nodejs.org/ and following the instructions there to install node.js version 10.
You will require a download tool; if curl is not installed on your system we recommend issuing the following command to have it and its dependencies installed:
sudo apt install curl
Once curl is installed, you can download and directly execute the script that will set up nodejs.org’s apt repositories for you with the following command:
curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
Next,
sudo apt install nodejs
should result in the proper version of node installed on your system.
Coming Soon.
Locate the appropriate .deb file at http://archive.distributed.computer/releases/linux/debian, download it to your local computer, and either let your browser launch it, or invoke the following command from the terminal:
sudo dpkg -i <path to deb file>
Workers are configured by files in /opt/dcp/etc. The default configuration file is called dcp-default-config.js and should not be modified; this file will be replaced during future updates to the worker. This file holds the default values for each of the configuration options for the worker.
Any of the options in the dcp-default-config.js file may be overridden creating the file /opt/dcp/etc/dcp-site-config.js, using JavaScript object syntax. When the worker starts it will first read in all the settings in dcp-default-config.js, and then read the dcp-site-config.js file; any options in there that match any of the options in dcp-default-config.js will have their settings updated to the one in dcp-site-config.js. Any customized configuration should be placed in dcp-site-config.js.
We don’t recommend changing anything other than the URLs for the bank, package manager, scheduler, and standaloneWorker.
{
scheduler: {
location: url('https://scheduler.distributed.computer/'),
},
bank: {
location: url('https://bank.distributed.computer/'),
},
packageManager: {
location: url('https://packages.distributed.computer/'),
}
}
When changing the standaloneWorker configuration, it is important that the listen address and locations match; otherwise, the Worker will be unable to locate the Evaluator when it needs to create Sandboxes.
{
standaloneWorker: {
listen: url('tcp://localhost:9009/'),
location: url('tcp://localhost:9009/')
}
}
There are other options; please be aware that changing them may result in the worker being rejected by the Scheduler, so be sure that the workers are monitored after changes are made.
Configuration changes can be verified using the get-config-value.js utility. This utility parses the dcp configuration files the same was as dcp-worker.js and inet-daemon.js, printing values requested to stdout. Passing the value --all prints the entire derived configuration.
# sudo --user=dcp /opt/dcp/bin/get-config-value.js inetDaemon.standaloneWorker.net.listen.port
9000
The worker will log to syslog facility local7.
Linux systems using systemd to run the dcp services emit log entries via to journalctl via their appropriate service units.
journalctl -u dcp-inet-daemonAdditionally, using the `-f` switch on `journalctl` will allow the system operator to view progress messages. --since='10 minutes ago'
journalctl -u dcp-sa-worker --since='10 minutes ago'
These journals will contain any uncaught exceptions, which should offer clues to help troubleshooting crashes and failures to start.
The DCP Standalone Worker is generally configured as a system service, with the operating system’s scheduler deciding how to schedule its access to CPU resources. The Worker itself consists of two components:
The Sandbox listens on a tcp/ip port; the default is port 9000. If your environment uses port 9000 for something else, you will have to alter the standaloneWorker.location and standaloneWorker.listen properties in your site configuration file.
Systemd is the default system service launcher for Ubuntu Linux.
When installed via the Debian package, the DCP Workerconfigured as a systemd service. Upon installation, the files dcp-sa-worker.service and dcp-inet-daemon.service
are created in /var/opt/dcp/etc; these files are then copied to /etc/systemd/system and systemd is configured to start them at launch.
Any customizations to how you want the worker to run should be made in the files
found in /etc/systemd/system.
In some circumstances, it may be desirable to launch the Worker from the command-line; in particular, in the case when a passphrase-protected keystore is used in order to determine the deposit address for the bank account. In the case, the inet-daemon.js program must still run as a service, in order to make Sandboxes available to the Worker.
sudo --user=dcp /opt/dcp/bin/dcp-worker.js start /opt/dcp/.dcp/default.keystore
The DCP Worker does not need any administrative privileges, we recommend always running it as an unprivileged user.
On Linux / UNIX / macOS, a new user is created during installation to own the worker and sandbox processes; this worker is named dcp. Under no circumstances should this user be placed into any group that may permit privilege escalation.
The Worker Process is a NodeJS program, which executes software found on npmjs.org and https://portal.distributed.computer.
The NPM software is updated at package install time, and at no other time. Updating the NPM software manually is not recommended; if a security vulnerability is uncovered which affects the versions of the modules used by the DCP Standalone Worker, Kings Distributed Systems will publish an updated version ASAP.
The Sandbox is JavaScript program running in a program known as “the evaluator”, which in turn embeds Google’s V8 engine. The V8 engine is the same JavaScript engine that powers Google Chrome and other web browsers.
The evaluator a very simple program which exposes only core JavaScript – no DOM, no disk I/O, no nSee: setpriority(2)
etwork I/O. In order to communicate with the Supervisor, via inet-daemon.js, Kings Distributed Systems has added the following functions to this engine (and no others):
The full source code to the evaluator will be published on http://github.com/.
The default.keystore file used by the Worker identifies a Bank account. The DCP Standalone Worker needs to know the public address of the Bank account in order to deposit money to it, however, this keystore also contains the encrypted private key, which would allow a malicious user who has access to both the keystore and the passphrase to withdraw money from the bank account. (Note: this will be changing soon in an update, to help system administrators improve security on multiuser systems).
It is possible to upload a keystore file from your system to your portal account on the Distributed.Computer. To do this, visit the portal at https://portal.distributed.computer/, sign in, and click on the Accounts link under Wallet. At the top-right corner of the screen is an option labelled ‘Upload Keystore’. Once the keystore has been uploaded, that Bank account will be associated with your portal account, and you will be able to see the number of DCCs earned by doing work with Workers using that keystore.
Remember that keystores contain both the public address of the Bank account, and the corresponding private key. Anyone who knows the public address can deposit money into the Bank account. Anyone who knows the private key can withdraw funds from the Bank account.
The private key is encrypted with a passphrase. Changing the passphrase on the keystore which is stored in the portal wallet does not change the passphrase on the keystore which is stored on your local disk.
The DCP Worker distribution ships with a utility, mkad.js, which can be used to manipulate the keystores stored on your local disk.
It is important to remember that Ethereum v3 keystores are non-revocable. This means that if a keystore and its passphrase are ever compromised, that Bank account should be considered permanently compromised; funds should be moved immediately from it into a new Bank account, workers should stop depositing money into it, and it should be deleted from your Wallet in the portal.
The DCP Standalone Worker will do its best to consume all possible resources allocated to it via the system scheduler. It is recommended that machines which are not dedicated to DCP work are configured to run the Worker at a low priority, such as nice level 18 on unices.
The Sandbox process are started by and children of the inet-daemon.js program, which is included in this distribution. Changing the priority assigned to this process has the most dramatic effect on the system load used by the worker.
It is not a problem if the system scheduler does not give any timeslices at all to the Sandboxes, nor if it kills them outright; DCP is designed with the idea that workers appear on and disappear from the network on a regular, ad-hoc basis.
Note: It is possible to replace inet-daemon.js program with the familiar inetd or xinetd utilities if desired.
By default, the DCP Standalone Worker will start N-1 Sandboxes, where N is the number of cores it can detect on the underlying hardware. Selecting a number which is smaller than this will reduce the income potential of the host, but may help it to operate more efficiently on a non-interference basis.
In addition to the traditional Unix nice levels, systems with systemd have addtional tools to manage process scheduling, including the following directives in /etc/systemd/system/dcp-inet-daemon.service:
Nice=18
See: setpriority(2)
or
CPUSchedulingPolicy=idle
CPUSchedulingPriority=2
CPUSchedulingResetOnFork=false
The DCP Worker requires the following in order to operate correctly:
/opt/dcp/.dcp/default.keystore.inet-daemon.js must be running, and able to listen on its designated interface/port (default: localhost:9000)inet-daemon.js program must be able to launch /opt/dcp/libexec/sa-worker-control.js processes.To verify that the Worker is working properly, the system administrator can check the log file (see: Logging) and/or check their Bank account balance from the Distributed Computer portal (see: Keystores and Bank Accounts).
To troubleshoot the Worker in the case where reading the log files does not help, we recommend running it from the command-line and observing its behaviour first-hand. (See: Launching from the Command-line, under Service Configuration).
It may also be beneficial to try to “speak” directly to the Evaluator, emulating what the Worker does to create Sandboxes. You can use the utility “netcat”, which ships with most Linux distributions as nc:
# nc localhost 9000
{"type":"die"}
DIE: Thu Jan 16 2020 09:06:55 GMT-0500 ()
MSG:{"type":"result","step":"die","success":true,"origin":"die"}
In the example above, we issued the command {"type":"die"}, which tells the sandbox to exit after we press enter one more time. The Evaluator responded with the lines beginning with DIE and MSG to confirmation receipt of the command. Nearly any other input will print an error on the screen, without closing the socket.