github.com/hechain20/hechain@v0.0.0-20220316014945-b544036ba106/docs/source/create_channel/create_channel_config.md (about)

     1  # Using configtx.yaml to build a channel configuration
     2  
     3  A channel is created by building a channel creation transaction artifact that specifies the initial configuration of the channel. The **channel configuration** is stored on the ledger, and governs all the subsequent blocks that are added to the channel. The channel configuration specifies which organizations are channel members, the ordering nodes that can add new blocks on the channel, as well as the policies that govern channel updates. The initial channel configuration, stored in the channel genesis block, can be updated through channel configuration updates. If a sufficient number of organizations approve a channel update, a new channel config block will govern the channel after it is committed to the channel.
     4  
     5  While it is possible to build the channel creation transaction file manually, it is easier to create a channel by using the `configtx.yaml` file and the [configtxgen](../commands/configtxgen.html) tool. The `configtx.yaml` file contains the information that is required to build the channel configuration in a format that can be easily read and edited by humans. The `configtxgen` tool reads the information in the `configtx.yaml` file and writes it to the [protobuf format](https://developers.google.com/protocol-buffers) that can be read by Fabric.
     6  
     7  ## Overview
     8  
     9  You can use this tutorial to learn how to use the `configtx.yaml` file to build the initial channel configuration that is stored in the genesis block. The tutorial will discuss the portion of channel configuration that is built by each section of file.
    10  
    11  - [Organizations](#organizations)
    12  - [Capabilities](#capabilities)
    13  - [Application](#application)
    14  - [Orderer](#orderer)
    15  - [Channel](#channel)
    16  - [Profiles](#profiles)
    17  
    18  Because different sections of the file work together to create the policies that govern the channel, we will discuss channel policies in [their own tutorial](channel_policies.html).
    19  
    20  Building off of the [Creating a channel tutorial](create_channel_participation.html), we will use the `configtx.yaml` file that is used to deploy the Fabric test network as an example. Open a command terminal on your local machine and navigate to the `test-network` directory in your local clone of the Fabric samples:
    21  ```
    22  cd fabric-samples/test-network
    23  ```
    24  
    25  The `configtx.yaml` file used by the test network is located in the `configtx` folder. Open the file in a text editor. You can refer back to this file as the tutorial goes through each section. You can find a more detailed version of the `configtx.yaml` file in the [Fabric sample configuration](https://github.com/hechain20/hechain/blob/{BRANCH}/sampleconfig/configtx.yaml).
    26  
    27  ## Organizations
    28  
    29  The most important information contained in the channel configuration are the organizations that are channel members.  Each organization is identified by an MSP ID and a [channel MSP](../membership/membership.html). The channel MSP is stored in the channel configuration and contains the certificates that are used to the identify the nodes, applications, and administrators of an organization. The **Organizations** section of `configtx.yaml` file is used to create the channel MSP and accompanying MSP ID for each member of the channel.
    30  
    31  The `configtx.yaml` file used by the test network contains three organizations. Two organizations are peer organizations, Org1 and Org2, that can be added to application channels. One organization, OrdererOrg, is the administrator of the ordering service. Because it is a best practice to use different certificate authorities to deploy peer nodes and ordering nodes, organizations are often referred to as peer organizations or ordering organizations, even if they are in fact run by the same company.
    32  
    33  You can see the part of `configtx.yaml` that defines Org1 of the test network below:
    34    ```yaml
    35    - &Org1
    36        # DefaultOrg defines the organization which is used in the sampleconfig
    37        # of the fabric.git development environment
    38        Name: Org1MSP
    39  
    40        # ID to load the MSP definition as
    41        ID: Org1MSP
    42  
    43        MSPDir: ../organizations/peerOrganizations/org1.example.com/msp
    44  
    45        # Policies defines the set of policies at this level of the config tree
    46        # For organization policies, their canonical path is usually
    47        #   /Channel/<Application|Orderer>/<OrgName>/<PolicyName>
    48        Policies:
    49            Readers:
    50                Type: Signature
    51                Rule: "OR('Org1MSP.admin', 'Org1MSP.peer', 'Org1MSP.client')"
    52            Writers:
    53                Type: Signature
    54                Rule: "OR('Org1MSP.admin', 'Org1MSP.client')"
    55            Admins:
    56                Type: Signature
    57                Rule: "OR('Org1MSP.admin')"
    58            Endorsement:
    59                Type: Signature
    60                Rule: "OR('Org1MSP.peer')"
    61  
    62        # OrdererEndpoints is a list of all orderers this org runs which clients
    63        # and peers may to connect to to push transactions and receive blocks respectively.
    64        OrdererEndpoints:
    65            - "orderer.example.com:7050"
    66    ```  
    67  
    68    - The `Name` field is an informal name used to identify the organization.
    69  
    70    - The `ID` field is the organization's MSP ID. The MSP ID acts as a unique identifier for your organization, and is referred to by channel policies and is included in the transactions submitted to the channel.
    71  
    72    - The `MSPDir` is the path to an MSP folder that was created by the organization. The `configtxgen` tool will use this MSP folder to create the channel MSP. This MSP folder needs to contain the following information, which will be transferred to the channel MSP and stored in the channel configuration:
    73      - A CA root certificate that establishes the root of trust for the organization. The CA root cert is used to verify if an application, node, or administrator belongs to a channel member.
    74      - A root cert from the TLS CA that issued the TLS certificates of the peer or orderer nodes. The TLS root cert is used to identify the organization by the gossip protocol.
    75      - If Node OUs are enabled, the MSP folder needs to contain a `config.yaml` file that identifies the administrators, nodes, and clients based on the OUs of their x509 certificates.
    76      - If Node OUs are not enabled, the MSP needs to contain an admincerts folder that contains the signing certificates of the organizations administrator identities.
    77  
    78      The MSP folder that is used to create the channel MSP only contains public certificates. As a result, you can build the MSP folder locally, and then send the MSP to the organization that is creating the channel.
    79  
    80    - The `Policies` section is used to define a set of signature policies that reference the channel member. We will discuss these policies in more detail when we discuss [channel policies](channel_policies.html).
    81  
    82    - The `OrdererEndpoints` indicates the orderer node endpoints that this organization makes available to clients and peers. Service discovery uses this information so that clients can pass the appropriate TLS certificates when connecting to an orderer endpoint.
    83  
    84  ## Capabilities
    85  
    86  Fabric channels can be joined by orderer and peer nodes that are running different versions of Hechain. Channel capabilities allow organizations that are running different Fabric binaries to participate on the same channel by only enabling certain features. For example, organizations that are running Fabric v1.4 and organizations that are running Fabric v2.x can join the same channel as long as the channel capabilities levels are set to V1_4_X or below. None of the channel members will be able to use the features introduced in Fabric v2.0.
    87  
    88  If you examine the `configtx.yaml` file, you will see three capability groups:
    89  
    90  - **Application** capabilities govern the features that are used by peer nodes, such as the Fabric chaincode lifecycle, and set the minimum version of the Fabric binaries that can be run by peers joined to the channel.
    91  
    92  - **Orderer** capabilities govern the features that are used by orderer nodes, such as Raft consensus, and set the minimum version of the Fabric binaries that can be run by ordering nodes that belong to the channel consenter set.
    93  
    94  - **Channel** capabilities set the minimum version of the Fabric that can be run by peer and ordering nodes.
    95  
    96  Because both of the peers and the ordering node of the Fabric test network run version v2.x, every capability group is set to `V2_0`. As a result, the test network cannot be joined by nodes that run a lower version of Fabric than v2.0. For more information, see the [capabilities](../capabilities_concept.html) concept topic.  
    97  
    98  ## Application
    99  
   100  The application section defines the policies that govern how peer organizations can interact with application channels. These policies govern the number of peer organizations that need to approve a chaincode definition or sign a request to update the channel configuration. These policies are also used to restrict access to channel resources, such as the ability to write to the channel ledger or to query channel events.
   101  
   102  The test network uses the default application policies provided by Hechain. If you use the default policies, all peer organizations will be able to read and write data to the ledger. The default policies also require that a majority of channel members sign channel configuration updates and that a majority of channel members need to approve a chaincode definition before a chaincode can be deployed to a channel. The contents of this section are discussed in more detail in the [channel policies](channel_policies.html) tutorial.
   103  
   104  ## Orderer
   105  
   106  Each channel configuration includes the orderer nodes in the channel [consenter set](../glossary.html#consenter-set). The consenter set is the group of ordering nodes that have the ability to create new blocks and distribute them to the peers joined to the channel. The endpoint information of each ordering node that is a member of the consenter set is stored in the channel configuration.
   107  
   108   The test network uses the **Orderer** section of the `configtx.yaml` file to create a single node Raft ordering service.
   109  
   110  - The `OrdererType` field is used to select Raft as the consensus type:
   111    ```
   112    OrdererType: etcdraft
   113    ```
   114  
   115    Raft ordering services are defined by the list of consenters that can participate in the consensus process. Because the test network only uses a single ordering node, the consenters list contains only one endpoint:
   116    ```yaml
   117    EtcdRaft:
   118        Consenters:
   119        - Host: orderer.example.com
   120          Port: 7050
   121          ClientTLSCert: ../organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/server.crt
   122          ServerTLSCert: ../organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/server.crt
   123    ```
   124  
   125    Each ordering node in the list of consenters is identified by their endpoint address and their client and server TLS certificate. If you are deploying a multi-node ordering service, you would need to provide the hostname, port, and the path to the TLS certificates used by each node.
   126  
   127  - You can use the `BatchTimeout` and `BatchSize` fields to tune the latency and throughput of the channel by changing the maximum size of each block and how often a new block is created. The `BatchSize` property includes `MaxMessageCount`, `AbsoluteMaxBytes`, and `PreferredMaxBytes` settings. A block will be cut when any of the `BatchTimeout` or `BatchSize` criteria has been met. For `AbsoluteMaxBytes` it is recommended not to exceed 49 MB, given the default gRPC maximum message size of 100 MB configured on orderer and peer nodes (and allowing for message expansion during communication).
   128  
   129  - The `Policies` section creates the policies that govern the channel consenter set. The test network uses the default policies provided by Fabric, which require that a majority of orderer administrators approve the addition or removal of ordering nodes, organizations, or an update to the block cutting parameters.
   130  
   131  Because the test network is used for development and testing, it uses an ordering service that consists of a single ordering node. Networks that are deployed in production should use a multi-node ordering service for security and availability. To learn more, see [Configuring and operating a Raft ordering service](../raft_configuration.html).  
   132  
   133  ## Channel
   134  
   135  The channel section defines that policies that govern the highest level of the channel configuration. For an application channel, these policies govern the hashing algorithm, the data hashing structure used to create new blocks, and the channel capability level. In the system channel, these policies also govern the creation or removal of consortiums of peer organizations.
   136  
   137  The test network uses the default policies provided by Fabric, which require that a majority of orderer service administrators would need to approve updates to these values in the system channel. In an application channel, changes would need to be approved by a majority of orderer organizations and a majority of channel members. Most users will not need to change these values.
   138  
   139  ## Profiles
   140  
   141  The `configtxgen` tool reads the channel profiles in the **Profiles** section to build a channel configuration. Each profile uses YAML syntax to gather data from other sections of the file. The `configtxgen` tool uses this configuration to create a channel creation transaction for an applications channel, or to write the channel genesis block for a system channel. To learn more about YAML syntax, [Wikipedia](https://en.wikipedia.org/wiki/YAML) provides a good place to get started.
   142  
   143  The `configtx.yaml` used by the test network contains two channel profiles, `TwoOrgsOrdererGenesis` and `TwoOrgsChannel`. If you want to create a channel without a system channel by using the `osnadmin CLI` then you can refer to the `SampleAppChannelEtcdRaft`
   144  
   145  ### TwoOrgsOrdererGenesis
   146  
   147  The `TwoOrgsOrdererGenesis` profile is used to create the system channel genesis block:
   148  ```yaml
   149  TwoOrgsOrdererGenesis:
   150      <<: *ChannelDefaults
   151      Orderer:
   152          <<: *OrdererDefaults
   153          Organizations:
   154              - *OrdererOrg
   155          Capabilities:
   156              <<: *OrdererCapabilities
   157      Consortiums:
   158          SampleConsortium:
   159              Organizations:
   160                  - *Org1
   161                  - *Org2
   162  ```
   163  
   164  The system channel defines the nodes of the ordering service and the set of organizations that are ordering service administrators. The system channel also includes a set of peer organizations that belong to the blockchain [consortium](../glossary.html#consortium). The channel MSP of each member of the consortium is included in the system channel, allowing them to create new application channels and add consortium members to the new channel.
   165  
   166  The profile creates a consortium named `SampleConsortium` that contains the two peer organizations in the `configtx.yaml` file, Org1 and Org2. The `Orderer` section of the profile uses the single node Raft ordering service defined in the **Orderer:** section of the file. The OrdererOrg from the **Organizations:** section is made the only administrator of the ordering service. Because our only ordering node is running Fabric 2.x, we can set the orderer system channel capability to `V2_0`. The system channel uses default policies from the **Channel** section and enables `V2_0` as the channel capability level.
   167  
   168  ### TwoOrgsChannel
   169  
   170  The `TwoOrgsChannel` profile is used by the test network to create application channels:
   171  ```yaml
   172  TwoOrgsChannel:
   173      Consortium: SampleConsortium
   174      <<: *ChannelDefaults
   175      Application:
   176          <<: *ApplicationDefaults
   177          Organizations:
   178              - *Org1
   179              - *Org2
   180          Capabilities:
   181              <<: *ApplicationCapabilities
   182  ```
   183  
   184  The system channel is used by the ordering service as a template to create application channels. The nodes of the ordering service that are defined in the system channel become the default consenter set of new channels, while the administrators of the ordering service become the orderer administrators of the channel. The channel MSPs of channel members are transferred to the new channel from the system channel. After the channel is created, ordering nodes can be added or removed from the channel by updating the channel configuration. You can also update the channel configuration to [add other organizations as channel members](../channel_update_tutorial.html).
   185  
   186  The `TwoOrgsChannel` provides the name of the consortium, `SampleConsortium`, hosted by the test network system channel. As a result, the ordering service defined in the `TwoOrgsOrdererGenesis` profile becomes channel consenter set. In the `Application` section, both organizations from the consortium, Org1 and Org2, are included as channel members. The channel uses `V2_0` as the application capabilities, and uses the default policies from the **Application** section to govern how peer organizations will interact with the channel. The application channel also uses the default policies from the **Channel** section and enables `V2_0` as the channel capability level.
   187  
   188  ### SampleAppChannelEtcdRaft
   189  
   190  The `SampleAppChannelEtcdRaft` profile is provided for customers that prefer to create a channel without a system channel by using the `osnadmin CLI`. The major difference is that a consortium definition is no longer required. Check out the [Create a channel](create_channel_participation.html) tutorial to learn more about how to use this profile.
   191  
   192  ```
   193  SampleAppChannelEtcdRaft:
   194      <<: *ChannelDefaults
   195      Orderer:
   196          <<: *OrdererDefaults
   197          OrdererType: etcdraft
   198          Organizations:
   199              - <<: *SampleOrg
   200                Policies:
   201                    <<: *SampleOrgPolicies
   202                    Admins:
   203                        Type: Signature
   204                        Rule: "OR('SampleOrg.member')"
   205      Application:
   206          <<: *ApplicationDefaults
   207          Organizations:
   208              - <<: *SampleOrg
   209                Policies:
   210                    <<: *SampleOrgPolicies
   211                    Admins:
   212                        Type: Signature
   213                        Rule: "OR('SampleOrg.member')"
   214  ```
   215  For simplicity, this snippet assumes that the peers and orderers belong to the same organization `SampleOrg`. For a production deployment however, it is recommended that the peer and ordering nodes belong to separate organizations.