Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Even more edits to docs for participation API #2208

Merged
merged 1 commit into from Jan 5, 2021
Merged

Even more edits to docs for participation API #2208

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/source/capability_requirements.rst
View file
Open in desktop
@@ -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 <https://hyperledger-fabric.readthedocs.io/en/release-2.2/capability_requirements.html>`_ 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
Expand All @@ -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
pamandrejko marked this conversation as resolved.
Show resolved Hide resolved
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand All @@ -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/
22 changes: 6 additions & 16 deletions docs/source/config_update.md
View file
Open in desktop
Expand Up @@ -2,14 +2,16 @@

*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**.

* **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**.

Expand All @@ -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).

<details>
<summary>
**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**
</summary>
```
{
Expand Down Expand Up @@ -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.
Expand All @@ -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.

Expand All @@ -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:
Expand All @@ -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.
Expand Down
131 changes: 10 additions & 121 deletions docs/source/configtx.rst
View file
Open in desktop
@@ -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) <https://hyperledger-fabric.readthedocs.io/en/release-2.2/configtx.html>`_
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
Expand Down Expand Up @@ -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<string, *ConfigGroup> {
"Orderer":&ConfigGroup{
Groups:map<String, *ConfigGroup> {
{{org_name}}:&ConfigGroup{
Values:map<string, *ConfigValue>{
"MSP":msp.MSPConfig,
},
},
},

Values:map<string, *ConfigValue> {
"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<string, *ConfigGroup> {
"Consortiums":&ConfigGroup{
Groups:map<String, *ConfigGroup> {
{{consortium_name}}:&ConfigGroup{
Groups:map<string, *ConfigGroup> {
{{org_name}}:&ConfigGroup{
Values:map<string, *ConfigValue>{
"MSP":msp.MSPConfig,
},
},
},
Values:map<string, *ConfigValue> {
"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:
Expand Down Expand Up @@ -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/