Operation Tutorial¶
FISCO BCOS generator contains multiple operations about node generation, expansion, group division, and certificate, which are introduced as below:
Command | Basic function | |
---|---|---|
create_group_genesis | assign folder | generate group Genesis Block in an assigned folder according to group_genesis.ini and the certificates in meta folder |
build_install_package | generate node configuration file folder of node_deployment.ini in assigned folder (node certificate should be placed in meta folder) |
|
generate_all_certificates | generate node certificate and private key according to node_deployment.ini | |
generate_*_certificate | generate chain, agency, node, SDK certificate or private key | |
merge_config | merge p2p parts of the two configuration files | |
deploy_private_key | import private keys in batch to the generated node configuration file folder | |
add_peers | import node connection files in batch to node configuration file folder | |
add_group | import Genesis Blocks in batch to node configuration file folder | |
version | print current version code | |
h/help | help command |
create_group_genesis (-c)¶
Command description | generate group Genesis Block |
Premise of use | user needs to configure group_genesis.ini and node certificates under meta folder |
Parameter setting | assign and generate node configuration file folder for group |
Function | generate a configuration of the new group under the assigned section according to the user of the certificate configured under meta folder |
Adaptable scenario | the existed nodes on consortium chain needs to form new group |
Operation Tutorial
$ cp node0/node.crt ./meta/cert_127.0.0.1_3030n.crt
...
$ vim ./conf/group_genesis.ini
$ ./generator --create_group_genesis ~/mydata
After the program is executed, group.i.genesis
of mgroup.ini will be generated under ~/mydata folder.
The generated group.i.genesis
is the Genesis Block of the new group.
Note
In FISCO BCOS 2.0+, each group has one Genesis Block.
build_install_package (-b)¶
Command description | deploy new node and new group |
Premise of use | user needs to configure node_deployment.ini and assign p2p connection file |
Parameter setting | assign file folder for the location of configuration file folder |
Function | generate node configuration file folder according to Genesis Block, node certificate and node information |
Adaptable scenario | generate node configuration file folder |
Operation Tutorial
$ vim ./conf/node_deployment.ini
$ ./generator --build_install_package ./peers.txt ~/mydata
After the program is executed, a few file folders named node_hostip_port will be generated under ~/mydata folder and pushed to the relative server to activate the node.
generate_chain_certificate¶
Command description | generate root certificate |
Premise of use | no |
Parameter setting | assign file folder for root certificate |
Function | generate root certificate and private key under assigned section |
Adaptable scenario | user needs to generate self-sign root certificate |
$ ./generator --generate_chain_certificate ./dir_chain_ca
Now, user can find root certificate ca.crt
and private key ca.key
under ./dir_chain_ca folder.
generate_agency_certificate¶
Command description | generate agency certificate |
Premise of use | root certificate and private key have been created |
Parameter setting | assign section for agency certificate, chain certificate, and private key and create agency name |
Function | generate agency certificate and private key under assigned section |
Adaptable scenario | user needs to create self-sign agency certificate |
$ ./generator --generate_agency_certificate ./dir_agency_ca ./chain_ca_dir The_Agency_Name
Now, user can locate The_Agency_Name folder containing agency certificate agency.crt
and private key agency.key
through route ./dir_agency_ca.
generate_node_certificate¶
Command description | generate node certificate |
Premise of use | agency certificate and private key have been created |
Parameter setting | assign section for node certificate, agency certificate, and private key and create node name |
Function | generate node certificate and private key under assigned section |
Adaptable scenario | user need to create self-sign node certificate |
$ ./generator --generate_node_certificate node_dir(SET) ./agency_dir node_p2pip_port
Then user can locate node certificate node.crt
and private key node.key
through route node_dir.
generate_sdk_certificate¶
Command description | generate SDK certificate |
Premise of use | agency certificate and private key have been created |
Parameter setting | assign section for node certificate, agency certificate and private key and create node name |
Function | generate SDK certificate and private key under assigned section |
Adaptable scenario | user needs to generate self-sign SDK certificate |
$ ./generator --generate_sdk_certificate ./dir_sdk_ca ./dir_agency_ca
Now user can locate SDK file folder containing SDK certificate sdk.crt
and private key sdk.key
through route ./sdk.
generate_all_certificates¶
Command description | generate certificates and private key according to node_deployment.ini |
Premise of use | no |
Parameter setting | assign section for node certificate |
Function | create private key and node certificate under meta folder, generate node certificate for exchanging and p2p connection file under assigned section according to node_deployment.ini |
Adaptable scenario | user needs to transfer data with other nodes |
$ ./generator --generate_all_certificates ./cert
Note
the above command will create node certificate according to ca.crt, agency.crt and agency.key of meta folder.
absence of any of the above 3 files will fail the creation of node certificate, and the program will throw an exception
Once the execution is done, user can find node certificate and private key under ./cert folder, and node certificate under ./meta folder.
merge_config (-m)¶
--merge_config command can merge p2p sections of 2 config.ini
For instance, the p2p section in config.ini of A is:
[p2p]
listen_ip = 127.0.0.1
listen_port = 30300
node.0 = 127.0.0.1:30300
node.1 = 127.0.0.1:30301
node.2 = 127.0.0.1:30302
node.3 = 127.0.0.1:30303
The p2p section in config.ini of B is:
[p2p]
listen_ip = 127.0.0.1
listen_port = 30303
node.0 = 127.0.0.1:30300
node.1 = 127.0.0.1:30303
node.2 = 127.0.0.1:30300
node.3 = 127.0.0.1:30301
The command will result in:
[p2p]
listen_ip = 127.0.0.1
listen_port = 30304
node.0 = 127.0.0.1:30300
node.1 = 127.0.0.1:30301
node.2 = 127.0.0.1:30302
node.3 = 127.0.0.1:30303
node.4 = 127.0.0.1:30300
node.5 = 127.0.0.1:30301
For example:
$ ./generator --merge_config ~/mydata/node_A/config.ini ~/mydata/node_B/config.ini
When it works, the p2p sections in config.ini of node_A and node_B will be merged to ~/mydata/node_B/config.ini
deploy_private_key (-d)¶
--deploy_private_key command will import the private key of nodes with same name to the generated configuration file folder
For example:
$./generator --deploy_private_key ./cert ./data
If ./cert contains file folders named node_127.0.0.1_30300 and node_127.0.0.1_30301, which are placed with node private key node.key,
./data contains file folders named node_127.0.0.1_30300 and node_127.0.0.1_30301,
then this command would import private key under./cert to ./data folder
add_peers (-p)¶
--add_peers command can import the files of assigned peers to the generated node configuration file folder.
For example:
$./generator --add_peers ./meta/peers.txt ./data
If ./data contains configuration file folder named node_127.0.0.1_30300 and node_127.0.0.1_30301, then this command will import peers file with connection information to the node configuration files config.ini
under ./data.
add_group (-a)¶
--add_group command will import assigned peers file to the generated node configuration file folder.
For example:
$./generator --add_group ./meta/group.2.genesis ./data
If ./data contains configuration file folder named node_127.0.0.1_30300 and node_127.0.0.1_30301, then this command will import connection information of Group 2 to conf
folder of all nodes under ./data.
download_fisco¶
--download_fisco can download fisco-bcos
binary file under assigned section.
For example:
$./generator --download_fisco ./meta
This command will download fisco-bcos
executable binary file under ./meta folder.
download_console¶
--download_consolecan download and control console under assigned section.
For example:
$./generator --download_console ./meta
This command will configure the console under ./meta folder according to node_deployment.ini
.
get_sdk_file¶
--get_sdk_file command can acquire sdk.crt
, sdk.key
, ca.crt
that are needed in configuration of console and sdk under assigned section.
For example:
$./generator --get_sdk_file ./sdk
This command will generate the above configuration file according to node_deployment.ini
under ./sdk
version (-v)¶
--version command can help view the version code of current deployment tool.
$ ./generator --version
help (-h)¶
User can use -h or –help command to check help list
For example:
$ ./generator -h
usage: generator [-h] [-v] [-b peer_path data_dir] [-c data_dir]
[--generate_chain_certificate chain_dir]
[--generate_agency_certificate agency_dir chain_dir agency_name]
[--generate_node_certificate node_dir agency_dir node_name]
[--generate_sdk_certificate sdk_dir agency_dir] [-g]
[--generate_all_certificates cert_dir] [-d cert_dir pkg_dir]
[-m config.ini config.ini] [-p peers config.ini]
[-a group genesis config.ini]
Operation in OSCCA standard (China)¶
All the commands in FISCO BCOS generator are adaptable for OSCCA version of fisco-bcos
(oscca-approved encryption). When using this version, every certificate and private key should be prefixed with gm
. The description reads below:
On-off switch (-g command)¶
Once -g command is executed, all the operations concerning certificates, nodes, and group Genesis Block will generate the above files of OSCCA standard.
generate certificate¶
When executing generate_*_certificate together with -g command, the generated certificate will be in OSCCA standard.
For example:
./generator --generate_all_certificates ./cert -g
Note
The above command will generate node certificate according to gmca.crt, agency certificate gmagency.crt, and agency private key gmagency.key placed under meta folder.
Absence of any one of the three files will fail the generation of node certificate, and the program will throw an exception.
generate group Genesis Block in OSCCA standard¶
For example:
$ cp node0/gmnode.crt ./meta/gmcert_127.0.0.1_3030n.crt
...
$ vim ./conf/group_genesis.ini
$ ./generator --create_group_genesis ~/mydata -g
After executing this program, the user can locate group.i.genesis
in mgroup.ini under ~/mydata folder.
group.i.genesis
is the Genesis Block of the new group.
generate node configuration file folder in OSCCA standard¶
For example:
$ vim ./conf/node_deployment.ini
$ ./generator --build_install_package ./peers.txt ~/mydata -g
After executing the program, multiple folders named node_hostip_port will be generated under ~/mydata folder and pushed to the relative server to activate the node.
Monitoring design¶
FISCO BCOS generator has a preset monitoring script in all generated node configuration folders. Warning information of node will be sent to the IP address assigned by the user after configuration. FISCO BCOS generator places the monitoring script under the assigned section for node configuration files. If the user assigns the folder named “data”, then the user can locate it under the monitor folder of the data section.
For example:
$ cd ./data/monitor
Purpose of use:
to monitor the status of nodes, to reactive node
to acquire block number of node and view information, to ensure the consensus of nodes
to analyze printing of node logs in last 1 minutes, to collect critical errors information of printed logs, to monitor the status of nodes in real-time
to assign log file or period, to analyze data of consensus message management, block generation, and transaction volume and node’s health.
Warning service configuration¶
Before using this service, the user needs to configure the warning service. Here we take the WeChat notification of server酱 as an example. You can read the configuration as reference: server酱
The user associates it with personal GitHub account and WeChat account, then uses -s command of this script to send a warning message to the associated WeChat.
If the user wants to try different services, the user can personalize the service by modifying alarm() {
# change HTTP server
} function of monitor.sh
Help command¶
The way to check the usage of the script by the help command
$ ./monitor.sh -h
Usage : bash monitor.sh
-s : send alert to your address
-m : monitor, statistics. default : monitor .
-f : log file to be analyzed.
-o : dirpath
-p : name of the monitored program , default is fisco-bcos
-g : specified the group list to be analyzed
-d : log analyze time range. default : 10(min), it should not bigger than max value : 60(min).
-r : setting alert receiver
-h : help.
example :
bash monitor.sh -s YourHttpAddr -o nodes -r your_name
bash monitor.sh -s YourHttpAddr -m statistics -o nodes -r your_name
bash monitor.sh -s YourHttpAddr -m statistics -f node0/log/log_2019021314.log -g 1 2 -r your_name
Command description:
-s assign the configuration address of warning service. It can be the ip of warning notification.
-m set monitor mode to statistics or monitor. Monitor is the default mode.
-f analyze node log
-o assign location of node
-p set notification name. “fisco-bcos” is the default one.
-g assign group to be monitored. All group is defaulted to be monitored.
-d time scope of log analysis. Default to be within 10 minutes and 60 minutes as the maximum
-r assign the receiver of warning notification
-h help command
For example¶
use script to monitor status of assigned nodes, send message to receiver Alice:
$ bash monitor.sh -s https://sc.ftqq.com/[SCKEY(登入后可见)].send -o alice/nodes -r Alice
use script to collect node information and send message to Alice:
$ bash monitor.sh -s https://sc.ftqq.com/[SCKEY(登入后可见)].send -m statistics -o alice/nodes -r Alice
use script to collect information of group 1 and group 2 of specific node log, send message to Alice:
$ bash monitor.sh -s https://sc.ftqq.com/[SCKEY(replace by your code)].send -m statistics -f node0/log/log_2019021314.log -g 1 2 -o alice/nodes -r Alice
handshake failed checked¶
The check_certificates.sh
script in the scripts folder of FISCO BCOS generator contains anomaly detection with error message handshake failed
in node log.
Acquire test script¶
If the user needs to test node generated by build_chain.sh
, the following command can help acquire test script:
curl -#LO https://raw.githubusercontent.com/FISCO-BCOS/generator/master/scripts/check_certificates.sh && chmod u+x check_certificates.sh
Note
If the script cannot be downloaded for a long time due to network problems, try curl -#LO https://gitee.com/FISCO-BCOS/generator/raw/master/scripts/check_certificates.sh && chmod u+x check_certificates.sh
The user that deployed node with a generator can acquire script from scripts/check_certificates.sh under the root directory of the generator.
Test valid date of certificate¶
-t command of check_certificates.sh
can test certificate by comparing the valid date with the current system time.
Example:
$ ./check_certificates.sh -t ~/certificates.crt
The second parameter can be any x509 certificate that prompt check certificates time successfully
after passing verification or exception if it is failing.
Certificate verification¶
-v command of check_certificates.sh
will verify node certificate according to the root certificate set by user.
$ ./check_certificates.sh -v ~/ca.crt ~/node.crt
After successful verification, it will prompt use ~/ca.crt verify ~/node.crt successful
, or prompt exception if it is failing.
Node configuration error checking¶
Acquire script¶
curl -#LO https://raw.githubusercontent.com/FISCO-BCOS/FISCO-BCOS/master-2.0/tools/check_node_config.sh && chmod u+x check_node_config.sh
Note
If the script cannot be downloaded for a long time due to network problems, try curl -#LO https://gitee.com/FISCO-BCOS/FISCO-BCOS/raw/master-2.0/tools/check_node_config.sh
使用¶
Using the following command, the script -p
option specifies the node path, and the script will analyze the configuration errors based on config. ini under the path.
bash check_node_config.sh -p node_127.0.0.1_30300