Scuttlebutt

Secure Scuttlebutt (SSB) is a peer-to-peer append-only messaging system on top of which a variety networking applications can be built such as the Patchwork social network. Scuttlebutt is able to operate offline and then sync when in the presence of another peer making it perfect for meshing environments, and even supports synchronisation via removable media to work as a "sneakernet". The word "scuttlebutt" is the equivalent of "watercooler" in an office, but applies to boats and ships.

The layers of Scuttlebutt

	Scuttlebutt, aims to provide a platform that is wholly modular, increasingly secure, and brilliantly inspired in order to tackle some of the roots of these problems and make the internet truly ungovernable.
	— Emmi Bevensee

Pubs

Pubs are permenantly connected peers in the Scuttlebutt network with the job of routing messages and storing them while recipients are offline. The name "pub" was used since they play a similar role to pubs in villages. Once you have scuttlebot running (see next section) you can configure it to be a pub simply by creating invites to it. see how to set up a pub for more detail.

A list of some of the pubs can be found here, and I set up ssb.organicdesign.pub to learn more about the process :-)

Updating the pub Docker image

First pull the latest images:

docker pull ahdinosaur/healer
docker pull ahdinosaur/ssb-pub

Then if an upgrade happened, first get the list of currently running containers and their images with docker ps, stop the current sbot container with docker stop <comtainer-id>, delete the container with docker rm <container-id> then delete the old image that container was using with docker rmi <image-id>. Then you can start the new image using the docker run command shown below, or using your create-sbot script which contains that command.

Scuttlebot

The easiest way to use Scuttlebutt is by running an end-user application like the Patchwork desktop client, or the Manyverse Android client, which will come pre-packaged with the necessary dependencies. But to run it on a server you need to install the scuttlebot (sbot) service.

If you want safely to run it on an exiting server and avoid version conflicts or other dependency issues, you can use the Docker image as described here. The default port that the pub will run on is 8008. To run it natively you can install the latest version of nodejs or use an existing version if you have one.

cd ~
sudo apt-get install autotools-dev automake
git clone https://github.com/ssbc/scuttlebot.git
cd scuttlebot
npm i
sudo ln -s ~/scuttlebot/bin.js /usr/bin/sbot
sbot server &
sbot whoami

sbot commands

If you're running the Docker image, you can't call the 'sbot daemon directly, you call it as follows instead:

To start it:

docker run -d --name sbot -v /home/USER/ssb-pub-data/:/home/node/.ssb/ -e ssb_host="YOUR-DOMAIN" -p 8008:8008 --restart unless-stopped --memory "800m" ahdinosaur/ssb-pub

Note: it's a good idea to put this command into a create-sbot script so you can run it easily after upgrades etc.

To be able to call the sbot command, you can create a script to call the Docker image with the passed arguments, e.g.

#!/bin/bash
docker exec -it sbot sbot $*

Find the pubs Scuttlebutt ID:

sbot whoami

Create an invitation to your pub (the number is how many times it can be used):

sbot invite.create 1

Note: To allow a web page to get invitations when sbot is in a Docker container, the page must NOT have the -it (interactive terminal) part in the command.

Give your pub a name:

sbot publish --type about --about @2mIg...5519 --name foobar.com

See more on updating profiles such as adding an image here, note that you can also add a --description field.

Posts:

sbot publish --type post --text "This is a test!"

To block someone from the pub, first unfollow them then block:

sbot publish --type contact --contact @...5519 --no-following
sbot publish --type contact --contact @...5519 --blocking

Plugins

Scuttlebot is extendable via a plugins model. Plugins are managed using the plugins commands in a running scuttlebot, e.g. to add the capability to send private encrypted messages, use the following:

sbot plugins.install ssb-private

JavaScript

To access the full functionality of sbot, commands need to be called from JavaScript. This is simply a matter of requiring the ssb-client, for example to send a private message (which can't be done from the command-line) you can use the following basic script which resides in the scuttlebot directory:

#!/usr/bin/env node
var ssbClient = require('ssb-client')

// Creates a client at localhost:8080, using key found at ~/.ssb/secret
ssbClient(function (err, sbot) {
	if (err) throw err

	// publish a private message to me
	sbot.private.publish({ type: 'post', text: 'My First Private Post!' }, ['@WeZBYERzjvfOVlgU7vMz7RSheqe4WaGEd87ewbMvnvQ=.ed25519'], function (err, msg) {
		console.log(msg);
	})

	// Stop the client
	sbot.close();
});

sbot troubleshooting

Node user: The Docker container seems to require some hard-wired paths involving the "node" UNIX account. I installed it in my own home directory as myself, and things kept failing due to missing files in /home/node, so I just made a symlink from /home/node to my own user dir and then things worked.

Calling sbot from web pages: Again this only affects Docker users, the recommended command to call sbot shown in the installation guide uses the -it (interactive terminal and TTY) options, but these will only work when you are running it from a shell and need to be removed if calling it from a web page (or a background task or something).

Dealing with problem plugins: You might install a plugin (with sbot plugins.install <PLUGIN>), but it turns out to have errors on startup which means the container can't start so you can't call sbot again to remove the plugin! You can edit the plugins manually since they are persistent data outside of the container which is transient. Plugins are listed in the config file in the root of the ssb data directory. You can nuke the container, remove the plugin from the list or set it to false, then run a new container.

Pruning the data directory: The data in a pub is really just a non-essential cache for the network, so data can be pruned without concern. old-files-purge.pl is a script that allows the recursive nuking of files in a directory structure older than a specified age.

Differences between Scuttlebutt and...

Retroshare

Retroshare has the features all inclusive in the application, requires explicit key sharing between people in order to exchange data, does not use rumor message passing, and does not use pubs as an on-ramp (or slip road) to the network. This was a few years ago, but the process of creating and sharing your key with another person in order to share things with them was far more difficult than using SSB. Also according to the outdated wiki, Retroshare does not support IPv6.

Projects based on ssb protocol

• LocalNative.app - a note/bookmark taking tool to save your notes in a local sqlite database, synced with other devices via ssb
• Bluetooth sync for Manyverse

See also

• Scuttlebutt FAQ
• Scuttlebutt viewer website
• List of Scuttlebutt users also on Twitter
• Intro to git-ssb for GitHub users
• Andre Staltz describing the structure of ssb at Fullstck Fest 2018
• Working example of ssb wiki idea
• How to use the same Scuttlebutt identity on multiple computers