github.com/kaituanwang/hyperledger@v2.0.1+incompatible/docs/source/configtx.rst (about) 1 Channel Configuration (configtx) 2 ================================ 3 4 Shared configuration for a Hyperledger Fabric blockchain network is 5 stored in a collection configuration transactions, one per channel. Each 6 configuration transaction is usually referred to by the shorter name 7 *configtx*. 8 9 Channel configuration has the following important properties: 10 11 1. **Versioned**: All elements of the configuration have an associated 12 version which is advanced with every modification. Further, every 13 committed configuration receives a sequence number. 14 2. **Permissioned**: Each element of the configuration has an associated 15 policy which governs whether or not modification to that element is 16 permitted. Anyone with a copy of the previous configtx (and no 17 additional info) may verify the validity of a new config based on 18 these policies. 19 3. **Hierarchical**: A root configuration group contains sub-groups, and 20 each group of the hierarchy has associated values and policies. These 21 policies can take advantage of the hierarchy to derive policies at 22 one level from policies of lower levels. 23 24 Anatomy of a configuration 25 -------------------------- 26 27 Configuration is stored as a transaction of type ``HeaderType_CONFIG`` 28 in a block with no other transactions. These blocks are referred to as 29 *Configuration Blocks*, the first of which is referred to as the 30 *Genesis Block*. 31 32 The proto structures for configuration are stored in 33 ``fabric-protos/common/configtx.proto``. The Envelope of type 34 ``HeaderType_CONFIG`` encodes a ``ConfigEnvelope`` message as the 35 ``Payload`` ``data`` field. The proto for ``ConfigEnvelope`` is defined 36 as follows: 37 38 :: 39 40 message ConfigEnvelope { 41 Config config = 1; 42 Envelope last_update = 2; 43 } 44 45 The ``last_update`` field is defined below in the **Updates to 46 configuration** section, but is only necessary when validating the 47 configuration, not reading it. Instead, the currently committed 48 configuration is stored in the ``config`` field, containing a ``Config`` 49 message. 50 51 :: 52 53 message Config { 54 uint64 sequence = 1; 55 ConfigGroup channel_group = 2; 56 } 57 58 The ``sequence`` number is incremented by one for each committed 59 configuration. The ``channel_group`` field is the root group which 60 contains the configuration. The ``ConfigGroup`` structure is recursively 61 defined, and builds a tree of groups, each of which contains values and 62 policies. It is defined as follows: 63 64 :: 65 66 message ConfigGroup { 67 uint64 version = 1; 68 map<string,ConfigGroup> groups = 2; 69 map<string,ConfigValue> values = 3; 70 map<string,ConfigPolicy> policies = 4; 71 string mod_policy = 5; 72 } 73 74 Because ``ConfigGroup`` is a recursive structure, it has hierarchical 75 arrangement. The following example is expressed for clarity in golang 76 notation. 77 78 :: 79 80 // Assume the following groups are defined 81 var root, child1, child2, grandChild1, grandChild2, grandChild3 *ConfigGroup 82 83 // Set the following values 84 root.Groups["child1"] = child1 85 root.Groups["child2"] = child2 86 child1.Groups["grandChild1"] = grandChild1 87 child2.Groups["grandChild2"] = grandChild2 88 child2.Groups["grandChild3"] = grandChild3 89 90 // The resulting config structure of groups looks like: 91 // root: 92 // child1: 93 // grandChild1 94 // child2: 95 // grandChild2 96 // grandChild3 97 98 Each group defines a level in the config hierarchy, and each group has 99 an associated set of values (indexed by string key) and policies (also 100 indexed by string key). 101 102 Values are defined by: 103 104 :: 105 106 message ConfigValue { 107 uint64 version = 1; 108 bytes value = 2; 109 string mod_policy = 3; 110 } 111 112 Policies are defined by: 113 114 :: 115 116 message ConfigPolicy { 117 uint64 version = 1; 118 Policy policy = 2; 119 string mod_policy = 3; 120 } 121 122 Note that Values, Policies, and Groups all have a ``version`` and a 123 ``mod_policy``. The ``version`` of an element is incremented each time 124 that element is modified. The ``mod_policy`` is used to govern the 125 required signatures to modify that element. For Groups, modification is 126 adding or removing elements to the Values, Policies, or Groups maps (or 127 changing the ``mod_policy``). For Values and Policies, modification is 128 changing the Value and Policy fields respectively (or changing the 129 ``mod_policy``). Each element's ``mod_policy`` is evaluated in the 130 context of the current level of the config. Consider the following 131 example mod policies defined at ``Channel.Groups["Application"]`` (Here, 132 we use the golang map reference syntax, so 133 ``Channel.Groups["Application"].Policies["policy1"]`` refers to the base 134 ``Channel`` group's ``Application`` group's ``Policies`` map's 135 ``policy1`` policy.) 136 137 * ``policy1`` maps to ``Channel.Groups["Application"].Policies["policy1"]`` 138 * ``Org1/policy2`` maps to 139 ``Channel.Groups["Application"].Groups["Org1"].Policies["policy2"]`` 140 * ``/Channel/policy3`` maps to ``Channel.Policies["policy3"]`` 141 142 Note that if a ``mod_policy`` references a policy which does not exist, 143 the item cannot be modified. 144 145 Configuration updates 146 --------------------- 147 148 Configuration updates are submitted as an ``Envelope`` message of type 149 ``HeaderType_CONFIG_UPDATE``. The ``Payload`` ``data`` of the 150 transaction is a marshaled ``ConfigUpdateEnvelope``. The ``ConfigUpdateEnvelope`` 151 is defined as follows: 152 153 :: 154 155 message ConfigUpdateEnvelope { 156 bytes config_update = 1; 157 repeated ConfigSignature signatures = 2; 158 } 159 160 The ``signatures`` field contains the set of signatures which authorizes 161 the config update. Its message definition is: 162 163 :: 164 165 message ConfigSignature { 166 bytes signature_header = 1; 167 bytes signature = 2; 168 } 169 170 The ``signature_header`` is as defined for standard transactions, while 171 the signature is over the concatenation of the ``signature_header`` 172 bytes and the ``config_update`` bytes from the ``ConfigUpdateEnvelope`` 173 message. 174 175 The ``ConfigUpdateEnvelope`` ``config_update`` bytes are a marshaled 176 ``ConfigUpdate`` message which is defined as follows: 177 178 :: 179 180 message ConfigUpdate { 181 string channel_id = 1; 182 ConfigGroup read_set = 2; 183 ConfigGroup write_set = 3; 184 } 185 186 The ``channel_id`` is the channel ID the update is bound for, this is 187 necessary to scope the signatures which support this reconfiguration. 188 189 The ``read_set`` specifies a subset of the existing configuration, 190 specified sparsely where only the ``version`` field is set and no other 191 fields must be populated. The particular ``ConfigValue`` ``value`` or 192 ``ConfigPolicy`` ``policy`` fields should never be set in the 193 ``read_set``. The ``ConfigGroup`` may have a subset of its map fields 194 populated, so as to reference an element deeper in the config tree. For 195 instance, to include the ``Application`` group in the ``read_set``, its 196 parent (the ``Channel`` group) must also be included in the read set, 197 but, the ``Channel`` group does not need to populate all of the keys, 198 such as the ``Orderer`` ``group`` key, or any of the ``values`` or 199 ``policies`` keys. 200 201 The ``write_set`` specifies the pieces of configuration which are 202 modified. Because of the hierarchical nature of the configuration, a 203 write to an element deep in the hierarchy must contain the higher level 204 elements in its ``write_set`` as well. However, for any element in the 205 ``write_set`` which is also specified in the ``read_set`` at the same 206 version, the element should be specified sparsely, just as in the 207 ``read_set``. 208 209 For example, given the configuration: 210 211 :: 212 213 Channel: (version 0) 214 Orderer (version 0) 215 Application (version 3) 216 Org1 (version 2) 217 218 To submit a configuration update which modifies ``Org1``, the 219 ``read_set`` would be: 220 221 :: 222 223 Channel: (version 0) 224 Application: (version 3) 225 226 and the ``write_set`` would be 227 228 :: 229 230 Channel: (version 0) 231 Application: (version 3) 232 Org1 (version 3) 233 234 When the ``CONFIG_UPDATE`` is received, the orderer computes the 235 resulting ``CONFIG`` by doing the following: 236 237 1. Verifies the ``channel_id`` and ``read_set``. All elements in the 238 ``read_set`` must exist at the given versions. 239 2. Computes the update set by collecting all elements in the 240 ``write_set`` which do not appear at the same version in the 241 ``read_set``. 242 3. Verifies that each element in the update set increments the version 243 number of the element update by exactly 1. 244 4. Verifies that the signature set attached to the 245 ``ConfigUpdateEnvelope`` satisfies the ``mod_policy`` for each 246 element in the update set. 247 5. Computes a new complete version of the config by applying the update 248 set to the current config. 249 6. Writes the new config into a ``ConfigEnvelope`` which includes the 250 ``CONFIG_UPDATE`` as the ``last_update`` field and the new config 251 encoded in the ``config`` field, along with the incremented 252 ``sequence`` value. 253 7. Writes the new ``ConfigEnvelope`` into a ``Envelope`` of type 254 ``CONFIG``, and ultimately writes this as the sole transaction in a 255 new configuration block. 256 257 When the peer (or any other receiver for ``Deliver``) receives this 258 configuration block, it should verify that the config was appropriately 259 validated by applying the ``last_update`` message to the current config 260 and verifying that the orderer-computed ``config`` field contains the 261 correct new configuration. 262 263 Permitted configuration groups and values 264 ----------------------------------------- 265 266 Any valid configuration is a subset of the following configuration. Here 267 we use the notation ``peer.<MSG>`` to define a ``ConfigValue`` whose 268 ``value`` field is a marshaled proto message of name ``<MSG>`` defined 269 in ``fabric-protos/peer/configuration.proto``. The notations 270 ``common.<MSG>``, ``msp.<MSG>``, and ``orderer.<MSG>`` correspond 271 similarly, but with their messages defined in 272 ``fabric-protos/common/configuration.proto``, 273 ``fabric-protos/msp/mspconfig.proto``, and 274 ``fabric-protos/orderer/configuration.proto`` respectively. 275 276 Note, that the keys ``{{org_name}}`` and ``{{consortium_name}}`` 277 represent arbitrary names, and indicate an element which may be repeated 278 with different names. 279 280 :: 281 282 &ConfigGroup{ 283 Groups: map<string, *ConfigGroup> { 284 "Application":&ConfigGroup{ 285 Groups:map<String, *ConfigGroup> { 286 {{org_name}}:&ConfigGroup{ 287 Values:map<string, *ConfigValue>{ 288 "MSP":msp.MSPConfig, 289 "AnchorPeers":peer.AnchorPeers, 290 }, 291 }, 292 }, 293 }, 294 "Orderer":&ConfigGroup{ 295 Groups:map<String, *ConfigGroup> { 296 {{org_name}}:&ConfigGroup{ 297 Values:map<string, *ConfigValue>{ 298 "MSP":msp.MSPConfig, 299 }, 300 }, 301 }, 302 303 Values:map<string, *ConfigValue> { 304 "ConsensusType":orderer.ConsensusType, 305 "BatchSize":orderer.BatchSize, 306 "BatchTimeout":orderer.BatchTimeout, 307 "KafkaBrokers":orderer.KafkaBrokers, 308 }, 309 }, 310 "Consortiums":&ConfigGroup{ 311 Groups:map<String, *ConfigGroup> { 312 {{consortium_name}}:&ConfigGroup{ 313 Groups:map<string, *ConfigGroup> { 314 {{org_name}}:&ConfigGroup{ 315 Values:map<string, *ConfigValue>{ 316 "MSP":msp.MSPConfig, 317 }, 318 }, 319 }, 320 Values:map<string, *ConfigValue> { 321 "ChannelCreationPolicy":common.Policy, 322 } 323 }, 324 }, 325 }, 326 }, 327 328 Values: map<string, *ConfigValue> { 329 "HashingAlgorithm":common.HashingAlgorithm, 330 "BlockHashingDataStructure":common.BlockDataHashingStructure, 331 "Consortium":common.Consortium, 332 "OrdererAddresses":common.OrdererAddresses, 333 }, 334 } 335 336 Orderer system channel configuration 337 ------------------------------------ 338 339 The ordering system channel needs to define ordering parameters, and 340 consortiums for creating channels. There must be exactly one ordering 341 system channel for an ordering service, and it is the first channel to 342 be created (or more accurately bootstrapped). It is recommended never to 343 define an Application section inside of the ordering system channel 344 genesis configuration, but may be done for testing. Note that any member 345 with read access to the ordering system channel may see all channel 346 creations, so this channel's access should be restricted. 347 348 The ordering parameters are defined as the following subset of config: 349 350 :: 351 352 &ConfigGroup{ 353 Groups: map<string, *ConfigGroup> { 354 "Orderer":&ConfigGroup{ 355 Groups:map<String, *ConfigGroup> { 356 {{org_name}}:&ConfigGroup{ 357 Values:map<string, *ConfigValue>{ 358 "MSP":msp.MSPConfig, 359 }, 360 }, 361 }, 362 363 Values:map<string, *ConfigValue> { 364 "ConsensusType":orderer.ConsensusType, 365 "BatchSize":orderer.BatchSize, 366 "BatchTimeout":orderer.BatchTimeout, 367 "KafkaBrokers":orderer.KafkaBrokers, 368 }, 369 }, 370 }, 371 372 Each organization participating in ordering has a group element under 373 the ``Orderer`` group. This group defines a single parameter ``MSP`` 374 which contains the cryptographic identity information for that 375 organization. The ``Values`` of the ``Orderer`` group determine how the 376 ordering nodes function. They exist per channel, so 377 ``orderer.BatchTimeout`` for instance may be specified differently on 378 one channel than another. 379 380 At startup, the orderer is faced with a filesystem which contains 381 information for many channels. The orderer identifies the system channel 382 by identifying the channel with the consortiums group defined. The 383 consortiums group has the following structure. 384 385 :: 386 387 &ConfigGroup{ 388 Groups: map<string, *ConfigGroup> { 389 "Consortiums":&ConfigGroup{ 390 Groups:map<String, *ConfigGroup> { 391 {{consortium_name}}:&ConfigGroup{ 392 Groups:map<string, *ConfigGroup> { 393 {{org_name}}:&ConfigGroup{ 394 Values:map<string, *ConfigValue>{ 395 "MSP":msp.MSPConfig, 396 }, 397 }, 398 }, 399 Values:map<string, *ConfigValue> { 400 "ChannelCreationPolicy":common.Policy, 401 } 402 }, 403 }, 404 }, 405 }, 406 }, 407 408 Note that each consortium defines a set of members, just like the 409 organizational members for the ordering orgs. Each consortium also 410 defines a ``ChannelCreationPolicy``. This is a policy which is applied 411 to authorize channel creation requests. Typically, this value will be 412 set to an ``ImplicitMetaPolicy`` requiring that the new members of the 413 channel sign to authorize the channel creation. More details about 414 channel creation follow later in this document. 415 416 Application channel configuration 417 --------------------------------- 418 419 Application configuration is for channels which are designed for 420 application type transactions. It is defined as follows: 421 422 :: 423 424 &ConfigGroup{ 425 Groups: map<string, *ConfigGroup> { 426 "Application":&ConfigGroup{ 427 Groups:map<String, *ConfigGroup> { 428 {{org_name}}:&ConfigGroup{ 429 Values:map<string, *ConfigValue>{ 430 "MSP":msp.MSPConfig, 431 "AnchorPeers":peer.AnchorPeers, 432 }, 433 }, 434 }, 435 }, 436 }, 437 } 438 439 Just like with the ``Orderer`` section, each organization is encoded as 440 a group. However, instead of only encoding the ``MSP`` identity 441 information, each org additionally encodes a list of ``AnchorPeers``. 442 This list allows the peers of different organizations to contact each 443 other for peer gossip networking. 444 445 The application channel encodes a copy of the orderer orgs and consensus 446 options to allow for deterministic updating of these parameters, so the 447 same ``Orderer`` section from the orderer system channel configuration 448 is included. However from an application perspective this may be largely 449 ignored. 450 451 Channel creation 452 ---------------- 453 454 When the orderer receives a ``CONFIG_UPDATE`` for a channel which does 455 not exist, the orderer assumes that this must be a channel creation 456 request and performs the following. 457 458 1. The orderer identifies the consortium which the channel creation 459 request is to be performed for. It does this by looking at the 460 ``Consortium`` value of the top level group. 461 2. The orderer verifies that the organizations included in the 462 ``Application`` group are a subset of the organizations included in 463 the corresponding consortium and that the ``ApplicationGroup`` is set 464 to ``version`` ``1``. 465 3. The orderer verifies that if the consortium has members, that the new 466 channel also has application members (creation consortiums and 467 channels with no members is useful for testing only). 468 4. The orderer creates a template configuration by taking the 469 ``Orderer`` group from the ordering system channel, and creating an 470 ``Application`` group with the newly specified members and specifying 471 its ``mod_policy`` to be the ``ChannelCreationPolicy`` as specified 472 in the consortium config. Note that the policy is evaluated in the 473 context of the new configuration, so a policy requiring ``ALL`` 474 members, would require signatures from all the new channel members, 475 not all the members of the consortium. 476 5. The orderer then applies the ``CONFIG_UPDATE`` as an update to this 477 template configuration. Because the ``CONFIG_UPDATE`` applies 478 modifications to the ``Application`` group (its ``version`` is 479 ``1``), the config code validates these updates against the 480 ``ChannelCreationPolicy``. If the channel creation contains any other 481 modifications, such as to an individual org's anchor peers, the 482 corresponding mod policy for the element will be invoked. 483 6. The new ``CONFIG`` transaction with the new channel config is wrapped 484 and sent for ordering on the ordering system channel. After ordering, 485 the channel is created. 486 487 .. Licensed under Creative Commons Attribution 4.0 International License 488 https://creativecommons.org/licenses/by/4.0/ 489