Management Tools
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.
Flag | Default | Required | Description | Notes |
---|---|---|---|---|
-h, --help | Show this help message and exits. | |||
Management arguments | ||||
--s3-access-key | S3 access key | Do not modify from the default provided in the service file.
| ||
--s3-secret | S3 access key secret | Do not modify from the default provided in the service file.
| ||
--s3-management-bucket | elixxir-management-mainnet | S3 management bucket name | ||
--s3-bin-bucket | elixxir-bins | S3 binary bucket name | ||
--s3-region | us-west-1 | S3 region | ||
Wrapper arguments | ||||
--verbose | Print debug information | |||
--gateway | Enable gateway mode | |||
--disable-cloudwatch | False | Disable uploading log events to CloudWatch | ||
--management-cert | /opt/xxnetwork/cred/network-management.crt | Path of the management certificate file | ||
--tmp-dir | /tmp | Directory for placing temporary files | ||
--cmd-dir | /opt/xxnetwork/log/cmd | Directory used for saving command file history | ||
--wrapper-log | /opt/xxnetwork/log/wrapper.log | Path of the wrapper script log file | ||
cMix/Gateway arguments | ||||
--binary-path | Path of the cMix/Gateway binary | |||
--config-path | Path of the cMix/Gateway config file | |||
--log-path | /opt/xxnetwork/log/xx.log | Path of the cMix/Gateway log file | ||
--gpu-lib | /opt/xxnetwork/lib/libpowmosm75.so | Path of the GPU exponentiation library | ||
--gpu-bin | /opt/xxnetwork/lib/libpow.fatbin | Path of the GPU binary file | ||
--id-path | /opt/xxnetwork/cred/IDF.json | 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 | Path of the cMix error recovery file | ||
--cloudwatch-log-group | xxnetwork-logs-mainnet | Log group for CloudWatch logging | ||
Consensus arguments | ||||
--disable-consensus | False | Disable Consensus integration (for test environments only) | ||
--consensus-log | /opt/xxnetwork/log/consensus.log | Path of the Consensus log file | ||
--consensus-cw-group | xxnetwork-consensus-mainnet | Log group for Consensus CloudWatch logging | ||
--consensus-url | ws://localhost:63007 | Listening address for blockchain-provided binary updates |