Ansible Role 🌸 🔗 Lotus
Table of Contents
- Supported Platforms
- Requirements
- Role Variables
- Dependencies
- Example Playbook
- License
- Author Information
Ansible role that installs and configures Lotus: a Go-implementation of the Filecoin distributed storage network blockchain protocol.
Supported Platforms:
* Debian
* Redhat(CentOS/Fedora)
* Ubuntu
Requirements
Requires the unzip/gtar
utility to be installed on the target host. See ansible unarchive
module notes for details.
Role Variables
Variables are available and organized according to the following software & machine provisioning stages:
- install
- config
- launch
- uninstall
Install
lotus
can be installed using compressed archives (.tar
, .zip
), downloaded and extracted from various sources, or built from git source.
The following variables can be customized to control various aspects of this installation process, ranging from software version and source location of binaries to the installation directory where they are stored:
lotus_user: <service-user-name>
(default: lotus)
- dedicated service user and group used by
lotus
for privilege separation (see here for details)
install_type: <archive | source>
(default: archive)
-
archive: currently supported by Ubuntu and Fedora distributions (due to availibity of version >= 2.27 of the
glibc
GNU libc libraries package -- see here for per-distribution package availability) and compatible with both tar and zip formats, installation of Lotus via compressed archives results in the direct download of its component binaries, thelotus
network client andlotus-storage-miner
mining software, from the specified archive url.note: archived installation binaries can be obtained from the official releases site or those generated from development/custom sources.
-
source: build lotus network client and storage miner binaries from source. This installation process consists of cloning the github hosted repository and building from source code using
make
directives. See here for more details on building from source.
install_dir: </path/to/installation/dir>
(default: /opt/lotus
)
- path on target host where the
lotus
binaries should be extracted to.
archive_url: <path-or-url-to-archive>
(default: see defaults/main.yml
)
- address of a compressed tar or zip archive containing
lotus
binaries. This method technically supports installation of any available version oflotus
. Links to official versions can be found here.
archive_checksum: <path-or-url-to-checksum>
(default: see defaults/main.yml
)
- address of a checksum file for verifying the data integrity of the specified archive. While recommended and generally considered a best practice, specifying a checksum is not required and can be disabled by providing an empty string (
''
) for its value.
checksum_format: <string>
(default: see sha512
)
- hash algorithm used for file verification associated with the specified archive or package checksum. Reference here for more information about checksums/cryptographic hashes.
git_url: <path-or-url-to-git-repo>
(default: see defaults/main.yml
)
- address of
lotus
git repository. Address can reference the Github site address or custom source hosted on an alternate git hosting site.
git_version: <string>
(default: v0.1.0
)
- version of the repository to check out. This can be the literal string HEAD, a branch name, a tag name.
lotus_path: </path/to/runtime/dir>
(default: /opt/lotus/.lotus
)
- path on target host the
lotus
service should establish as its runtime configuration and data directory.
lotus_storage_path: </path/to/miner/data-dir>
(default: /opt/lotus/.lotusstorage
)
- path on target host the
lotus-storage-miner
service should establish as its runtime and data storage directory.
go_autoinstall: <true|false>
(default: false
)
- automatically install the specified version of Go packages and binaries. Useful when installing from source which requires
go
as a part of its build process
go_url: <path-or-url-to-archive>
(default: see defaults/main.yml
)
- address of a compressed tar or zip archive containing
go
binaries or source for compilation. This method technically supports installation of any available version ofgo
. Links to official versions can be found here.
go_install_dir: </path/to/install/dir>
(default: /usr/local
)
- path on target host where the
go
binaries should be extracted to.
Config
Configuration of the lotus
client can be expressed in a config file written in TOML, a minimal markup language. Note: This file can be found under the directory specified by the LOTUS_PATH
(for the lotus client/service) or LOTUS_STORAGE_PATH
(for the lotus miner) environment variables. For an idea of the available configuration options, reference this example (installed by default).
The following variables can be customized to manage the content of this TOML configuration:
config: {"<config-section>": {"<section-setting>": "<setting-value>",..},..}
default: see defaults/main.yml
-
Any configuration setting/value key-pair supported by
lotus
should be expressible within theconfig
hash and properly rendered within the associated TOML config. Values can be expressed in typical yaml/ansible form (e.g. Strings, numbers and true/false values should be written as is and without quotes).Furthermore, configuration is not constrained by hardcoded author defined defaults or limited by pre-baked templating. If the config section, setting and value are recognized by the
lotus
tool, 👍 to define withinconfig
.Keys of the
config
hash represent TOML config sections:config: # [TOML Section 'API'] API: {}
Values of
config[<key>]
represent key,value pairs within an embedded hash expressing config settings:config: # TOML Section '[API]' API: # Section setting ListenAddress with value of localhost binding at port 1234 ListenAddress: "/ip4/127.0.0.1/tcp/1234/http"
Launch
Running the lotus
distributed storage network protocol service/API server in addition to the lotus-storage-miner
storage miner agent is accomplished utilizing the systemd service management tool for both archive and source installations. Launched as background processes or daemons subject to the configuration and execution potential provided by the underlying management framework, launch of either service can be set to adhere to system administrative policies right for your environment and organization.
The following variables can be customized to manage the services' systemd [Service] unit definition and execution profile/policy:
extra_run_args: <lotus-cli-options>
(default: []
)
- list of
lotus daemon
commandline arguments to pass to the binary at runtime for customizing launch. Supporting full expression oflotus daemon
's cli, this variable enables the launch to be customized according to the user's specification.
extra_miner_args: <lotus-storage-miner-cli-options>
(default: []
)
- list of
lotus-storage-miner run
commandline arguments to pass to the binary at runtime for customizing launch. Supporting full expression oflotus-storage-miner run
's cli, this variable enables the launch to be customized according to the user's specification.
custom_unit_properties: <hash-of-systemd-service-settings>
(default: []
)
- hash of settings used to customize the
[Service]
unit configuration and execution environment of the Lotus systemd service.
custom_miner_properties: <hash-of-systemd-service-settings>
(default: []
)
- hash of settings used to customize the
[Service]
unit configuration and execution environment of the Lotus Storage Miner systemd service.
Example
custom_unit_properties:
Environment: "LOTUS_PATH=/var/data/lotus"
custom_miner_properties:
Environment: "LOTUS_STORAGE_PATH=/var/data/lotus-storage-miner"
Reference the systemd.service man page for a configuration overview and reference.
Uninstall
Support for uninstalling and removing artifacts necessary for provisioning allows for users/operators to return a target host to its configured state prior to application of this role. This can be useful for recycling nodes and roles and perhaps providing more graceful/managed transitions between tooling upgrades.
The following variable(s) can be customized to manage this uninstall process:
perform_uninstall: <true | false>
(default: false
)
- whether to uninstall and remove all artifacts and remnants of this
lotus
installation on a target host (see:handlers/main.yml
for details)
Dependencies
- 0x0i.systemd
Example Playbook
default example:
- hosts: all
roles:
- role: 0x0I.lotus
install lotus
from specified git source version:
- hosts: all
roles:
- role: 0x0I.lotus
vars:
install_type: source
git_url: https://github.com/filecoin-project/lotus.git
git_version: v0.1.1
expose lotus
API/JSON-RPC server on non-loopback (wildcard/*) address
- hosts: all
roles:
- role: 0x0I.lotus
vars:
install_type: archive
config:
API:
ListenAddress: /ip4/0.0.0.0/tcp/1234/http
LibP2P:
ListenAddresses: ["/ip4/0.0.0.0/tcp/0", "/ip6/::/tcp/0"]
launch lotus
service and lotus-storage-miner
agents with custom runtime/storage paths and launch options:
- hosts: all
roles:
- role: 0x0I.lotus
vars:
install_type: source
lotus_path: /mnt/lotus
lotus_storage_path: /mnt/lotus/miner
config:
Metrics:
Nickname: "my_miner"
extra_run_args: ['--bootstrap']
extra_miner_args: ['--nosync']
custom_miner_properties:
LimitDATA: 1T
License
MIT
Author Information
This role was created in 2019 by O1.IO.