Documentation > Getting Started >> edit on GitHub

Getting Started

This section explains how to run register with the Fabric Center online service (CFC), get and run a Fabric instance, pair that instance with the Fabric Center service, as well as some basic example configuration actions.

Basic Concepts

You register with the CFC via the Fabric Shell. This also handles the authentication for the examples contained in this repository.

Open source versions of cannot connect to the CFC. This requires a closed source version, Fabric.

Within the CFC, you can create multiple management realms (but need to create only a single one initially). Fabric nodes connect to a specific management realm.

You can then access and manage the Fabric nodes via the CFC API.

The Fabric Shell as well as the included example code use this API.


You will need

installed on your machine.

Everything here assumes a Linux/*nix machine. (Things may work on other systems, but are not tested by us.)

Fabric Nodes

Running nodes

We provide a Docker image of Fabric.

Start a Fabric Docker container which connects to the CFC:

docker run -it --rm \
    -v ~/.cbf/test_01:/node \
    --entrypoint=/usr/local/bin/crossbar \
    crossbario/crossbar-fabric:latest \
    start --personality fabric --cbdir /node/.crossbar/

Note: above will pull the Fabric Docker image for x86-64. For ARM (32 bit) based devices like the Pi, use the crossbario/crossbar-fabric-armhf image. For ARM 64 bit based devices, use the crossbario/crossbar-fabric-aarch64 image.

As the node is started the first time, a new node public/private key pair is generated and stored in the directory we give (test_01 - parts of the path which don't exist yet are created).

This key pair is then used when authenticating to CFC.

The node public key needs to be assigned to a management realm ("paired").

Pairing a node with a management realm can be done via Fabric Shell and programatically via the CFC API today, and we are working on a Web user interface.

Checking version

To check the software version of Fabric:

ubuntu@cb-eu1:~$ docker run -it --rm \
    --entrypoint /usr/local/bin/crossbar crossbario/crossbar-fabric version --loglevel=debug
     __  __  __  __  __  __      __     __
    /  `|__)/  \/__`/__`|__) /\ |__)  |/  \
    \__,|  \\__/.__/.__/|__)/~~\|  \. |\__/        : 17.9.2 ( FABRIC)
   Autobahn         : 17.9.1 (with JSON, MessagePack, CBOR, UBJSON)
     txaio          : 2.8.2
     UTF8 Validator : autobahn
     XOR Masker     : autobahn
     JSON Codec     : stdlib
     MsgPack Codec  : u-msgpack-python-2.4.1
     CBOR Codec     : cbor-1.0.0
     UBJSON Codec   : ubjson-0.9.0
   Twisted          : 17.5.0-EPollReactor
   LMDB             : 0.93/lmdb-0.9.18
   Python           : 3.6.2/CPython Fabric : 17.9.1
 OS                 : Linux-4.4.0-1032-aws-x86_64-with
 Machine            : x86_64
 Release key        : RWRj+Sb8UH/pwLCycZ+3OroR5UV9aaLUDVbKxNcj+gYoOOZv0LrzMH1a

Fabric Shell Fabric Shell is a management client Python package that includes

  • an interactive management shell
  • a management client library

We'll go throught the steps of

  • installing the shell
  • creating a CFC user account
  • pairing the Fabric node we just started
  • getting basic information about this node


To install Python 3 and virtualenv (on Debian/Ubuntu):

sudo apt-get install -y python3 python3-pip python3-venv

To install, create a new dedicated Python virtualenv, activate it and install Fabric Shell from PyPI in there:

virtualenv ~/.cbsh
source ~/.cbsh/bin/activate
pip install crossbarfabricshell

Note: we do not recommend installing cbsh into a Python environment shared with other applications, or shared system wide. cbsh is well packaged and follows best practices, but we cannot support all combinations of dependencies. A Python virtualenv comes with a good compromise for isolation versus overhead.


Now register for Fabric Center by running:

cbsh auth

This will ask for an email address, to which an activation code is sent.

It will also create a pair of public an private key files and the default configuration:

(cpy362_1) oberstet@thinkpad-t430s:~$ ll ~/.cbf/
insgesamt 20
drwxrwxr-x  2 oberstet oberstet 4096 Aug 14 13:16 ./
drwxr-xr-x 94 oberstet oberstet 4096 Aug 20 21:49 ../
-rw-rw-r--  1 oberstet oberstet   78 Aug 14 13:16 config.ini
-rw-------  1 oberstet oberstet  332 Aug 14 13:16 default.priv
-rw-r--r--  1 oberstet oberstet  227 Aug 14 13:16

Keep the default.priv private key file safe!

Once you've received the activation code, authenticate yourself by doing:

cbsh auth --code <YOUR ACTIVATION CODE>

When successful, this will print out a short welcome notice and then exit again.

For subsequent access, the shell will use the private key.

Starting the shell

Start the shell in interactive mode:


This will bring up a full screen console mode interactive shell.

Creating a Management Realm

To create a CFC management realm for your CF nodes, start cbsh and enter

create management-realm <realm-name>

Here, chose a <realm-name for your management realm. The name must be unique globally within CFC.

Pairing a node

To pair a CF node to a management realm, start cbsh and enter

pair node <public-key> <realm-name> <node-id>

Your node's public key Hex value (to use as ) is printed to the log when the node starts.

Use the name of the management realm you just created for <realm-name>.

Finally, chose a <node-id> the node should be assigned to. The node ID needs to be unique within the management realm

Once the pairing is shown as successful in the shell, restart the node to complete the pairing (same command as for initially starting it).

Managing the node

The Fabric Shell is still mostly under construction, so for the time being you need to access the Fabric service API from code.

Clone the git repository containing the example code by doing

git clone

or download this if you don't have git installed.

In the repo directory (and with the virtualenv into which you've installed the Fabric Shell activated), run a first example

mmake ex_list_nodes realm=<realm-name>

which should return something like

python3 -u examples/ --url "wss://" --realm goeddea_test_01 --keyfile /home/goeddea/.cbf/default.priv
2017-09-08T15:42:38 Node "test_02" is online:

{'controller_pid': 1,
 'directory': '/node/.crossbar',
 'has_docker': False,
 'management_node_extra': None,
 'management_node_id': 'test_02',
 'management_realm': 'goeddea_test_01',
 'management_session_id': 3487657792610076,
 'pubkey': '7f65d857179a2805b6a9f02c44bf3a85fd6567b17e3d786b914d37df234ca18a',
 'running_workers': 1,
 'started': '2017-09-08T13:41:59.018Z',
 'title': ' FABRIC 17.9.2'}

For other examples, see the Examples Overview

Community Chat