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