Skip to content

Commit 4ee7ce1

Browse files
nickgaskinickgaski
committed
WIP [FAB-4821] - Add configtxlator to RTD
WIP effort to eliminate requirement to build fabric from source incorporates the configtxlator README into the published docs. Conversion to .rst and formatting + grammar add orderer to release distribution? update samples.rst according with makefile change Fix merge Change-Id: I95861591c6541579eb72d4c342e38d63f1c602cb Signed-off-by: Nick Gaski <[email protected]> Signed-off-by: Christopher Ferris <[email protected]>
1 parent ced20e8 commit 4ee7ce1

File tree

3 files changed

+294
-1
lines changed

3 files changed

+294
-1
lines changed

‎Makefile

+1-1
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ PROJECT_FILES = $(shell git ls-files | grep -v ^test | grep -v ^unit-test | \
8282
RELEASE_TEMPLATES = $(shell git ls-files | grep "release/templates")
8383
IMAGES = peer orderer ccenv javaenv buildenv testenv zookeeper kafka couchdb tools
8484
RELEASE_PLATFORMS = windows-amd64 darwin-amd64 linux-amd64 linux-ppc64le linux-s390x
85-
RELEASE_PKGS = configtxgen cryptogen configtxlator peer
85+
RELEASE_PKGS = configtxgen cryptogen configtxlator peer orderer
8686

8787
pkgmap.cryptogen := $(PKGNAME)/common/tools/cryptogen
8888
pkgmap.configtxgen := $(PKGNAME)/common/configtx/tool/configtxgen

‎docs/source/configtxlator.rst

+292
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
Reconfiguring with configtxlator
2+
================================
3+
4+
Overview
5+
--------
6+
7+
The ``configtxlator`` tool was created to support reconfiguration independent
8+
of SDKs. Channel configuration is stored as a transaction in configuration
9+
blocks of a channel and may be manipulated directly, such as in the bdd behave
10+
tests. However, at the time of this writing, no SDK natively supports
11+
manipulating the configuration directly, so the ``configtxlator`` tool is
12+
designed to provide an API which consumers of any SDK may interact with to
13+
assist with configuration updates.
14+
15+
The tool name is a portmanteau of *configtx* and *translator* and is intended to
16+
convey that the tool simply converts between different equivalent data
17+
representations. It does not generate configuration. It does not submit or
18+
retrieve configuration. It does not modify configuration itself, it simply
19+
provides some bijective operations between different views of the configtx
20+
format.
21+
22+
The standard usage is expected to be:
23+
24+
1. SDK retrieves latest config
25+
2. ``configtxlator`` produces human readable version of config
26+
3. User or application edits the config
27+
4. ``configtxlator`` is used to compute config update representation of
28+
changes to the config
29+
5. SDK submits signs and submits config
30+
31+
The ``configtxlator`` tool exposes a truly stateless REST API for interacting
32+
with configuration elements. These REST components support converting the
33+
native configuration format to/from a human readable JSON representation, as
34+
well as computing configuration updates based on the difference between two
35+
configurations.
36+
37+
Because the ``configtxlator`` service deliberately does not contain any crypto
38+
material, or otherwise secret information, it does not include any authorization
39+
or access control. The anticipated typical deployment would be to operate as
40+
a sandboxed container, locally with the application, so that there is a
41+
dedicated ``configtxlator`` process for each consumer of it.
42+
43+
Running the configtxlator
44+
-------------------------
45+
46+
The ``configtxlator`` tool can be downloaded with the other Hyperledger Fabric
47+
platform-specific binaries. Please see :ref:`download-platform-specific-binaries`
48+
for details.
49+
50+
The tool may be configured to listen on a different port and you may also
51+
specify the hostname using the ``--port`` and ``--hostname`` flags. To explore
52+
the complete set of commands and flags, run ``configtxlator --help``.
53+
54+
The binary will start an http server listening on the designated port and is now
55+
ready to process request.
56+
57+
To start the ``configtxlator`` server:
58+
59+
.. code:: bash
60+
61+
configtxlator start
62+
2017-06-21 18:16:58.248 HKT [configtxlator] startServer -> INFO 001 Serving HTTP requests on 0.0.0.0:7059
63+
64+
Proto translation
65+
-----------------
66+
67+
For extensibility, and because certain fields must be signed over, many proto
68+
fields are stored as bytes. This makes the natural proto to JSON translation
69+
using the ``jsonpb`` package ineffective for producing a human readable version
70+
of the protobufs. Instead, the ``configtxlator`` exposes a REST component to do
71+
a more sophisticated translation.
72+
73+
To convert a proto to its human readable JSON equivalent, simply post the binary
74+
proto to the rest target
75+
``http://$SERVER:$PORT/protolator/decode/<message.Name>``,
76+
where ``<message.Name>`` is the fully qualified proto name of the message.
77+
78+
For instance, to decode a configuration block saved as
79+
``configuration_block.pb``, run the command:
80+
81+
.. code:: bash
82+
83+
curl -X POST --data-binary @configuration_block.pb http://127.0.0.1:7059/protolator/decode/common.Block
84+
85+
To convert the human readable JSON version of the proto message, simply post the
86+
JSON version to ``http://$SERVER:$PORT/protolator/encode/<message.Name``, where
87+
``<message.Name>`` is again the fully qualified proto name of the message.
88+
89+
For instance, to re-encode the block saved as ``configuration_block.json``, run
90+
the command:
91+
92+
.. code:: bash
93+
94+
curl -X POST --data-binary @configuration_block.json http://127.0.0.1:7059/protolator/encode/common.Block
95+
96+
Any of the configuration related protos, including ``common.Block``,
97+
``common.Envelope``, ``common.ConfigEnvelope``, ``common.ConfigUpdateEnvelope``,
98+
``common.Configuration``, and ``common.ConfigUpdate`` are valid targets for
99+
these URLs. In the future, other proto decoding types may be added, such as
100+
for endorser transactions.
101+
102+
Config update computation
103+
-------------------------
104+
105+
Given two different configurations, it is possible to compute the config update
106+
which transitions between them. Simply POST the two ``common.Config`` proto
107+
encoded configurations as ``multipart/formdata``, with the original as field
108+
``original`` and the updated as field ``updated``, to
109+
``http://$SERVER:$PORT/configtxlator/compute/update-from-configs``.
110+
111+
For example, given the original config as the file ``original_config.pb`` and
112+
the updated config as the file ``updated_config.pb`` for the channel
113+
``desiredchannel``:
114+
115+
.. code:: bash
116+
117+
curl -X POST -F channel=desiredchannel -F original=@original_config.pb -F updated=@updated_config.pb http://127.0.0.1:7059/configtxlator/compute/update-from-configs
118+
119+
Bootstraping example
120+
--------------------
121+
122+
First start the ``configtxlator``:
123+
124+
.. code:: bash
125+
126+
$ configtxlator start
127+
2017-05-31 12:57:22.499 EDT [configtxlator] main -> INFO 001 Serving HTTP requests on port: 7059
128+
129+
First, produce a genesis block for the ordering system channel:
130+
131+
.. code:: bash
132+
133+
$ configtxgen -outputBlock genesis_block.pb
134+
2017-05-31 14:15:16.634 EDT [common/configtx/tool] main -> INFO 001 Loading configuration
135+
2017-05-31 14:15:16.646 EDT [common/configtx/tool] doOutputBlock -> INFO 002 Generating genesis block
136+
2017-05-31 14:15:16.646 EDT [common/configtx/tool] doOutputBlock -> INFO 003 Writing genesis block
137+
138+
Decode the genesis block into a human editable form:
139+
140+
.. code:: bash
141+
142+
curl -X POST --data-binary @genesis_block.pb http://127.0.0.1:7059/protolator/decode/common.Block > genesis_block.json
143+
144+
Edit the ``genesis_block.json`` file in your favorite JSON editor, or manipulate
145+
it programatically. Here we use the JSON CLI tool ``jq``. For simplicity, we
146+
are editing the batch size for the channel, because it is a single numeric
147+
field. However, any edits, including policy and MSP edits may be made here.
148+
149+
First, let's establish an environment variable to hold the string that defines
150+
the path to a property in the json:
151+
152+
.. code:: bash
153+
154+
export MAXBATCHSIZEPATH=".data.data[0].payload.data.config.channel_group.groups.Orderer.values.BatchSize.value.max_message_count"
155+
156+
Next, let's display the value of that property:
157+
158+
.. code:: bash
159+
160+
jq "$MAXBATCHSIZEPATH" genesis_block.json
161+
10
162+
163+
Now, let's set the new batch size, and display the new value:
164+
165+
jq "$MAXBATCHSIZEPATH = 20" genesis_block.json > updated_genesis_block.json
166+
jq "$MAXBATCHSIZEPATH" updated_genesis_block.json
167+
20
168+
169+
The genesis block is now ready to be re-encoded into the native proto form to be
170+
used for bootstrapping:
171+
172+
.. code:: bash
173+
174+
curl -X POST --data-binary @updated_genesis_block.json http://127.0.0.1:7059/protolator/encode/common.Block > updated_genesis_block.pb
175+
176+
The ``updated_genesis_block.pb`` file may now be used as the genesis block for
177+
bootstrapping an ordering system channel.
178+
179+
Reconfiguration example
180+
-----------------------
181+
182+
In another terminal window, start the orderer using the default options,
183+
including the provisional bootstrapper which will create a ``testchainid``
184+
ordering system channel.
185+
186+
.. code:: bash
187+
188+
ORDERER_GENERAL_LOGLEVEL=debug orderer
189+
190+
Reconfiguring a channel can be performed in a very similar way to modifying a
191+
genesis config.
192+
193+
First, fetch the config_block proto:
194+
195+
.. code:: bash
196+
197+
$ peer channel fetch config config_block.pb -o 127.0.0.1:7050 -c testchainid
198+
2017-05-31 15:11:37.617 EDT [msp] getMspConfig -> INFO 001 intermediate certs folder not found at [/home/yellickj/go/src/github.com/hyperledger/fabric/sampleconfig/msp/intermediatecerts]. Skipping.: [stat /home/yellickj/go/src/github.com/hyperledger/fabric/sampleconfig/msp/intermediatecerts: no such file or directory]
199+
2017-05-31 15:11:37.617 EDT [msp] getMspConfig -> INFO 002 crls folder not found at [/home/yellickj/go/src/github.com/hyperledger/fabric/sampleconfig/msp/intermediatecerts]. Skipping.: [stat /home/yellickj/go/src/github.com/hyperledger/fabric/sampleconfig/msp/crls: no such file or directory]
200+
Received block: 1
201+
Received block: 1
202+
2017-05-31 15:11:37.635 EDT [main] main -> INFO 003 Exiting.....
203+
204+
Next, send the config block to the ``configtxlator`` service for decoding:
205+
206+
.. code:: bash
207+
208+
curl -X POST --data-binary @config_block.pb http://127.0.0.1:7059/protolator/decode/common.Block > config_block.json
209+
210+
Extract the config section from the block:
211+
212+
.. code:: bash
213+
214+
jq .data.data[0].payload.data.config config_block.json > config.json
215+
216+
Edit the config, saving it as a new ``updated_config.json``. Here, we set the
217+
batch size to 30.
218+
219+
.. code:: bash
220+
221+
jq ".channel_group.groups.Orderer.values.BatchSize.value.max_message_count = 30" config.json > updated_config.json
222+
223+
Re-encode both the original config, and the updated config into proto:
224+
225+
.. code:: bash
226+
227+
curl -X POST --data-binary @config.json http://127.0.0.1:7059/protolator/encode/common.Config > config.pb
228+
229+
.. code:: bash
230+
231+
curl -X POST --data-binary @updated_config.json http://127.0.0.1:7059/protolator/encode/common.Config > updated_config.pb
232+
233+
Now, with both configs properly encoded, send them to the `configtxlator`
234+
service to compute the config update which transitions between the two.
235+
236+
.. code:: bash
237+
238+
curl -X POST -F [email protected] -F updated=@updated_config.pb http://127.0.0.1:7059/configtxlator/compute/update-from-configs -F channel=testchainid > config_update.pb
239+
240+
At this point, the computed config update is now prepared. Traditionally,
241+
an SDK would be used to sign and wrap this message. However, in the interest of
242+
using only the peer cli, the `configtxlator` can also be used for this task.
243+
244+
First, we decode the ConfigUpdate so that we may work with it as text:
245+
246+
.. code:: bash
247+
248+
$ curl -X POST --data-binary @config_update.pb http://127.0.0.1:7059/protolator/decode/common.ConfigUpdate > config_update.json
249+
250+
Then, we wrap it in an envelope message:
251+
252+
.. code:: bash
253+
254+
echo '{"payload":{"header":{"channel_header":{"channel_id":"testchainid", "type":2}},"data":{"config_update":'$(cat config_update.json)'}}}' > config_update_as_envelope.json
255+
256+
Next, convert it back into the proto form of a full fledged config
257+
transaction:
258+
259+
.. code:: bash
260+
261+
curl -X POST --data-binary @config_update_as_envelope.json http://127.0.0.1:7059/protolator/encode/common.Envelope > config_update_as_envelope.pb
262+
263+
Finally, submit the config update transaction to ordering to perform a config
264+
update.
265+
266+
.. code:: bash
267+
268+
peer channel update -f config_update_as_envelope.pb -c testchainid -o 127.0.0.1:7050
269+
270+
Adding an organization
271+
----------------------
272+
273+
First start the ``configtxlator``:
274+
275+
.. code:: bash
276+
277+
$ configtxlator start
278+
2017-05-31 12:57:22.499 EDT [configtxlator] main -> INFO 001 Serving HTTP requests on port: 7059
279+
280+
Start the orderer using the ``SampleDevModeSolo`` profile option.
281+
282+
.. code:: bash
283+
284+
ORDERER_GENERAL_LOGLEVEL=debug ORDERER_GENERAL_GENESISPROFILE=SampleDevModeSolo orderer
285+
286+
The process to add an organization then follows exactly like the batch size
287+
example. However, instead of setting the batch size, a new org is defined at
288+
the application level. Adding an organization is slightly more involved because
289+
we must first create a channel, then modify its membership set.
290+
291+
.. Licensed under Creative Commons Attribution 4.0 International License
292+
https://creativecommons.org/licenses/by/4.0/

‎docs/source/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ Before diving in, watch how Fabric is `Building a Blockchain for Business
5858
msp
5959
configtx
6060
configtxgen
61+
configtxlator
6162
cc-packaging-and-signing
6263
endorsement-policies
6364
error-handling

0 commit comments

Comments
 (0)