Reconfiguring with configtxlator¶
Overview¶
The configtxlator
tool was created to support reconfiguration independent
of SDKs. Channel configuration is stored as a transaction in configuration
blocks of a channel and may be manipulated directly, such as in the bdd behave
tests. However, at the time of this writing, no SDK natively supports
manipulating the configuration directly, so the configtxlator
tool is
designed to provide an API which consumers of any SDK may interact with to
assist with configuration updates.
The tool name is a portmanteau of configtx and translator and is intended to convey that the tool simply converts between different equivalent data representations. It does not generate configuration. It does not submit or retrieve configuration. It does not modify configuration itself, it simply provides some bijective operations between different views of the configtx format.
The standard usage is expected to be:
- SDK retrieves latest config
configtxlator
produces human readable version of config- User or application edits the config
configtxlator
is used to compute config update representation of changes to the config- SDK submits signs and submits config
The configtxlator
tool exposes a truly stateless REST API for interacting
with configuration elements. These REST components support converting the
native configuration format to/from a human readable JSON representation, as
well as computing configuration updates based on the difference between two
configurations.
Because the configtxlator
service deliberately does not contain any crypto
material, or otherwise secret information, it does not include any authorization
or access control. The anticipated typical deployment would be to operate as
a sandboxed container, locally with the application, so that there is a
dedicated configtxlator
process for each consumer of it.
Running the configtxlator¶
The configtxlator
tool can be downloaded with the other Hyperledger Fabric
platform-specific binaries. Please see download-platform-specific-binaries
for details.
The tool may be configured to listen on a different port and you may also
specify the hostname using the --port
and --hostname
flags. To explore
the complete set of commands and flags, run configtxlator --help
.
The binary will start an http server listening on the designated port and is now ready to process request.
To start the configtxlator
server:
configtxlator start
2017-06-21 18:16:58.248 HKT [configtxlator] startServer -> INFO 001 Serving HTTP requests on 0.0.0.0:7059
Proto translation¶
For extensibility, and because certain fields must be signed over, many proto
fields are stored as bytes. This makes the natural proto to JSON translation
using the jsonpb
package ineffective for producing a human readable version
of the protobufs. Instead, the configtxlator
exposes a REST component to do
a more sophisticated translation.
To convert a proto to its human readable JSON equivalent, simply post the binary
proto to the rest target
http://$SERVER:$PORT/protolator/decode/<message.Name>
,
where <message.Name>
is the fully qualified proto name of the message.
For instance, to decode a configuration block saved as
configuration_block.pb
, run the command:
curl -X POST --data-binary @configuration_block.pb http://127.0.0.1:7059/protolator/decode/common.Block
To convert the human readable JSON version of the proto message, simply post the
JSON version to http://$SERVER:$PORT/protolator/encode/<message.Name
, where
<message.Name>
is again the fully qualified proto name of the message.
For instance, to re-encode the block saved as configuration_block.json
, run
the command:
curl -X POST --data-binary @configuration_block.json http://127.0.0.1:7059/protolator/encode/common.Block
Any of the configuration related protos, including common.Block
,
common.Envelope
, common.ConfigEnvelope
, common.ConfigUpdateEnvelope
,
common.Config
, and common.ConfigUpdate
are valid targets for
these URLs. In the future, other proto decoding types may be added, such as
for endorser transactions.
Config update computation¶
Given two different configurations, it is possible to compute the config update
which transitions between them. Simply POST the two common.Config
proto
encoded configurations as multipart/formdata
, with the original as field
original
and the updated as field updated
, to
http://$SERVER:$PORT/configtxlator/compute/update-from-configs
.
For example, given the original config as the file original_config.pb
and
the updated config as the file updated_config.pb
for the channel
desiredchannel
:
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
Bootstraping example¶
First start the configtxlator
:
$ configtxlator start
2017-05-31 12:57:22.499 EDT [configtxlator] main -> INFO 001 Serving HTTP requests on port: 7059
First, produce a genesis block for the ordering system channel:
$ configtxgen -outputBlock genesis_block.pb
2017-05-31 14:15:16.634 EDT [common/configtx/tool] main -> INFO 001 Loading configuration
2017-05-31 14:15:16.646 EDT [common/configtx/tool] doOutputBlock -> INFO 002 Generating genesis block
2017-05-31 14:15:16.646 EDT [common/configtx/tool] doOutputBlock -> INFO 003 Writing genesis block
Decode the genesis block into a human editable form:
curl -X POST --data-binary @genesis_block.pb http://127.0.0.1:7059/protolator/decode/common.Block > genesis_block.json
Edit the genesis_block.json
file in your favorite JSON editor, or manipulate
it programatically. Here we use the JSON CLI tool jq
. For simplicity, we
are editing the batch size for the channel, because it is a single numeric
field. However, any edits, including policy and MSP edits may be made here.
First, let’s establish an environment variable to hold the string that defines the path to a property in the json:
export MAXBATCHSIZEPATH=".data.data[0].payload.data.config.channel_group.groups.Orderer.values.BatchSize.value.max_message_count"
Next, let’s display the value of that property:
jq "$MAXBATCHSIZEPATH" genesis_block.json
10
Now, let’s set the new batch size, and display the new value:
jq “$MAXBATCHSIZEPATH = 20” genesis_block.json > updated_genesis_block.json jq “$MAXBATCHSIZEPATH” updated_genesis_block.json 20
The genesis block is now ready to be re-encoded into the native proto form to be used for bootstrapping:
curl -X POST --data-binary @updated_genesis_block.json http://127.0.0.1:7059/protolator/encode/common.Block > updated_genesis_block.pb
The updated_genesis_block.pb
file may now be used as the genesis block for
bootstrapping an ordering system channel.
Reconfiguration example¶
In another terminal window, start the orderer using the default options,
including the provisional bootstrapper which will create a testchainid
ordering system channel.
ORDERER_GENERAL_LOGLEVEL=debug orderer
Reconfiguring a channel can be performed in a very similar way to modifying a genesis config.
First, fetch the config_block proto:
$ peer channel fetch config config_block.pb -o 127.0.0.1:7050 -c testchainid
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]
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]
Received block: 1
Received block: 1
2017-05-31 15:11:37.635 EDT [main] main -> INFO 003 Exiting.....
Next, send the config block to the configtxlator
service for decoding:
curl -X POST --data-binary @config_block.pb http://127.0.0.1:7059/protolator/decode/common.Block > config_block.json
Extract the config section from the block:
jq .data.data[0].payload.data.config config_block.json > config.json
Edit the config, saving it as a new updated_config.json
. Here, we set the
batch size to 30.
jq ".channel_group.groups.Orderer.values.BatchSize.value.max_message_count = 30" config.json > updated_config.json
Re-encode both the original config, and the updated config into proto:
curl -X POST --data-binary @config.json http://127.0.0.1:7059/protolator/encode/common.Config > config.pb
curl -X POST --data-binary @updated_config.json http://127.0.0.1:7059/protolator/encode/common.Config > updated_config.pb
Now, with both configs properly encoded, send them to the configtxlator service to compute the config update which transitions between the two.
curl -X POST -F original=@config.pb -F updated=@updated_config.pb http://127.0.0.1:7059/configtxlator/compute/update-from-configs -F channel=testchainid > config_update.pb
At this point, the computed config update is now prepared. Traditionally, an SDK would be used to sign and wrap this message. However, in the interest of using only the peer cli, the configtxlator can also be used for this task.
First, we decode the ConfigUpdate so that we may work with it as text:
$ curl -X POST --data-binary @config_update.pb http://127.0.0.1:7059/protolator/decode/common.ConfigUpdate > config_update.json
Then, we wrap it in an envelope message:
echo '{"payload":{"header":{"channel_header":{"channel_id":"testchainid", "type":2}},"data":{"config_update":'$(cat config_update.json)'}}}' > config_update_as_envelope.json
Next, convert it back into the proto form of a full fledged config transaction:
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
Finally, submit the config update transaction to ordering to perform a config update.
peer channel update -f config_update_as_envelope.pb -c testchainid -o 127.0.0.1:7050
Adding an organization¶
First start the configtxlator
:
$ configtxlator start
2017-05-31 12:57:22.499 EDT [configtxlator] main -> INFO 001 Serving HTTP requests on port: 7059
Start the orderer using the SampleDevModeSolo
profile option.
ORDERER_GENERAL_LOGLEVEL=debug ORDERER_GENERAL_GENESISPROFILE=SampleDevModeSolo orderer
The process to add an organization then follows exactly like the batch size example. However, instead of setting the batch size, a new org is defined at the application level. Adding an organization is slightly more involved because we must first create a channel, then modify its membership set.