#------------------------------------------------------------------------------- # # #------------------------------------------------------------------------------- # # Contents # # 1. Server # # 2. Peer Protocol # # 3. Ripple Protocol # # 4. HTTPS Client # # 5. # # 6. Database # # 7. Diagnostics # # 8. Voting # # 9. Misc Settings # # 10. Example Settings # #------------------------------------------------------------------------------- # # Purpose # # This file documents and provides examples of all rippled server process # configuration options. When the rippled server instance is launched, it # looks for a file with the following name: # # rippled.cfg # # For more information on where the rippled server instance searches for the # file, visit: # # https://xrpl.org/commandline-usage.html#generic-options # # This file should be named rippled.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 # #---------- # # # # rippled offers various server protocols to clients making inbound # connections. The listening ports rippled 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, rippled 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 rippled 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, rippled 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, rippled 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, rippled 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 rippled 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, # rippled 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. Use ssl_chain if # your certificate includes one or more intermediates. # # ssl_chain # # If you need a certificate chain, specify the path to the # certificate chain here. The chain may include the end certificate. # This must be used if the certificate includes intermediates. # # 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, rippled 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 rippled from connecting to other instances of rippled 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" : "ripplecalc", "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 rippled process. Peer Protocol implements the # Ripple Payment protocol. It is over peer connections that transactions # and validations are passed from to machine to machine, to determine the # contents of validated ledgers. # # # # [compression] # # true or false # # true - enables compression # false - disables compression [default]. # # The rippled server can save bandwidth by compressing its peer-to-peer communications, # at a cost of greater CPU usage. If you enable link compression, # the server automatically compresses communications with peer servers # that also have link compression enabled. # https://xrpl.org/enable-link-compression.html # # # # [ips] # # List of hostnames or ips where the Ripple 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 be specified # after adding a space to the address. If a port is not specified, the default # port of 2459 will be used. Many servers still use the legacy port of 51235. # To connect to such servers, you must specify the port number. The ordering # of entries does not generally matter. # # The default list of entries is: # - r.ripple.com 51235 # - sahyadri.isrdc.in 51235 # - hubs.xrpkuwait.com 51235 # - hub.xrpl-commons.org 51235 # # Examples: # # [ips] # 192.168.0.1 # 192.168.0.1 2459 # r.ripple.com 51235 # # # [ips_fixed] # # List of IP addresses or hostnames to which rippled 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 # Ripple 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. # # # # [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 rippled 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 rippled 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 rippled.cfg file is located. # # Examples: # /home/ripple/validators.txt # C:/home/ripple/validators.txt # # Example content: # [validators] # n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7 # n9MD5h24qrQqiyBC8aeqqCWvpiBiYQ3jxSr91uiDvmrkyHRdYLUj # n9L81uNCaPgtUJfaHh89gmdvXKAmSt5Gdsw2g1iPWaPkAHW5Nm4C # n9KiYM9CgngLvtRCQHZwgC2gjpdaZcCcbt3VboxiNFcKuwFVujzS # n9LdgEtkmGB9E2h3K4Vp7iGUaKuq23Zr32ehxiU8FWY7xoxbWTSA # # # # [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 rippled 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 rippled 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 Ripple Payment # Network 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. # #------------------------------------------------------------------------------- # # 6. Database # #------------ # # rippled 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. # # 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 rippled.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=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 rippled 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 rippled 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. # # Required keys for NuDB and RocksDB: # # path Location to store the database # # 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. # # 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. # # Optional keys for NuDB or RocksDB: # # earliest_seq The default is 32570 to match the XRP ledger # network's earliest allowed sequence. Alternate # networks may set this value. Minimum value of 1. # # 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. # # 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. # Minimizes memory footprint and provides consistent # low-latency access patterns across diverse hardware. # # - 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. Offers better sequential throughput and # reduced I/O operations at the cost of higher memory # usage per operation. # # - 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. Best suited for # enterprise environments with abundant RAM. # # Performance testing is recommended before deploying # any non-default block size in production environments. # # 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 rippled 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. # # 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 rippled.cfg file. # Partial pathnames are relative to the location of the rippled executable. # # [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 # rippled 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 rippled 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 # rippled 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. # # page_size Valid values: integer (MUST be power of 2 between 512 and 65536) # The default is 4096 bytes. This setting determines # the size of a page in the transaction.db file. # See https://www.sqlite.org/pragma.html#pragma_page_size # for more details about the available options. # # journal_size_limit Valid values: integer # The default is 1582080. This setting limits # the size of the journal for transaction.db file. When the limit is # reached, older entries will be deleted. # See https://www.sqlite.org/pragma.html#pragma_journal_size_limit # for more details about the available options. # # #------------------------------------------------------------------------------- # # 7. Diagnostics # #--------------- # # These settings are designed to help server administrators diagnose # problems, and obtain detailed information about the activities being # performed by the rippled 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 rippled # 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 rippled 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 rippled. # # 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/rippled/perf.log # log_interval=2 # #------------------------------------------------------------------------------- # # 8. Voting # #---------- # # The vote settings configure settings for the entire Ripple network. # While a single instance of rippled 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 XRP payment between two parties. # # If this parameter is unspecified, rippled 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 XRP 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, rippled will use an internal # default. Don't change this without understanding the consequences. # # Example: # account_reserve = 10000000 # 10 XRP # # owner_reserve = # # The owner reserve is the amount of XRP 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, rippled will use an internal # default. Don't change this without understanding the consequences. # # Example: # owner_reserve = 2000000 # 2 XRP # # extension_compute_limit = # # The extension compute limit is the maximum amount of gas that can be # consumed by a single transaction. The gas limit is used to prevent # transactions from consuming too many resources. # # If this parameter is unspecified, rippled will use an internal # default. Don't change this without understanding the consequences. # # Example: # extension_compute_limit = 1000000 # 1 million gas # # extension_size_limit = # # The extension size limit is the maximum size of a WASM extension in # bytes. The size limit is used to prevent extensions from consuming # too many resources. # # If this parameter is unspecified, rippled will use an internal # default. Don't change this without understanding the consequences. # # Example: # extension_size_limit = 100000 # 100 kb # # gas_price = # # The gas price is the conversion between WASM gas and its price in drops. # # If this parameter is unspecified, rippled will use an internal # default. Don't change this without understanding the consequences. # # Example: # gas_price = 1000000 # 1 drop per gas #------------------------------------------------------------------------------- # # 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 rippled 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 rippled, 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 rippled 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). # # "grpc" # # ETL commands for Clio. We recommend setting secure_gateway # in this section to a comma-separated list of the addresses # of your Clio servers, in order to bypass rippled's rate limiting. # # 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 rippled to # run with administrator privileges, or else rippled 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 = 5005 ip = 127.0.0.1 admin = 127.0.0.1 protocol = http [port_peer] # Many servers still use the legacy port of 51235, so for backward-compatibility # we maintain that port number here. However, for new servers we recommend # changing this to the default port of 2459. port = 51235 ip = 0.0.0.0 # alternatively, to accept connections on IPv4 + IPv6, use: #ip = :: protocol = peer [port_ws_admin_local] port = 6006 ip = 127.0.0.1 admin = 127.0.0.1 protocol = ws send_queue_limit = 500 [port_grpc] port = 50051 ip = 127.0.0.1 secure_gateway = 127.0.0.1 #[port_ws_public] #port = 6005 #ip = 127.0.0.1 #protocol = wss #send_queue_limit = 500 #------------------------------------------------------------------------------- # This is primary persistent datastore for rippled. This includes transaction # metadata, account states, and ledger headers. Helpful information can be # found at https://xrpl.org/capacity-planning.html#node-db-type # 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=/var/lib/rippled/db/nudb nudb_block_size=4096 online_delete=512 advisory_delete=0 [database_path] /var/lib/rippled/db # This needs to be an absolute directory reference, not a relative one. # Modify this value as required. [debug_logfile] /var/log/rippled/debug.log # To use the XRP test network # (see https://xrpl.org/connect-your-rippled-to-the-xrp-test-net.html), # use the following [ips] section: # [ips] # r.altnet.rippletest.net 51235 # 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 rippled.cfg file is located. [validators_file] validators.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