zmq: update and cleanup build-unix, release-notes, and zmq docs
Signed-off-by: Johnathan Corgan <johnathan@corganlabs.com>
This commit is contained in:
Johnathan Corgan
parent
6cebd5d854
commit
ab0b8be857
@ -1,6 +1,6 @@
|
||||
UNIX BUILD NOTES
|
||||
====================
|
||||
Some notes on how to build Bitcoin in Unix.
|
||||
Some notes on how to build Bitcoin in Unix.
|
||||
|
||||
Note
|
||||
---------------------
|
||||
@ -44,6 +44,7 @@ Optional dependencies:
|
||||
qt | GUI | GUI toolkit (only needed when GUI enabled)
|
||||
protobuf | Payments in GUI | Data interchange format used for payment protocol (only needed when GUI enabled)
|
||||
libqrencode | QR codes in GUI | Optional for generating QR codes (only needed when GUI enabled)
|
||||
libzmq3 | ZMQ notification | Optional, allows generating ZMQ notifications (requires ZMQ version >= 4.x)
|
||||
|
||||
For the versions used in the release, see [release-process.md](release-process.md) under *Fetch and build inputs*.
|
||||
|
||||
@ -59,7 +60,7 @@ Dependency Build Instructions: Ubuntu & Debian
|
||||
Build requirements:
|
||||
|
||||
sudo apt-get install build-essential libtool autotools-dev autoconf pkg-config libssl-dev libevent-dev
|
||||
|
||||
|
||||
For Ubuntu 12.04 and later or Debian 7 and later libboost-all-dev has to be installed:
|
||||
|
||||
sudo apt-get install libboost-all-dev
|
||||
@ -81,6 +82,11 @@ Optional:
|
||||
|
||||
sudo apt-get install libminiupnpc-dev (see --with-miniupnpc and --enable-upnp-default)
|
||||
|
||||
ZMQ dependencies:
|
||||
|
||||
sudo apt-get install libzmq3-dev (provides ZMQ API 4.x)
|
||||
|
||||
|
||||
Dependencies for the GUI: Ubuntu & Debian
|
||||
-----------------------------------------
|
||||
|
||||
@ -229,4 +235,3 @@ In this case there is no dependency on Berkeley DB 4.8.
|
||||
|
||||
Mining is also possible in disable-wallet mode, but only using the `getblocktemplate` RPC
|
||||
call not `getwork`.
|
||||
|
||||
|
||||
@ -46,7 +46,7 @@ caching. A sample config for apache2 could look like:
|
||||
# optional enable digest auth
|
||||
# AuthType Digest
|
||||
# ...
|
||||
|
||||
|
||||
# optional bypass bitcoind rpc basic auth
|
||||
# RequestHeader set Authorization "Basic <hash>"
|
||||
# get the <hash> from the shell with: base64 <<< bitcoinrpc:<password>
|
||||
@ -171,3 +171,11 @@ configured specifically to process scriptPubKey and not scriptSig scripts.
|
||||
|
||||
- Removed bitrpc.py from contrib
|
||||
|
||||
Addition of ZMQ-based Notifcations
|
||||
==================================
|
||||
|
||||
Bitcoind can now (optionally) asynchronously notify clients through a
|
||||
ZMQ-based PUB socket of the arrival of new transactions and blocks.
|
||||
This feature requires installation of the ZMQ C API library 4.x and
|
||||
configuring its use through the command line or configuration file.
|
||||
Please see docs/zmq.md for details of operation.
|
||||
|
||||
53
doc/zmq.md
53
doc/zmq.md
@ -1,7 +1,7 @@
|
||||
# Block and Transaction Broadcasting With ZeroMQ
|
||||
|
||||
[ZeroMQ](http://zeromq.org/) is a lightweight wrapper around TCP
|
||||
connections, inter-process communications, and shared-memory,
|
||||
connections, inter-process communication, and shared-memory,
|
||||
providing various message-oriented semantics such as publish/subcribe,
|
||||
request/reply, and push/pull.
|
||||
|
||||
@ -14,17 +14,18 @@ requesting blockchain related data. However, there exists only a
|
||||
limited service to notify external software of events like the arrival
|
||||
of new blocks or transactions.
|
||||
|
||||
The ZeroMQ facility implements a notification interface through a
|
||||
set of specific notifiers. Currently there are notifiers that publish
|
||||
The ZeroMQ facility implements a notification interface through a set
|
||||
of specific notifiers. Currently there are notifiers that publish
|
||||
blocks and transactions. This read-only facility requires only the
|
||||
connection of a corresponding ZeroMQ subscriber port in receiving
|
||||
connection of a corresponding ZeroMQ subscriber port in receiving
|
||||
software; it is not authenticated nor is there any two-way protocol
|
||||
involvement. Therefore, subscribers should validate the received data
|
||||
since it may be out of date, incomplete or even invalid.
|
||||
|
||||
ZeroMQ sockets are self-connecting and self-healing; that is, connects
|
||||
made between two endpoints will be automatically restored after an
|
||||
outage, and either end may be freely started or stopped in any order.
|
||||
ZeroMQ sockets are self-connecting and self-healing; that is,
|
||||
connections made between two endpoints will be automatically restored
|
||||
after an outage, and either end may be freely started or stopped in
|
||||
any order.
|
||||
|
||||
Because ZeroMQ is message oriented, subscribers receive transactions
|
||||
and blocks all-at-once and do not need to implement any sort of
|
||||
@ -32,13 +33,13 @@ buffering or reassembly.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The ZeroMQ feature in Bitcoin Core uses only a very small part of the
|
||||
ZeroMQ C API, and is thus compatible with any version of ZeroMQ
|
||||
from 2.1 onward, including all versions in the 3.x and 4.x release
|
||||
series. Typically, it is packaged by distributions as something like
|
||||
*libzmq-dev*.
|
||||
The ZeroMQ feature in Bitcoin Core requires ZeroMQ API version 4.x or
|
||||
newer. Typically, it is packaged by distributions as something like
|
||||
*libzmq3-dev*. The C++ wrapper for ZeroMQ is *not* needed.
|
||||
|
||||
The C++ wrapper for ZeroMQ is *not* needed.
|
||||
In order to run the example Python client scripts in contrib/ one must
|
||||
also install *python-zmq*, though this is not necessary for daemon
|
||||
operation.
|
||||
|
||||
## Enabling
|
||||
|
||||
@ -60,17 +61,19 @@ Currently, the following notifications are supported:
|
||||
-zmqpubrawblock=address
|
||||
-zmqpubrawtx=address
|
||||
|
||||
The socket type is PUB and the address must be a valid ZeroMQ
|
||||
socket address. The same address can be used in more than one notification.
|
||||
The socket type is PUB and the address must be a valid ZeroMQ socket
|
||||
address. The same address can be used in more than one notification.
|
||||
|
||||
For instance:
|
||||
|
||||
$ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 -zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw
|
||||
$ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 \
|
||||
-zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw
|
||||
|
||||
Each PUB notification has a topic and body, where the header
|
||||
corresponds to the notification type. For instance, for the notification
|
||||
`-zmqpubhashtx` the topic is `hashtx` (no null terminator) and the body is the
|
||||
hexadecimal transaction hash (32 bytes).
|
||||
corresponds to the notification type. For instance, for the
|
||||
notification `-zmqpubhashtx` the topic is `hashtx` (no null
|
||||
terminator) and the body is the hexadecimal transaction hash (32
|
||||
bytes).
|
||||
|
||||
These options can also be provided in bitcoin.conf.
|
||||
|
||||
@ -78,9 +81,9 @@ ZeroMQ endpoint specifiers for TCP (and others) are documented in the
|
||||
[ZeroMQ API](http://api.zeromq.org).
|
||||
|
||||
Client side, then, the ZeroMQ subscriber socket must have the
|
||||
ZMQ_SUBSCRIBE option set to one or either of these prefixes (for instance, just `hash`); without
|
||||
doing so will result in no messages arriving. Please see `contrib/zmq/zmq_sub.py`
|
||||
for a working example.
|
||||
ZMQ_SUBSCRIBE option set to one or either of these prefixes (for
|
||||
instance, just `hash`); without doing so will result in no messages
|
||||
arriving. Please see `contrib/zmq/zmq_sub.py` for a working example.
|
||||
|
||||
## Remarks
|
||||
|
||||
@ -93,6 +96,6 @@ No authentication or authorization is done on connecting clients; it
|
||||
is assumed that the ZeroMQ port is exposed only to trusted entities,
|
||||
using other means such as firewalling.
|
||||
|
||||
Note that when the block chain tip changes, a reorganisation may occur and just
|
||||
the tip will be notified. It is up to the subscriber to retrieve the chain
|
||||
from the last known block to the new tip.
|
||||
Note that when the block chain tip changes, a reorganisation may occur
|
||||
and just the tip will be notified. It is up to the subscriber to
|
||||
retrieve the chain from the last known block to the new tip.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user