#------------------------------------------------------------------------------- # # #------------------------------------------------------------------------------- # # Contents # # 1. Server # # 2. Peer Protocol # # 3. XRPL Protocol # # 4. HTTPS Client # # 5. Reporting Mode # # 6. Database # # 7. Diagnostics # # 8. Voting # # 9. Misc Settings # # 10. Example Settings # #------------------------------------------------------------------------------- # # Purpose # # This file documents and provides examples of all xahaud server process # configuration options. When the xahaud server instance is launched, it # looks for a file with the following name: # # xahaud.cfg # # To run xahaud with a custom configuration file, use the "--conf {file}" flag. # By default, xahaud will look in the local working directory or the home directory. # # # This file should be named xahaud.cfg. This file is UTF-8 with DOS, UNIX, # or Mac style end of lines. Blank lines and lines beginning with '#' are # ignored. Undefined sections are reserved. No escapes are currently defined. # # Notation # # In this document a simple BNF notation is used. Angle brackets denote # required elements, square brackets denote optional elements, and single # quotes indicate string literals. A vertical bar separating 1 or more # elements is a logical "or"; any one of the elements may be chosen. # Parentheses are notational only, and used to group elements; they are not # part of the syntax unless they appear in quotes. White space may always # appear between elements, it has no effect on values. # # A required identifier # '=' The equals sign character # | Logical "or" # ( ) Used for grouping # # # An identifier is a string of upper or lower case letters, digits, or # underscores subject to the requirement that the first character of an # identifier must be a letter. Identifiers are not case sensitive (but # values may be). # # Some configuration sections contain key/value pairs. A line containing # a key/value pair has this syntax: # # '=' # # Depending on the section and key, different value types are possible: # # A signed integer # An unsigned integer # A boolean. 1 = true/yes/on, 0 = false/no/off. # # Consult the documentation on the key in question to determine the possible # value types. # # # #------------------------------------------------------------------------------- # # 1. Server # #---------- # # # # xahaud offers various server protocols to clients making inbound # connections. The listening ports xahaud uses are "universal" ports # which may be configured to handshake in one or more of the available # supported protocols. These universal ports simplify administration: # A single open port can be used for multiple protocols. # # NOTE At least one server port must be defined in order # to accept incoming network connections. # # # [server] # # A list of port names and key/value pairs. A port name must start with a # letter and contain only letters and numbers. The name is not case-sensitive. # For each name in this list, xahaud will look for a configuration file # section with the same name and use it to create a listening port. The # name is informational only; the choice of name does not affect the function # of the listening port. # # Key/value pairs specified in this section are optional, and apply to all # listening ports unless the port overrides the value in its section. They # may be considered default values. # # Suggestion: # # To avoid a conflict with port names and future configuration sections, # we recommend prepending "port_" to the port name. This prefix is not # required, but suggested. # # This example defines two ports with different port numbers and settings: # # [server] # port_public # port_private # port = 80 # # [port_public] # ip = 0.0.0.0 # port = 443 # protocol = peer,https # # [port_private] # ip = 127.0.0.1 # protocol = http # # When xahaud is used as a command line client (for example, issuing a # server stop command), the first port advertising the http or https # protocol will be used to make the connection. # # # # [] # # A series of key/value pairs that define the settings for the port with # the corresponding name. These keys are possible: # # ip = # # Required. Determines the IP address of the network interface to bind # to. To bind to all available IPv4 interfaces, use 0.0.0.0 # To binding to all IPv4 and IPv6 interfaces, use :: # # NOTE if the ip value is ::, then any incoming IPv4 connections will # be made as mapped IPv4 addresses. # # port = # # Required. Sets the port number to use for this port. # # protocol = [ http, https, peer ] # # Required. A comma-separated list of protocols to support: # # http JSON-RPC over HTTP # https JSON-RPC over HTTPS # ws Websockets # wss Secure Websockets # peer Peer Protocol # # Restrictions: # # Only one port may be configured to support the peer protocol. # A port cannot have websocket and non websocket protocols at the # same time. It is possible have both Websockets and Secure Websockets # together in one port. # # NOTE If no ports support the peer protocol, xahaud cannot # receive incoming peer connections or become a superpeer. # # limit = # # Optional. An integer value that will limit the number of connected # clients that the port will accept. Once the limit is reached, new # connections will be refused until other clients disconnect. # Omit or set to 0 to allow unlimited numbers of clients. # # user = # password = # # When set, these credentials will be required on HTTP/S requests. # The credentials must be provided using HTTP's Basic Authentication # headers. If either or both fields are empty, then no credentials are # required. IP address restrictions, if any, will be checked in addition # to the credentials specified here. # # When acting in the client role, xahaud will supply these credentials # using HTTP's Basic Authentication headers when making outbound HTTP/S # requests. # # admin = [ IP, IP, IP, ... ] # # A comma-separated list of IP addresses or subnets. Subnets # should be represented in "slash" notation, such as: # 10.0.0.0/8 # 172.16.0.0/12 # 192.168.0.0/16 # Those examples are ipv4, but ipv6 is also supported. # When configuring subnets, the address must match the # underlying network address. Otherwise, the desired IP range is # ambiguous. For example, 10.1.2.3/24 has a network address of # 10.1.2.0. Therefore, that subnet should be configured as # 10.1.2.0/24. # # When set, grants administrative command access to the specified # addresses. These commands may be issued over http, https, ws, or wss # if configured on the port. If not provided, the default is to not allow # administrative commands. # # NOTE A common configuration value for the admin field is "localhost". # If you are listening on all IPv4/IPv6 addresses by specifing # ip = :: then you can use admin = ::ffff:127.0.0.1,::1 to allow # administrative access from both IPv4 and IPv6 localhost # connections. # # *SECURITY WARNING* # 0.0.0.0 or :: may be used to allow access from any IP address. It must # be the only address specified and cannot be combined with other IPs. # Use of this address can compromise server security, please consider its # use carefully. # # admin_user = # admin_password = # # When set, clients must provide these credentials in the submitted # JSON for any administrative command requests submitted to the HTTP/S, # WS, or WSS protocol interfaces. If administrative commands are # disabled for a port, these credentials have no effect. # # When acting in the client role, xahaud will supply these credentials # in the submitted JSON for any administrative command requests when # invoking JSON-RPC commands on remote servers. # # secure_gateway = [ IP, IP, IP, ... ] # # A comma-separated list of IP addresses or subnets. See the # details for the "admin" option above. # # When set, allows the specified addresses to pass HTTP headers # containing username and remote IP address for each session. If a # non-empty username is passed in this way, then resource controls # such as often resulting in "tooBusy" errors will be lifted. However, # administrative RPC commands such as "stop" will not be allowed. # The HTTP headers that secure_gateway hosts can set are X-User and # X-Forwarded-For. Only the X-User header affects resource controls. # However, both header values are logged to help identify user activity. # If no X-User header is passed, or if its value is empty, then # resource controls will default to those for non-administrative users. # # The secure_gateway IP addresses are intended to represent # proxies. Since xahaud trusts these hosts, they must be # responsible for properly authenticating the remote user. # # If some IP addresses are included for both "admin" and # "secure_gateway" connections, then they will be treated as # "admin" addresses. # # ssl_key = # ssl_cert = # ssl_chain = # # Use the specified files when configuring SSL on the port. # # NOTE If no files are specified and secure protocols are selected, # xahaud will generate an internal self-signed certificate. # # The files have these meanings: # # ssl_key # # Specifies the filename holding the SSL key in PEM format. # # ssl_cert # # Specifies the path to the SSL certificate file in PEM format. # This is not needed if the chain includes it. # # ssl_chain # # If you need a certificate chain, specify the path to the # certificate chain here. The chain may include the end certificate. # # ssl_ciphers = # # Control the ciphers which the server will support over SSL on the port, # specified using the OpenSSL "cipher list format". # # NOTE If unspecified, xahaud will automatically configure a modern # cipher suite. This default suite should be widely supported. # # You should not modify this string unless you have a specific # reason and cryptographic expertise. Incorrect modification may # keep xahaud from connecting to other instances of xahaud or # prevent RPC and WebSocket clients from connecting. # # send_queue_limit = [1..65535] # # A Websocket will disconnect when its send queue exceeds this limit. # The default is 100. A larger value may help with erratic disconnects but # may adversely affect server performance. # # WebSocket permessage-deflate extension options # # These settings configure the optional permessage-deflate extension # options and may appear on any port configuration entry. They are meaningful # only to ports which have enabled a WebSocket protocol. # # permessage_deflate = # # Determines if permessage_deflate extension negotiations are enabled. # When enabled, clients may request the extension and the server will # offer the enabled extension in response. # # client_max_window_bits = [9..15] # server_max_window_bits = [9..15] # client_no_context_takeover = # server_no_context_takeover = # # These optional settings control options related to the permessage-deflate # extension negotiation. For precise definitions of these fields please see # the RFC 7692, "Compression Extensions for WebSocket": # https://tools.ietf.org/html/rfc7692 # # compress_level = [0..9] # # When set, determines the amount of compression attempted, where 0 is # the least amount and 9 is the most amount. Higher levels require more # CPU resources. Levels 1 through 3 use a fast compression algorithm, # while levels 4 through 9 use a more compact algorithm which uses more # CPU resources. If unspecified, a default of 3 is used. # # memory_level = [1..9] # # When set, determines the relative amount of memory used to hold # intermediate compression data. Higher numbers can give better compression # ratios at the cost of higher memory and CPU resources. # # [rpc_startup] # # Specify a list of RPC commands to run at startup. # # Examples: # { "command" : "server_info" } # { "command" : "log_level", "partition" : "xahaudcalc", "severity" : "trace" } # # # # [websocket_ping_frequency] # # # # The amount of time to wait in seconds, before sending a websocket 'ping' # message. Ping messages are used to determine if the remote end of the # connection is no longer available. # # # [server_domain] # # domain name # # The domain under which a TOML file applicable to this server can be # found. A server may lie about its domain so the TOML should contain # a reference to this server by pubkey in the [nodes] array. # # #------------------------------------------------------------------------------- # # 2. Peer Protocol # #----------------- # # These settings control security and access attributes of the Peer to Peer # server section of the xahaud process. It is over peer connections that # transactions and validations are passed from to machine to machine, to # determine the contents of validated ledgers. # # # # [ips] # # List of hostnames or ips where the XRPL protocol is served. A default # starter list is included in the code and used if no other hostnames are # available. # # One address or domain name per line is allowed. A port may must be # specified after adding a space to the address. The ordering of entries # does not generally matter. # # The default list of entries is: # - hubs.xahau.as16089.net 21337 # - bacab.alloy.ee 21337 # # Examples: # # [ips] # 192.168.0.1 # 192.168.0.1 21337 # bacab.alloy.ee 21337 # # # [ips_fixed] # # List of IP addresses or hostnames to which xahaud should always attempt to # maintain peer connections with. This is useful for manually forming private # networks, for example to configure a validation server that connects to the # Xahau Network through a public-facing server, or for building a set # of cluster peers. # # One address or domain names per line is allowed. A port must be specified # after adding a space to the address. # # # # [peer_private] # # 0 or 1. # # 0: Request peers to broadcast your address. Normal outbound peer connections [default] # 1: Request peers not broadcast your address. Only connect to configured peers. # # # # [peers_max] # # The largest number of desired peer connections (incoming or outgoing). # Cluster and fixed peers do not count towards this total. There are # implementation-defined lower limits imposed on this value for security # purposes. # # # # [node_seed] # # This is used for clustering. To force a particular node seed or key, the # key can be set here. The format is the same as the validation_seed field. # To obtain a validation seed, use the validation_create command. # # Examples: RASH BUSH MILK LOOK BAD BRIM AVID GAFF BAIT ROT POD LOVE # shfArahZT9Q9ckTf3s1psJ7C7qzVN # # # # [cluster_nodes] # # To extend full trust to other nodes, place their node public keys here. # Generally, you should only do this for nodes under common administration. # Node public keys start with an 'n'. To give a node a name for identification # place a space after the public key and then the name. # # # # [sntp_servers] # # IP address or domain of NTP servers to use for time synchronization. # # These NTP servers are suitable for xahaud servers located in the United # States: # time.windows.com # time.apple.com # time.nist.gov # pool.ntp.org # # # # [max_transactions] # # Configure the maximum number of transactions to have in the job queue # # Must be a number between 100 and 1000, defaults to 250 # # # [overlay] # # Controls settings related to the peer to peer overlay. # # A set of key/value pair parameters to configure the overlay. # # public_ip = # # If the server has a known, fixed public IPv4 address, # specify that IP address here in dotted decimal notation. # Peers will use this information to reject attempt to proxy # connections to or from this server. # # ip_limit = # # The maximum number of incoming peer connections allowed by a single # IP that isn't classified as "private" in RFC1918. The implementation # imposes some hard and soft upper limits on this value to prevent a # single host from consuming all inbound slots. If the value is not # present the server will autoconfigure an appropriate limit. # # max_unknown_time = # # The maximum amount of time, in seconds, that an outbound connection # is allowed to stay in the "unknown" tracking state. This option can # take any value between 300 and 1800 seconds, inclusive. If the option # is not present the server will autoconfigure an appropriate limit. # # The current default (which is subject to change) is 600 seconds. # # max_diverged_time = # # The maximum amount of time, in seconds, that an outbound connection # is allowed to stay in the "diverged" tracking state. The option can # take any value between 60 and 900 seconds, inclusive. If the option # is not present the server will autoconfigure an appropriate limit. # # The current default (which is subject to change) is 300 seconds. # # # [transaction_queue] EXPERIMENTAL # # This section is EXPERIMENTAL, and should not be # present for production configuration settings. # # A set of key/value pair parameters to tune the performance of the # transaction queue. # # ledgers_in_queue = # # The queue will be limited to this of average ledgers' # worth of transactions. If the queue fills up, the transactions # with the lowest fee levels will be dropped from the queue any # time a transaction with a higher fee level is added. # Default: 20. # # minimum_queue_size = # # The queue will always be able to hold at least this of # transactions, regardless of recent ledger sizes or the value of # ledgers_in_queue. Default: 2000. # # retry_sequence_percent = # # If a client replaces a transaction in the queue (same sequence # number as a transaction already in the queue), the new # transaction's fee must be more than percent higher # than the original transaction's fee, or meet the current open # ledger fee to be considered. Default: 25. # # minimum_escalation_multiplier = # # At ledger close time, the median fee level of the transactions # in that ledger is used as a multiplier in escalation # calculations of the next ledger. This minimum value ensures that # the escalation is significant. Default: 500. # # minimum_txn_in_ledger = # # Minimum number of transactions that must be allowed into the # ledger at the minimum required fee before the required fee # escalates. Default: 5. # # minimum_txn_in_ledger_standalone = # # Like minimum_txn_in_ledger when xahaud is running in standalone # mode. Default: 1000. # # target_txn_in_ledger = # # Number of transactions allowed into the ledger at the minimum # required fee that the queue will "work toward" as long as # consensus stays healthy. The limit will grow quickly until it # reaches or exceeds this number. After that the limit may still # change, but will stay above the target. If consensus is not # healthy, the limit will be clamped to this value or lower. # Default: 50. # # maximum_txn_in_ledger = # # (Optional) Maximum number of transactions that will be allowed # into the ledger at the minimum required fee before the required # fee escalates. Default: no maximum. # # normal_consensus_increase_percent = # # (Optional) When the ledger has more transactions than "expected", # and performance is humming along nicely, the expected ledger size # is updated to the previous ledger size plus this percentage. # Default: 20 # # slow_consensus_decrease_percent = # # (Optional) When consensus takes longer than appropriate, the # expected ledger size is updated to the minimum of the previous # ledger size or the "expected" ledger size minus this percentage. # Default: 50 # # maximum_txn_per_account = # # Maximum number of transactions that one account can have in the # queue at any given time. Default: 10. # # minimum_last_ledger_buffer = # # If a transaction has a LastLedgerSequence, it must be at least # this much larger than the current open ledger sequence number. # Default: 2. # # zero_basefee_transaction_feelevel = # # So we don't deal with infinite fee levels, treat any transaction # with a 0 base fee (ie. SetRegularKey password recovery) as # having this fee level. # Default: 256000. # # #------------------------------------------------------------------------------- # # 3. Protocol # #------------------- # # These settings affect the behavior of the server instance with respect # to protocol level activities such as validating and closing ledgers # adjusting fees in response to server overloads. # # # # # [relay_proposals] # # Controls the relay and processing behavior for proposals received by this # server that are issued by validators that are not on the server's UNL. # # Legal values are: # "all" - Relay and process all incoming proposals # "trusted" - Relay only trusted proposals, but locally process all # "drop_untrusted" - Relay only trusted proposals, do not process untrusted # # The default is "trusted". # # # [relay_validations] # # Controls the relay and processing behavior for validations received by this # server that are issued by validators that are not on the server's UNL. # # Legal values are: # "all" - Relay and process all incoming validations # "trusted" - Relay only trusted validations, but locally process all # "drop_untrusted" - Relay only trusted validations, do not process untrusted # # The default is "all". # # # # # # [ledger_history] # # The number of past ledgers to acquire on server startup and the minimum to # maintain while running. # # To serve clients, servers need historical ledger data. Servers that don't # need to serve clients can set this to "none". Servers that want complete # history can set this to "full". # # This must be less than or equal to online_delete (if online_delete is used) # # The default is: 256 # # # # [fetch_depth] # # The number of past ledgers to serve to other peers that request historical # ledger data (or "full" for no limit). # # Servers that require low latency and high local performance may wish to # restrict the historical ledgers they are willing to serve. Setting this # below 32 can harm network stability as servers require easy access to # recent history to stay in sync. Values below 128 are not recommended. # # The default is: full # # # # [validation_seed] # # To perform validation, this section should contain either a validation seed # or key. The validation seed is used to generate the validation # public/private key pair. To obtain a validation seed, use the # validation_create command. # # Examples: RASH BUSH MILK LOOK BAD BRIM AVID GAFF BAIT ROT POD LOVE # shfArahZT9Q9ckTf3s1psJ7C7qzVN # # # # [validator_token] # # This is an alternative to [validation_seed] that allows xahaud to perform # validation without having to store the validator keys on the network # connected server. The field should contain a single token in the form of a # base64-encoded blob. # An external tool is available for generating validator keys and tokens. # # # # [validator_key_revocation] # # If a validator's secret key has been compromised, a revocation must be # generated and added to this field. The revocation notifies peers that it is # no longer safe to trust the revoked key. The field should contain a single # revocation in the form of a base64-encoded blob. # An external tool is available for generating and revoking validator keys. # # # # [validators_file] # # Path or name of a file that determines the nodes to always accept as validators. # # The contents of the file should include a [validators] and/or # [validator_list_sites] and [validator_list_keys] entries. # [validators] should be followed by a list of validation public keys of # nodes, one per line. # [validator_list_sites] should be followed by a list of URIs each serving a # list of recommended validators. # [validator_list_keys] should be followed by a list of keys belonging to # trusted validator list publishers. Validator lists fetched from configured # sites will only be considered if the list is accompanied by a valid # signature from a trusted publisher key. # # Specify the file by its name or path. # Unless an absolute path is specified, it will be considered relative to # the folder in which the xahaud.cfg file is located. # # Examples: # /home/xahaud/validators.txt # C:/home/xahaud/validators.txt # # Example content: # [validators] # n9L3GdotB8a3AqtsvS7NXt4BUTQSAYyJUr9xtFj2qXJjfbZsawKY # n9LQDHLWyFuAn5BXJuW2ow5J9uGqpmSjRYS2cFRpxf6uJbxwDzvM # n9MCWyKVUkiatXVJTKUrAESB5kBFP8R3hm43jGHtg8WBnjv3iDfb # n9KWXCLRhjpajuZtULTXsy6R5xbisA6ozGxM4zdEJFq6uHiFZDvW # # # # [path_search] # When searching for paths, the default search aggressiveness. This can take # exponentially more resources as the size is increased. # # The recommended value to support advanced pathfinding is: 7 # # The default is: 2 # # [path_search_fast] # [path_search_max] # When searching for paths, the minimum and maximum search aggressiveness. # # If you do not need pathfinding, you can set path_search_max to zero to # disable it and avoid some expensive bookkeeping. # # To support advanced pathfinding the recommended value for # 'path_search_fast' is 2, and for 'path_search_max' is 10. # # The default for 'path_search_fast' is 2. The default for 'path_search_max' is 3. # # [path_search_old] # # For clients that use the legacy path finding interfaces, the search # aggressiveness to use. # # The recommended value to support advanced pathfinding is: 7. # # The default is: 2 # # # # [fee_default] # # Sets the base cost of a transaction in drops. Used when the server has # no other source of fee information, such as signing transactions offline. # # # # [workers] # # Configures the number of threads for processing work submitted by peers # and clients. If not specified, then the value is automatically set to the # number of processor threads plus 2 for networked nodes. Nodes running in # stand alone mode default to 1 worker. # # [io_workers] # # Configures the number of threads for processing raw inbound and outbound IO. # # [prefetch_workers] # # Configures the number of threads for performing nodestore prefetching. # # # # [network_id] # # Specify the network which this server is configured to connect to and # track. If set, the server will not establish connections with servers # that are explicitly configured to track another network. # # Network identifiers are usually unsigned integers in the range 0 to # 4294967295 inclusive. The server also maps the following well-known # names to the corresponding numerical identifier: # # main -> 0 # testnet -> 1 # devnet -> 2 # # If this value is not specified the server is not explicitly configured # to track a particular network. # # # [ledger_replay] # # 0 or 1. # # 0: Disable the ledger replay feature [default] # 1: Enable the ledger replay feature. With this feature enabled, when # acquiring a ledger from the network, a xahaud node only downloads # the ledger header and the transactions instead of the whole ledger. # And the ledger is built by applying the transactions to the parent # ledger. # #------------------------------------------------------------------------------- # # 4. HTTPS Client # #---------------- # # The xahaud server instance uses HTTPS GET requests in a variety of # circumstances, including but not limited to contacting trusted domains to # fetch information such as mapping an email address to a user's r address. # # [ssl_verify] # # 0 or 1. # # 0. HTTPS client connections will not verify certificates. # 1. Certificates will be checked for HTTPS client connections. # # If not specified, this parameter defaults to 1. # # # # [ssl_verify_file] # # # # A file system path leading to the certificate verification file for # HTTPS client requests. # # # # [ssl_verify_dir] # # # # # A file system path leading to a file or directory containing the root # certificates that the server will accept for verifying HTTP servers. # Used only for outbound HTTPS client connections. # #------------------------------------------------------------------------------- # # 5. Reporting Mode # #------------ # # xahaud has an optional operating mode called Reporting Mode. In Reporting # Mode, xahaud does not connect to the peer to peer network. Instead, xahaud # will continuously extract data from one or more xahaud servers that are # connected to the peer to peer network (referred to as an ETL source). # Reporting mode servers will forward RPC requests that require access to the # peer to peer network (submit, fee, etc) to an ETL source. # # [reporting] Settings for Reporting Mode. If and only if this section is # present, xahaud will start in reporting mode. This section # contains a list of ETL source names, and key-value pairs. The # ETL source names each correspond to a configuration file # section; the names must match exactly. The key-value pairs are # optional. # # # [] # # A series of key/value pairs that specify an ETL source. # # source_ip = # # Required. IP address of the ETL source. Can also be a DNS record. # # source_ws_port = # # Required. Port on which ETL source is accepting unencrypted websocket # connections. # # source_grpc_port = # # Required for ETL. Port on which ETL source is accepting gRPC requests. # If this option is ommitted, this ETL source cannot actually be used for # ETL; the Reporting Mode server can still forward RPCs to this ETL # source, but cannot extract data from this ETL source. # # # Key-value pairs (all optional): # # read_only Valid values: 0, 1. Default is 0. If set to 1, the server # will start in strict read-only mode, and will not perform # ETL. The server will still handle RPC requests, and will # still forward RPC requests that require access to the p2p # network. # # start_sequence # Sequence of first ledger to extract if the database is empty. # ETL extracts ledgers in order. If this setting is absent and # the database is empty, ETL will start with the next ledger # validated by the network. If this setting is present and the # database is not empty, an exception is thrown. # # num_markers Degree of parallelism used during the initial ledger # download. Only used if the database is empty. Valid values # are 1-256. A higher degree of parallelism results in a # faster download, but puts more load on the ETL source. # Default is 2. # # Example: # # [reporting] # etl_source1 # etl_source2 # read_only=0 # start_sequence=32570 # num_markers=8 # # [etl_source1] # source_ip=1.2.3.4 # source_ws_port=6005 # source_grpc_port=50051 # # [etl_source2] # source_ip=5.6.7.8 # source_ws_port=6005 # source_grpc_port=50051 # # Minimal Example: # # [reporting] # etl_source1 # # [etl_source1] # source_ip=1.2.3.4 # source_ws_port=6005 # source_grpc_port=50051 # # # Notes: # # Reporting Mode requires Postgres (instead of SQLite). The Postgres # connection info is specified under the [ledger_tx_tables] config section; # see the Database section for further documentation. # # Each ETL source specified must have gRPC enabled (by adding a [port_grpc] # section to the config). It is recommended to add a secure_gateway entry to # the gRPC section, in order to bypass the server's rate limiting. # This section needs to be added to the config of the ETL source, not # the config of the reporting node. In the example below, the # reporting server is running at 127.0.0.1. Multiple IPs can be # specified in secure_gateway via a comma separated list. # # [port_grpc] # ip = 0.0.0.0 # port = 50051 # secure_gateway = 127.0.0.1 # # #------------------------------------------------------------------------------- # # 6. Database # #------------ # # xahaud creates 4 SQLite database to hold bookkeeping information # about transactions, local credentials, and various other things. # It also creates the NodeDB, which holds all the objects that # make up the current and historical ledgers. In Reporting Mode, xahauad # uses a Postgres database instead of SQLite. # # The simplest way to work with Postgres is to install it locally. # When it is running, execute the initdb.sh script in the current # directory as: sudo -u postgres ./initdb.sh # This will create the xahaud user and an empty database of the same name. # # The size of the NodeDB grows in proportion to the amount of new data and the # amount of historical data (a configurable setting) so the performance of the # underlying storage media where the NodeDB is placed can significantly affect # the performance of the server. # # Partial pathnames will be considered relative to the location of # the xahaud.cfg file. # # [node_db] Settings for the Node Database (required) # # Format (without spaces): # One or more lines of case-insensitive key / value pairs: # '=' # ... # # Example: # type=nudb # path=/opt/xahaud/db/nudb # # The "type" field must be present and controls the choice of backend: # # type = NuDB # # NuDB is a high-performance database written by Ripple Labs and optimized # for and solid-state drives. # # NuDB maintains its high speed regardless of the amount of history # stored. Online delete may be selected, but is not required. NuDB is # available on all platforms that xahaud runs on. # # type = RocksDB # # RocksDB is an open-source, general-purpose key/value store - see # http://rocksdb.org/ for more details. # # RocksDB is an alternative backend for systems that don't use solid-state # drives. Because RocksDB's performance degrades as it stores more data, # keeping full history is not advised, and using online delete is # recommended. # # type = Cassandra # # Apache Cassandra is an open-source, distributed key-value store - see # https://cassandra.apache.org/ for more details. # # Cassandra is an alternative backend to be used only with Reporting Mode. # See the Reporting Mode section for more details about Reporting Mode. # # type = RWDB # # RWDB is a high-performance memory store written by XRPL-Labs and optimized # for xahaud. RWDB is NOT persistent and the data will be lost on restart. # RWDB is recommended for Validator and Peer nodes that are not required to # store history. # # Required keys for NuDB and RocksDB: # # path Location to store the database # # Required keys for RWDB: # # online_delete Required. RWDB stores data in memory and will # grow unbounded without online_delete. See the # online_delete section below. # # Required keys for Cassandra: # # contact_points IP of a node in the Cassandra cluster # # port CQL Native Transport Port # # secure_connect_bundle # Absolute path to a secure connect bundle. When using # a secure connect bundle, contact_points and port are # not required. # # keyspace Name of Cassandra keyspace to use # # table_name Name of table in above keyspace to use # # Optional keys # # cache_size Size of cache for database records. Default is 16384. # Setting this value to 0 will use the default value. # # cache_age Length of time in minutes to keep database records # cached. Default is 5 minutes. Setting this value to # 0 will use the default value. # # Note: if neither cache_size nor cache_age is # specified, the cache for database records will not # be created. If only one of cache_size or cache_age # is specified, the cache will be created using the # default value for the unspecified parameter. # # Note: the cache will not be created if online_delete # is specified, or if shards are used. # # fast_load Boolean. If set, load the last persisted ledger # from disk upon process start before syncing to # the network. This is likely to improve performance # if sufficient IOPS capacity is available. # Default 0. # # online_delete for RWDB, NuDB and RocksDB: # # online_delete Minimum value of 256. Enable automatic purging # of older ledger information. Maintain at least this # number of ledger records online. Must be greater # than or equal to ledger_history. # # REQUIRED for RWDB to prevent out-of-memory errors. # Optional for NuDB and RocksDB. # # Optional keys for NuDB and RocksDB: # # earliest_seq The default is 32570 to match the XRP Ledger's # network's earliest allowed sequence. Alternate # networks may set this value. Minimum value of 1. # If a [shard_db] section is defined, and this # value is present either [node_db] or [shard_db], # it must be defined with the same value in both # sections. # # Optional keys for NuDB only: # # nudb_block_size EXPERIMENTAL: Block size in bytes for NuDB storage. # Must be a power of 2 between 4096 and 32768. Default is 4096. # # This parameter controls the fundamental storage unit # size for NuDB's internal data structures. The choice # of block size can significantly impact performance # depending on your storage hardware and filesystem: # # - 4096 bytes: Optimal for most standard SSDs and # traditional filesystems (ext4, NTFS, HFS+). # Provides good balance of performance and storage # efficiency. Recommended for most deployments. # # - 8192-16384 bytes: May improve performance on # high-end NVMe SSDs and copy-on-write filesystems # like ZFS or Btrfs that benefit from larger block # alignment. Can reduce metadata overhead for large # databases. # # - 32768 bytes (32K): Maximum supported block size # for high-performance scenarios with very fast # storage. May increase memory usage and reduce # efficiency for smaller databases. # # Note: This setting cannot be changed after database # creation without rebuilding the entire database. # Choose carefully based on your hardware and expected # database size. # # Example: nudb_block_size=4096 # # These keys modify the behavior of online_delete, and thus are only # relevant if online_delete is defined and non-zero: # # advisory_delete 0 for disabled, 1 for enabled. If set, the # administrative RPC call "can_delete" is required # to enable online deletion of ledger records. # Online deletion does not run automatically if # non-zero and the last deletion was on a ledger # greater than the current "can_delete" setting. # Default is 0. # # delete_batch When automatically purging, SQLite database # records are deleted in batches. This value # controls the maximum size of each batch. Larger # batches keep the databases locked for more time, # which may cause other functions to fall behind, # and thus cause the node to lose sync. # Default is 100. # # back_off_milliseconds # Number of milliseconds to wait between # online_delete batches to allow other functions # to catch up. # Default is 100. # # age_threshold_seconds # The online delete process will only run if the # latest validated ledger is younger than this # number of seconds. # Default is 60. # # recovery_wait_seconds # The online delete process checks periodically # that xahaud is still in sync with the network, # and that the validated ledger is less than # 'age_threshold_seconds' old. If not, then continue # sleeping for this number of seconds and # checking until healthy. # Default is 5. # # Optional keys for Cassandra: # # username Username to use if Cassandra cluster requires # authentication # # password Password to use if Cassandra cluster requires # authentication # # max_requests_outstanding # Limits the maximum number of concurrent database # writes. Default is 10 million. For slower clusters, # large numbers of concurrent writes can overload the # cluster. Setting this option can help eliminate # write timeouts and other write errors due to the # cluster being overloaded. # io_threads # Set the number of IO threads used by the # Cassandra driver. Defaults to 4. # # Notes: # The 'node_db' entry configures the primary, persistent storage. # # The 'import_db' is used with the '--import' command line option to # migrate the specified database into the current database given # in the [node_db] section. # # [import_db] Settings for performing a one-time import (optional) # [database_path] Path to the book-keeping databases. # # The server creates and maintains 4 to 5 bookkeeping SQLite databases in # the 'database_path' location. If you omit this configuration setting, # the server creates a directory called "db" located in the same place as # your xahaud.cfg file. # Partial pathnames are relative to the location of the xahaud executable. # # [shard_db] Settings for the Shard Database (optional) # # Format (without spaces): # One or more lines of case-insensitive key / value pairs: # '=' # ... # # Example: # path=db/shards/nudb # # Required keys: # path Location to store the database # # Optional keys: # max_historical_shards # The maximum number of historical shards # to store. # # [historical_shard_paths] Additional storage paths for the Shard Database (optional) # # Format (without spaces): # One or more lines, each expressing a full path for storing historical shards: # /mnt/disk1 # /mnt/disk2 # ... # # [sqlite] Tuning settings for the SQLite databases (optional) # # Format (without spaces): # One or more lines of case-insensitive key / value pairs: # '=' # ... # # Example 1: # safety_level=low # # Example 2: # journal_mode=off # synchronous=off # # WARNING: These settings can have significant effects on data integrity, # particularly in systemic failure scenarios. It is strongly recommended # that they be left at their defaults unless the server is having # performance issues during normal operation or during automatic purging # (online_delete) operations. A warning will be logged on startup if # 'ledger_history' is configured to store more than 10,000,000 ledgers and # any of these settings are less safe than the default. This is due to the # inordinate amount of time and bandwidth it will take to safely rebuild a # corrupted database of that size from other peers. # # Optional keys: # # safety_level Valid values: high, low # The default is "high", which tunes the SQLite # databases in the most reliable mode, and is # equivalent to: # journal_mode=wal # synchronous=normal # temp_store=file # "low" is equivalent to: # journal_mode=memory # synchronous=off # temp_store=memory # These "low" settings trade speed and reduced I/O # for a higher risk of data loss. See the # individual settings below for more information. # This setting may not be combined with any of the # other tuning settings: "journal_mode", # "synchronous", or "temp_store". # # journal_mode Valid values: delete, truncate, persist, memory, wal, off # The default is "wal", which uses a write-ahead # log to implement database transactions. # Alternately, "memory" saves disk I/O, but if # xahaud crashes during a transaction, the # database is likely to be corrupted. # See https://www.sqlite.org/pragma.html#pragma_journal_mode # for more details about the available options. # This setting may not be combined with the # "safety_level" setting. # # synchronous Valid values: off, normal, full, extra # The default is "normal", which works well with # the "wal" journal mode. Alternatively, "off" # allows xahaud to continue as soon as data is # passed to the OS, which can significantly # increase speed, but risks data corruption if # the host computer crashes before writing that # data to disk. # See https://www.sqlite.org/pragma.html#pragma_synchronous # for more details about the available options. # This setting may not be combined with the # "safety_level" setting. # # temp_store Valid values: default, file, memory # The default is "file", which will use files # for temporary database tables and indices. # Alternatively, "memory" may save I/O, but # xahaud does not currently use many, if any, # of these temporary objects. # See https://www.sqlite.org/pragma.html#pragma_temp_store # for more details about the available options. # This setting may not be combined with the # "safety_level" setting. # # [ledger_tx_tables] (optional) # # conninfo Info for connecting to Postgres. Format is # postgres://[username]:[password]@[ip]/[database]. # The database and user must already exist. If this # section is missing and xahaud is running in # Reporting Mode, xahaud will connect as the # user running xahaud to a database with the # same name. On Linux and Mac OS X, the connection # will take place using the server's UNIX domain # socket. On Windows, through the localhost IP # address. Default is empty. # # use_tx_tables Valid values: 1, 0 # The default is 1 (true). Determines whether to use # the SQLite transaction database. If set to 0, # xahaud will not write to the transaction database, # and will reject tx, account_tx and tx_history RPCs. # In Reporting Mode, this setting is ignored. # # max_connections Valid values: any positive integer up to 64 bit # storage length. This configures the maximum # number of concurrent connections to postgres. # Default is the maximum possible value to # fit in a 64 bit integer. # # timeout Number of seconds after which idle postgres # connections are discconnected. If set to 0, # connections never timeout. Default is 600. # # # remember_ip Value values: 1, 0 # Default is 1 (true). Whether to cache host and # port connection settings. # # #------------------------------------------------------------------------------- # # 7. Diagnostics # #--------------- # # These settings are designed to help server administrators diagnose # problems, and obtain detailed information about the activities being # performed by the xahaud process. # # # # [debug_logfile] # # Specifies where a debug logfile is kept. By default, no debug log is kept. # Unless absolute, the path is relative the directory containing this file. # # Example: debug.log # # # # [insight] # # Configuration parameters for the Beast. Insight stats collection module. # # Insight is a module that collects information from the areas of xahaud # that have instrumentation. The configuration parameters control where the # collection metrics are sent. The parameters are expressed as key = value # pairs with no white space. The main parameter is the choice of server: # # "server" # # Choice of server to send metrics to. Currently the only choice is # "statsd" which sends UDP packets to a StatsD daemon, which must be # running while xahaud is running. More information on StatsD is # available here: # https://github.com/b/statsd_spec # # When server=statsd, these additional keys are used: # # "address" The UDP address and port of the listening StatsD server, # in the format, n.n.n.n:port. # # "prefix" A string prepended to each collected metric. This is used # to distinguish between different running instances of xahaud. # # If this section is missing, or the server type is unspecified or unknown, # statistics are not collected or reported. # # Example: # # [insight] # server=statsd # address=192.168.0.95:4201 # prefix=my_validator # # [perf] # # Configuration of performance logging. If enabled, write Json-formatted # performance-oriented data periodically to a distinct log file. # # "perf_log" A string specifying the pathname of the performance log # file. A relative pathname will log relative to the # configuration directory. Required to enable # performance logging. # # "log_interval" Integer value for number of seconds between writing # to performance log. Default 1. # # Example: # [perf] # perf_log=/var/log/xahaud/perf.log # log_interval=2 # #------------------------------------------------------------------------------- # # 8. Voting # #---------- # # The vote settings configure settings for the entire Xahau Network. # While a single instance of xahaud cannot unilaterally enforce network-wide # settings, these choices become part of the instance's vote during the # consensus process for each voting ledger. # # [voting] # # A set of key/value pair parameters used during voting ledgers. # # reference_fee = # # The cost of the reference transaction fee, specified in drops. # The reference transaction is the simplest form of transaction. # It represents an XAH payment between two parties. # # If this parameter is unspecified, xahaud will use an internal # default. Don't change this without understanding the consequences. # # Example: # reference_fee = 10 # 10 drops # # account_reserve = # # The account reserve requirement is specified in drops. The portion of an # account's XAH balance that is at or below the reserve may only be # spent on transaction fees, and not transferred out of the account. # # If this parameter is unspecified, xahaud will use an internal # default. Don't change this without understanding the consequences. # # Example: # account_reserve = 10000000 # 10 XAH # # owner_reserve = # # The owner reserve is the amount of XAH reserved in the account for # each ledger item owned by the account. Ledger items an account may # own include trust lines, open orders, and tickets. # # If this parameter is unspecified, xahaud will use an internal # default. Don't change this without understanding the consequences. # # Example: # owner_reserve = 2000000 # 2 XAH # #------------------------------------------------------------------------------- # # 9. Misc Settings # #----------------- # # [node_size] # # Tunes the servers based on the expected load and available memory. Legal # sizes are "tiny", "small", "medium", "large", and "huge". We recommend # you start at the default and raise the setting if you have extra memory. # # The code attempts to automatically determine the appropriate size for # this parameter based on the amount of RAM and the number of execution # cores available to the server. The current decision matrix is: # # | | Cores | # |---------|------------------------| # | RAM | 1 | 2 or 3 | ≥ 4 | # |---------|------|--------|--------| # | < ~8GB | tiny | tiny | tiny | # | < ~12GB | tiny | small | small | # | < ~16GB | tiny | small | medium | # | < ~24GB | tiny | small | large | # | < ~32GB | tiny | small | huge | # # [signing_support] # # Specifies whether the server will accept "sign" and "sign_for" commands # from remote users. Even if the commands are sent over a secure protocol # like secure websocket, this should generally be discouraged, because it # requires sending the secret to use for signing to the server. In order # to sign transactions, users should prefer to use a standalone signing # tool instead. # # This flag has no effect on the "sign" and "sign_for" command line options # that xahaud makes available. # # The default value of this field is "false" # # Example: # # [signing_support] # true # # [crawl] # # List of options to control what data is reported through the /crawl endpoint # See https://xrpl.org/peer-crawler.html # # # # Enable or disable access to /crawl requests. Default is '1' which # enables access. # # overlay = # # Report information about peers this server is connected to, similar # to the "peers" RPC API. Default is '1' which means to report peer # overlay info. # # server = # # Report information about the local server, similar to the "server_state" # RPC API. Default is '1' which means to report local server info. # # counts = # # Report information about the local server health counters, similar to # the "get_counts" RPC API. Default is '0' which means not to report # server counts. # # unl = # # Report information about the local server's validator lists, similar to # the "validators" and "validator_list_sites" RPC APIs. Default is '1' # which means to report server validator lists. # # Examples: # # [crawl] # 0 # # [crawl] # overlay = 1 # server = 1 # counts = 0 # unl = 1 # # [vl] # # Options to control what data is reported through the /vl endpoint # See [...] # # enable = # # Enable or disable access to /vl requests. Default is '1' which # enables access. # # [beta_rpc_api] # # 0 or 1. # # 0: Disable the beta API version for JSON-RPC and WebSocket [default] # 1: Enable the beta API version for testing. The beta API version # contains breaking changes that require a new API version number. # They are not ready for public consumption. # #------------------------------------------------------------------------------- # # 10. Example Settings # #-------------------- # # Administrators can use these values as a starting point for configuring # their instance of xahaud, but each value should be checked to make sure # it meets the business requirements for the organization. # # Server # # These example configuration settings create these ports: # # "peer" # # Peer protocol open to everyone. This is required to accept # incoming xahaud connections. This does not affect automatic # or manual outgoing Peer protocol connections. # # "rpc" # # Administrative RPC commands over HTTPS, when originating from # the same machine (via the loopback adapter at 127.0.0.1). # # "wss_admin" # # Admin level API commands over Secure Websockets, when originating # from the same machine (via the loopback adapter at 127.0.0.1). # # This port is commented out but can be enabled by removing # the '#' from each corresponding line including the entry under [server] # # "wss_public" # # Guest level API commands over Secure Websockets, open to everyone. # # For HTTPS and Secure Websockets ports, if no certificate and key file # are specified then a self-signed certificate will be generated on startup. # If you have a certificate and key file, uncomment the corresponding lines # and ensure the paths to the files are correct. # # NOTE # # To accept connections on well known ports such as 80 (HTTP) or # 443 (HTTPS), most operating systems will require xahaud to # run with administrator privileges, or else xahaud will not start. [server] port_rpc_admin_local port_peer port_ws_admin_local #port_ws_public #ssl_key = /etc/ssl/private/server.key #ssl_cert = /etc/ssl/certs/server.crt [port_rpc_admin_local] port = 5009 ip = 127.0.0.1 admin = 127.0.0.1 protocol = http [port_peer] port = 21337 ip = 0.0.0.0 # alternatively, to accept connections on IPv4 + IPv6, use: #ip = :: protocol = peer [port_ws_admin_local] port = 6009 ip = 127.0.0.1 admin = 127.0.0.1 protocol = ws [port_grpc] port = 50051 ip = 127.0.0.1 secure_gateway = 127.0.0.1 #[port_ws_public] #port = 6008 #ip = 127.0.0.1 #protocol = wss #------------------------------------------------------------------------------- # This is primary persistent datastore for xahaud. This includes transaction # metadata, account states, and ledger headers. Helpful information can be # found at https://xahau.network/docs/infrastructure/system-requirements # type=NuDB is recommended for non-validators with fast SSDs. Validators or # slow / spinning disks should use RocksDB. Caution: Spinning disks are # not recommended. They do not perform well enough to consistently remain # synced to the network. # online_delete=512 is recommended to delete old ledgers while maintaining at # least 512. # advisory_delete=0 allows the online delete process to run automatically # when the node has approximately two times the "online_delete" value of # ledgers. No external administrative command is required to initiate # deletion. [node_db] type=NuDB path=/opt/xahaud/db/nudb online_delete=512 advisory_delete=0 # This is the persistent datastore for shards. It is important for the health # of the Xahau Network that xahaud operators shard as much as practical. # NuDB requires SSD storage. Helpful information can be found at # https://xrpl.org/history-sharding.html #[shard_db] #path=/opt/xahaud/db/shards/nudb #max_historical_shards=50 # # This optional section can be configured with a list # of paths to use for storing historical shards. Each # path must correspond to a unique filesystem. #[historical_shard_paths] #/path/1 #/path/2 [database_path] /opt/xahaud/db # To use Postgres, uncomment this section and fill in the appropriate connection # info. Postgres can only be used in Reporting Mode. # To disable writing to the transaction database, uncomment this section, and # set use_tx_tables=0 # [ledger_tx_tables] # conninfo = postgres://[username]:[password]@[ip]/[database] # use_tx_tables=1 # This needs to be an absolute directory reference, not a relative one. # Modify this value as required. [debug_logfile] /var/log/xahaud/debug.log [sntp_servers] time.windows.com time.apple.com time.nist.gov pool.ntp.org # To use the Xahau Test Network # (see https://xahau.network/docs/infrastructure/installing-xahaud), # use the following [ips] section: # [ips] # 79.110.60.121 21338 # 79.110.60.122 21338 # 79.110.60.124 21338 # 79.110.60.125 21338 # File containing trusted validator keys or validator list publishers. # Unless an absolute path is specified, it will be considered relative to the # folder in which the xahaud.cfg file is located. [validators_file] validators-xahau.txt # Turn down default logging to save disk space in the long run. # Valid values here are trace, debug, info, warning, error, and fatal [rpc_startup] { "command": "log_level", "severity": "warning" } # If ssl_verify is 1, certificates will be validated. # To allow the use of self-signed certificates for development or internal use, # set to ssl_verify to 0. [ssl_verify] 1 # To run in Reporting Mode, uncomment this section and fill in the appropriate # connection info for one or more ETL sources. # [reporting] # etl_source # # # [etl_source] # source_grpc_port=50051 # source_ws_port=6005 # source_ip=127.0.0.1