Ansible role that will install (& uninstall), configure and runs Besu: an enterprise Java Ethereum Client

13 KiB

Raw Blame History

Ansible Role: Besu

Description

Ansible role that will install, configure and runs Besu: an enterprise Java Ethereum Client

Supported Platforms
Dependencies
Role Variables
Example Playbook
License
Author Information

Supported Platforms

* MacOS
* Debian
* Ubuntu
* Redhat(CentOS/Fedora)
* Amazon

Dependencies

JDK 11 or greater

Role Variables:

All variables which can be overridden are stored in defaults/main.yml file. By and large these variables are configuration options. Please refer to the Besu docs for more information

Name	Default Value	Description
`besu_build_from_source`	unset	When set to `true`, Besu is build from git sources. See also `besu_git_repo` and `besu_git_commit`
`besu_version`	unset	REQUIRED if `besu_build_from_source` is false. Version of Besu to install and run. All available versions are listed on our Besu solutions page
`besu_git_repo`	https://github.com/hyperledger/besu.git	The URL to use when cloning besu sources. Only necessary when `besu_build_from_source` is `true`.
`besu_git_commit`	master	The git commit to use when building Besu from source. Can be a branchname, commit hash, or anything that's legal to be used as an argument to `git checkout`. Only used if `besu_build_from_source` is `true`.
`besu_user`	besu	Besu user
`besu_group`	besu	Besu group
`besu_download_url`	https://hyperledger.jfrog.io/artifactory/besu-binaries/besu/{{ besu_version }}/besu-{{ besu_version }}.tar.gz	The download tar.gz file used. You can use this if you need to retrieve besu from a custom location such as an internal repository.
`besu_install_dir`	/opt/besu	Path to install to
`besu_config_dir`	/etc/besu	Path for default configuration
`besu_node_private_key_file`	""	Path for node private key, if supplied. This needs to include the node key file name and path like so `/home/me/me_node/myPrivateKey`. If not supplied Besu will create one automatically
`besu_data_dir`	/opt/besu/data	Path for data directory
`besu_log_dir`	/var/log/besu	Path for logs
`besu_log4j_config_file`	unset	Absolute path for a custom log4j config file. Note this log configuration is overriden if `besu_log_level` is set
`besu_profile_file`	/etc/profile.d/besu-path.sh	Path to allow loading Besu into the system PATH
`besu_managed_service`	true	Enables a systemd service (or launchd if on Darwin)
`besu_launchd_dir`	/Library/LaunchAgents	The default launchd directory
`besu_systemd_dir`	/etc/systemd/system/	The default systemd directory
`besu_systemd_state`	restarted	The default option for the systemd service state
`besu_identity`	unset	Configuration of Identity in the Client ID
`besu_host_ip`	""	The host IP that Besu uses for the P2P network. This specifies the host on which P2P listens
`besu_default_ip`	"{{ default(ansible_host) \| default('127.0.0.1') }}"	The fallback default for `besu_host_ip`
`besu_max_peers`	unset	The maximum number of P2P connections you can establish
`besu_network`	mainnet	The network that this node will join. Other values are 'ropsten', 'rinkeby', 'goerli', 'classic', 'mordor', 'kotti', 'dev' and 'custom'
`besu_genesis_path`	unset	The path to the genesis file, only valid when `besu_network` is `custom`
`besu_required_blocks`	[]	Requires a peer with the specified block number to have the specified hash when connecting, or Besu rejects that peer
`besu_sync_mode`	FAST	Specifies the synchronization mode. Other values are 'FULL'
`besu_log_level`	unset	The log level to use. Other log levels are 'OFF', 'FATAL', 'WARN', 'INFO', 'DEBUG', 'TRACE', 'ALL'. Note setting this has priority over the configuration set by `besu_log4j_config_file`
`besu_data_storage_format`	unset	Data storage format. Possible values are 'FOREST' and 'BONSAI'. The besu default is 'FOREST'
`besu_engine_jwt_disabled`	unset	Disables authentication for the Engine API. The besu default is false.
`besu_engine_jwt_secret`	unset	Path to the shared secret file used to authenticate consensus clients when using the Engine JSON-RPC API (both HTTP and WebSocket). Contents of file could be set with `besu_engine_jwt_secret_content` and must be at least 32 hex-encoded bytes, not begin with 0x, otherwise a random value if automatically set, but only if a secret does not already exist on disk. If not specified, by default Besu creates an ephemeral secret in the data dir, that is deleted on exit.
`besu_engine_jwt_secret_content`	random value	Only available if `besu_engine_jwt_secret` specified, the file is populated with this value, that must be at least 32 hex-encoded bytes and not begin with 0x, and should be encrypted with Ansible Vault.
`besu_engine_rpc_port`	unset	The listening port for the Engine API calls (ENGINE, ETH) for JSON-RPC over HTTP and WebSocket. The besu default is 8551
`besu_p2p_port`	30303	Specifies the P2P listening ports (UDP and TCP). Ports must be exposed appropriately
`besu_min_gas`	1000	The minimum price that a transaction offers for it to be included in a mined block
`besu_miner_enabled`	false	Enables mining when the node is started
`besu_miner_coinbase`	0x	Account to which mining rewards are paid
`besu_miner_extra_data`	""	A hex string representing the 32 bytes to be included in the extra data field of a mined block.
`besu_rpc_http_enabled`	true	Enabled the HTTP JSON-RPC service
`besu_rpc_http_host`	0.0.0.0	Specifies the host on which HTTP JSON-RPC listens
`besu_rpc_http_port`	8545	Specifies the port on which HTTP JSON-RPC listens
`besu_rpc_http_api`	["ADMIN","DEBUG","NET","ETH","MINER","WEB3"]	Comma-separated APIs to enable on the HTTP JSON-RPC channel. When you use this option, the `besu_rpc_http_enabled` option must also be enabled
`besu_rpc_http_cors_origins`	["all"]	Comma separated origin domain URLs for CORS validation
`besu_rpc_ws_enabled`	true	Enabled the WebSockets service
`besu_rpc_ws_api`	["NET", "ETH", "WEB3"]	Comma-separated APIs to enable on the HTTP JSON-RPC channel. When you use this option, the `besu_rpc_ws_enabled` option must also be enabled
`besu_rpc_ws_host`	0.0.0.0	Specifies the host on which WebSockets listens
`besu_rpc_ws_port`	8546	Specifies Websockets JSON-RPC listening port (TCP). Port must be exposed appropriately
`besu_graphql_http_enabled`	true	Enabled the HTTP JSON-RPC service
`besu_graphql_http_host`	0.0.0.0	Specifies the host on which HTTP JSON-RPC listens
`besu_graphql_http_port`	8547	Specifies the port on which HTTP JSON-RPC listens
`besu_graphql_http_cors_origins`	["all"]	Comma separated origin domain URLs for CORS validation
`besu_rpc_http_authentication_enabled`	"false"	Enable RPC WS authentication
`besu_rpc_http_authentication_credentials_file`	""	Specifies the file to use for RPC http credentials
`besu_rpc_http_authentication_jwt_public_key_file`	""	Specifies the file to use for RPC http credentials via pubkey
`besu_rpc_ws_authentication_enabled`	"false"	Enable RPC WS authentication
`besu_rpc_ws_authentication_credentials_file`	""	Specifies the file to use for RPC http credentials
`besu_rpc_ws_authentication_jwt_public_key_file`	""	Specifies the file to use for RPC http credentials via pubkey
`besu_metrics_host`	0.0.0.0	Specifies the host on which Prometheus accesses Besu metrics. The metrics server respects the `besu_whitelist` option
`besu_metrics_port`	9545	Specifies the port on which Prometheus accesses Besu metrics
`besu_bootnodes`	[]	List of comma-separated enode URLs for P2P discovery bootstrap. When connecting to MainNet or public testnets, the default is a predefined list of enode URLs
`besu_static_nodes_file`	/etc/besu/static-nodes.json	Path to the static nodes file
`besu_host_whitelist`	`["*"]`	Comma-separated list of hostnames to allow access to the JSON-RPC API. By default, access from localhost and 127.0.0.1 is accepted.
`besu_local_permissions_enabled`	"false"	Enable local permissioning
`besu_local_permissions_config_file`	/etc/besu/permissions_config.toml	Path to the local accounts permissioning file and local nodes permissioning file
`besu_local_permissions_accounts`	[]	List of permissioned accounts
`besu_local_permissions_nodes`	[]	List of permissioned nodes
`besu_permissions_accounts_contract_address`	unset	The contract address for onchain accounts permissioning
`besu_permissions_nodes_contract_address`	unset	The contract address for onchain nodes permissioning
`besu_cmdline_args`	""	Command line args that are passed in as overrides
`besu_env_opts`	[]	Settings passed to the JVM through `BESU_OPTS` environment variable. eg: `[-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005]s`
`besu_env_vars`	{}	Dictionary with environment variables to set when running Besu as systemd service. eg: `{MALLOC_ARENA_MAX: 2}`
`besu_privacy_enabled`	false	Enable privacy
`besu_privacy_url`	""	URL to contact Orion on including port eg: `http://localhost:8888`
`besu_privacy_public_key_file`	""	Path to Orion public key
`besu_privacy_marker_tx_signing_key_file`	""	Path of the private key file used to sign Privacy Marker Transactions. If you do not specify this option, Besu signs each transaction with a different randomly generated key.
`besu_xdns_enabled`	"false"	DNS support with a trusted DNS provider in private networks because of limitations where IP addresses can change. For example, when using Kubernetes pods
`besu_target_gas_limit`	unset	Configuration of the target gas limit
`besu_tx_pool`	layered	Select the transaction pool implementation, set to `legacy` to switch to the old implementation
`besu_tx_pool_price_bump`	10	The price bump percentage to replace an existing transaction
`besu_tx_pool_limit_by_account_percentage`	0.001	The maximum number of transactions, relative to the max pool size, for the same sender allowed in the transaction pool. Defaults to 5 to prevent a DoS attack. This uses a float value [0..1], so setting it to 1 means a single sender can fill the entire tx pool. Only apply if `legacy` implementation is selected
`besu_tx_pool_max_size`	4096	The maximum number of transactions kept in the transaction pool. Only apply if `legacy` implementation is selected
`besu_tx_pool_retention_hours`	13	The maximum period, in hours, to hold pending transactions in the transaction pool. Only apply if `legacy` implementation is selected

Example Playbook

Default setup: Install the role from galaxy

ansible-galaxy install consensys.hyperledger_besu

Create a requirements.yml with the following: Replace x.y.z below with the version you would like to use from the Besu solutions page

---
- hosts: localhost
  connection: local
  force_handlers: True

  roles:
  - role: consensys.hyperledger_besu
    vars:
      besu_version: x.y.z

Run with ansible-playbook:

ansible-playbook -v /path/to/requirements.yml

Install via github

ansible-galaxy install git+https://github.com/consensys/ansible-role-besu.git

Create a requirements.yml with the following: Replace x.y.z below with the version you would like to use from the Besu solutions page

---
- hosts: localhost
  connection: local
  force_handlers: True

  roles:
  - role: ansible-role-besu
    vars:
      besu_version: x.y.z

Run with ansible-playbook:

ansible-playbook -v /path/to/requirements.yml

License

Apache

Author Information

Consensys, 2023

13 KiB Raw Blame History