github.com/osdi23p228/fabric@v0.0.0-20221218062954-77808885f5db/release_notes/v2.2.1.md

v2.2.1 Release Notes - September 30, 2020
=========================================

What's New in Hyperledger Fabric v2.2.1
---------------------------------------

Hyperledger Fabric v2.2.1 provides important improvements and fixes, with a focus on the following areas:
* Management of certificate expirations
* Hardware security module (HSM) efficiency
* Upgrade to v2.x


Fixes
-----

**FAB-18163: orderer certificate expiration - TLSHandshakeTimeShift without separate cluster port**

If the TLS certificates of the ordering service nodes expire and are not replaced in time,
communication between them cannot be established, making it impossible to send
new transactions to the ordering service. To recover from such a scenario, it is possible
to configure a backwards timeshift that ordering service nodes will utilize for TLS
handshakes so that transactions can be processed.
If the Raft cluster service is sharing the orderer’s main gRPC server port,
configure the new orderer.yaml `General.TLS.TLSHandshakeTimeShift` property.
If using a separate cluster listener port,
configure the orderer.yaml `General.Cluster.TLSHandshakeTimeShift` property.

**FAB-18205: orderer certificate expiration - Permit peer CLI to communicate with orderers with expired TLS certificates**

The change allows peer CLI to communicate with ordering service nodes with expired TLS certificates
by setting the `--tlsHandshakeTimeShift` flag to a desired backwards timeshift.
The change applies to the `peer channel fetch` and `peer channel update` commands to allow
fetching configuration blocks and updating the channel configuration for orderers with expired TLS certificates.

**FAB-18171: orderer certificate expiration - Disregard certificate validity period in intra-orderer communication**

This change makes the orderer cluster authentication infrastructure
disregard validity periods when comparing certificates, and only regard public keys.
With this change, an expiring Raft TLS certificate can be replaced
with a new certificate that has the same public key, without requiring channel configuration updates.

**FAB-18188: peer and orderer certificate expiration - Log expiration date upon startup**

The enrollment, TLS server, and TLS client certificate expiration dates are now logged upon peer and orderer startup.

**peer and orderer PKCS#11 - Add object handle cache**

With this change, object handles are cached in the PKCS#11 implementation.
In support of this change, in addition to pooling idle sessions, the
provider tracks active sessions. If some condition occurs that results
in all sessions being closed, cached object handles are no longer valid
so the handle cache is purged.

**FAB-18250: peer and orderer PKCS#11 - Introduce error checking for evicting invalid PKCS#11 sessions**

FAB-17722 introduced a call to the pkcs11 GetSessionInfo function for retrieving the current state of
the PKCS11 session. The result of this function was used to determine whether a session was still
valid to perform HSM operations or if it should be evicted from the session pool. Performance tests
showed that the call to GetSessionInfo was computationally prohibitively expensive. FAB-18242 reverted
this change and FAB-18250 introduced a new method for determining if the PKCS11 session is invalid.
Now when an HSM operation fails, we check the resultant error against the known session error codes and
evict the session from the pool if the error was the result of an invalid session.

**FAB-18208: peer - Do not sign gossip message if membership is empty**

This change suppresses the signing of gossip messages if the message will not get
sent regardless due to an empty gossip membership. The change reduces CPU consumption
and eliminates unnecessary calls to an HSM.

**peer and orderer PKCS#11 - Add log message if a key cannot be found**

A debug message is now provided in the bccsp_p11 logger if a key cannot be found in the HSM.

**FAB-18194: peer - Fix service discovery for legacy installed chaincodes**

The service discovery endorsers query may fail with errors
"failed constructing descriptor for chaincodes" and
"required chaincodes are not installed on sufficient peers", even
when a chaincode is installed on a sufficient number of peers.
The peer initialization has been fixed so that chaincodes installed with the legacy chaincode
lifecycle are correctly recognized by service discovery.

**FAB-18191: peer - Remove contents of leveldb directory instead of the directory when dropping databases**

The peer `upgrade-dbs`, `rebuild-dbs`, `reset`, and `rollback` commands each drop a peer's
leveldb databases so that they can be rebuilt upon the next peer startup.
The commands now remove all contents of the leveldb directories, rather than dropping the
directory itself. This fix is required if mounting one of the leveldb directories in addition
to the overall peer data directory as specified in core.yaml `peer.fileSystemPath`.

**FAB-15810: peer - Deprioritize fetching of missing private data**

The private data reconciler attempts to retrieve missing private data from other
peers in a channel that belong to the same private data collection based on the interval
configured in core.yaml `peer.gossip.pvtData.reconcileSleepInterval`
(by default every one minute). If private data cannot be reconciled, it will be attempted
every interval and may block the reconciliation of other private data. This fix places
private data that can't be reconciled in a depriorized queue so that other private data
can be reconciled. The depriorized entries will be re-attempted less often based on the
interval configured in core.yaml `ledger.pvtdataStore.deprioritizedDataReconcilerInterval`
(by default every 60 minutes).

**orderer - Check suspect info once per suspect interval when using Raft**

The Raft-based ordering service node was checking to see if it was evicted too often.
This fix ensures that the ordering service node only checks once per suspect interval,
which is every 10 minutes by default.

**cryptogen - Duplicate alternate names in multi-domain certificates**

When using cryptogen to generate certificates, the X509v3 Subject Alternative Name field contained duplicate entries.
The Subject Alternative Name now contains one entry per alternate name.

**FAB-18245: peer - Large values retrieved from chaincode may be incorrect when using CouchDB**

Chaincode values larger than 64kb are saved to CouchDB,
but not saved to the peer's CouchDB cache.
However, chaincode still attempted to retrieve from the cache,
and therefore an incorrect value may be retrieved.
The fix ensures that for values larger than 64kb, the data will be retrieved from CouchDB.


Deprecations (existing)
-----------------------

**FAB-15754: The 'Solo' consensus type is deprecated.**

The 'Solo' consensus type has always been marked non-production and should be in
use only in test environments, however for compatibility it is still available,
but may be removed entirely in a future release.

**FAB-16408: The 'Kafka' consensus type is deprecated.**

The 'Raft' consensus type was introduced in v1.4.1 and has become the preferred
production consensus type.  There is a documented and tested migration path from
Kafka to Raft, and existing users should migrate to the newer Raft consensus type.
For compatibility with existing deployments, Kafka is still supported,
but may be removed entirely in a future release.
Additionally, the fabric-kafka and fabric-zookeeper docker images are no longer updated, maintained, or published.

**Fabric CouchDB image is deprecated**

v2.2.0 added support for CouchDB 3.1.0 as the recommended and tested version of CouchDB.
If prior versions are utilized, a Warning will appear in peer log.
Note that CouchDB 3.1.0 requires that an admin username and password be set,
while this was optional in CouchDB v2.x. See the
[Fabric CouchDB documentation](https://hyperledger-fabric.readthedocs.io/en/v2.2.0/couchdb_as_state_database.html#couchdb-configuration)
for configuration details.
Also note that CouchDB 3.1.0 default max_document_size is reduced to 8MB. Set a higher value if needed in your environment.
Finally, the fabric-couchdb docker image will not be updated to v3.1.0 and will no longer be updated, maintained, or published.
Users can utilize the official CouchDB docker image maintained by the Apache CouchDB project instead.

**FAB-7559: Support for specifying orderer endpoints at the global level in channel configuration is deprecated.**

Utilize the new 'OrdererEndpoints' stanza within the channel configuration of an organization instead.
Configuring orderer endpoints at the organization level accommodates
scenarios where orderers are run by different organizations. Using
this configuration ensures that only the TLS CA certificates of that organization
are used for orderer communications, in contrast to the global channel level endpoints which
would cause an aggregation of all orderer TLS CA certificates across
all orderer organizations to be used for orderer communications.

**FAB-17428: Support for configtxgen flag `--outputAnchorPeersUpdate` is deprecated.**

The `--outputAnchorPeersUpdate` mechanism for updating anchor peers has always had
limitations (for instance, it only works the first time anchor peers are updated).
Instead, anchor peer updates should be performed through the normal config update flow.

**FAB-15406: The fabric-tools docker image is deprecated**

The fabric-tools docker image will not be published in future Fabric releases.
Instead of using the fabric-tools docker image, users should utilize the
published Fabric binaries. The Fabric binaries can be used to make client calls
to Fabric runtime components, regardless of where the Fabric components are running.

**FAB-15317: Block dissemination via gossip is deprecated**

Block dissemination via gossip is deprecated and may be removed in a future release.
Fabric peers can be configured to receive blocks directly from an ordering service
node by using the following configuration:
```
peer.gossip.orgLeader: true
peer.gossip.useLeaderElection: false
peer.gossip.state.enabled: false
```

**FAB-15061: Legacy chaincode lifecycle is deprecated**

The legacy chaincode lifecycle from v1.x is deprecated and will be removed
in a future release. To prepare for the eventual removal, utilize the v2.x
chaincode lifecycle instead, by enabling V2_0 application capability on all
channels, and redeploying all chaincodes using the v2.x lifecycle. The new
chaincode lifecycle provides a more flexible and robust governance model
for chaincodes. For more details see the
[documentation for enabling the new lifecycle](https://hyperledger-fabric.readthedocs.io/en/release-2.2/enable_cc_lifecycle.html).


Change log
----------
For the full list of changes, refer to the release change log:
https://github.com/osdi23p228/fabric/blob/release-2.2/CHANGELOG.md#v221