From 81c2da26a9e094e9300bebd2b0d5349bc46102cc Mon Sep 17 00:00:00 2001 From: Stanislav Jakuschevskij Date: Thu, 24 Oct 2024 15:17:55 +0200 Subject: [PATCH] Add SELinux section to prerequisites docs The documentation update adds a description on how to resolve two issues when running the test-network on a host with SELinux enabled: 1. Peer and orderer crashing after start using Docker or Podman. 2. Chaincode container can not be build when using Docker. The reason for the first issue are permission errors. This can be seen in the container logs. To resolve the errors the volume sections of the compose files needs to be modified. The reason for the second issue is that the peer container can not access the Docker socket. To resolve it only the Docker compose file needs to be modified. The errors in the container logs and during chaincode deployment were added to the test_network.md 'Troubleshooting' section as an aid if someone searches the documentation for those errors. The necessary changes are documented in a new section called 'Distros with SELinux enabled' under the 'Linux' prerequisites. Signed-off-by: Stanislav Jakuschevskij --- docs/source/prereqs.md | 53 ++++++++++++++++++++++++++++++++++++- docs/source/test_network.md | 19 +++++++++++++ 2 files changed, 71 insertions(+), 1 deletion(-) diff --git a/docs/source/prereqs.md b/docs/source/prereqs.md index bf0402f256a..84148bb3aa0 100644 --- a/docs/source/prereqs.md +++ b/docs/source/prereqs.md @@ -86,7 +86,7 @@ brew install jq jq --version # => jq-1.6 ``` -## **Linux (Ubuntu/Debian based distro)** +## **Linux (Ubuntu/Debian based distro, Distros with SELinux enabled)** Prerequisites: [git](https://git-scm.com/downloads), [cURL](https://curl.haxx.se/download.html), [Docker](https://docs.docker.com/get-docker/) @@ -115,6 +115,57 @@ Optional: Install the latest version of [Go](https://golang.org/doc/install) (on Optional: Install the latest version of [jq](https://stedolan.github.io/jq/download/) (only required for the tutorials related to channel configuration transactions). +### Distros with SELinux enabled + +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-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-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 +``` + ## **Windows** ### Docker diff --git a/docs/source/test_network.md b/docs/source/test_network.md index 34fc73d78a3..da896d2bb5a 100644 --- a/docs/source/test_network.md +++ b/docs/source/test_network.md @@ -673,6 +673,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 *"Distros with SELinux enabled"* section in the [Prerequisites](prereqs.html). + +- 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 *"Distros with SELinux enabled"* section in the [Prerequisites](prereqs.html). + 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).