gitee.com/Mydawng/fabric-ca@v2.0.0-alpha.0.20201214145411-9ea68369cb61+incompatible/README.md (about) 1 # Fabric CA Developer's Guide 2 3 This is the Developer's Guide for Fabric CA, which is a Certificate Authority for Hyperledger Fabric. 4 5 See [User's Guide for Fabric CA](https://hyperledger-fabric-ca.readthedocs.io) for information on how to use Fabric CA. 6 7 ## Prerequisites 8 9 * Go 1.13+ installation or later 10 * **GOPATH** environment variable is set correctly 11 * docker version 17.03 or later 12 * docker-compose version 1.11 or later 13 * A Linux Foundation ID (see [create a Linux Foundation ID](https://identity.linuxfoundation.org/)) 14 15 16 ## Contribution guidelines 17 18 You are welcome to contribute to Fabric CA! 19 20 The following are guidelines to follow when contributing: 21 22 1. See the general information about [contributing to fabric](http://hyperledger-fabric.readthedocs.io/en/latest/CONTRIBUTING.html). 23 24 2. To run the unit tests manually: 25 26 ``` 27 # cd $GOPATH/src/github.com/hyperledger/fabric-ca 28 # make unit-tests 29 ``` 30 31 The test coverage for each package must be 75% or greater. If this fails due to insufficient test coverage, then you can run `gencov` to get a coverage report to see what code is not being tested. Once you have added additional test cases, you can run `go test -cover` in the appropriate package to see the current coverage level. 32 33 WARNING: Running the unit-tests may fail due to too many open file descriptors. 34 Depending on where the failure occurs, the error message may not be obvious and may only say something similar to "unable to open database file". 35 Depending on the settings on your host, you may need to increase the maximum number of open file descriptors. 36 For example, the OSX default per-process maximum number of open file descriptors is 256. 37 You may issue the following command to display your current setting: 38 39 ``` 40 # ulimit -n 41 256 42 ``` 43 44 And the following command will increase this setting to 65536: 45 46 ``` 47 # ulimit -n 65536 48 ``` 49 50 Please note that this change is only temporary. To make it permanent, you will need to consult the documentation for your host operating system. 51 52 ## Package overview 53 54 1. **cmd/fabric-ca-server** contains the main for the fabric-ca-server command. 55 2. **cmd/fabric-ca-client** contains the main for the fabric-ca-client command. 56 3. **lib** contains most of the code. 57 a) **server.go** contains the main Server object, which is configured by **serverconfig.go**. 58 b) **client.go** contains the main Client object, which is configured by **clientconfig.go**. 59 4. **util/csp.go** contains the Crypto Service Provider implementation. 60 5. **lib/dbutil** contains database utility functions. 61 6. **lib/ldap** contains LDAP client code. 62 7. **lib/spi** contains Service Provider Interface code for the user registry. 63 8. **lib/tls** contains TLS related code for server and client. 64 9. **util** contains various utility functions. 65 66 ## Additional info 67 68 ### Profiling Fabric CA server 69 70 To enable profiling on the server, set the FABRIC_CA_SERVER_PROFILE_PORT environment variable to a valid, available port number and start the server. The server will start listening for profile requests at the */debug/pprof/* HTTP endpoint and the specified port. Then run `go tool pprof` with server's profiling URL (http://<server host>:<profiling port>/debug/pprof/<profile|heap|block>) as an argument, it will download and examine a live profile. 71 72 You can start the server in the FVT image by running following docker command from the fabric-ca root directory: 73 74 `docker run -p 8888:8888 -p 8054:8054 -v $PWD:/opt/gopath/src/github.com/hyperledger/fabric-ca -e FABRIC_CA_SERVER_PROFILE_PORT=8054 --name loadTest -td hyperledger/fabric-ca-fvt test/fabric-ca-load-tester/launchServer.sh 1` 75 76 Then start the load by running `/test/fabric-ca-load-tester/runLoad.sh -B` 77 78 In other window, you can start profiling by running (assuming load test takes about a minute to complete): 79 80 `curl http://localhost:8054/debug/pprof/profile?seconds=60 > load-cpu.prof` 81 82 then analyze the profile: 83 84 `go tool pprof bin/fabric-ca-server load-cpu.prof` 85 86 OR simply run: 87 88 `go tool pprof -seconds=60 -output=load-cpu.prof http://localhost:8054/debug/pprof/profile` 89 90 You can use commands like *top*, *top -cum*, *list* and *web* to look at the top consumers, list the code to see the hotspots and to view the graph in a browser. You can run `go tool pprof -h` to view all the options supported by the pprof tool 91 92 You can also use [**go-torch**](https://github.com/uber/go-torch) tool to analyze the profile: 93 94 `go-torch bin/fabric-ca-server load-cpu.prof` 95 96 ### Profiling Fabric CA client 97 To enable profiling on the client, set the FABRIC_CA_CLIENT_PROFILE_MODE environment variable to either "heap" or "cpu" to enable heap, cpu profiling respectively. A file containing profiling data is created in the present working directory of the client. Heap profiling data is written to **mem.pprof** and cpu profiling data is written to **cpu.pprof**. You can run `go tool pprof <client executable> <profiling file>` to analyze the profiling data. 98 99 ### Profiling links 100 101 * [Profiling Go Programs](https://blog.golang.org/profiling-go-programs) 102 * [Daily code optimization using benchmarks and profiling in Golang - Gophercon India 2016 talk 103 ](https://medium.com/@hackintoshrao/daily-code-optimization-using-benchmarks-and-profiling-in-golang-gophercon-india-2016-talk-874c8b4dc3c5) 104 * [Golang UK Conference 2016 - Dave Cheney - Seven ways to Profile Go Applications 105 ](https://www.youtube.com/watch?v=2h_NFBFrciI) 106 * [Debugging performance issues in Go* programs 107 ](https://software.intel.com/en-us/blogs/2014/05/10/debugging-performance-issues-in-go-programs) 108 * [Beautifully Simple Benchmarking with Go 109 ](http://www.soroushjp.com/2015/01/27/beautifully-simple-benchmarking-with-go/) 110 * [Profiling memory usage of a Go app](https://vinceyuan.github.io/profiling-memory-usage-of-a-go-app/) 111 * [Profiling and Optimizing Go 112 ](https://www.youtube.com/watch?v=N3PWzBeLX2M&feature=youtu.be) 113 * [Golang UK Conference 2015 - Francesc Campoy - Program Analysis 114 ](https://www.youtube.com/watch?v=oorX84tBMqo&feature=youtu.be) 115 116 ### FVT 117 118 See [FVT tests](scripts/fvt/README.md) for information on functional verification test cases. 119 120 121 ### Updating the cfssl vendored package 122 Following are the steps to update cfssl package using version 1.0.8 of govendor tool. 123 124 * Remove cfssl from vendor folder 125 * cd $GOPATH/src/github.com/hyperledger/fabric-ca/vendor 126 * govendor remove github.com/cloudflare/cfssl/... 127 * rm -rf github.com/cloudflare/cfssl/ 128 129 * Clone cfssl repo 130 * cd $GOPATH/src/github.com/ 131 * mkdir cloudflare 132 * cd cloudflare 133 * git clone https://github.com/cloudflare/cfssl.git 134 135 * Add cfssl from $GOPATH to the vendor folder 136 * cd $GOPATH/src/github.com/hyperledger/fabric-ca/vendor 137 * govendor add github.com/cloudflare/cfssl/^ 138 * You can optionally specify revision or tag to add a particular revision of code to the vendor folder 139 * govendor add github.com/cloudflare/cfssl/^@abc12032 140 141 * Remove sqlx package from cfssl vendor folder. This is because certsql.NewAccessor (called by fabric-ca) requires sqlx.db object to be passed from the same package. If we were to have sqlx package both in fabric-ca and cfssl vendor folder, go compiler will throw an error 142 * rm -rf github.com/cloudflare/cfssl/vendor/github.com/jmoiron/sqlx 143 144 * Remove the packages that are added to the fabric-ca vendor folder that are not needed by fabric-ca 145 146 ## Continuous Integration 147 148 Please have a look at [Continuous Integration Process](docs/source/ca-ci.md) 149 150 151 ## License <a name="license"></a> 152 153 Hyperledger Project source code files are made available under the Apache License, Version 2.0 (Apache-2.0), located in the [LICENSE](LICENSE) file. Hyperledger Project documentation files are made available under the Creative Commons Attribution 4.0 International License (CC-BY-4.0), available at http://creativecommons.org/licenses/by/4.0/.