Skip to content

Commit

Permalink
[FAB-4462] Scripts to dynamically generate readme
Browse files Browse the repository at this point in the history 
Added script that will pull in CLI flags from client
and server and create a RST file, the same will also be done
for the configuration file templates. The main fabric-ca
readme will then point to these files as appropriate.

This will remove the need to manually update the doc
everytime a new configuration options is added to
fabric-ca.

Change-Id: I06f5d78e59305b9f0e3272068c5fbf93bac53483
Signed-off-by: Saad Karim <[email protected]>
  • Loading branch information
Saad Karim committed Aug 28, 2017
1 parent 446f9cf commit d332960
Show file tree
Hide file tree
Showing 8 changed files with 722 additions and 452 deletions.
6 changes: 5 additions & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ PKGNAME = github.com/hyperledger/$(PROJECT_NAME)

METADATA_VAR = Version=$(PROJECT_VERSION)

GO_SOURCE := $(shell find . -name '*.go')
GO_LDFLAGS = $(patsubst %,-X $(PKGNAME)/cmd.%,$(METADATA_VAR))
export GO_LDFLAGS

Expand Down Expand Up @@ -94,10 +95,13 @@ lint: .FORCE
vet: .FORCE
@scripts/check_vet

docs: fabric-ca-client fabric-ca-server
@scripts/regenDocs

fabric-ca-client: bin/fabric-ca-client
fabric-ca-server: bin/fabric-ca-server

bin/%:
bin/%: $(GO_SOURCE)
@echo "Building ${@F} in bin directory ..."
@mkdir -p bin && go build -o bin/${@F} -ldflags "$(GO_LDFLAGS)" $(path-map.${@F})
@echo "Built bin/${@F}"
Expand Down
47 changes: 47 additions & 0 deletions docs/source/clientcli.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
Fabric-CA Client's CLI
======================

::

Hyperledger Fabric Certificate Authority Client
Usage:
fabric-ca-client [command]
Available Commands:
enroll Enroll an identity
gencsr Generate a CSR
getcacert Get CA certificate chain
reenroll Reenroll an identity
register Register an identity
revoke Revoke an identity
version Prints Fabric CA Client version
Flags:
--caname string Name of CA
-c, --config string Configuration file (default "<CLIENT_HOME>/fabric-ca-client-config.yaml")
--csr.cn string The common name field of the certificate signing request
--csr.hosts stringSlice A list of space-separated host names in a certificate signing request
--csr.names stringSlice A list of comma-separated CSR names of the form <name>=<value> (e.g. C=CA,O=Org1)
--csr.serialnumber string The serial number in a certificate signing request
-d, --debug Enable debug level logging
--enrollment.label string Label to use in HSM operations
--enrollment.profile string Name of the signing profile to use in issuing the certificate
--id.affiliation string The identity's affiliation
--id.attrs stringSlice A list of comma-separated attributes of the form <name>=<value> (e.g. foo=foo1,bar=bar1)
--id.maxenrollments int The maximum number of times the secret can be reused to enroll. (default -1)
--id.name string Unique name of the identity
--id.secret string The enrollment secret for the identity being registered
--id.type string Type of identity being registered (e.g. 'peer, app, user')
-M, --mspdir string Membership Service Provider directory (default "msp")
-m, --myhost string Hostname to include in the certificate signing request during enrollment (default "<HOSTNAME>")
-a, --revoke.aki string AKI (Authority Key Identifier) of the certificate to be revoked
-e, --revoke.name string Identity whose certificates should be revoked
-r, --revoke.reason string Reason for revocation
-s, --revoke.serial string Serial number of the certificate to be revoked
--tls.certfiles stringSlice A list of comma-separated PEM-encoded trusted certificate files (e.g. root1.pem,root2.pem)
--tls.client.certfile string PEM-encoded certificate file when mutual authenticate is enabled
--tls.client.keyfile string PEM-encoded key file when mutual authentication is enabled
-u, --url string URL of fabric-ca-server (default "http://localhost:7054")
Use "fabric-ca-client [command] --help" for more information about a command.
158 changes: 158 additions & 0 deletions docs/source/clientconfig.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
Fabric-CA Client's Configuration File
======================================

::

#############################################################################
# This is a configuration file for the fabric-ca-client command.
#
# COMMAND LINE ARGUMENTS AND ENVIRONMENT VARIABLES
# ------------------------------------------------
# Each configuration element can be overridden via command line
# arguments or environment variables. The precedence for determining
# the value of each element is as follows:
# 1) command line argument
# Examples:
# a) --url https://localhost:7054
# To set the fabric-ca server url
# b) --tls.client.certfile certfile.pem
# To set the client certificate for TLS
# 2) environment variable
# Examples:
# a) FABRIC_CA_CLIENT_URL=https://localhost:7054
# To set the fabric-ca server url
# b) FABRIC_CA_CLIENT_TLS_CLIENT_CERTFILE=certfile.pem
# To set the client certificate for TLS
# 3) configuration file
# 4) default value (if there is one)
# All default values are shown beside each element below.
#
# FILE NAME ELEMENTS
# ------------------
# The value of all fields whose name ends with "file" or "files" are
# name or names of other files.
# For example, see "tls.certfiles" and "tls.client.certfile".
# The value of each of these fields can be a simple filename, a
# relative path, or an absolute path. If the value is not an
# absolute path, it is interpretted as being relative to the location
# of this configuration file.
#
#############################################################################
#############################################################################
# Client Configuration
#############################################################################
# URL of the Fabric-ca-server (default: http://localhost:7054)
url: <<<URL>>>
# Membership Service Provider (MSP) directory
# This is useful when the client is used to enroll a peer or orderer, so
# that the enrollment artifacts are stored in the format expected by MSP.
mspdir:
#############################################################################
# TLS section for secure socket connection
#
# certfiles - PEM-encoded list of trusted root certificate files
# client:
# certfile - PEM-encoded certificate file for when client authentication
# is enabled on server
# keyfile - PEM-encoded key file for when client authentication
# is enabled on server
#############################################################################
tls:
# TLS section for secure socket connection
certfiles:
client:
certfile:
keyfile:
#############################################################################
# Certificate Signing Request section for generating the CSR for
# an enrollment certificate (ECert)
#
# cn - Used by CAs to determine which domain the certificate is to be generated for
# names - A list of name objects. Each name object should contain at least one
# "C", "L", "O", "OU", or "ST" value (or any combination of these). These values are:
# "C": country
# "L": locality or municipality (such as city or town name)
# "O": organisation
# "OU": organisational unit, such as the department responsible for owning the key;
# it can also be used for a "Doing Business As" (DBS) name
# "ST": the state or province
# hosts - A list of space-separated host names which the certificate should be valid for
#
# NOTE: The serialnumber field below, if specified, becomes part of the issued
# certificate's DN (Distinguished Name). For example, one use case for this is
# a company with its own CA (Certificate Authority) which issues certificates
# to its employees and wants to include the employee's serial number in the DN
# of its issued certificates.
#
# WARNING: This serialnumber field should not be confused with the certificate's
# serial number which is set by the CA but is not a component of the
# certificate's DN.
#############################################################################
csr:
cn: <<<ENROLLMENT_ID>>>
serialnumber:
names:
- C: US
ST: North Carolina
L:
O: Hyperledger
OU: Fabric
hosts:
- <<<MYHOST>>>
ca:
pathlen:
pathlenzero:
expiry:
#############################################################################
# Registration section used to register a new identity with fabric-ca server
#
# name - Unique name of the identity
# type - Type of identity being registered (e.g. 'peer, app, user')
# affiliation - The identity's affiliation
# maxenrollments - The maximum number of times the secret can be reused to enroll.
# Specially, -1 means unlimited; 0 means disabled
# attributes - List of name/value pairs of attribute for identity
#############################################################################
id:
name:
type:
affiliation:
maxenrollments: -1
attributes:
- name:
value:
#############################################################################
# Enrollment section used to enroll an identity with fabric-ca server
#
# profile - Name of the signing profile to use in issuing the certificate
# label - Label to use in HSM operations
#############################################################################
enrollment:
profile:
label:
#############################################################################
# Name of the CA to connect to within the fabric-ca server
#############################################################################
caname:
#############################################################################
# BCCSP (BlockChain Crypto Service Provider) section allows to select which
# crypto implementation library to use
#############################################################################
bccsp:
default: SW
sw:
hash: SHA2
security: 256
filekeystore:
# The directory used for the software file-based keystore
keystore: msp/keystore
58 changes: 58 additions & 0 deletions docs/source/servercli.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
Fabric-CA Server's CLI
=======================

::

Hyperledger Fabric Certificate Authority Server
Usage:
fabric-ca-server [command]
Available Commands:
init Initialize the fabric-ca server
start Start the fabric-ca server
version Prints Fabric CA Server version
Flags:
--address string Listening address of fabric-ca-server (default "0.0.0.0")
-b, --boot string The user:pass for bootstrap admin which is required to build default config file
--ca.certfile string PEM-encoded CA certificate file (default "ca-cert.pem")
--ca.chainfile string PEM-encoded CA chain file (default "ca-chain.pem")
--ca.keyfile string PEM-encoded CA key file (default "ca-key.pem")
-n, --ca.name string Certificate Authority name
--cacount int Number of non-default CA instances
--cafiles stringSlice A list of comma-separated CA configuration files
-c, --config string Configuration file (default "fabric-ca-server-config.yaml")
--crlsizelimit int Size limit of an acceptable CRL in bytes (default 512000)
--csr.cn string The common name field of the certificate signing request to a parent fabric-ca-server
--csr.hosts stringSlice A list of space-separated host names in a certificate signing request to a parent fabric-ca-server
--csr.serialnumber string The serial number in a certificate signing request to a parent fabric-ca-server
--db.datasource string Data source which is database specific (default "fabric-ca-server.db")
--db.tls.certfiles stringSlice A list of comma-separated PEM-encoded trusted certificate files (e.g. root1.pem,root2.pem)
--db.tls.client.certfile string PEM-encoded certificate file when mutual authenticate is enabled
--db.tls.client.keyfile string PEM-encoded key file when mutual authentication is enabled
--db.type string Type of database; one of: sqlite3, postgres, mysql (default "sqlite3")
-d, --debug Enable debug level logging
--intermediate.enrollment.label string Label to use in HSM operations
--intermediate.enrollment.profile string Name of the signing profile to use in issuing the certificate
--intermediate.parentserver.caname string Name of the CA to connect to on fabric-ca-server
-u, --intermediate.parentserver.url string URL of the parent fabric-ca-server (e.g. http://<username>:<password>@<address>:<port)
--intermediate.tls.certfiles stringSlice A list of comma-separated PEM-encoded trusted certificate files (e.g. root1.pem,root2.pem)
--intermediate.tls.client.certfile string PEM-encoded certificate file when mutual authenticate is enabled
--intermediate.tls.client.keyfile string PEM-encoded key file when mutual authentication is enabled
--ldap.enabled Enable the LDAP client for authentication and attributes
--ldap.groupfilter string The LDAP group filter for a single affiliation group (default "(memberUid=%s)")
--ldap.tls.certfiles stringSlice A list of comma-separated PEM-encoded trusted certificate files (e.g. root1.pem,root2.pem)
--ldap.tls.client.certfile string PEM-encoded certificate file when mutual authenticate is enabled
--ldap.tls.client.keyfile string PEM-encoded key file when mutual authentication is enabled
--ldap.url string LDAP client URL of form ldap://adminDN:adminPassword@host[:port]/base
--ldap.userfilter string The LDAP user filter to use when searching for users (default "(uid=%s)")
-p, --port int Listening port of fabric-ca-server (default 7054)
--registry.maxenrollments int Maximum number of enrollments; valid if LDAP not enabled (default -1)
--tls.certfile string PEM-encoded TLS certificate file for server's listening port (default "tls-cert.pem")
--tls.clientauth.certfiles stringSlice A list of comma-separated PEM-encoded trusted certificate files (e.g. root1.pem,root2.pem)
--tls.clientauth.type string Policy the server will follow for TLS Client Authentication. (default "noclientcert")
--tls.enabled Enable TLS on the listening port
--tls.keyfile string PEM-encoded TLS key for server's listening port
Use "fabric-ca-server [command] --help" for more information about a command.
Loading

0 comments on commit d332960

Please sign in to comment.