Management Tools

From xx network wiki
Jump to navigation Jump to search
This is a team contributed page

Wrapper Scripts Features

The management scripts are designed to make administration of the xx network software easier and less time consuming, as well as provide data back to the xx network about the functionality of each server. However, many features that it provides require trusting the xx network. Therefore, the usage of the management scripts is not required and can be disabled. The following are the primary features of these scripts.

  • Binary restart:The Wrapper Script will restart if the binary process stops due to a handled error. The process can crash because, in the current implementation, some errors are not entirely handled when caused by cMix failures on the network. It is highly recommended that this feature be utilized.
  • Binary update: The Wrapper Script can accept automatic binary and Wrapper Script updates provided by the xx network. In theory, the xx network can push any code it wants if this feature is activated, but it greatly simplifies running the cMix and Gateway software. This feature includes the ability to send stop and start commands to the cMix and Gateway software. All commands are signed and can be proved to have come from the xx network. This feature is always enabled when using the Wrapper Script.
  • Log upload: This feature uploads logs to xx network for debugging. It can be disabled and is not mandatory but is useful to the xx network for development purposes.

The Management Script is two scripts combined, the service file and the actual Wrapper Script. The service file is a systemd script that starts the Wrapper Script and ensures it stays running. The wrapper script is written in Python and does most of the heavy lifting. Both can be found in the Elixxir wrapper repository.

The service file for xx chain does not have any additional scripts. Instead, the service file runs the binary directly.

Service File Arguments

The service files maintain the cMix, Gateway, and xx chain processes running in the background. There is a different service for each. By default, these files (xxnetwork-cmix.service for Node, xxnetwork-gateway.service for Gateway, and xxnetwork-chain.service for xx chain) are located in /opt/xxnetwork/ and are soft linked to /etc/systemd/system/. They are the same script, just configured differently for cMix and Gateway. These scripts call the Wrapper Script with different options. To see the full details of the options, refer to the Wrapper Script Arguments section below.

cMix Service File Arguments

The following are the available options in the service file configured for cMix. The sections in red should never be modified and should maintain the original values as provided. The items in blue can be modified. By default, this file is located at /opt/xxnetwork/xxnetwork-cmix.service on the Node machine.

ExecStart=/opt/xxnetwork/cmix-wrapper.py \
 --err-path /opt/xxnetwork/log/cmix-err.log \
 --cmd-dir /opt/xxnetwork/log/cmix-cmd \
 --wrapper-log /opt/xxnetwork/log/cmix-wrapper.log \
 --binary-path /opt/xxnetwork/bin/xxnetwork-cmix \
 --gpu-lib /opt/xxnetwork/lib/libpowmosm75.so \
 --gpu-bin /opt/xxnetwork/lib/libpow.fatbin \
 --config-path /opt/xxnetwork/config/cmix.yaml \
 --id-path /opt/xxnetwork/cred/cmix-IDF.json \
 --log-path /opt/xxnetwork/log/cmix.log \
 --management-cert /opt/xxnetwork/cred/network-management.crt \
 --s3-access-key AKIAT3MRRAOJFIIU2ZPE \
 --s3-secret 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 \
 --s3-management-bucket alphanet-management-default \
 --s3-bin-bucket elixxir-bins \
 --cloudwatch-log-group xxnetwork-logs-default \
 --tmp-dir /tmp/xxnetwork/cmix/

Gateway Service File Arguments

The following are the available options in the service file configured for Gateway. The sections in red should never be modified and should maintain the original values as provided. The items in blue can be modified. By default, this file is located at /opt/xxnetwork/xxnetwork-gateway.service on the Gateway machine.

ExecStart=/opt/xxnetwork/gateway-wrapper.py \
 --wrapper-log /opt/xxnetwork/log/gateway-wrapper.log \
 --cmd-dir /opt/xxnetwork/log/gateway-cmd \
 --gateway \
 --binary-path /opt/xxnetwork/bin/xxnetwork-gateway \
 --config-path /opt/xxnetwork/config/gateway.yaml \
 --id-path /opt/xxnetwork/cred/gateway-IDF.json \
 --log-path /opt/xxnetwork/log/gateway.log \
 --management-cert /opt/xxnetwork/cred/network-management.crt \
 --s3-access-key AKIAT3MRRAOJFIIU2ZPE \
 --s3-secret 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 \
 --s3-management-bucket alphanet-management-default \
 --s3-bin-bucket elixxir-bins \
 --cloudwatch-log-group xxnetwork-logs-default \
 --tmp-dir /tmp/xxnetwork/cmix/

xx chain Service File Arguments (On Node Machine)

The following are the available options in the service file configured for xx chain on the Node machine. The sections in red should never be modified and should maintain the original values as provided. The items in blue can be modified. By default, this file is located at /opt/xxnetwork/xxnetwork-chain.service on both the Node and Gateway machines.

ExecStart=/bin/bash -c '/opt/xxnetwork/bin/xxnetwork-chain
  --validator
  --base-path /opt/xxnetwork/db
  --port 15974
  --ws-port 63007 >> /opt/xxnetwork/logs/chain.log 2>&1'

xx chain Service File Arguments (On Gateway Machine)

The following are the available options in the service file configured for xx chain on the Gateway machine. The sections in red should never be modified and should maintain the original values as provided. The items in blue can be modified. By default, this file is located at /opt/xxnetwork/xxnetwork-chain.service on both the Node and Gateway machines.

ExecStart=/bin/bash -c '/opt/xxnetwork/bin/xxnetwork-chain
  --base-path /opt/xxnetwork/db
  --port 15974
  --ws-port 63007 >> /opt/xxnetwork/logs/chain.log 2>&1'

Wrapper Script Arguments

The following arguments should be modified inside the service file described above.

The s3* options are set per the deployment package sent to you and should not be changed. The other options can be changed per your installation, but it is highly recommended that you go with the defaults sent with the install package.
usage: wrapper.py [-h] --s3-access-key S3_ACCESS_KEY --s3-secret S3_SECRET [--s3-management-bucket S3_MANAGEMENT_BUCKET] [--s3-bin-bucket S3_BIN_BUCKET] [--s3-region S3_REGION] [--verbose] [--gateway] [--disable-cloudwatch] [--management-cert MANAGEMENT_CERT] [--tmp-dir TMP_DIR] [--cmd-dir CMD_DIR] [--wrapper-log WRAPPER_LOG] --binary-path BINARY_PATH --config-path CONFIG_PATH [--log-path LOG_PATH] [--gpu-lib GPU_LIB] [--gpu-bin GPU_BIN] [--id-path ID_PATH] [--err-path ERR_PATH] [--cloudwatch-log-group CLOUDWATCH_LOG_GROUP] [--disable-consensus] [--consensus-log CONSENSUS_LOG] [--consensus-cw-group CONSENSUS_CW_GROUP] [--consensus-url CONSENSUS_URL]
Flag Default Required Description Notes
-h, --help NoN Show this help message and exits.
Management arguments
--s3-access-key Checked S3 access key
Do not modify from the default provided in the service file.
--s3-secret Checked S3 access key secret
Do not modify from the default provided in the service file.
--s3-management-bucket elixxir-management-mainnet NoN S3 management bucket name
--s3-bin-bucket elixxir-bins NoN S3 binary bucket name
--s3-region us-west-1 NoN S3 region
Wrapper arguments
--verbose NoN Print debug information
--gateway NoN Enable gateway mode
--disable-cloudwatch False NoN Disable uploading log events to CloudWatch
--management-cert /opt/xxnetwork/cred/network-management.crt NoN Path of the management certificate file
--tmp-dir /tmp NoN Directory for placing temporary files
--cmd-dir /opt/xxnetwork/log/cmd NoN Directory used for saving command file history
--wrapper-log /opt/xxnetwork/log/wrapper.log NoN Path of the wrapper script log file
cMix/Gateway arguments
--binary-path Checked Path of the cMix/Gateway binary
--config-path Checked Path of the cMix/Gateway config file
--log-path /opt/xxnetwork/log/xx.log NoN Path of the cMix/Gateway log file
--gpu-lib /opt/xxnetwork/lib/libpowmosm75.so NoN Path of the GPU exponentiation library
--gpu-bin /opt/xxnetwork/lib/libpow.fatbin NoN Path of the GPU binary file
--id-path /opt/xxnetwork/cred/IDF.json NoN Path of the cMix/Gateway ID file
Make sure to set to the correct ID file for your binary.
--err-path /opt/xxnetwork/log/cmix-err.log NoN Path of the cMix error recovery file
--cloudwatch-log-group xxnetwork-logs-mainnet NoN Log group for CloudWatch logging
Consensus arguments
--disable-consensus False NoN Disable Consensus integration (for test environments only)
--consensus-log /opt/xxnetwork/log/consensus.log NoN Path of the Consensus log file
--consensus-cw-group xxnetwork-consensus-mainnet NoN Log group for Consensus CloudWatch logging
--consensus-url ws://localhost:63007 NoN Listening address for blockchain-provided binary updates