Configuring
Before attempting to configure stellar-core, it is highly recommended to first try running a private network or joining the test network.
Configuration Basics
After you've installed Stellar Core, your next step is to complete a configuration file that specifies crucial things about your node — like whether it connects to the Testnet or the Mainnet public network, what database it writes to, and which other nodes are in its quorum set.
All configuration for stellar-core is done with a TOML file. By default, Stellar Core loads that file from ./stellar-core.cfg, but you can specify a different file to load on the command line:
stellar-core --conf betterfile.cfg <COMMAND>
The examples in these docs don't specify --conf betterfile.cfg for the sake of brevity.
This page will walk you through the key fields you'll need to include in your config file to get your node up and runninig.
This page attempts (as strictly as is possible) to focus on the specific fields and values that you may need to modify in your Stellar Core configuration file. To keep this page concise, we try to avoid conceptual context and background information. You will likely find some of that related information on the prerequisites or environment preparation pages, if you'd like.
Example Configurations
While we're looking at some of the config basics on this page, we've written this content to work best in conjunction with concrete config examples, so as you read through it, you may want to review the following:
The complete example config is not a real configuration, but thoroughly documents all possible configuration elements, as well as their default values. It's got every knob you can turn and every setting you can tweak along with detailed explanations of how to turn and tweak them. You don't need to put everything from the complete example config into your config file. Fields you omit will assume the default setting, and the default setting will generally serve you well. There are a few required fields, though, and this page will explain what they are.
If you want to connect to the Testnet network, check out the example Testnet config. As you can see, most of the fields from the complete example config are omitted since the default settings work fine. You can easily tailor this config to meet your Testnet needs.
If you want to connect to the Mainnet network, check out this example Mainnet config for a full validator. It includes a properly crafted quorum set with all the current Tier 1 validators, which is a good place to start for most configurations. This node is set up to both validate and write history to a public archive, but you can disable either feature by adjusting this config so it's a little lighter.
Auditing of the P2P network is enabled by default, see the overlay topology section for more detail if you'd like to disable it
Network Passphrase
Use the NETWORK_PASSPHRASE field to specify whether your node connects to the Testnet or the Mainnet network.
NETWORK_PASSPHRASE="Test SDF Network ; September 2015"NETWORK_PASSPHRASE="Public Global Stellar Network ; September 2015"
For more about the Network Passphrase and how it works, check out the encyclopedia entry.
Database
You specify your node's database by using the aptly named DATABASE field of your config file, which you can can read more about in the complete example config. It defaults to an in-memory database, but you can specify a path as per the example.
Buckets
The flat XDR files of Stellar Core (the duplicate copy of the ledger) are placed in a directory specified in the config file as BUCKET_DIR_PATH, which defaults to buckets.
Validating Node
If you don't intend for your node to participate in consensus votes, you can skip ahead to configuring your quorum set
If you want to validate, you must generate a public/private key for your node. Nodes shouldn't share keys. You should carefully secure your private key. If it is compromised, someone can send false messages to the network and those messages will look like they came from you.
Generate a key pair for your validating node like this:
stellar-core gen-seed
Your output should look something like:
Secret seed: SBAAOHEU4WSWX6GBZ3VOXEGQGWRBJ72ZN3B3MFAJZWXRYGDIWHQO37SY
Public: GDMTUTQRCP6L3JQKX3OOKYIGZC6LG2O6K2BSUCI6WNGLL4XXCIB3OK2P
Add this secret seed to your config file, and mark the node as "validator":
NODE_SEED="SBAAOHEU4WSWX6GBZ3VOXEGQGWRBJ72ZN3B3MFAJZWXRYGDIWHQO37SY mynode"
NODE_IS_VALIDATOR=true
NODE_HOME_DOMAIN=<your domain name here - i.e., stellar.org>
[[HOME_DOMAINS]]
HOME_DOMAIN=<your domain name here, same as NODE_HOME_DOMAIN>
QUALITY="MEDIUM"
If you don't include a NODE_SEED or set NODE_IS_VALIDATOR=true, your node will still watch SCP and see all the data in the network, but it will not send validation messages.
If you run multiple validators, make sure to set a common HOME_DOMAIN for them by setting the NODE_HOME_DOMAIN property to the same value. This will ensure your nodes get grouped correctly during quorum set generation. You also need to include your other nodes in in your config file's VALIDATORS array.
If you want other validators to add your node to their quorum sets, you should also share your public key (GDMTUTQ...) by publishing a stellar.toml file on your home domain following specifications laid out by SEP-20.
Choosing Your Quorum Set
To create your quorum set, Stellar Core relies on two arrays of tables: [[HOME_DOMAINS]] and [[VALIDATORS]]. Check out the example config's HOME_DOMAINS array and VALIDATORS array to see them in action.
It is beneficial to take a brief detour here and explore some background information of validator quorums and network consensus. If you'd like, you can skip ahead and begin creating your home domains array now. Otherwise, read on, my friend!
No matter what kind of node you run — Basic or Full Validator — you need to select a quorum set, which consists of validators (grouped by organization) that your node checks with to determine whether to apply a transaction set to a ledger. If you want to know more about how quorum sets work, check this article about how Stellar approaches quorums. If you want to see what a quorum set consisting of all the Tier 1 validators looks like — a tried and true setup — check out the public network config for a Full Validator.
A good quorum set:
- aligns with your organization's priorities,
- has enough redundancy to handle arbitrary node failures, and
- maintains good quorum intersection.
Since crafting a good quorum set is a difficult thing to do, stellar core automatically generates a quorum set for you based on structured information you provide in your config file. You choose the validators you want to trust; stellar core configures them into an optimal quorum set.
To generate a quorum set, stellar core:
- Groups validators run by the same organization into a subquorum
- Sets the threshold for each of those subquorums
- Gives weights to those subquorums based on quality
While this does not absolve you of all responsibility — you still need to pick trustworthy validators and keep an eye on them to ensure that they're consistent and reliable — it does make your life easier and reduces the chances for human error.
Validator Discovery
When you add a validating node to your quorum set, it's generally because you trust the organization running the node: you trust SDF, not some anonymous Stellar public key.
In order to create a self-verified link between a node and the organization that runs it, a validator declares a home domain on-chain using a set_options operation, and publishes organizational information in a stellar.toml file hosted on that domain. To find out how that works, take a look at SEP-20.
As a result of that link, you can look up a node by its Stellar public key and check the stellar.toml file to find out who runs it. It's possible to do that manually, but you can also just consult the list of nodes on Stellarbeat.io. If you decide to trust an organization, you can use that list to collect the information necessary to add their nodes to your configuration.
When you look at that list, you will discover that the most reliable organizations actually run more than one validator, and adding all of an organization's nodes to your quorum set creates the redundancy necessary to sustain arbitrary node failure. When an organization with a trio of nodes takes one down for maintenance, for instance, the remaining two nodes vote on the organization's behalf, and the organization's network presence persists.
Home Domains Array
[[HOME_DOMAINS]] defines a superset of validators: when you add nodes hosted by the same organization to your configuration, they share a home domain, and the information in the [[HOME_DOMAINS]] table, specifically the quality rating, will automatically apply to every one of those validators.
For each organization you want to add, create a separate [[HOME_DOMAINS]] table, and complete the following required fields:
| Field | Requirements | Description |
|---|---|---|
| HOME_DOMAIN | string | URL of home domain linked to a group of validators |
| QUALITY | string | Rating for this organization's nodes: HIGH, MEDIUM, or LOW |
Here is an example [[HOME_DOMAINS]] array, which creates two [[HOME_DOMAINS]] tables:
[[HOME_DOMAINS]]
HOME_DOMAIN="testnet.stellar.org"
QUALITY="HIGH"
[[HOME_DOMAINS]]
HOME_DOMAIN="some-other-domain"
QUALITY="LOW"
Validators Array
For each node you would like to add to your quorum set, complete a [[VALIDATORS]] table with the following fields:
| Field | Requirements | Description |
|---|---|---|
| NAME | string | A unique alias for the node |
| QUALITY | string | Rating for node (required unless specified in [[HOME_DOMAINS]]): HIGH, MEDIUM, or LOW. |
| HOME_DOMAIN | string | URL of home domain linked to validator |
| PUBLIC_KEY | string | Stellar public key associated with validator |
| ADDRESS | string | Peer:port associated with validator (optional) |
| HISTORY | string | archive GET command associated with validator (optional) |
If the node's HOME_DOMAIN aligns with an organization defined in the [[HOME_DOMAINS]] array, the quality rating specified there will apply to the node. If you're adding an individual node that is not covered in that array, you'll need to specify the QUALITY here.
Here is an example, which creates three [[VALIDATORS]] tables:
[[VALIDATORS]]
NAME="sdftest1"
HOME_DOMAIN="testnet.stellar.org"
PUBLIC_KEY="GDKXE2OZMJIPOSLNA6N6F2BVCI3O777I2OOC4BV7VOYUEHYX7RTRYA7Y"
ADDRESS="core-testnet1.stellar.org"
HISTORY="curl -sf http://history.stellar.org/prd/core-testnet/core_testnet_001/{0} -o {1}"
[[VALIDATORS]]
NAME="sdftest2"
HOME_DOMAIN="testnet.stellar.org"
PUBLIC_KEY="GCUCJTIYXSOXKBSNFGNFWW5MUQ54HKRPGJUTQFJ5RQXZXNOLNXYDHRAP"
ADDRESS="core-testnet2.stellar.org"
HISTORY="curl -sf http://history.stellar.org/prd/core-testnet/core_testnet_002/{0} -o {1}"
[[VALIDATORS]]
NAME="rando-node"
QUALITY="LOW"
HOME_DOMAIN="rando.com"
PUBLIC_KEY="GC2V2EFSXN6SQTWVYA5EPJPBWWIMSD2XQNKUOHGEKB535AQE2I6IXV2Z"
ADDRESS="core.rando.com"
Validator Quality
QUALITY is a required field for each node you add to your quorum set. Whether you specify it for a suite of nodes in a [[HOME_DOMAINS]] table, or for a single node in a [[VALIDATORS]] table, it means the same thing, and you have the same three rating options: HIGH, MEDIUM, or LOW.
HIGH Quality
HIGH quality validators are given the most weight in automatic quorum set configuration. Before assigning a high quality rating to a node, make sure it has low latency and good uptime, and that the organization running the node is reliable and trustworthy.
A high quality validator:
- publishes an archive, and
- belongs to a suite of nodes that provide redundancy.
Choosing redundant nodes is good practice. The archive requirement is programmatically enforced.
MEDIUM Quality
MEDIUM quality validators are nested below high quality validators, and their combined weight is equivalent to a single high quality entity. If a node doesn't publish an archive, but you deem it reliable, or have an organizational interest in including it in your quorum set, give it a medium quality rating.
LOW Quality
LOW quality validators are nested below medium quality validators, and their combined weight is equivalent to a single medium quality entity. Should they prove reliable over time, you can upgrade their rating to medium to give them a bigger role in your quorum set configuration.
Automatic Quorum Set Generation
You need to either depend on exactly one entity OR have at least 4 entities for automatic quorum set configuration to work properly. At least 4 is the better option.
Once you add validators to your configuration, stellar core automatically generates a quorum set using the following rules:
- Validators with the same home domain are automatically grouped together and given a threshold requiring a simple majority (
2f+1) - Heterogeneous groups of validators are given a threshold assuming byzantine failure (
3f+1) - Entities are grouped by
QUALITYand nested fromHIGHtoLOW HIGHquality entities are at the top, and are given decision-making priority- The combined weight of
MEDIUMquality entities equals a singleHIGHquality entity - The combined weight of
LOWquality entities equals a singleMEDIUMquality entity
Diagram: Depiction of the nested quality levels and how they interact.
Quorum and Overlay Network
It is generally a good idea to give information to your validator on other validators that you rely on. This is achieved by configuring the KNOWN_PEERS and PREFERRED_PEERS fields with the addresses of nodes you depend on.
Additionally, configuring PREFERRED_PEER_KEYS with the keys from your quorum set might be a good idea to give priority to the nodes that allow you to reach consensus.
Without those settings, your validator depends on other nodes on the network to forward you the right messages, which is typically done as a best effort.