Skip to content

Commit

Permalink
Add SELinux section to test network docs
Browse files Browse the repository at this point in the history
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 <stas@two-giants.com>
twoGiants authored and denyeart committed Oct 30, 2024
1 parent 73c2273 commit 6c2e87c
Showing 1 changed file with 93 additions and 1 deletion.
94 changes: 93 additions & 1 deletion docs/source/test_network.md
Original file line number Diff line number Diff line change
@@ -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).

0 comments on commit 6c2e87c

Please sign in to comment.