#------------------------------------------------------------------------------- # # Rippled Server Instance Configuration Example # #------------------------------------------------------------------------------- # # Contents # # 1. Server # # 2. Peer Protocol # # 3. Ripple Protocol # # 4. HTTPS Client # # 5. Database # # 6. Diagnostics # # 7. Voting # # 8. 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 please visit the Ripple wiki. Specifically, the section explaining # the --conf command line option: # # https://ripple.com/wiki/Rippled#--conf.3Dpath # # 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. # Parenthesis 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 interfaces, uses 0.0.0.0 # # 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. # # 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. # # When set, grants administrative command access to the specified IP # addresses. These commands may be issued over http, https, ws, or wss # if configured on the port. If unspecified, the default is to not allow # administrative commands. # # *SECURITY WARNING* # 0.0.0.0 may be specified 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. # # When set, allows the specified IP 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. # # The same IP address cannot be used in both "admin" and "secure_gateway" # lists for the same port. In this case, rippled will abort with an error # message to the console shortly after startup # # 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. # # 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, 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. # # # # [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. # # # #------------------------------------------------------------------------------- # # 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. # # # # [ips] # # List of hostnames or ips where the Ripple protocol is served. For a starter # list, you can either copy entries from: https://ripple.com/ripple.txt or if # you prefer you can specify r.ripple.com 51235 # # One IPv4 address or domain names per line is allowed. A port may must be # specified after adding a space to the address. By convention, if known, # IPs are listed in from most to least trusted. # # Examples: # 192.168.0.1 # 192.168.0.1 3939 # r.ripple.com 51235 # # This will give you a good, up-to-date list of addresses: # # [ips] # r.ripple.com 51235 # # The default is: [ips_fixed] addresses (if present) or 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 IPv4 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 rippled servers located in the United # States: # time.windows.com # time.apple.com # time.nist.gov # pool.ntp.org # # # # [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. # # # # [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. # # 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. # # multi_txn_percent = # # If a client submits multiple transactions (different sequence # numbers), later transactions must pay a fee at least # percent higher than the transaction with the previous sequence # number. # Default: -90. # # 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. # # 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. Ripple Protocol # #------------------- # # These settings affect the behavior of the server instance with respect # to Ripple payment protocol level activities such as validating and # closing ledgers, establishing a quorum, or adjusting fees in response # to server overloads. # # # # [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 default is "tiny". # # # # [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 # # # # [validators_file] # # Path or name of a file that contains the validation public keys of nodes # to always accept as validators as well as the minimum number of validators # needed to accept consensus. # # The contents of the file should include a [validators] and a # [validation_quorum] entry. [validators] should be followed by # a list of validation public keys of nodes, one per line, optionally # followed by a comment separated by whitespace. # [validation_quorum] should be followed by a number. # # 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 RL1 # n9MD5h24qrQqiyBC8aeqqCWvpiBiYQ3jxSr91uiDvmrkyHRdYLUj RL2 # n9L81uNCaPgtUJfaHh89gmdvXKAmSt5Gdsw2g1iPWaPkAHW5Nm4C RL3 # n9KiYM9CgngLvtRCQHZwgC2gjpdaZcCcbt3VboxiNFcKuwFVujzS RL4 # n9LdgEtkmGB9E2h3K4Vp7iGUaKuq23Zr32ehxiU8FWY7xoxbWTSA RL5 # # [validation_quorum] # 3 # # # [path_search] # When searching for paths, the default search aggressiveness. This can take # exponentially more resources as the size is increased. # # The default is: 7 # # [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. # # The default for 'path_search_fast' is 2. The default for 'path_search_max' is 10. # # [path_search_old] # # For clients that use the legacy path finding interfaces, the search # aggressiveness to use. The default is 7. # # # # [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. # # # #------------------------------------------------------------------------------- # # 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. # # # #------------------------------------------------------------------------------- # # 5. 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. RocksDB is not available on Windows. # # The RocksDB backend also provides these optional parameters: # # compression 0 for none, 1 for Snappy compression # # # # Required keys: # path Location to store the database (all types) # # Optional keys: # # These keys are possible for any type of backend: # # 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. # # advisory_delete 0 for disabled, 1 for enabled. If set, then # require administrative RPC call "can_delete" # to enable online deletion of ledger records. # # 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. # # There are 4 bookkeeping SQLite database that the server creates and # maintains. If you omit this configuration setting, it will default to # creating a directory called "db" located in the same place as your # rippled.cfg file. Partial pathnames will be considered relative to # the location of the rippled executable. # # # # #------------------------------------------------------------------------------- # # 6. 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 # #------------------------------------------------------------------------------- # # 7. 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 = 20000000 # 20 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 = 5000000 # 5 XRP # #------------------------------------------------------------------------------- # # 8. 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). # # 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] port = 51235 ip = 0.0.0.0 protocol = peer [port_ws_admin_local] port = 6006 ip = 127.0.0.1 admin = 127.0.0.1 protocol = ws #[port_ws_public] #port = 5005 #ip = 127.0.0.1 #protocol = wss #------------------------------------------------------------------------------- [node_size] medium # This is primary persistent datastore for rippled. This includes transaction # metadata, account states, and ledger headers. Helpful information can be # found here: https://ripple.com/wiki/NodeBackEnd # delete old ledgers while maintaining at least 2000. Do not require an # external administrative command to initiate deletion. [node_db] type=RocksDB path=/var/lib/rippled/db/rocksdb open_files=2000 filter_bits=12 cache_mb=256 file_size_mb=8 file_size_mult=2 online_delete=2000 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 [sntp_servers] time.windows.com time.apple.com time.nist.gov pool.ntp.org # Where to find some other servers speaking the Ripple protocol. # [ips] r.ripple.com 51235 # File containing validation quorum and trusted validator keys. # 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