Home

Awesome

ssb-config

This module helps you to generate and manipulate the startup configuration for an ssb-server.

Table of contents

Example usage | Api | Configuration | License

Example usage

This is the most use basic use case where it is not necessary to modify any configuration parameters.

var Server = require('ssb-server')
var config = require('ssb-config')

var server = Server(config)
server.whoami((err, feed) => {
  console.log(feed)

  server.close(() => console.log('closing the server!'))
})

If you want to change the default values you can use inject to overwrite them, without having to specify all the settings. For example you can setup a test network that doesn't collide with the main ssb network:

var Server = require('ssb-server')
var Config = require('ssb-config/inject')

var config = Config('testnet', { port: 9999 })

var server = Server(config)
server.whoami((err, feed) => {
  console.log(feed)

  server.close(() => console.log('closing the server!'))
})

API

require('ssb-config')

Returns you the stock standard config for starting an ssb-server.

require('ssb-config/inject')(appName, opts) => Object

A function which takes:

Configuration

All configuration is loaded via rc. This means the final config is a result of config collected from opts passed into the inject method, cli args, env var, and config (e.g. ~/.ssb/config). See the rc repo for full details.

Options

Deprecated Options

You should use connections to more explicitly configure connections. These values are currently only used to generate connections.incoming if that option isn't provided. The raw options are no longer returned in the final config - this is to ensure we don't have multiple places where different host / port / ws are being set!

connections

An object with two required properties: incoming and outgoing to specify transports and transformations for connections. Defaults to the following:

{
  "incoming": {
    "net": [{ "port": 8008, "scope": "public", "transform": "shs" }]
  },
  "outgoing": {
    "net": [{ "transform": "shs" }],
    "onion": [{ "transform": "shs" }]
  }
}

It specifies the default TCP network transport for incoming and outging connections, using secret-handshake/boxstream (shs) for authentication and encryption.

A transport is a vehicle or avenue for communication. The following transports are currently supported:

Each transport can have an array of different configurations passed to it, these are objects with properties:

Scopes

An address scope is the area from which it's possible to connect to an address.

Some protocols only work in particular scopes. unix socket requires file system access, so it only works for the device scope. onion (tor) routes connections through a distributed network, so it only works if you are fully connected to the public internet. Some mesh networks are really large, so they might seem public. Some overlay networks, such as cjdns and ZeroTier create a fake local network that is publically accessible (these should be manually configured as public addresses!).

Most ssb peers just have a local and device scopes. Pubs require a public scope. ssb-tunnel allows any peer to have a public address, by routing connections through a friendly pub.

Addresses for scopes are provides secret-stacks getAddress(scope) method, which in turn calls multiservers stringify(scope) method.

Example connnections configurations

If you only want to use Tor to create outgoing connections you can specify your outgoing like this. It will use localhost:9050 as the socks server for creating this.

{
  "incoming": {
    "net": [{ "port": 8008, "scope": "public", "transform": "shs" }]
  },
  "outgoing": {
    "onion": [{ "transform": "shs" }]
  }
}

If you want to run a peer behind NAT or other kind of proxy but still want ssb-server to be able to create invites for the outside address, you can specify a public scope as your incoming.net by defining the external parameter like this:

{ 
  "incoming": {
    "net": [
      { "scope": "public",  "external": ["cryptop.home"], "transform": "shs", "port": 8008 },
      { "scope": "private", "transform": "shs", "port": 8008, "host": "internal1.con.taine.rs" },
    ]
  },
  "outgoing": {
    "net": [{ "transform": "shs" }]
  }
}

One thing to notice is that you need incoming connections for Apps (like patchwork or git-ssb) to function. By default they use the same authentication mechanism (shs) to grant access to the database, choosing access levels depending on the keypair that opens the connection. If you connect to yourself, you get full access (query and publish). If a remote peer connects, it can only replicate. So be sure to have at least one incoming connection.

That being said, the overhead of encryption for local applications can be very high, especially on low-powered devices. For this use-case there is a noauth transform which by-passes the authentication and grants full access to anybody that can connect to it. hint: This is risky! it might expose private messages or enables people to publish as you! Therefore be sure to bind the listener to localhost or use the unix socket. The unix file socket is created as $HOME/.ssb/socket by default and has permissions such that only the user running ssb-server start can open it, just like the $HOME/.ssb/secret file.

{ 
  "incoming": {
    "unix": [{ "scope":"device", "transform":"noauth" }],
    "net": [{ "scope": "device", "transform": "noauth", "port": 8009, "host": "localhost" }]
  },
  "outgoing": {
    "net": [{ "transform": "shs" }]
  }
}

The local plugin inside ssb-server will use the first incoming connection of either public or private scope.

gossip

Set which sorts of gossip connections are permitted:

For example, allow only gossip connections with peers found on the same local network as you, but prioritize connections with friends:

{
  gossip: {
    connections: 3,
    local: true,
    friends: false,
    seed: false,
    global: true
  }
}

License

MIT