The organization (Org) and channel names are two fairly important configuration parameters of a Fabric network. Both are already set in the samples Fabric provides: the organizations are usually named "Org1" and "Org2", and the channel "mychannel". In real application development, however, you usually need custom organization and channel names. Here I use balance-transfer, the sample closest to a real application, to show how to set custom organization and channel names.

Introduction

Before a Fabric network starts, the binary tools cryptogen and configtxgen generate the members' certificate directories, the orderer genesis block, and the channel configuration transaction. This is when the organization and channel names get written into the configuration.

So to customize these two parameters, you need to regenerate these artifacts, and also modify the other related configuration files and the application code.

balance-transfer is a sample in fabric-samples that implements a fairly complete application on top of the Fabric Node SDK. I use version v1.0.0 here.

1. Get the cryptogen and configtxgen tools

How to download cryptogen and configtxgen was covered in the first-network sample. Besides downloading them directly, you can also build them by hand from the fabric project.

cd ~/go/src/github/hyperledger/fabric     // enter the fabric directory
make cryptogen && make configtxgen        // build the tools

The tools are generated under fabric/build/bin. Move them to .../fabric-samples/balance-transfer/artifacts/channel for later use.

2. Edit the cryptogen.yaml and configtx.yaml config files

These two files are in the artifacts/channel directory. They work together with the tools above to generate the configuration used to initialize the network.
The change is simple: replace "Org1" and "Org2" in the files with the organization names you want.

3. Generate the certificate directory, genesis block, and channel configuration transaction

Run the following commands in the artifacts/channel directory to generate the configuration.

rm -rf crypto-config genesis.block mychannel.tx      //remove the existing artifacts
./cryptogen generate --config=./cryptogen.yaml 
./configtxgen -profile TwoOrgsOrdererGenesis -outputBlock ./genesis.block 
./configtxgen -profile TwoOrgsChannel -outputCreateChannelTx ./newchannel.tx -channelID newchannel

Note: to change the channel name, just pass the channel name after the --channelID flag in this step (the default is mychannel), then edit config.json in the balance-transfer directory and replace the channelName parameter. That is all it takes to rename the channel.

When this finishes, the channel directory contains a crypto-config directory with the new organization names, genesis.block, and newchannel.tx.

4. Edit the network config file network-config.json

The file is at app/network-config.json. It mainly sets the ip and port of each node in the network and the organization each node belongs to.
Likewise, replace every parameter in this file that relates to the organization names, and make sure not to miss the related certificate paths.

5. Edit the CA server config file

Changing this file is more involved, because it is generated automatically inside the CA node when the node starts. The only way to modify it is to copy its contents out of the container, edit them there, and mount the file back in to override the original.
The file lives in the CA node's file system, so you need to enter the container after starting the CA node:

docker exec -it ca_peerOrg1            // assuming the organization name hasn't been changed yet
cat /etc/hyperledger/fabric-ca-server/fabric-ca-server-config.yaml

Open the file and find the affiliations section:

affiliations:
org1:
    - department1
    - department2
org2:
    - department1

The organization names are hardcoded here. If you don't change them, user registration will fail with an error. First create a fabric-ca-server-config.yaml file in the artifacts directory on the host, paste in the full file contents that cat printed inside the container, and change the organization names in the affiliations section to the ones you want.
The new CA config file now exists outside the container. In the next step it is mounted into the container, where it overrides the auto-generated config file and puts the change into effect.

6. Edit the container config file docker-compose.yaml

  1. First, batch-replace every organization name that needs to change in docker-compose.yaml.
  2. In the environment section of the CA node config, change the private key file name (ending in _sk) at the end of the CA KEYFILE and TLS KEYFILE values to the name of the private key file in the crypto-config/peerOrganizations/orgname.example.com/ca directory, where orgname is the new organization name.

This is needed because we regenerated the MSP directory crypto-config, so the private key path has changed as well. If it isn't updated, the CA node fails to start because it can't find the file.

  1. Set the CA server config file. To mount the CA config file created in the previous step into the container, add one line to the volumes section:
- ./fabric-ca-server-config.yaml:/etc/hyperledger/fabric-ca-server/fabric-ca-server-config.yaml

7. Modify the application code

1. Edit app/helper.js
The global code at the top of helper.js contains the following statement:

for (let key in ORGS) {
    if (key.indexOf('org') === 0) {
        ...
    }
}

The ORGS object holds all organization information read from network-config.json, with the keys "orderer", "org1", and "org2" (before renaming). The loop is meant to operate on every organization other than orderer, but the if statement clearly assumes the names org1 and org2, so it stops working as soon as we rename the organizations.
So the if statement should be changed to

if (key != 'orderer') {...}

2. Update the startup and test scripts
Finally, update the variables related to the organization and channel names in the startup script runApp.sh and the test script testAPIs.sh. Once that's done, run the two scripts to start and test the new network, and you'll see that the organization and channel names are now the custom ones we set!

One-command setup script

I didn't expect that changing two small parameters would take this many tedious steps and touch so many config files, which is frankly a bit absurd. To deal with this, I wrote a script that performs all of the steps above in one go: https://github.com/zhayujie/fabric-tools. Run the following command to set the organization and channel names for the whole project:

./set_config.sh <orgName> <channelName>

What it mainly does is generate the initial artifacts such as certificates automatically, and batch-replace the config files that need to change. For now the script only supports a single machine with a single organization. With minor changes it can be used in multi-machine and multi-organization setups.

Tags: fabric

8 comments

  1. yyy yyy

    请问下:我只是用 generate.sh 重新生成了一下配置文件,然后也改了docker-compose.yml里的keyfile,网络是可以启动,但marbles实例没法再正常运行了(报找不到链码)要怎么解决啊?是还有别的东西要改吗?

    1. zyj zyj

      可以看下启动脚本中链码安装和实例化的命令,是否有涉及到组织或通道名称。

      1. 哦哦,可是我没有改过名称(什么东西都没有动过),就只是重新生成了一下配置文件。

        1. zyj zyj

          需要看下generate.sh脚本的具体内容和报错详情,加我qq吧420536405

  2. 我现在用的是fabric2.1,没有balance-transfer,我想自己建一个这个,但是新版本.yaml很多配置项有添加,真的是束手无策。大神,救救我

    1. zyj zyj

      fabric 1.1版本后我就没有太关注了。2.1版本的fabric-samples里面有fabcar以及一系列其它的例子,可以参考它们的配置文件,开发模式都是类似的。

  3. YUX YUX

    方便加下QQ质询一下那个fabric-tools的东西吗

    1. zyj zyj

      可以,先email我一下吧 yjzha1996@163.com

Leave a Comment