Advanced Configurations

This guide documents environment variables, configuration and other advanced features in the Lotus Node.

The Lotus daemon stores a configuration file in ~/.lotus/config.toml. Note that by default all settings are commented. Here is an example configuration:

[API]
  # Binding address for the Lotus API
  #
  # type: string
  # env var: LOTUS_API_LISTENADDRESS
  #ListenAddress = "/ip4/127.0.0.1/tcp/1234/http"

  # type: string
  # env var: LOTUS_API_REMOTELISTENADDRESS
  #RemoteListenAddress = ""

  # type: Duration
  # env var: LOTUS_API_TIMEOUT
  #Timeout = "30s"


[Backup]
  # When set to true disables metadata log (.lotus/kvlog). This can save disk
  # space by reducing metadata redundancy.
  #
  # Note that in case of metadata corruption it might be much harder to recover
  # your node if metadata log is disabled
  #
  # type: bool
  # env var: LOTUS_BACKUP_DISABLEMETADATALOG
  #DisableMetadataLog = true


[Logging]
  [Logging.SubsystemLevels]
    # env var: LOTUS_LOGGING_SUBSYSTEMLEVELS_EXAMPLE-SUBSYSTEM
    #example-subsystem = "INFO"


[Libp2p]
  # Binding address for the libp2p host - 0 means random port.
  # Format: multiaddress; see https://multiformats.io/multiaddr/
  #
  # type: []string
  # env var: LOTUS_LIBP2P_LISTENADDRESSES
  #ListenAddresses = ["/ip4/0.0.0.0/tcp/0", "/ip6/::/tcp/0"]

  # Addresses to explicitally announce to other peers. If not specified,
  # all interface addresses are announced
  # Format: multiaddress
  #
  # type: []string
  # env var: LOTUS_LIBP2P_ANNOUNCEADDRESSES
  #AnnounceAddresses = []

  # Addresses to not announce
  # Format: multiaddress
  #
  # type: []string
  # env var: LOTUS_LIBP2P_NOANNOUNCEADDRESSES
  #NoAnnounceAddresses = []

  # When not disabled (default), lotus asks NAT devices (e.g., routers), to
  # open up an external port and forward it to the port lotus is running on.
  # When this works (i.e., when your router supports NAT port forwarding),
  # it makes the local lotus node accessible from the public internet
  #
  # type: bool
  # env var: LOTUS_LIBP2P_DISABLENATPORTMAP
  #DisableNatPortMap = false

  # ConnMgrLow is the number of connections that the basic connection manager
  # will trim down to.
  #
  # type: uint
  # env var: LOTUS_LIBP2P_CONNMGRLOW
  #ConnMgrLow = 150

  # ConnMgrHigh is the number of connections that, when exceeded, will trigger
  # a connection GC operation. Note: protected/recently formed connections don't
  # count towards this limit.
  #
  # type: uint
  # env var: LOTUS_LIBP2P_CONNMGRHIGH
  #ConnMgrHigh = 180

  # ConnMgrGrace is a time duration that new connections are immune from being
  # closed by the connection manager.
  #
  # type: Duration
  # env var: LOTUS_LIBP2P_CONNMGRGRACE
  #ConnMgrGrace = "20s"


[Pubsub]
  # Run the node in bootstrap-node mode
  #
  # type: bool
  # env var: LOTUS_PUBSUB_BOOTSTRAPPER
  #Bootstrapper = false

  # type: string
  # env var: LOTUS_PUBSUB_REMOTETRACER
  #RemoteTracer = ""

  # Path to file that will be used to output tracer content in JSON format.
  # If present tracer will save data to defined file.
  # Format: file path
  #
  # type: string
  # env var: LOTUS_PUBSUB_JSONTRACER
  #JsonTracer = ""

  # Connection string for elasticsearch instance.
  # If present tracer will save data to elasticsearch.
  # Format: https://<username>:<password>@<elasticsearch_url>:<port>/
  #
  # type: string
  # env var: LOTUS_PUBSUB_ELASTICSEARCHTRACER
  #ElasticSearchTracer = ""

  # Name of elasticsearch index that will be used to save tracer data.
  # This property is used only if ElasticSearchTracer property is set.
  #
  # type: string
  # env var: LOTUS_PUBSUB_ELASTICSEARCHINDEX
  #ElasticSearchIndex = ""

  # Auth token that will be passed with logs to elasticsearch - used for weighted peers score.
  #
  # type: string
  # env var: LOTUS_PUBSUB_TRACERSOURCEAUTH
  #TracerSourceAuth = ""


[Client]
  # type: bool
  # env var: LOTUS_CLIENT_USEIPFS
  #UseIpfs = false

  # type: bool
  # env var: LOTUS_CLIENT_IPFSONLINEMODE
  #IpfsOnlineMode = false

  # type: string
  # env var: LOTUS_CLIENT_IPFSMADDR
  #IpfsMAddr = ""

  # type: bool
  # env var: LOTUS_CLIENT_IPFSUSEFORRETRIEVAL
  #IpfsUseForRetrieval = false

  # The maximum number of simultaneous data transfers between the client
  # and storage providers for storage deals
  #
  # type: uint64
  # env var: LOTUS_CLIENT_SIMULTANEOUSTRANSFERSFORSTORAGE
  #SimultaneousTransfersForStorage = 20

  # The maximum number of simultaneous data transfers between the client
  # and storage providers for retrieval deals
  #
  # type: uint64
  # env var: LOTUS_CLIENT_SIMULTANEOUSTRANSFERSFORRETRIEVAL
  #SimultaneousTransfersForRetrieval = 20

  # Require that retrievals perform no on-chain operations. Paid retrievals
  # without existing payment channels with available funds will fail instead
  # of automatically performing on-chain operations.
  #
  # type: bool
  # env var: LOTUS_CLIENT_OFFCHAINRETRIEVAL
  #OffChainRetrieval = false


[Wallet]
  # type: string
  # env var: LOTUS_WALLET_REMOTEBACKEND
  #RemoteBackend = ""

  # type: bool
  # env var: LOTUS_WALLET_ENABLELEDGER
  #EnableLedger = false

  # type: bool
  # env var: LOTUS_WALLET_DISABLELOCAL
  #DisableLocal = false


[Fees]
  # type: types.FIL
  # env var: LOTUS_FEES_DEFAULTMAXFEE
  #DefaultMaxFee = "0.07 FIL"


[Chainstore]
  # type: bool
  # env var: LOTUS_CHAINSTORE_ENABLESPLITSTORE
  EnableSplitstore = true

  [Chainstore.Splitstore]
    # ColdStoreType specifies the type of the coldstore.
    # It can be "messages" (default) to store only messages, "universal" to store all chain state or "discard" for discarding cold blocks.
    #
    # type: string
    # env var: LOTUS_CHAINSTORE_SPLITSTORE_COLDSTORETYPE
    #ColdStoreType = "discard"

    # HotStoreType specifies the type of the hotstore.
    # Only currently supported value is "badger".
    #
    # type: string
    # env var: LOTUS_CHAINSTORE_SPLITSTORE_HOTSTORETYPE
    #HotStoreType = "badger"

    # MarkSetType specifies the type of the markset.
    # It can be "map" for in memory marking or "badger" (default) for on-disk marking.
    #
    # type: string
    # env var: LOTUS_CHAINSTORE_SPLITSTORE_MARKSETTYPE
    #MarkSetType = "badger"

    # HotStoreMessageRetention specifies the retention policy for messages, in finalities beyond
    # the compaction boundary; default is 0.
    #
    # type: uint64
    # env var: LOTUS_CHAINSTORE_SPLITSTORE_HOTSTOREMESSAGERETENTION
    #HotStoreMessageRetention = 0

    # HotStoreFullGCFrequency specifies how often to perform a full (moving) GC on the hotstore.
    # A value of 0 disables, while a value 1 will do full GC in every compaction.
    # Default is 20 (about once a week).
    #
    # type: uint64
    # env var: LOTUS_CHAINSTORE_SPLITSTORE_HOTSTOREFULLGCFREQUENCY
    #HotStoreFullGCFrequency = 20

    # HotStoreMaxSpaceTarget sets a target max disk size for the hotstore. Splitstore GC
    # will run moving GC if disk utilization gets within a threshold (150 GB) of the target.
    # Splitstore GC will NOT run moving GC if the total size of the move would get
    # within 50 GB of the target, and instead will run a more aggressive online GC.
    # If both HotStoreFullGCFrequency and HotStoreMaxSpaceTarget are set then splitstore
    # GC will trigger moving GC if either configuration condition is met.
    # A reasonable minimum is 2x fully GCed hotstore size + 50 G buffer.
    # At this minimum size moving GC happens every time, any smaller and moving GC won't
    # be able to run. In spring 2023 this minimum is ~550 GB.
    #
    # type: uint64
    # env var: LOTUS_CHAINSTORE_SPLITSTORE_HOTSTOREMAXSPACETARGET
    #HotStoreMaxSpaceTarget = 650000000000

    # When HotStoreMaxSpaceTarget is set Moving GC will be triggered when total moving size
    # exceeds HotstoreMaxSpaceTarget - HotstoreMaxSpaceThreshold
    #
    # type: uint64
    # env var: LOTUS_CHAINSTORE_SPLITSTORE_HOTSTOREMAXSPACETHRESHOLD
    #HotStoreMaxSpaceThreshold = 150000000000

    # Safety buffer to prevent moving GC from overflowing disk when HotStoreMaxSpaceTarget
    # is set.  Moving GC will not occur when total moving size exceeds
    # HotstoreMaxSpaceTarget - HotstoreMaxSpaceSafetyBuffer
    #
    # type: uint64
    # env var: LOTUS_CHAINSTORE_SPLITSTORE_HOTSTOREMAXSPACESAFETYBUFFER
    #HotstoreMaxSpaceSafetyBuffer = 50000000000


[Cluster]
  # EXPERIMENTAL. config to enabled node cluster with raft consensus
  #
  # type: bool
  # env var: LOTUS_CLUSTER_CLUSTERMODEENABLED
  #ClusterModeEnabled = false

  # A folder to store Raft's data.
  #
  # type: string
  # env var: LOTUS_CLUSTER_DATAFOLDER
  #DataFolder = ""

  # InitPeersetMultiAddr provides the list of initial cluster peers for new Raft
  # peers (with no prior state). It is ignored when Raft was already
  # initialized or when starting in staging mode.
  #
  # type: []string
  # env var: LOTUS_CLUSTER_INITPEERSETMULTIADDR
  #InitPeersetMultiAddr = []

  # LeaderTimeout specifies how long to wait for a leader before
  # failing an operation.
  #
  # type: Duration
  # env var: LOTUS_CLUSTER_WAITFORLEADERTIMEOUT
  #WaitForLeaderTimeout = "15s"

  # NetworkTimeout specifies how long before a Raft network
  # operation is timed out
  #
  # type: Duration
  # env var: LOTUS_CLUSTER_NETWORKTIMEOUT
  #NetworkTimeout = "1m40s"

  # CommitRetries specifies how many times we retry a failed commit until
  # we give up.
  #
  # type: int
  # env var: LOTUS_CLUSTER_COMMITRETRIES
  #CommitRetries = 1

  # How long to wait between retries
  #
  # type: Duration
  # env var: LOTUS_CLUSTER_COMMITRETRYDELAY
  #CommitRetryDelay = "200ms"

  # BackupsRotate specifies the maximum number of Raft's DataFolder
  # copies that we keep as backups (renaming) after cleanup.
  #
  # type: int
  # env var: LOTUS_CLUSTER_BACKUPSROTATE
  #BackupsRotate = 6

  # Tracing enables propagation of contexts across binary boundaries.
  #
  # type: bool
  # env var: LOTUS_CLUSTER_TRACING
  #Tracing = false


[Fevm]
  # EnableEthRPC enables eth_ rpc, and enables storing a mapping of eth transaction hashes to filecoin message Cids.
  # This will also enable the RealTimeFilterAPI and HistoricFilterAPI by default, but they can be disabled by config options above.
  #
  # type: bool
  # env var: LOTUS_FEVM_ENABLEETHRPC
  #EnableEthRPC = false

  # EthTxHashMappingLifetimeDays the transaction hash lookup database will delete mappings that have been stored for more than x days
  # Set to 0 to keep all mappings
  #
  # type: int
  # env var: LOTUS_FEVM_ETHTXHASHMAPPINGLIFETIMEDAYS
  #EthTxHashMappingLifetimeDays = 0

  [Fevm.Events]
    # EnableEthRPC enables APIs that
    # DisableRealTimeFilterAPI will disable the RealTimeFilterAPI that can create and query filters for actor events as they are emitted.
    # The API is enabled when EnableEthRPC is true, but can be disabled selectively with this flag.
    #
    # type: bool
    # env var: LOTUS_FEVM_EVENTS_DISABLEREALTIMEFILTERAPI
    #DisableRealTimeFilterAPI = false

    # DisableHistoricFilterAPI will disable the HistoricFilterAPI that can create and query filters for actor events
    # that occurred in the past. HistoricFilterAPI maintains a queryable index of events.
    # The API is enabled when EnableEthRPC is true, but can be disabled selectively with this flag.
    #
    # type: bool
    # env var: LOTUS_FEVM_EVENTS_DISABLEHISTORICFILTERAPI
    #DisableHistoricFilterAPI = false

    # FilterTTL specifies the time to live for actor event filters. Filters that haven't been accessed longer than
    # this time become eligible for automatic deletion.
    #
    # type: Duration
    # env var: LOTUS_FEVM_EVENTS_FILTERTTL
    #FilterTTL = "24h0m0s"

    # MaxFilters specifies the maximum number of filters that may exist at any one time.
    #
    # type: int
    # env var: LOTUS_FEVM_EVENTS_MAXFILTERS
    #MaxFilters = 100

    # MaxFilterResults specifies the maximum number of results that can be accumulated by an actor event filter.
    #
    # type: int
    # env var: LOTUS_FEVM_EVENTS_MAXFILTERRESULTS
    #MaxFilterResults = 10000

    # MaxFilterHeightRange specifies the maximum range of heights that can be used in a filter (to avoid querying
    # the entire chain)
    #
    # type: uint64
    # env var: LOTUS_FEVM_EVENTS_MAXFILTERHEIGHTRANGE
    #MaxFilterHeightRange = 2880

    # DatabasePath is the full path to a sqlite database that will be used to index actor events to
    # support the historic filter APIs. If the database does not exist it will be created. The directory containing
    # the database must already exist and be writeable. If a relative path is provided here, sqlite treats it as
    # relative to the CWD (current working directory).
    #
    # type: string
    # env var: LOTUS_FEVM_EVENTS_DATABASEPATH
    #DatabasePath = ""


[Index]
  # EXPERIMENTAL FEATURE. USE WITH CAUTION
  # EnableMsgIndex enables indexing of messages on chain.
  #
  # type: bool
  # env var: LOTUS_INDEX_ENABLEMSGINDEX
  #EnableMsgIndex = false

Connectivity

Usually your lotus daemon will establish connectivity with others in the network and try to make itself diallable using UPnP. If you wish to manually ensure that your daemon is reachable:

Set a fixed port of your choice in the ListenAddresses in the Libp2p section (i.e. 6665).
Open a port in your router that is forwarded to this port. This is usually called featured as “Port forwarding” and the instructions differ from router model to model but there are many guides online.
Add your public IP/port to AnnounceAddresses. i.e. /ip4/<yourIP>/tcp/6665.

Note that it is not a requirement to use Lotus as a client to the network to be fully reachable, as your node already dials-out to others nodes and miners directly.

Environment variables

Some aspects of the Lotus Node can be controlled using environment variables.

Variables common to most Lotus binaries:

LOTUS_FD_MAX: Sets the file descriptor limit for the process
LOTUS_JAEGER: Sets the Jaeger URL to send traces.
LOTUS_DEV: Any non-empty value will enable more verbose logging, useful only for developers.
GOLOG_OUTPUT: Controls where the program logs. Possible values: stdout, stderr, file. Multiple values can be combined with ‘+’.
GOLOG_FILE: Path to file to log to.
GOLOG_LOG_FMT: Logging format (json, nocolor).

Variables specific to the Lotus daemon:

LOTUS_PATH: Location to store Lotus data (defaults to ~/.lotus).
LOTUS_MAX_HEAP (v1.2.3+): Maximum heap size that the memory watchdog will try to respect. Values are a numeric byte amount (12345678) or a storage unit in metric system (e.g. 16GiB). If not set, the memory watchdog will use the total system memory as a limit for the memory watchdog. The memory watchdog is necessary to overcome GC-related shortcomings in the Go runtime.
LOTUS_DISABLE_WATCHDOG=1 (v1.2.3+): If set, will disable the memory watchdog. May be necessary in environments where the OS/kernel doesn’t report correct information.
LOTUS_SKIP_GENESIS_CHECK=_yes_: Set only if you wish to run a lotus network with a different genesis block.
LOTUS_CHAIN_TIPSET_CACHE: Sets the size for the chainstore tipset cache. Defaults to 8192. Increase if you perform frequent arbitrary tipset lookups.
LOTUS_CHAIN_INDEX_CACHE: Sets the size for the epoch index cache. Defaults to 32768. Increase if you perform frequent deep chain lookups for block heights far from the latest height.
LOTUS_CHAIN_BADGERSTORE_COMPACTIONWORKERNUM: Sets the number of compaction workers for the badger blockstore.
LOTUS_BSYNC_MSG_WINDOW: Sets the initial maximum window size for message fetching blocksync request. Set to 10-20 if you have an internet connection with low bandwidth.
LOTUS_MIGRATION_MAX_WORKER_COUNT: Limits the number of actors being migrated simultaneously.

Controlling a remote daemon

The lotus application, as a client to the lotus daemon, can talk to a Lotus daemon running on any location (not just the local one), by setting the following environment variable:

FULLNODE_API_INFO="TOKEN:/ip4/<IP>/tcp/<PORT>/http"

On the Lotus Node, the full variable string, including a new token, can be produced with:

lotus auth api-info --perm admin

Note that you may need to edit the result to place the right IP for the remote node. See the docs about API tokens for more information about tokens.

Log level control

lotus log set-level <level>

This command can be used to toggle the logging levels of the different systems of a Lotus node. In decreasing order of logging detail, the levels are debug, info, warn, and error.

As an example, to set the chain and blocksync to log at the debug level, run lotus log set-level --system chain --system blocksync debug.

To see the various logging systems, run:

lotus log list

💡

The Environment variables section section above documents some GOLOG_* variables that allow to control logging locations and formats.

Eth Service

The ActorEvent configuration section contains settings for the event filtering API. These settings control various aspects of the event filtering API. The following setting are available:

EnableRealTimeFilterAPI: determines if the APIs that can create and query filters for actor events as they are emitted are enabled.
EnableHistoricFilterAPI: determines if the APIs that can create and query filters for actor events that occurred in the past are enabled. A queryable index of events will be maintained.
FilterTTL: specifies the time to live for actor event filters. Filters that haven’t been accessed longer than this time will become eligible for automatic deletion.
MaxFilters: integer value that specifies the maximum number of filters that may exist at any one time.
MaxFilterResults: integer value that specifies the maximum number of results that can be accumulated by an actor event filter.
MaxFilterHeightRange: An unsigned 64-bit integer value that specifies the maximum range of heights that can be used in a filter to avoid querying the entire chain.
ActorEventDatabasePath: A string value that specifies the full path to an SQLite database that will be used to index actor events to support the historic filter APIs. The database will be created if it does not exist. The directory containing the database must already exist and be writeable.

Indexing

This feature is experimental – use with caution.

The EnableMsgIndex variable allows users to accelerate StateSearchMessage and related functionality. This feature comes with two lotus-shed commands:

lotus-shed msgindex backfill: backfill the index.
lotus-shed msgindex prune: prune old index entries.

Users can enable this feature by creating a LOTUS_INDEX_ENABLEMSINDEX environment variable or setting EnableMsgIndex to true within their ~/.lotus/config.toml file (or wherever their config.toml file is located). This feature is disabled by default.

Edit this page on GitHub

Advanced Configurations

Connectivity #

Environment variables #

Controlling a remote daemon #

Log level control #

Eth Service #