Struct zebra_network::config::Config

pub struct Config {
    pub listen_addr: SocketAddr,
    pub external_addr: Option<SocketAddr>,
    pub network: Network,
    pub initial_mainnet_peers: IndexSet<String>,
    pub initial_testnet_peers: IndexSet<String>,
    pub cache_dir: CacheDir,
    pub peerset_initial_target_size: usize,
    pub crawl_new_peer_interval: Duration,
    pub max_connections_per_ip: usize,
}

Configuration for networking code.

Fields

listen_addr: SocketAddr

The address on which this node should listen for connections.

Can be address:port or just address. If there is no configured port, Zebra will use the default port for the configured network.

address can be an IP address or a DNS name. DNS names are only resolved once, when Zebra starts up.

If a specific listener address is configured, Zebra will advertise it to other nodes. But by default, Zebra uses an unspecified address (“0.0.0.0” or “[::]”), which is not advertised to other nodes.

Zebra does not currently support:

• Advertising a different external IP address #1890, or
• Auto-discovering its own external IP address #1893.

However, other Zebra instances compensate for unspecified or incorrect listener addresses by adding the external IP addresses of peers to their address books.

external_addr: Option<SocketAddr>

The external address of this node if any.

Zebra bind to listen_addr but this can be an internal address if the node is behind a firewall, load balancer or NAT. This field can be used to advertise a different address to peers making it possible to receive inbound connections and contribute to the P2P network from behind a firewall, load balancer, or NAT.

network: Network

The network to connect to.

initial_mainnet_peers: IndexSet<String>

A list of initial peers for the peerset when operating on mainnet.

initial_testnet_peers: IndexSet<String>

A list of initial peers for the peerset when operating on testnet.

cache_dir: CacheDir

An optional root directory for storing cached peer address data.

Configuration

Set to:

• true to read and write peer addresses to disk using the default cache path,
• false to disable reading and writing peer addresses to disk,
• '/custom/cache/directory' to read and write peer addresses to a custom directory.

By default, all Zebra instances run by the same user will share a single peer cache. If you use a custom cache path, you might also want to change state.cache_dir.

Functionality

The peer cache is a list of the addresses of some recently useful peers.

For privacy reasons, the cache does not include any other information about peers, such as when they were connected to the node.

Deleting or modifying the peer cache can impact your node’s:

• reliability: if DNS or the Zcash DNS seeders are unavailable or broken
• security: if DNS is compromised with malicious peers

If you delete it, Zebra will replace it with a fresh set of peers from the DNS seeders.

Defaults

The default directory is platform dependent, based on dirs::cache_dir():

Platform	Value	Example
Linux	$XDG_CACHE_HOME/zebra or $HOME/.cache/zebra	/home/alice/.cache/zebra
macOS	$HOME/Library/Caches/zebra	/Users/Alice/Library/Caches/zebra
Windows	{FOLDERID_LocalAppData}\zebra	C:\Users\Alice\AppData\Local\zebra
Other	std::env::current_dir()/cache/zebra	/cache/zebra

Security

If you are running Zebra with elevated permissions (“root”), create the directory for this file before running Zebra, and make sure the Zebra user account has exclusive access to that directory, and other users can’t modify its parent directories.

Implementation Details

Each network has a separate peer list, which is updated regularly from the current address book. These lists are stored in network/mainnet.peers and network/testnet.peers files, underneath the cache_dir path.

Previous peer lists are automatically loaded at startup, and used to populate the initial peer set and address book.

peerset_initial_target_size: usize

The initial target size for the peer set.

Also used to limit the number of inbound and outbound connections made by Zebra, and the size of the cached peer list.

If you have a slow network connection, and Zebra is having trouble syncing, try reducing the peer set size. You can also reduce the peer set size to reduce Zebra’s bandwidth usage.

crawl_new_peer_interval: Duration

How frequently we attempt to crawl the network to discover new peer addresses.

Zebra asks its connected peers for more peer addresses:

• regularly, every time crawl_new_peer_interval elapses, and
• if the peer set is busy, and there aren’t any peer addresses for the next connection attempt.

max_connections_per_ip: usize

The maximum number of peer connections Zebra will keep for a given IP address before it drops any additional peer connections with that IP.

The default and minimum value are 1.

Security

Increasing this config above 1 reduces Zebra’s network security.

If this config is greater than 1, Zebra can initiate multiple outbound handshakes to the same IP address.

This config does not currently limit the number of inbound connections that Zebra will accept from the same IP address.

If Zebra makes multiple inbound or outbound connections to the same IP, they will be dropped after the handshake, but before adding them to the peer set. The total numbers of inbound and outbound connections are also limited to a multiple of peerset_initial_target_size.

Implementations

impl Config

pub fn peerset_outbound_connection_limit(&self) -> usize

The maximum number of outbound connections that Zebra will open at the same time. When this limit is reached, Zebra stops opening outbound connections.

Security

See the note at INBOUND_PEER_LIMIT_MULTIPLIER.

Performance

Zebra’s peer set should be limited to a reasonable size, to avoid queueing too many in-flight block downloads. A large queue of in-flight block downloads can choke a constrained local network connection.

We assume that Zebra nodes have at least 10 Mbps bandwidth. Therefore, a maximum-sized block can take up to 2 seconds to download. So the initial outbound peer set adds up to 100 seconds worth of blocks to the queue. If Zebra has reached its outbound peer limit, that adds an extra 200 seconds of queued blocks.

But the peer set for slow nodes is typically much smaller, due to the handshake RTT timeout. And Zebra responds to inbound request overloads by dropping peer connections.

pub fn peerset_inbound_connection_limit(&self) -> usize

The maximum number of inbound connections that Zebra will accept at the same time. When this limit is reached, Zebra drops new inbound connections, without handshaking on them.

Security

See the note at INBOUND_PEER_LIMIT_MULTIPLIER.

pub fn peerset_total_connection_limit(&self) -> usize

The maximum number of inbound and outbound connections that Zebra will have at the same time.

pub fn initial_peer_hostnames(&self) -> IndexSet<String>

Returns the initial seed peer hostnames for the configured network.

pub async fn initial_peers(&self) -> HashSet<PeerSocketAddr>

Resolve initial seed peer IP addresses, based on the configured network, and load cached peers from disk, if available.

Panics

If a configured address is an invalid SocketAddr or DNS name.

async fn resolve_peers(peers: &HashSet<String>) -> HashSet<PeerSocketAddr>

Concurrently resolves peers into zero or more IP addresses, with a timeout of a few seconds on each DNS request.

If DNS resolution fails or times out for all peers, continues retrying until at least one peer is found.

async fn resolve_host(host: &str, max_retries: usize) -> HashSet<PeerSocketAddr>

Resolves host into zero or more IP addresses, retrying up to max_retries times.

If DNS continues to fail, returns an empty list of addresses.

Panics

If a configured address is an invalid SocketAddr or DNS name.

async fn resolve_host_once( host: &str, ) -> Result<HashSet<PeerSocketAddr>, BoxError>

Resolves host into zero or more IP addresses.

If host is a DNS name, performs DNS resolution with a timeout of a few seconds. If DNS resolution fails or times out, returns an error.

Panics

If a configured address is an invalid SocketAddr or DNS name.

pub async fn load_peer_cache(&self) -> Result<HashSet<PeerSocketAddr>>

Returns the addresses in the peer list cache file, if available.

pub async fn update_peer_cache( &self, peer_list: HashSet<PeerSocketAddr>, ) -> Result<()>

Atomically writes a new peer_list to the peer list cache file, if configured. If the list is empty, keeps the previous cache file.

Also creates the peer cache directory, if it doesn’t already exist.

Atomic writes avoid corrupting the cache if Zebra panics or crashes, or if multiple Zebra instances try to read and write the same cache file.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Config

fn default() -> Config

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Config

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Config

fn eq(&self, other: &Config) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Config

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Config

impl StructuralPartialEq for Config