Grenache CLI

• Introduction
• Copying
• Prerequisites
• Install
• Initialize
• Store items to the DHT
  • Immutable items
  • Mutable items
• Retreive items from the DHT
• Lookup peers
• Announce services
• Maintainers

Introduction

The Grenache Command Line Interface is a set of tools to use the grenache-grape suite directly from your command line. Using this set of tools you can create fancy scripts that communicate directly with the DHT.

Copying

The Grenache Command Line Interface is free software. See the files whose names start with LICENSE (case-insensitive) for copying permission. The manuals, and some of the runtime libraries, are under different terms; see the individual source files for details.

Copyright years on Grenache Command Line Interface source files may be listed using range notation, e.g., 2017-2021, indicating that every year in the range, inclusive, is a copyrightable year that could otherwise be listed individually.

Prerequisites

Be sure that your version of grenache-grape supports the mutable items (see pull request #35).

Install

Briefly, the shell command

./configure && make && make install

should configure, build and install this package.

Initialize

Before start using this set of tools you need to initialize the granache-cli environment; use:

grenache-keygen

This will also generate your key pair that will be used when mutable items are stored to the DHT. This is a one time only task but you can regenerate your key pair at any time if you want to.

Store items to the DHT

The grenache-put command writes an arbitrary payload to the DHT (see BEP 44 for more information). There are two types of items you can store to the DHT; the immutable items and the mutable ones. In any case, you will get the key under which the item has been stored.

Immutable items

Immutable items cannot be modified, thus there is no need to authenticate the origin of them. This makes immutable items simple. To write an immutable item to the DHT simply run something like this:

grenache-put "$(uname -n)"

Mutable items

Mutable items can be updated, without changing their DHT keys. In order to create your key pair, see grenache-keygen. To write a mutable item to the DHT simply run something like this:

grenache-put --mutable "$(uptime -p)"

In order to support a single key being used to store separate items in the DHT, an optional salt can be specified in the put request of mutable items:

grenache-put --mutable --salt 'sys:mem:available' "$(awk '/^MemAvailable:/ { print $2 "Ki" }' < /proc/meminfo)"

Note that grenache-put is agnostic and it will treat your payload as a single string. Other useful options are -n or --number that will let you set the sequence number to use in your request and -c or --cas that let you use the compare and swap feature. See

grenache-put --help

to retrieve the complete options list.

Retreive items from the DHT

The grenache-get command reads a data record from the DHT (see BEP 44 for more information). There is no differences in retreiving a mutable or an immutable item; in both cases the key returned by the PUT request must be provided. Furthermore, starting from version 0.9.6 of grenache-grape, the salt specified during the PUT operation must be provided if used. In any case, grenache-get validates the payload it receive; this will ensure that the key provided really match the payload and, in case of a mutable item, that the signature is correct. This will protect you from evil nodes on the network. To read an item from the DHT simply run something like this:

grenache-get '81c2a8157780989af9a16661324fafbd7803877d'

For example, you can format the previously stored available memory amount using something like this:

numfmt --from=auto --to=iec-i < <(
   grenache-get --salt 'sys:mem:available' '633def0b4349e2ed5bfbe0a5a1bb34e622f8c20d'
)

You can also retrieve the raw packet received from the network using the -r switch or its long form --raw. See

grenache-get --help

to retrieve the complete options list.

Lookup peers

The grenache-lookup command finds peers that expose the supplied service identifier. To find a random peer that provides the rest:net:util service simply run something like this:

grenache-lookup 'rest:net:util'

For example, you can check the platform status on each peer that exposes the rest:api:v2 service using something like this:

for authority in $(grenache-lookup --all 'rest:api:v2'); \
do \
  curl --write-out '\n' "http://${authority}/v2/platform/status"; \
done

You can also pick the first peer in list using the -f switch or its long form --first. See

grenache-lookup --help

to retrieve the complete options list.

Announce services

The grenache-announce command announces the given services in order to be stored in the DHT. To announce the rest:net:util service on port 31337, simply run something like this:

grenache-announce 'rest:net:util,31337'

If no services are specified, grenache-announce enters the streaming mode, reading the standard input. All comments (marked by a # or ;) and blank lines are ignored. For example, a list of services can be announced using something like this:

grenache-announce <services.lst

An announce service can also be created using a named pipe:

mkfifo --mode=0622 /run/grape/announce && \
  grenache-announce <>/run/grape/announce

Storing a service in the DHT now simply requires something like this:

echo 'rest:net:util,31337' >/run/grape/announce

A JSON stream can also be required (perhaps to implement a network service with something like tcpserver) using the -j switch or its long form --json. The JSON document must contain a data array in which the first position is the service name while the second is the port number. Another useful option is -d or --delimiter which allows you to set the delimiter string between the service name and port number when not using JSON mode. See

grenache-announce --help

to retrieve the complete options list.

Maintainers

Current maintainers:

• Davide Scola - davide@bitfinex.com