From 601d084de90be0fefc958d04eac2cf0d633e2f0e Mon Sep 17 00:00:00 2001 From: joe-alewine Date: Wed, 9 Dec 2020 11:29:23 -0500 Subject: [PATCH] Even more edits to docs for participation API Change-Id: I972391863241bbcfcc0e443e874c54fc77934a92 Signed-off-by: joe-alewine --- docs/source/capability_requirements.rst | 16 +-- docs/source/config_update.md | 22 ++-- docs/source/configtx.rst | 131 ++---------------------- docs/source/membership/membership.md | 15 +-- docs/source/msp.rst | 118 ++++----------------- docs/source/raft_configuration.md | 72 ++++--------- docs/source/updating_capabilities.md | 75 ++------------ 7 files changed, 82 insertions(+), 367 deletions(-) diff --git a/docs/source/capability_requirements.rst b/docs/source/capability_requirements.rst index 6be355fd1d9..f4b44370805 100644 --- a/docs/source/capability_requirements.rst +++ b/docs/source/capability_requirements.rst @@ -1,6 +1,14 @@ Defining capability requirements ================================ +.. note:: This topic describes a network that does not use a "system channel", a + channel that the ordering service is bootstrapped with and the ordering + service exclusively controls. Since the release of v2.3, using a system + channel is now considered the legacy process as compared to the process + to :doc:`create_channel_participation`. For a version of this topic that + includes information about the system channel, check out + `Capability requirements `_ from the v2.2 documentation. + As discussed in :doc:`capabilities_concept`, capability requirements are defined per channel in the channel configuration (found in the channel’s most recent configuration block). The channel configuration contains three locations, each @@ -27,11 +35,6 @@ reconfiguration). .. note:: For more information about how to update a channel configuration, check out :doc:`config_update`. -Because new channels copy the configuration of the ordering system channel by -default, new channels will automatically be configured to work with the orderer -and channel capabilities of the ordering system channel and the application -capabilities specified by the channel creation transaction. - Capabilities in an Initial Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -42,8 +45,5 @@ for each capability type (Channel, Orderer, and Application). Note that there is a ``Capabilities`` section defined at the root level (for the channel capabilities), and at the Orderer level (for orderer capabilities). -When defining the orderer system channel there is no Application section, as those -capabilities are defined during the creation of an application channel. - .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/ diff --git a/docs/source/config_update.md b/docs/source/config_update.md index f26c85abcf5..feb79469659 100644 --- a/docs/source/config_update.md +++ b/docs/source/config_update.md @@ -2,6 +2,8 @@ *Audience: network administrators, node administrators* +Note: this topic describes the process for updating a channel on a network that does not have a system channel. For a version of this topic that includes information about the system channel, check out [Updating a channel configuration](https://hyperledger-fabric.readthedocs.io/en/release-2.2/config_update.html). + ## What is a channel configuration? Like many complex systems, Hyperledger Fabric networks are comprised of both **structure** and a number related of **processes**. @@ -9,7 +11,7 @@ Like many complex systems, Hyperledger Fabric networks are comprised of both **s * **Structure**: encompassing users (like admins), organizations, peers, ordering nodes, CAs, smart contracts, and applications. * **Process**: the way these structures interact. Most important of these are [Policies](./policies/policies.html), the rules that govern which users can do what, and under what conditions. -Information identifying the structure of blockchain networks and the processes governing how structures interact are contained in **channel configurations**. These configurations are collectively decided upon by the members of channels and are contained in blocks that are committed to the ledger of a channel. Channel configurations can be built using a tool called `configtxgen`, which uses a `configtx.yaml` file as its input. You can look at a [sample `configtx.yaml` file here](http://github.com/hyperledger/fabric/blob/release-2.0/sampleconfig/configtx.yaml). +Information identifying the structure of blockchain networks and the processes governing how structures interact are contained in **channel configurations**. These configurations are collectively decided upon by the members of channels and are contained in blocks that are committed to the ledger of a channel. Channel configurations can be built using a tool called `configtxgen`, which uses a `configtx.yaml` file as its input. You can look at a [sample `configtx.yaml` file here](http://github.com/hyperledger/fabric/blob/{BRANCH}/sampleconfig/configtx.yaml). Because configurations are contained in blocks (the first of these is known as the genesis block with the latest representing the current configuration of the channel), the process for updating a channel configuration (changing the structure by adding members, for example, or processes by modifying channel policies) is known as a **configuration update transaction**. @@ -33,11 +35,9 @@ In this section, we'll look a sample channel configuration and show the configur To see what the configuration file of an application channel looks like after it has been pulled and scoped, click **Click here to see the config** below. For ease of readability, it might be helpful to put this config into a viewer that supports JSON folding, like atom or Visual Studio. -Note: for simplicity, we are only showing an application channel configuration here. The configuration of the orderer system channel is very similar, but not identical, to the configuration of an application channel. However, the same basic rules and structure apply, as do the commands to pull and edit a configuration, as you can see in our topic on [Updating the capability level of a channel](./updating_capabilities.html). -
- **Click here to see the config**. Note that this is the configuration of an application channel, not the orderer system channel. + **Click here to see the config** ``` { @@ -880,8 +880,6 @@ A config might look intimidating in this form, but once you study it you’ll se For example, let's take a look at the config with a few of the tabs closed. -Note that this is the configuration of an application channel, not the orderer system channel. - ![Sample config simplified](./images/sample_config.png) The structure of the config should now be more obvious. You can see the config groupings: `Channel`, `Application`, and `Orderer`, and the configuration parameters related to each config grouping (we'll talk more about these in the next section), but also where the MSPs representing organizations are. Note that the `Channel` config grouping is below the `Orderer` group config values. @@ -906,7 +904,7 @@ Governs the configuration parameters unique to application channels (for example #### `Channel/Orderer` -Governs configuration parameters unique to the ordering service or the orderer system channel, requires a majority of the ordering organizations’ admins (by default there is only one ordering organization, though more can be added, for example when multiple organizations contribute nodes to the ordering service). +Governs configuration parameters unique to the ordering service and requires a majority of the ordering organizations’ admins (by default there is only one ordering organization, though more can be added, for example when multiple organizations contribute nodes to the ordering service). * **Batch size**. These parameters dictate the number and size of transactions in a block. No block will appear larger than `absolute_max_bytes` large or with more than `max_message_count` transactions inside the block. If it is possible to construct a block under `preferred_max_bytes`, then a block will be cut prematurely, and transactions larger than this size will appear in their own block. @@ -930,14 +928,6 @@ Governs configuration parameters that both the peer orgs and the ordering servic * **Hashing algorithm**. The algorithm used for computing the hash values encoded into the blocks of the blockchain. In particular, this affects the data hash, and the previous block hash fields of the block. Note, this field currently only has one valid value (`SHA256`) and should not be changed. -#### System channel configuration parameters - -Certain configuration values are unique to the orderer system channel. - -* **Channel creation policy.** Defines the policy value which will be set as the mod_policy for the Application group of new channels for the consortium it is defined in. The signature set attached to the channel creation request will be checked against the instantiation of this policy in the new channel to ensure that the channel creation is authorized. Note that this config value is only set in the orderer system channel. - -* **Channel restrictions.** Only editable in the orderer system channel. The total number of channels the orderer is willing to allocate may be specified as `max_count`. This is primarily useful in pre-production environments with weak consortium `ChannelCreation` policies. - ## Editing a config Updating a channel configuration is a three step operation that's conceptually simple: @@ -957,7 +947,7 @@ In this topic, we'll show the process of editing a channel configuration indepen ### Set environment variables for your config update -Before you attempt to use the sample commands, make sure to export the following environment variables, which will depend on the way you have structured your deployment. Note that the channel name, `CH_NAME` will have to be set for every channel being updated, as channel configuration updates only apply to the configuration of the channel being updated (with the exception of the ordering system channel, whose configuration is copied into the configuration of application channels by default). +Before you attempt to use the sample commands, make sure to export the following environment variables, which will depend on the way you have structured your deployment. Note that the channel name, `CH_NAME` will have to be set for every channel being updated, as channel configuration updates only apply to the configuration of the channel being updated. * `CH_NAME`: the name of the channel being updated. * `TLS_ROOT_CA`: the path to the root CA cert of the TLS CA of the organization proposing the update. diff --git a/docs/source/configtx.rst b/docs/source/configtx.rst index 29412ea3fc5..fe8ff2bcdb2 100644 --- a/docs/source/configtx.rst +++ b/docs/source/configtx.rst @@ -1,6 +1,13 @@ Channel Configuration (configtx) ================================ +.. note:: This topic describes how channels are configured when the network has + not been bootstrapped using a system channel genesis block. For + information about the structure of configurations, including the + configuration of the system channel, check out + `Channel Configuration (configtx) `_ + from the v2.2 documentation. + Shared configuration for a Hyperledger Fabric blockchain network is stored in a collection configuration transactions, one per channel. Each configuration transaction is usually referred to by the shorter name @@ -333,88 +340,8 @@ with different names. }, } -Orderer system channel configuration ------------------------------------- - -The ordering system channel needs to define ordering parameters, and -consortiums for creating channels. There must be exactly one ordering -system channel for an ordering service, and it is the first channel to -be created (or more accurately bootstrapped). It is recommended never to -define an Application section inside of the ordering system channel -genesis configuration, but may be done for testing. Note that any member -with read access to the ordering system channel may see all channel -creations, so this channel's access should be restricted. - -The ordering parameters are defined as the following subset of config: - -:: - - &ConfigGroup{ - Groups: map { - "Orderer":&ConfigGroup{ - Groups:map { - {{org_name}}:&ConfigGroup{ - Values:map{ - "MSP":msp.MSPConfig, - }, - }, - }, - - Values:map { - "ConsensusType":orderer.ConsensusType, - "BatchSize":orderer.BatchSize, - "BatchTimeout":orderer.BatchTimeout, - "KafkaBrokers":orderer.KafkaBrokers, - }, - }, - }, - -Each organization participating in ordering has a group element under -the ``Orderer`` group. This group defines a single parameter ``MSP`` -which contains the cryptographic identity information for that -organization. The ``Values`` of the ``Orderer`` group determine how the -ordering nodes function. They exist per channel, so -``orderer.BatchTimeout`` for instance may be specified differently on -one channel than another. - -At startup, the orderer is faced with a filesystem which contains -information for many channels. The orderer identifies the system channel -by identifying the channel with the consortiums group defined. The -consortiums group has the following structure. - -:: - - &ConfigGroup{ - Groups: map { - "Consortiums":&ConfigGroup{ - Groups:map { - {{consortium_name}}:&ConfigGroup{ - Groups:map { - {{org_name}}:&ConfigGroup{ - Values:map{ - "MSP":msp.MSPConfig, - }, - }, - }, - Values:map { - "ChannelCreationPolicy":common.Policy, - } - }, - }, - }, - }, - }, - -Note that each consortium defines a set of members, just like the -organizational members for the ordering orgs. Each consortium also -defines a ``ChannelCreationPolicy``. This is a policy which is applied -to authorize channel creation requests. Typically, this value will be -set to an ``ImplicitMetaPolicy`` requiring that the new members of the -channel sign to authorize the channel creation. More details about -channel creation follow later in this document. - -Application channel configuration ---------------------------------- +Channel configuration +--------------------- Application configuration is for channels which are designed for application type transactions. It is defined as follows: @@ -442,48 +369,10 @@ information, each org additionally encodes a list of ``AnchorPeers``. This list allows the peers of different organizations to contact each other for peer gossip networking. -The application channel encodes a copy of the orderer orgs and consensus -options to allow for deterministic updating of these parameters, so the -same ``Orderer`` section from the orderer system channel configuration -is included. However from an application perspective this may be largely -ignored. - Channel creation ---------------- -When the orderer receives a ``CONFIG_UPDATE`` for a channel which does -not exist, the orderer assumes that this must be a channel creation -request and performs the following. - -1. The orderer identifies the consortium which the channel creation - request is to be performed for. It does this by looking at the - ``Consortium`` value of the top level group. -2. The orderer verifies that the organizations included in the - ``Application`` group are a subset of the organizations included in - the corresponding consortium and that the ``ApplicationGroup`` is set - to ``version`` ``1``. -3. The orderer verifies that if the consortium has members, that the new - channel also has application members (creation consortiums and - channels with no members is useful for testing only). -4. The orderer creates a template configuration by taking the - ``Orderer`` group from the ordering system channel, and creating an - ``Application`` group with the newly specified members and specifying - its ``mod_policy`` to be the ``ChannelCreationPolicy`` as specified - in the consortium config. Note that the policy is evaluated in the - context of the new configuration, so a policy requiring ``ALL`` - members, would require signatures from all the new channel members, - not all the members of the consortium. -5. The orderer then applies the ``CONFIG_UPDATE`` as an update to this - template configuration. Because the ``CONFIG_UPDATE`` applies - modifications to the ``Application`` group (its ``version`` is - ``1``), the config code validates these updates against the - ``ChannelCreationPolicy``. If the channel creation contains any other - modifications, such as to an individual org's anchor peers, the - corresponding mod policy for the element will be invoked. -6. The new ``CONFIG`` transaction with the new channel config is wrapped - and sent for ordering on the ordering system channel. After ordering, - the channel is created. +For information about how to create a channel, check out :doc:`create_channel/create_channel_participation`. .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/ - diff --git a/docs/source/membership/membership.md b/docs/source/membership/membership.md index e43fb77832c..0a5aaa1589f 100644 --- a/docs/source/membership/membership.md +++ b/docs/source/membership/membership.md @@ -1,5 +1,7 @@ # Membership Service Provider (MSP) +Note: this topic describes a network that does not use a "system channel", a channel that the ordering service is bootstrapped with and the ordering service exclusively controls. Since the release of v2.3, using system channel is now considered the legacy process as compared to the process to [Create a channel without a system channel](../create_channel/create_channel_participation.html). For a version of this topic that includes information about the system channel, check out [Membership Service Provider (MSP)](https://hyperledger-fabric.readthedocs.io/en/release-2.2/membership/membership.html) from the v2.2 documentation. + ## Why do I need an MSP? Because Fabric is a permissioned network, blockchain participants need a way to prove their identity to the rest of the network in order to transact on the network. If you've read through the documentation on [Identity](../identity/identity.html) @@ -15,13 +17,13 @@ This ability to turn verifiable identities into roles is fundamental to the way *Identities are similar to your credit cards that are used to prove you can pay. The MSP is similar to the list of accepted credit cards.* -Consider a consortium of banks that operate a blockchain network. Each bank operates peer and ordering nodes, and the peers endorse transactions submitted to the network. However, each bank would also have departments and account holders. The account holders would belong to each organization, but would not run nodes on the network. They would only interact with the system from their mobile or web application. So how does the network recognize and differentiate these identities? A CA was used to create the identities, but like the card example, those identities can't just be issued, they need to be recognized by the network. MSPs are used to define the organizations that are trusted by the network members. MSPs are also the mechanism that provide members with a set of roles and permissions within the network. Because the MSPs defining these organizations are known to the members of a network, they can then be used to validate that network entities that attempt to perform actions are allowed to. +Consider a group of banks that operate a blockchain network. Each bank operates peer and ordering nodes, and the peers endorse transactions submitted to the network. However, each bank would also have departments and account holders. The account holders would belong to each organization, but would not run nodes on the network. They would only interact with the system from their mobile or web application. So how does the network recognize and differentiate these identities? A CA was used to create the identities, but like the card example, those identities can't just be issued, they need to be recognized by the network. MSPs are used to define the organizations that are trusted by the network members. MSPs are also the mechanism that provide members with a set of roles and permissions within the network. Because the MSPs defining these organizations are known to the members of a network, they can then be used to validate that network entities that attempt to perform actions are allowed to. Finally, consider if you want to join an _existing_ network, you need a way to turn your identity into something that is recognized by the network. The MSP is the mechanism that enables you to participate on a permissioned blockchain network. To transact on a Fabric network a member needs to: 1. Have an identity issued by a CA that is trusted by the network. 2. Become a member of an _organization_ that is recognized and approved by the network members. The MSP is how the identity is linked to the membership of an organization. Membership is achieved by adding the member's public key (also known as certificate, signing cert, or signcert) to the organization’s MSP. -3. Add the MSP to either a [consortium](../glossary.html#consortium) on the network or a channel. +3. Add the MSP to a channel. 4. Ensure the MSP is included in the [policy](../policies/policies.html) definitions on the network. ## What is an MSP? @@ -65,16 +67,15 @@ The channel MSP defines the _relationship_ between the identities of channel mem **Every organization participating in a channel must have an MSP defined for it**. In fact, it is recommended that there is a one-to-one mapping between organizations and MSPs. The MSP defines which members are empowered to act on behalf of the organization. This includes configuration of the MSP itself as well as approving administrative tasks that the organization has role, such as adding new members to a channel. If all network members were part of a single organization or MSP, data privacy is sacrificed. Multiple organizations facilitate privacy by segregating ledger data to only channel members. If more granularity is required within an organization, the organization can be further divided into organizational units (OUs) which we describe in more detail later in this topic. -**The system channel MSP includes the MSPs of all the organizations that participate in an ordering service.** An ordering service will likely include ordering nodes from multiple organizations and collectively these organizations run the ordering service, most importantly managing the consortium of organizations and the default policies that are inherited by the application channels. +**The channel MSP includes the MSPs of all the organizations on a channel.** This includes not just "peer organizations", which own peers and invoke chaincodes, but the organizations that own and run the ordering service. -**Local MSPs are only defined on the file system of the node or user** to which they apply. Therefore, physically and logically there is only one local MSP per -node. However, as channel MSPs are available to all nodes in the channel, they are logically defined once in the channel configuration. However, **a channel MSP is also instantiated on the file system of every node in the channel and kept synchronized via consensus**. So while there is a copy of each channel MSP on the local file system of every node, logically a channel MSP resides on and is maintained by the channel or the network. +**Local MSPs are only defined on the file system of the node or user** to which they apply. Therefore, physically and logically there is only one local MSP per node. However, as channel MSPs are available to all nodes in the channel, they are logically defined once in the channel configuration. However, **a channel MSP is also instantiated on the file system of every node in the channel and kept synchronized via consensus**. So while there is a copy of each channel MSP on the local file system of every node, logically a channel MSP resides on and is maintained by the channel or the network. The following diagram illustrates how local and channel MSPs coexist on the network: ![MSP3](./membership.diagram.2.png) -*The MSPs for the peer and orderer are local, whereas the MSPs for a channel (including the network configuration channel, also known as the system channel) are global, shared across all participants of that channel. In this figure, the network system channel is administered by ORG1, but another application channel can be managed by ORG1 and ORG2. The peer is a member of and managed by ORG2, whereas ORG1 manages the orderer of the figure. ORG1 trusts identities from RCA1, whereas ORG2 trusts identities from RCA2. It is important to note that these are administration identities, reflecting who can administer these components. So while ORG1 administers the network, ORG2.MSP does exist in the network definition.* +*In this figure, ORG1, owns the ordering node joined to the channel. The MSPs related to ORG1, the local MSP of the node and the global MSP that formally represents ORG1 on the channel, have been created by RCA1, the CA for ORG1. The peer organization, ORG2, also has a local MSP for its peer and another global MSP that represents ORG2 on the channel. Both ORG1 and ORG2 are channel members, and manage the channel in their areas of administration, and trust identities created by each other's CA. Note that in a production scenario, it is likely that there will be several peer organizations who collaborate in the administration of the channel, and potentially more than one orderer organization as well.* ## What role does an organization play in an MSP? @@ -130,7 +131,7 @@ The resulting ROLE and OU attributes are visible inside the X.509 signing certif **Note:** For Channel MSPs, just because an actor has the role of an administrator it doesn't mean that they can administer particular resources. The actual power a given identity has with respect to administering the system is determined by the _policies_ that manage system resources. For example, a channel policy might specify that `ORG1-MANUFACTURING` administrators, meaning identities with a role of `admin` and a Node OU of `ORG1-MANUFACTURING`, have the rights to add new organizations to the channel, whereas the `ORG1-DISTRIBUTION` administrators have no such rights. -Finally, OUs could be used by different organizations in a consortium to distinguish each other. But in such cases, the different organizations have to use the same Root CAs and Intermediate CAs for their chain of trust, and assign the OU field to identify members of each organization. When every organization has the same CA or chain of trust, this makes the system more centralized than what might be desirable and therefore deserves careful consideration on a blockchain network. +Finally, OUs could be used by different organizations to distinguish each other. But in such cases, the different organizations have to use the same Root CAs and Intermediate CAs for their chain of trust, and assign the OU field to identify members of each organization. When every organization has the same CA or chain of trust, this makes the system more centralized than what might be desirable and therefore deserves careful consideration on a blockchain network. ## MSP Structure diff --git a/docs/source/msp.rst b/docs/source/msp.rst index c9749be807e..bfc8f8c87e5 100644 --- a/docs/source/msp.rst +++ b/docs/source/msp.rst @@ -1,26 +1,13 @@ Membership Service Providers (MSP) ================================== -The document serves to provide details on the setup and best practices for MSPs. +For a conceptual overview of the Membership Service Provider (MSP), check out +:doc:`membership/membership`. -Membership Service Provider (MSP) is a Hyperledger Fabric component that offers -an abstraction of membership operations. +This topic elaborates on the setup of the MSP implementation supported by +Hyperledger Fabric and discusses best practices concerning its use. -In particular, an MSP abstracts away all cryptographic mechanisms and protocols -behind issuing certificates, validating certificates, and user authentication. -An MSP may define its own notion of identity, and the rules by which those -identities are governed (identity validation) and authenticated (signature -generation and verification). - -A Hyperledger Fabric blockchain network can be governed by one or more MSPs. -This provides modularity of membership operations, and interoperability -across different membership standards and architectures. - -In the rest of this document we elaborate on the setup of the MSP -implementation supported by Hyperledger Fabric, and discuss best practices -concerning its use. - -MSP Configuration +MSP configuration ----------------- To setup an instance of the MSP, its configuration needs to be specified @@ -34,8 +21,7 @@ in the network (e.g. ``msp1``, ``org2``, and ``org3.divA``). This is the name un which membership rules of an MSP representing a consortium, organization or organization division is to be referenced in a channel. This is also referred to as the *MSP Identifier* or *MSP ID*. MSP Identifiers are required to be unique per MSP -instance. For example, shall two MSP instances with the same identifier be -detected at the system channel genesis, orderer setup will fail. +instance. In the case of the default MSP implementation, a set of parameters need to be specified to allow for identity (certificate) validation and signature @@ -98,54 +84,10 @@ How to generate MSP certificates and their signing keys? certificates and keys. Please note that Hyperledger Fabric does not support RSA key and certificates. -Alternatively, the ``cryptogen`` tool can be used as described in -:doc:`getting_started`. - -`Hyperledger Fabric CA `_ -can also be used to generate the keys and certificates needed to configure an MSP. - -MSP setup on the peer & orderer side ------------------------------------- - -To set up a local MSP (for either a peer or an orderer), the administrator -should create a folder (e.g. ``$MY_PATH/mspconfig``) that contains six subfolders -and a file: - -1. a folder ``admincerts`` to include PEM files each corresponding to an - administrator certificate -2. a folder ``cacerts`` to include PEM files each corresponding to a root - CA's certificate -3. (optional) a folder ``intermediatecerts`` to include PEM files each - corresponding to an intermediate CA's certificate -4. (optional) a file ``config.yaml`` to configure the supported Organizational Units - and identity classifications (see respective sections below). -5. (optional) a folder ``crls`` to include the considered CRLs -6. a folder ``keystore`` to include a PEM file with the node's signing key; - we emphasise that currently RSA keys are not supported -7. a folder ``signcerts`` to include a PEM file with the node's X.509 - certificate -8. (optional) a folder ``tlscacerts`` to include PEM files each corresponding to a TLS root - CA's certificate -9. (optional) a folder ``tlsintermediatecerts`` to include PEM files each - corresponding to an intermediate TLS CA's certificate - -In the configuration file of the node (core.yaml file for the peer, and -orderer.yaml for the orderer), one needs to specify the path to the -mspconfig folder, and the MSP Identifier of the node's MSP. The path to the -mspconfig folder is expected to be relative to FABRIC_CFG_PATH and is provided -as the value of parameter ``mspConfigPath`` for the peer, and ``LocalMSPDir`` -for the orderer. The identifier of the node's MSP is provided as a value of -parameter ``localMspId`` for the peer and ``LocalMSPID`` for the orderer. -These variables can be overridden via the environment using the CORE prefix for -peer (e.g. CORE_PEER_LOCALMSPID) and the ORDERER prefix for the orderer (e.g. -ORDERER_GENERAL_LOCALMSPID). Notice that for the orderer setup, one needs to -generate, and provide to the orderer the genesis block of the system channel. -The MSP configuration needs of this block are detailed in the next section. - -*Reconfiguration* of a "local" MSP is only possible manually, and requires that -the peer or orderer process is restarted. In subsequent releases we aim to -offer online/dynamic reconfiguration (i.e. without requiring to stop the node -by using a node managed system chaincode). +The Hyperledger Fabric CA can also be used to generate the keys and certificates +needed to configure an MSP. Check out +`Registering and enrolling identities with a CA `_ +for more information about how to generate MSPs for nodes and organizations. Organizational Units -------------------- @@ -169,7 +111,7 @@ The ``Certificate`` field refers to the CA or intermediate CA certificate path under which identities, having that specific OU, should be validated. The path is relative to the MSP root folder and cannot be empty. -Identity Classification +Identity classification ----------------------- The default MSP implementation allows organizations to further classify identities into clients, @@ -241,38 +183,14 @@ without the certificate being stored in the ``admincerts`` folder of the MSP. In with the admin OU. Certificates in the ``admincerts`` folder will still grant the role of administrator to their bearer, provided that they possess the client or admin OU. -Channel MSP setup ------------------ +Adding MSPs to channels +----------------------- + +For information about how to add MSPs to a channel (including the decision of +whether to bootstrap ordering nodes with a system channel genesis block), check +out :doc:`create_channel/create_channel_overview`. -At the genesis of the system, verification parameters of all the MSPs that -appear in the network need to be specified, and included in the system -channel's genesis block. Recall that MSP verification parameters consist of -the MSP identifier, the root of trust certificates, intermediate CA and admin -certificates, as well as OU specifications and CRLs. -The system genesis block is provided to the orderers at their setup phase, -and allows them to authenticate channel creation requests. Orderers would -reject the system genesis block, if the latter includes two MSPs with the same -identifier, and consequently the bootstrapping of the network would fail. - -For application channels, the verification components of only the MSPs that -govern a channel need to reside in the channel's genesis block. We emphasize -that it is **the responsibility of the application** to ensure that correct -MSP configuration information is included in the genesis blocks (or the -most recent configuration block) of a channel prior to instructing one or -more of their peers to join the channel. - -When bootstrapping a channel with the help of the configtxgen tool, one can -configure the channel MSPs by including the verification parameters of MSP -in the mspconfig folder, and setting that path in the relevant section in -``configtx.yaml``. - -*Reconfiguration* of an MSP on the channel, including announcements of the -certificate revocation lists associated to the CAs of that MSP is achieved -through the creation of a ``config_update`` object by the owner of one of the -administrator certificates of the MSP. The client application managed by the -admin would then announce this update to the channels in which this MSP appears. - -Best Practices +Best practices -------------- In this section we elaborate on best practices for MSP diff --git a/docs/source/raft_configuration.md b/docs/source/raft_configuration.md index 4b9a4298d58..bc37737080a 100644 --- a/docs/source/raft_configuration.md +++ b/docs/source/raft_configuration.md @@ -2,6 +2,8 @@ **Audience**: *Raft ordering node admins* +Note: this topic describes the process for configuring a Raft ordering service that has not been bootstrapped with a system channel genesis block. For a version of this topic that includes information about the system channel, check out [Configuring and operating a Raft ordering service](https://hyperledger-fabric.readthedocs.io/en/release-2.2/raft_configuration.html). + ## Conceptual overview For a high level overview of the concept of ordering and how the supported @@ -13,17 +15,7 @@ documentation on [Planning for an ordering service](./deployorderer/ordererplan. ## Configuration -While every Raft node must be added to the system channel, a node does not need -to be added to every application channel. Additionally, you can remove and add a -node from a channel dynamically without affecting the other nodes, a process -described in the Reconfiguration section below. - -Raft nodes identify each other using TLS pinning, so in order to impersonate a -Raft node, an attacker needs to obtain the **private key** of its TLS -certificate. As a result, it is not possible to run a Raft node without a valid -TLS configuration. - -A Raft cluster is configured in two planes: +A Raft cluster is configured in two places: * **Local configuration**: Governs node specific aspects, such as TLS communication, replication behavior, and file storage. @@ -32,6 +24,11 @@ A Raft cluster is configured in two planes: corresponding channel, as well as protocol specific parameters such as heartbeat frequency, leader timeouts, and more. +Raft nodes identify each other using TLS pinning, so in order to impersonate a +Raft node, an attacker needs to obtain the **private key** of its TLS +certificate. As a result, it is not possible to run a Raft node without a valid +TLS configuration. + Recall, each channel has its own instance of a Raft protocol running. Thus, a Raft node must be referenced in the configuration of each channel it belongs to by adding its server and client TLS certificates (in `PEM` format) to the channel @@ -57,13 +54,12 @@ The following section from `configtx.yaml` shows three Raft nodes (also called ServerTLSCert: path/to/ServerTLSCert2 ``` -Note: an orderer will be listed as a consenter in the system channel as well as -any application channels they're joined to. - When the channel config block is created, the `configtxgen` tool reads the paths to the TLS certificates, and replaces the paths with the corresponding bytes of the certificates. +Note: it is possible to remove and add an ordering node from a channel dynamically without affecting the other nodes, a process described in the Reconfiguration section below. + ### Local configuration The `orderer.yaml` has two configuration sections that are relevant for Raft @@ -202,23 +198,13 @@ one or two). So by extending a cluster of three nodes to four nodes (while only two are alive) you are effectively stuck until the original offline node is resurrected. -Adding a new node to a Raft cluster is done by: - - 1. **Adding the TLS certificates** of the new node to the channel through a - channel configuration update transaction. Note: the new node must be added to - the system channel before being added to one or more application channels. - 2. **Fetching the latest config block** of the system channel from an orderer node - that's part of the system channel. - 3. **Ensuring that the node that will be added is part of the system channel** - by checking that the config block that was fetched includes the certificate of - (soon to be) added node. - 4. **Starting the new Raft node** with the path to the config block in the - `General.BootstrapFile` configuration parameter. - 5. **Waiting for the Raft node to replicate the blocks** from existing nodes for - all channels its certificates have been added to. After this step has been - completed, the node begins servicing the channel. - 6. **Adding the endpoint** of the newly added Raft node to the channel - configuration of all channels. +To add a new node to the ordering service: + + 1. **Ensure the orderer organization that owns the new node is one of the orderer organizations on the channel**. If the orderer organization is not an administrator, the node will be unable to pull blocks as a follower or be joined to the consenter set. + 2. **Start the new ordering node**. For information about how to deploy an ordering node, check out [Planning for an ordering service](./deployorderer/ordererdeploy.html). Note that when you use the `osnadmin` CLI to create and join a channel, you do not need to point to a configuration block when starting the node. + 3. **Use the `osnadmin` CLI to add the first orderer to the channel**. For more information, check out [Create a channel without a system channel](../create_channel/create_channel_participation.html#step-two-use-the-osnadmin-cli-to-add-the-first-orderer-to-the-channel) tutorial. + 4. **Wait for the Raft node to replicate the blocks** from existing nodes for all channels its certificates have been added to. When an ordering node is added to a channel, it is added as a "follower", a state in which it can replicate blocks but is not part of the "consenter set" actively servicing the channel. When the node finishes replicating the blocks, its status should change from "onboarding" to "active". Note that an "active" ordering node is still not part of the consenter set. + 5. **Add the new ordering node to the consenter set**. For more information, check out [Create a channel without a system channel](../create_channel/create_channel_participation.html#step-three-join-additional-ordering-nodes). It is possible to add a node that is already running (and participates in some channels already) to a channel while the node itself is running. To do this, simply @@ -231,27 +217,13 @@ channel, and then start the Raft instance for that chain. After it has successfully done so, the channel configuration can be updated to include the endpoint of the new Raft orderer. -Removing a node from a Raft cluster is done by: +To remove an ordering node from the consenter set of a channel, use the `osnadmin channel remove` command to remove its endpoint and certificates from the channel. For more information, check out [Add or remove orderers from existing channels](../create_channel/create_channel_participation.html#add-or-remove-orderers-from-existing-channels). - 1. Removing its endpoint from the channel config for all channels, including - the system channel controlled by the orderer admins. - 2. Removing its entry (identified by its certificates) from the channel - configuration for all channels. Again, this includes the system channel. - 3. Shut down the node. +Once an ordering node is removed from the channel, the other ordering nodes stop communicating with the removed orderer in the context of the removed channel. They might still be communicating on other channels. -Removing a node from a specific channel, but keeping it servicing other channels -is done by: +The node that is removed from the channel automatically detects its removal either immediately or after `EvictionSuspicion` time has passed (10 minutes by default) and shuts down its Raft instance on that channel. - 1. Removing its endpoint from the channel config for the channel. - 2. Removing its entry (identified by its certificates) from the channel - configuration. - 3. The second phase causes: - * The remaining orderer nodes in the channel to cease communicating with - the removed orderer node in the context of the removed channel. They might - still be communicating on other channels. - * The node that is removed from the channel would autonomously detect its - removal either immediately or after `EvictionSuspicion` time has passed - (10 minutes by default) and will shut down its Raft instance. +If the intent is to delete the node entirely, remove it from all channels before shutting down the node. ### TLS certificate rotation for an orderer node @@ -259,7 +231,7 @@ All TLS certificates have an expiration date that is determined by the issuer. These expiration dates can range from 10 years from the date of issuance to as little as a few months, so check with your issuer. Before the expiration date, you will need to rotate these certificates on the node itself and every channel -the node is joined to, including the system channel. +the node is joined to. **Note:** In case the public key of the TLS certificate remains the same, there is no need to issue channel configuration updates. diff --git a/docs/source/updating_capabilities.md b/docs/source/updating_capabilities.md index 52cafcb12c9..aedfcae428a 100644 --- a/docs/source/updating_capabilities.md +++ b/docs/source/updating_capabilities.md @@ -2,9 +2,11 @@ *Audience: network administrators, node administrators* +Note: this topic describes the process for updating capabilities on a network that has not been bootstrapped with a system channel genesis block. For a version of this topic that includes information about updating system channel capabilities, check out [Updating the capability level of a channel](https://hyperledger-fabric.readthedocs.io/en/release-2.2/updating_capabilities.html). + If you're not familiar with capabilities, check out [Capabilities](./capabilities_concept.html) before proceeding, paying particular attention to the fact that **peers and orderers that belong to the channel must be upgraded before enabling capabilities**. -For information about any new capability levels in the latest release of Fabric, check out [Upgrading your components](./upgrade_to_newest_version.html#Capabilities). +For information about any new capability levels in the latest release of Fabric, check out [Upgrading your components](./upgrade_to_newest_version.html#capabilities). Note: when we use the term “upgrade” in Hyperledger Fabric, we’re referring to changing the version of a component (for example, going from one version of a binary to the next version). The term “update,” on the other hand, refers not to versions but to configuration changes, such as updating a channel configuration or a deployment script. As there is no data migration, technically speaking, in Fabric, we will not use the term "migration" or "migrate" here. @@ -20,8 +22,6 @@ For this reason, think of enabling channel capabilities as a point of no return. ## Overview -In this tutorial, we will show the process for updating capabilities in all of the parts of the configuration of both the ordering system channel and any application channels. - Whether you will need to update every part of the configuration for all of your channels will depend on the contents of the latest release as well as your own use case. For more information, check out [Upgrading to the latest version of Fabric](./upgrade_to_newest_version.html). Note that it may be necessary to update to the newest capability levels before using the features in the latest release, and it is considered a best practice to always be at the latest binary versions and capability levels. Because updating the capability level of a channel involves the configuration update transaction process, we will be relying on our [Updating a channel configuration](./config_update.html) topic for many of the commands. @@ -32,24 +32,17 @@ As with any channel configuration update, updating capabilities is, at a high le 2. Create a modified channel config 3. Create a config update transaction -We will enable these capabilities in the following order: - -1. [Orderer system channel](#orderer-system-channel-capabilities) - - * Orderer group - * Channel group - -2. [Application channels](#enable-capabilities-on-existing-channels) +Recall from the conceptual topic on capabilities that three types of capabilities exist, reflecting the three areas of administration: * Orderer group * Channel group * Application group -While it is possible to edit multiple parts of the configuration of a channel at the same time, in this tutorial we will show how this process is done incrementally. In other words, we will not bundle a change to the `Orderer` group and the `Channel` group of the system channel into one configuration change. This is because not every release will have both a new `Orderer` group capability and a `Channel` group capability. +While it is possible to edit multiple parts of the configuration of a channel at the same time, in this tutorial we will show how this process is done incrementally. In other words, we will not bundle a change to the `Orderer` group and the `Channel` group into one configuration change. This is because not every release will have both a new `Orderer` group capability and a `Channel` group capability. -Note that in production networks, it will not be possible or desirable for one user to be able to update all of these channels (and parts of configurations) unilaterally. The orderer system channel, for example, is administered exclusively by ordering organization admins (though it is possible to add peer organizations as ordering service organizations). Similarly, updating either the `Orderer` or `Channel` groups of a channel configuration requires the signature of an ordering service organization in addition to peer organizations. Distributed systems require collaborative management. +Note that in production networks, it will not be possible or desirable for one user to be able to update all of these channels (and parts of configurations) unilaterally. Updating either the `Orderer` or `Channel` groups of a channel configuration, for example, requires the signature of an ordering service organization in addition to peer organizations. Distributed systems require collaborative management. -#### Create a capabilities config file +## Create a capabilities config file Note that this tutorial presumes that a file called `capabilities.json` has been created and includes the capability updates you want to make to the various sections of the config. It also uses `jq` to apply the edits to the modified config file. @@ -91,57 +84,9 @@ In this example, the ``capabilities.json`` file looks like this (note: if you ar } ``` -Note that by default peer organizations are not admins of the orderer system channel and will therefore be unable to propose configuration updates to it. An orderer organization admin would have to create a file like this (without the `application` group capability, which does not exist in the system channel) to propose updating the system channel configuration. Note that because application channel copy the system channel configuration by default, unless a different channel profile is created which specifies capability levels, the `Channel` and `Orderer` group capabilities for the application channel will be the same as those in the network's system channel. - -## Orderer system channel capabilities - -Because application channels copy the configuration of the orderer system channel by default, it is considered a best practice to update the capabilities of the system channel before any application channels. This mirrors the process of updating ordering nodes to the newest version before peers, as described in [Upgrading your components](./upgrading_your_components.html). - -Note that the orderer system channel is administered by ordering service organizations. By default this will be a single organization (the organization that created the initial nodes in the ordering service), but more organizations can be added here (for example, if multiple organizations have contributed nodes to the ordering service). - -Make sure all of the ordering nodes in your ordering service have been upgraded to the required binary level before updating the `Orderer` and `Channel` capability. If an ordering node is not at the required level, it will be unable to process the config block with the capability and will crash. Similarly, note that if a new channel is created on this ordering service, all of the peers that will be joined to it must be at least to the node level corresponding to the `Channel` and `Application` capabilities, otherwise they will also crash when attempting to process the config block. For more information, check out [Capabilities](./capabilities_concept.html). - -### Set environment variables - -You will need to export the following variables: - -* `CH_NAME`: the name of the system channel being updated. -* `CORE_PEER_LOCALMSPID`: the MSP ID of the organization proposing the channel update. This will be the MSP of one of the orderer organizations. -* `TLS_ROOT_CA`: the absolute path to the TLS cert of your ordering node(s). -* `CORE_PEER_MSPCONFIGPATH`: the absolute path to the MSP representing your organization. -* `ORDERER_CONTAINER`: the name of an ordering node container. When targeting the ordering service, you can target any particular node in the ordering service. Your requests will be forwarded to the leader automatically. - -### `Orderer` group - -For the commands on how to pull, translate, and scope the channel config, navigate to [Step 1: Pull and translate the config](./config_update.html#step-1-pull-and-translate-the-config). Once you have a `modified_config.json`, add the capabilities to the `Orderer` group of the config (as listed in `capabilities.json`) using this command: - -``` -jq -s '.[0] * {"channel_group":{"groups":{"Orderer": {"values": {"Capabilities": .[1].orderer}}}}}' config.json ./capabilities.json > modified_config.json -``` - -Then, follow the steps at [Step 3: Re-encode and submit the config](./config_update.html#step-3-re-encode-and-submit-the-config). - -Note that because you are updating the system channel, the `mod_policy` for the system channel will only require the signature of ordering service organization admins. - -### `Channel` group - -Once again, navigate to [Step 1: Pull and translate the config](./config_update.html#step-1-pull-and-translate-the-config). Once you have a `modified_config.json`, add the capabilities to the `Channel` group of the config (as listed in `capabilities.json`) using this command: - -``` -jq -s '.[0] * {"channel_group":{"values": {"Capabilities": .[1].channel}}}' config.json ./capabilities.json > modified_config.json -``` - -Then, follow the steps at [Step 3: Re-encode and submit the config](./config_update.html#step-3-re-encode-and-submit-the-config). - -Note that because you are updating the system channel, the `mod_policy` for the system channel will only require the signature of ordering service organization admins. In an application channel, as you'll see, you would normally need to satisfy both the `MAJORITY` `Admins` policy of both the `Application` group (consisting of the MSPs of peer organizations) and the `Orderer` group (consisting of ordering service organizations), assuming you have not changed the default values. - -## Enable capabilities on existing channels - -Now that we have updating the capabilities on the orderer system channel, we need to updating the configuration of any existing application channels you want to update. - -As you will see, the configuration of application channels is very similar to that of the system channel. This is what allows us to re-use `capabilities.json` and the same commands we used for updating the system channel (using different environment variables which we will discuss below). +## Update capabilities on existing channels -**Make sure all of the ordering nodes in your ordering service and peers on the channel have been upgraded to the required binary level before updating capabilities. If a peer or an ordering node is not at the required level, it will be unable to process the config block with the capability and will crash**. For more information, check out [Capabilities](./capabilities_concept.html). +Make sure all of the ordering nodes in your ordering service and peers on the channel have been upgraded to the required binary level before updating capabilities. If a peer or an ordering node is not at the required level, it will be unable to process the config block with the capability and will crash. For more information, check out [Capabilities](./capabilities_concept.html). ### Set environment variables @@ -163,7 +108,7 @@ jq -s '.[0] * {"channel_group":{"groups":{"Orderer": {"values": {"Capabilities": Then, follow the steps at [Step 3: Re-encode and submit the config](./config_update.html#step-3-re-encode-and-submit-the-config). -Note the `mod_policy` for this capability defaults to the `MAJORITY` of the `Admins` of the `Orderer` group (in other words, a majority of the admins of the ordering service). Peer organizations can propose an update to this capability, but their signatures will not satisfy the relevant policy in this case. +Note the `mod_policy` for this capability defaults to the `MAJORITY` of the `Admins` of the `Orderer` group (in other words, a majority of the admins of the ordering service). Peer organizations can propose an update to this capability, but their signatures will not satisfy the default policy in this case. ### `Channel` group