_                      _
| |_   __ _  _ __ ___  | |_   __ _  _ __ ___
| __| / _` || '_ ` _ \ | __| / _` || '_ ` _ \
| |_ | (_| || | | | | || |_ | (_| || | | | | |
 \__| \__,_||_| |_| |_| \__| \__,_||_| |_| |_|

Introduction

TamTam is a utility that provides a command line and gRPC interface to Smudge.

TamTam allows you to create a decentralized cluster on top of an IP network (both IPv4 and IPv6 are supported). It has a similar but simplified function as Serf but uses only UDP which allows it work over, for example, a Thread network.

TamTam uses the Smudge library that provides group member discovery, status dissemination and failure detection to the cluster. Smudge implements the SWIM protocol (paper) (explained 1) (explained 2).

Getting the binary

Binaries are automatically being build by the CI/CD pipeline on each release and can be downloaded from the releases. There are also cross-platform docker images available.

But you can also build your binaries from source.

Command line interface

TamTam has the following options and commands:

Options

      --config string   Config file (default is $HOME/.tamtam.yaml)
  -h, --help            help for tamtam
      --nobanner        disables printing the banner
      --rpc string      The RPC address the agent binds to or other commands query a running agent on (default "localhost:6262")
      --trace           turn on trace logging
      --verbose         turn on verbose logging

Commands

• tamtam address - Gets the local bind address of a running agent
• tamtam agent - Starts a TamTam agent.
• tamtam broadcast - Broadcasts a message to other nodes in the network
• tamtam configure - Configure a running agent
• tamtam gendoc - Generates markdown docs for TamTam
• tamtam healthy - Displays the healthy nodes in the network
• tamtam join - joins a node to the network
• tamtam leave - Removes a node from the network
• tamtam monitor - Monitors the network status
• tamtam nodes - Displays a list of known nodes in the network
• tamtam ping - Pings a remote node in the network
• tamtam stream - Streams broadcast events that are received from other nodes in the network
• tamtam version - Prints the version number

Usage example

In the example below we will run 2 agents that connect to each other. We will demonstrate how to connect to the broadcast stream and how to broadcast a message in the network.

Open a terminal window and issue the following command to start a TamTam agent:

./tamtam agent

You should now see logging indicating that TamTam is running and a warning that it detected a new node (namely itself). Now lets start another agent running on another port. Open another terminal window and execute the following command:

./tamtam --rpc localhost:6363 agent -p 9998

When the second agent is also running you can ask one of the agents to join the other and after that to start listening to broadcast messages. Open another terminal and issue the following commands:

./tamtam join 127.0.0.1:9998
./tamtam stream

The first command should give you a message that the remote host was joined. The second command is waiting for broadcast messages to display. Lets send a broadcast message... Open another terminal and execute the following command:

./tamtam --rpc localhost:6363 broadcast "Hello world!"

The broadcast message should now appear stream process at the 3rd terminal window.

The next step is to bind the messages to your own process of script. This can be done by using the gRPC interface or by binding the broadcast stream to a script. Take for example the following handler.sh bash script:

#!/bin/bash
while read msg; do
    printf "${msg}\n"
done

You can bind this script to TamTam using the following command:

./tamtam stream | ./handler.sh

Demo

Configuration

TamTam can be configured using a configuration file, environment variables or command line. Note that command line takes precedence over the environment variables which in their turn take precedence over the values from the configuration file.

The default location for the configuration file is $HOME/.tamtam.yml but you can also specify the location via the command line option --config. Currently only a few global options can be configured using the environment or configuration file.

Example of the configuration file:

nobanner: false
verbose: false
trace: false
rpc: "localhost:6262"

The following environment variables are supported:

Variable        | Description
--------------- | -----------------------------------------------------------------------
TAMTAM_NOBANNER | When set TamTam won't print out the banner on startup
TAMTAM_VERBOSE  | Set to enable verbose logging
TAMTAM_TRACE    | Set to enable trace logging
TAMTAM_RPC      | The host and port to bind the RPC interface to. Default: localhost:6262

gRPC interaface

The gRPC protocol is described in the protocol definition. To build an RPC client that connects to the TamTam agent please refer to the gRPC documentation for you programming language or check the source code of TamTam for golang examples. All TamTam commands, with the exception of agent and gendoc use a gRPC client to connect to the agent.

Building from source

If you feel lucky you can try go get -u github.com/servicelab/tamtam

Otherwise, you can setup the build environment by executing the following script:

cd $GOPATH
git clone https://github.com/servicelab/tamtam src/github.com/servicelab/tamtam
cd src/github.com/servicelab/tamtam
make # builds TamTam for your current architecture

You will find the TamTam binary the current folder.