Add SELinux section to test network 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
'SELinux' under the 'Tutorials/Using the Fabric test network' docs.

Signed-off-by: Stanislav Jakuschevskij <[email protected]>

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