#------------------------------------------------------------------------------- # # Rippled Server Instance Configuration Example # #------------------------------------------------------------------------------- # # Contents # # 1. Server # # 2. Peer Protocol # # 3. SMS Gateway # # 4. Ripple Protocol # # 5. HTTPS Client # # 6. Database # # 7. Diagnostics # # 8. Voting # # 9. 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 = no | allow # # Controls whether or not administrative commands are allowed. 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. # # 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. # # 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. # # # # [rpc_admin_allow] # # Specify a list of IP addresses allowed to have admin access. One per line. # If you want to test the output of non-admin commands add this section and # just put an ip address not under your control. # Defaults to 127.0.0.1. # # # # [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 optionally # 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 # # # # [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 may optionally # 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] EXPERIMENTAL # # This section is EXPERIMENTAL, and should not be # present for production configuration settings. # # A set of key/value pair parameters to configure the overlay. # # auto_connect = 0 | 1 # # When set, activates the autoconnect feature. This maintains outgoing # connections using PeerFinder's "Outgoing Connection Strategy." # # http_handshake = 0 | 1 # # When set, outgoing peer connections will handshaking using a HTTP # request instead of the legacy TMHello protocol buffers message. # Incoming peer connections have their handshakes detected automatically. # # become_superpeer = 'never' | 'always' | 'auto' # # Controls the selection of peer roles: # # 'never' Always handshake in the leaf role. # 'always' Always handshake in the superpeer role. # 'auto' Start as a leaf, promote to superpeer after # passing capability check (default). # # In the leaf role, a peer does not advertise its IP and port for # the purpose of receiving incoming connections. The peer also does # not forward transactions and validations received from other peers. # # In the superpeer role, a peer advertises its IP and port for # receiving incoming connections after passing an incoming connection # test. Superpeers forward transactions and protocol messages to all # other peers. Superpeers do not forward validations to other superpeers. # Instead, a validation received by a superpeer from a leaf is forwarded # only to other leaf connections. # # # #------------------------------------------------------------------------------- # # 3. SMS Gateway # #--------------- # # If you have a certain SMS messaging provider you can configure these # settings to allow the rippled server instance to send an SMS text to the # configured gateway in response to an admin-level RPC command "sms" with # one parameter, 'text' containing the message to send. This allows backend # applications to use the rippled instance to securely notify administrators # of custom events or information via SMS gateway. # # When the 'sms' RPC command is issued, the configured SMS gateway will be # contacted via HTTPS GET at the URL indicated by sms_url. The URI formed # will be in this format: # # [sms_url]?from=[sms_from]&to=[sms_to]&api_key=[sms_key]&api_secret=[sms_secret]&text=['text'] # # Where [...] are the corresponding values from the configuration file, and # ['test'] is the value of the JSON field with name 'text'. # # [sms_url] # # The URL to contact via HTTPS when sending SMS messages # # [sms_from] # [sms_to] # [sms_key] # [sms_secret] # # These are all strings passed directly in the URI as query parameters # to the provider of the SMS gateway. # # # #------------------------------------------------------------------------------- # # 4. 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". # # # # [validation_quorum] # # Sets the minimum number of trusted validations a ledger must have before # the server considers it fully validated. Note that if you are validating, # your validation counts. # # # # [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". # # The default is: 256 # # # # [ledger_history_index] # # If set to greater than 0, the index number of the earliest ledger to # acquire. # # # # [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] # # List of nodes to always accept as validators. Nodes are specified by domain # or public key. # # For domains, rippled will probe for https web servers at the specified # domain in the following order: ripple.DOMAIN, www.DOMAIN, DOMAIN # # For public key entries, a comment may optionally be specified after adding # a space to the public key. # # Examples: # ripple.com # n9KorY8QtTdRx7TVDpwnG9NvyxsDwHUKUEeDLY3AkiGncVaSXZi5 # n9MqiExBcoG19UXwoLjBJnhsxEhAZMuWwJDRdkyDz1EkEkwzQTNt John Doe # # # # [validators_file] # # Path to file contain a list of nodes to always accept as validators. Use # this to specify a file other than this file to manage your validators list. # # If this entry is not present or empty and no nodes from previous runs were # found in the database, rippled will look for a validators.txt in the config # directory. If not found there, it will attempt to retrieve the file from # the [validators_site] web site. # # After specifying a different [validators_file] or changing the contents of # the validators file, issue a RPC unl_load command to have rippled load the # file. # # Specify the file by specifying its full path. # # Examples: # C:/home/johndoe/ripple/validators.txt # /home/johndoe/ripple/validators.txt # # # # [validators_site] # # Specifies where to find validators.txt for UNL boostrapping and RPC # unl_network command. # # Example: ripple.com # # # # [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. # # 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 # agressivness 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. # # # #------------------------------------------------------------------------------- # # 5. HTTPS Client # #---------------- # # The rippled server instance uses HTTPS GET requests in a variety of # circumstances, including but not limited to the SMS Messaging Gateway # feature and also for 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). # # The performance of the underlying storage media where the NodeDB # is placed can affect the performance of the server. Some virtual # hosting providers offer high speed secondary storage, with the # caveat that the data is not persisted across launches. If rippled # runs in such an environment, it can be beneficial to configure the # temp_db setting, which activates a secondary "look-aside" cache # that can speed up the server. Some testing is suggested to determine # if the temp_db setting is an improvement for your environment # # Partial pathnames will be considered relative to the location of # the rippled.cfg file. # # [node_db] Settings for the NodeDB (required) # [temp_db] Settings for the look-aside temporary db (optional) # [import_db] Settings for performing a one-time import (optional) # # Format (without spaces): # One or more lines of key / value pairs: # '=' # ... # # Examples: # type=HyperLevelDB # path=db/hyperldb # compression=0 # # Choices for 'type' (not case-sensitive) # RocksDB Use Facebook's RocksDB database (preferred) # NuDB Use Ripple Labs' NuDB (Windows preferred) # HyperLevelDB (Deprecated) # SQLite (Deprecated) # LevelDB (Deprecated) # none (No backend) # # Required keys: # path Location to store the database (all types) # # Optional keys: # compression 0 for none, 1 for Snappy compression # 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 'temp_db' configures a look-aside cache for high volume storage # which doesn't necessarily persist between server launches. This # is an optional configuration parameter. If it is left out then # no look-aside database is created or used. # # 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. # # [database_path] Path to the book-keeping databases. # # There are 4 book-keeping 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. # # # #------------------------------------------------------------------------------- # # 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 were 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 paramters 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 # #------------------------------------------------------------------------------- # # 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 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 # #------------------------------------------------------------------------------- # # 9. Example Settings # #-------------------- # # Administrators can use these values as a starting poing 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 port_peer port_wss_admin #port_ws_public #ssl_key = /etc/ssl/private/server.key #ssl_cert = /etc/ssl/certs/server.crt [port_rpc] port = 5005 ip = 127.0.0.1 admin = allow protocol = https [port_peer] port = 51235 ip = 0.0.0.0 protocol = peer [port_wss_admin] port = 6006 ip = 127.0.0.1 admin = allow protocol = wss #[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 # The latest validators can be obtained from # https://ripple.com/ripple.txt # [validators] n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7 RL1 n9MD5h24qrQqiyBC8aeqqCWvpiBiYQ3jxSr91uiDvmrkyHRdYLUj RL2 n9L81uNCaPgtUJfaHh89gmdvXKAmSt5Gdsw2g1iPWaPkAHW5Nm4C RL3 n9KiYM9CgngLvtRCQHZwgC2gjpdaZcCcbt3VboxiNFcKuwFVujzS RL4 n9LdgEtkmGB9E2h3K4Vp7iGUaKuq23Zr32ehxiU8FWY7xoxbWTSA RL5 # Ditto. [validation_quorum] 3 # 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" } # Defaults to 1 ("yes") so that certificates will be validated. To allow the use # of self-signed certificates for development or internal use, set to 0 ("no"). #[ssl_verify] #0