Ansible Role 🌸 🔗 Lotus

Table of Contents

• Supported Platforms
• Requirements
• Role Variables
  • Install
  • Config
  • Launch
  • Uninstall
• 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_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, the lotus network client and lotus-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.

include_benchmarks: <true|false> (default: false)

• to build and install lotus-bench. More information here.

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 of lotus. 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-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 of go. 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 the config 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 within config.

  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

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 of lotus daemon's cli, this variable enables the launch to be customized according to the user's specification.

extra_miner_args: <lotus-miner-cli-options> (default: [])

• list of lotus-miner run commandline arguments to pass to the binary at runtime for customizing launch. Supporting full expression of lotus-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-miner"

To set multiple environment variables, they need to be space-separated:

custom_unit_properties:
  Environment: "BELLMAN_CPU_UTILIZATION=0.875 FIL_PROOFS_MAXIMIZE_CACHING=1 FIL_PROOFS_USE_GPU_COLUMN_BUILDER=1"
custom_miner_properties:
  Environment: "BELLMAN_CPU_UTILIZATION=0.875 FIL_PROOFS_MAXIMIZE_CACHING=1 FIL_PROOFS_USE_GPU_COLUMN_BUILDER=1"

Reference the systemd.service man page for a configuration overview and reference.

Uninstall

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

install lotus for the calibration network; include SHA extensions; include rust; include lotus-bench:

- hosts: all
  roles:
    - ansible-rustup

- hosts: all
  environment:
    # SHA Extensions
    RUSTFLAGS: "-C target-cpu=native -g"
    FFI_BUILD_FROM_SOURCE: 1
  vars:
    # Path for rust/cargo
    cargo_home: "{{ /home/{{ ansible_env.HOME }}/.cargo }}"
  roles:
    - role: 0x0I.lotus
      vars:
        install_type: source
        include_benchmarks: true
        git_url: https://github.com/filecoin-project/lotus.git
        git_version: ntwk-calibration
        go_autoinstall: true
        go_url: https://dl.google.com/go/go1.15.5.linux-amd64.tar.gz

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-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
      managed_services: ['lotus', '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.