diff --git a/docs/source/test_network.md b/docs/source/test_network.md index 34fc73d78a3..db17f059616 100644 --- a/docs/source/test_network.md +++ b/docs/source/test_network.md @@ -24,7 +24,7 @@ current main branch, it is possible that you will encounter errors. Before you can run the test network, you need to install Fabric Samples in your environment. Follow the instructions on [getting_started](getting_started.html) -to install the required software. +to install the required software. If you are using a Linux distribution with SELinux enabled you need to add a small change to the Docker/Podman compose files described in the [SELinux section](#selinux) below. ## Bring up the test network @@ -579,6 +579,79 @@ To understand more about the BFT ordering service, refer to the following inform - [Adding orderer to an existing network](./create_channel/add_orderer.html) - [Configuring and operating a BFT ordering service](./bft_configuration.html) +## SELinux + +To use the test-network on Linux distributions where SELinux is enabled like Fedora or RHEL you need to modify the Docker/Podman compose files or you will run into permission issues with volumes and access to the Docker socket when building the Chaincode container. + +Resolve the volume permission issues by adding a `:z` to the end of the line in the volume entries shown in: +- `test-network/compose/compose-ca.yaml`, +- `test-network/compose/compose-test-net.yaml`, +- `test-network/compose/docker/docker-compose-test-net.yaml` in case you use Docker +- OR `test-network/compose/podman/podman-compose-test-net.yaml` in case you use Podman. + +```yaml +# test-network/compose/compose-ca.yaml +# ca_org1 container + volumes: + - ../organizations/fabric-ca/org1:/etc/hyperledger/fabric-ca-server:z + +# ca_org2 container + volumes: + - ../organizations/fabric-ca/org2:/etc/hyperledger/fabric-ca-server:z + +# ca_orderer container + volumes: + - ../organizations/fabric-ca/ordererOrg:/etc/hyperledger/fabric-ca-server:z + +# test-network/compose/compose-test-net.yaml +# Orderer container + volumes: + - ../organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp:/var/hyperledger/orderer/msp:z + - ../organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/:/var/hyperledger/orderer/tls:z + +# PeerOrg1 container + volumes: + - ../organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com:/etc/hyperledger/fabric:z + +# PeerOrg2 container + volumes: + - ../organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com:/etc/hyperledger/fabric:z + +# test-network/compose/docker/docker-compose-test-net.yaml +# PeerOrg1 container + volumes: + - ./docker/peercfg:/etc/hyperledger/peercfg:z + +# PeerOrg2 container + volumes: + - ./docker/peercfg:/etc/hyperledger/peercfg:z +``` + +Resolve the issue with forbidden access to the Docker socket by either using Chaincode-as-a-Service or opting out of SELinux enforcement for the peer containers. You can do the latter by adding `:z` to Docker socket volume entries and disabling the security options in `test-network/compose/docker/docker-compose-test-net.yaml`: + +```yaml +# test-network/compose/docker/docker-compose-test-net.yaml +# PeerOrg1 container + volumes: + - ${DOCKER_SOCK}:/host/var/run/docker.sock:z + security_opt: + - label:disable + +# PeerOrg2 container + volumes: + - ${DOCKER_SOCK}:/host/var/run/docker.sock:z + security_opt: + - label:disable +``` + +### BTF ordering service on SELinux + +If you want to start the test-network with the BTF ordering service on a Linux distribution with SELinux enabled you have to perform the changes listed above in the compose files with `*-btf-test-net.yaml` in their names instead of `*-test-net.yaml`: +- `test-network/compose/compose-ca.yaml`, +- `test-network/compose/compose-btf-test-net.yaml`, +- `test-network/compose/docker/docker-compose-btf-test-net.yaml` in case you use Docker +- OR `test-network/compose/podman/podman-compose-btf-test-net.yaml` in case you use Podman. + ## Troubleshooting If you have any problems with the tutorial, review the following: @@ -673,6 +746,25 @@ If you have any problems with the tutorial, review the following: :set ff=unix ``` +- If you are running on a Linux distribution with SELinux enabled like Fedora or RHEL and your test-network peer and orderer containers keep crashing with the following errors: + ```bash + # peer 1 & 2 + ERRO [main] InitCmd -> Fatal error when initializing core config : error when reading core config file: Config File "core" Not Found in "[/etc/hyperledger/peercfg]" + + # orderer + PANI [orderer.common.server] loadLocalMSP -> Failed to get local msp config: could not initialize BCCSP Factories: Failed initializing BCCSP: Could not initialize BCCSP SW [Failed to initialize software key store: open /var/hyperledger/orderer/msp/keystore: permission denied] + ``` + Read the [SELinux section](#selinux) above. + +- If you are running on a Linux distribution with SELinux enabled like Fedora or RHEL and you can not install a chaincode on your test-network with the following error: + ```bash + Error: chaincode install failed with status: 500 - failed to invoke backing implementation of 'InstallChaincode': could not build chaincode: docker build failed: docker image inspection failed: Get "http://unix.sock/images/dev-peer0.org1.example.com-basic_1.0-c6a45e2d5563c883869149c3dbd941c22fbe27daa21f0552834f5a53fbb8058a-fe69b7bdc0bbe5769bbff0572aa6986343c77b61c84077999a9b65f29c5c0025/json": dial unix /host/var/run/docker.sock: connect: permission denied + Chaincode installation on peer0.org1 has failed + Deploying chaincode failed + ``` + + Read the [SELinux section](#selinux) above. + If you continue to see errors, share your logs on one of the Fabric [Discord channels](https://discord.com/invite/hyperledger) or on [StackOverflow](https://stackoverflow.com/questions/tagged/hyperledger-fabric).