Files
rippled/doc/rippled-example.cfg
2014-10-23 13:48:52 -07:00

941 lines
27 KiB
INI

#-------------------------------------------------------------------------------
#
# Rippled Server Instance Configuration Example
#
#-------------------------------------------------------------------------------
#
# Contents
#
# 1. Peer Networking
#
# 2. Websocket Networking
#
# 3. RPC Networking
#
# 4. SMS Gateway
#
# 5. Ripple Protcol
#
# 6. HTTPS Client
#
# 7. Database
#
# 8. Diagnostics
#
# 9. Voting
#
#-------------------------------------------------------------------------------
#
# 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.
#
#
#
#-------------------------------------------------------------------------------
#
# 1. Peer Networking
#
#-------------------
#
# These settings control security and access attributes of the Peer to Peer
# server section of the rippled process. Peer Networking implements the
# Ripple Payment protocol. It is over peer connections that transactions
# and validations are passed from to machine to machine, to make up the
# components of closed 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_ip]
#
# IP address or domain to bind to allow external connections from peers.
# Defaults to not binding, which disallows external connections from peers.
#
# Examples: 0.0.0.0 - Bind on all interfaces.
#
#
#
# [peer_port]
#
# If peer_ip is supplied, corresponding port to bind to for peer connections.
#
#
#
# [peer_port_proxy]
#
# An optional, additional listening port number for peers. Incoming
# connections on this port will be required to provide a PROXY Protocol
# handshake, described in this document (external link):
#
# http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt
#
# The PROXY Protocol is a popular method used by elastic load balancing
# service providers such as Amazon, to identify the true IP address and
# port number of external incoming connections.
#
# In addition to enabling this setting, it will also be required to
# use your provider-specific control panel or administrative web page
# to configure your server instance to receive PROXY Protocol handshakes,
# and also to restrict access to your instance to the Elastic Load Balancer.
#
#
#
# [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.
#
#
#
# [peer_ssl_cipher_list]
#
# A colon delimited string with the allowed SSL cipher modes for peer. The
# choices for for ciphers are defined by the OpenSSL API function
# SSL_CTX_set_cipher_list, documented here (external link):
#
# http://pic.dhe.ibm.com/infocenter/tpfhelp/current/index.jsp?topic=%2Fcom.ibm.ztpf-ztpfdf.doc_put.cur%2Fgtpc2%2Fcpp_ssl_ctx_set_cipher_list.html
#
# The default setting is "ALL:!LOW:!EXP:!MD5:@STRENGTH", which allows
# non-authenticated peer connections (they are, however, secure).
#
#
#
# [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
#
#
#
#-------------------------------------------------------------------------------
#
# 2. Websocket Networking
#
#------------------------
#
# These settings control security and access attributes of the Websocket
# server section of the rippled process, primarily used to service
# client requests and backend applications.
#
#
#
# [websocket_public_ip]
#
# IP address or domain to bind to allow untrusted connections from clients.
# In the future, this option will go away and the peer_ip will accept
# websocket client connections.
#
# Examples: 0.0.0.0 - Bind on all interfaces.
# 127.0.0.1 - Bind on localhost interface. Only local programs may connect.
#
#
#
# [websocket_public_port]
#
# Port to bind to allow untrusted connections from clients. In the future,
# this option will go away and the peer_ip will accept websocket client
# connections.
#
#
#
# [websocket_public_secure]
#
# 0, 1 or 2.
# 0: Provide ws service for websocket_public_ip/websocket_public_port.
# 1: Provide both ws and wss service for websocket_public_ip/websocket_public_port. [default]
# 2: Provide wss service only for websocket_public_ip/websocket_public_port.
#
# Browser pages like the Ripple client will not be able to connect to a secure
# websocket connection if a self-signed certificate is used. As the Ripple
# reference client currently shares secrets with its server, this should be
# enabled.
#
#
#
# [websocket_ping_frequency]
#
# <number>
#
# 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.
#
#
#
# [websocket_ip]
#
# IP address or domain to bind to allow trusted ADMIN connections from backend
# applications.
#
# Examples: 0.0.0.0 - Bind on all interfaces.
# 127.0.0.1 - Bind on localhost interface. Only local programs may connect.
#
#
#
# [websocket_port]
#
# Port to bind to allow trusted ADMIN connections from backend applications.
#
#
#
# [websocket_secure]
#
# 0, 1, or 2.
# 0: Provide ws service only for websocket_ip/websocket_port. [default]
# 1: Provide ws and wss service for websocket_ip/websocket_port
# 2: Provide wss service for websocket_ip/websocket_port.
#
#
#
# [websocket_ssl_cert]
#
# Specify the path to the SSL certificate file in PEM format.
# This is not needed if the chain includes it.
#
#
#
# [websocket_ssl_chain]
#
# If you need a certificate chain, specify the path to the certificate chain
# here. The chain may include the end certificate.
#
#
#
# [websocket_ssl_key]
#
# Specify the filename holding the SSL key in PEM format.
#
#
#
#-------------------------------------------------------------------------------
#
# 3. RPC Networking
#
#------------------
#
# This group of settings configures security and access attributes of the
# RPC server section of the rippled process, used to service both local
# and optional remote clients.
#
#
#
# [rpc_allow_remote]
#
# 0 or 1.
#
# 0: Allow RPC connections only from 127.0.0.1. [default]
# 1: Allow RPC connections from any IP.
#
#
#
# [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_admin_user]
#
# As a server, require this as the admin user to be specified. Also, require
# rpc_admin_user and rpc_admin_password to be checked for RPC admin functions.
# The request must specify these as the admin_user and admin_password in the
# request object.
#
# As a client, supply this to the server in the request object.
#
#
#
# [rpc_admin_password]
#
# As a server, require this as the admin password to be specified. Also,
# require rpc_admin_user and rpc_admin_password to be checked for RPC admin
# functions. The request must specify these as the admin_user and
# admin_password in the request object.
#
# As a client, supply this to the server in the request object.
#
#
#
# [rpc_ip]
#
# IP address or domain to bind to allow insecure RPC connections.
# Defaults to not binding, which disallows RPC connections.
#
#
#
# [rpc_port]
#
# If rpc_ip is supplied, corresponding port to bind to for peer connections.
#
#
#
# [rpc_user]
#
# As a server, require this user to be specified and require rpc_password to
# be checked for RPC access via the rpc_ip and rpc_port. The user and password
# must be specified via HTTP's basic authentication method.
# As a client, supply this to the server via HTTP's basic authentication
# method.
#
#
#
# [rpc_password]
#
# As a server, require this password to be specified and require rpc_user to
# be checked for RPC access via the rpc_ip and rpc_port. The user and password
# must be specified via HTTP's basic authentication method.
# As a client, supply this to the server via HTTP's basic authentication
# method.
#
#
#
# [rpc_startup]
#
# Specify a list of RPC commands to run at startup.
#
# Examples:
# { "command" : "server_info" }
# { "command" : "log_level", "partition" : "ripplecalc", "severity" : "trace" }
#
#
#
# [rpc_secure]
#
# 0 or 1.
#
# 0: Server certificates are not provided for RPC clients using SSL [default]
# 1: Client RPC connections wil be provided with SSL certificates.
#
# Note that if rpc_secure is enabled, it will also be necessary to configure
# the certificate file settings located in rpc_ssl_cert, rpc_ssl_chain, and
# rpc_ssl_key
#
#
#
# [rpc_ssl_cert]
#
# <pathname>
#
# A file system path leading to the SSL certificate file to use for secure
# RPC. The file is in PEM format. The file is not needed if the chain
# includes it.
#
#
#
# [rpc_ssl_chain]
#
# <pathname>
#
# A file system path leading to the file with the certificate chain.
# The chain may include the end certificate.
#
#
#
# [rpc_ssl_key]
#
# <pathname>
#
# A file system path leading to the file with the SSL key.
# The file is in PEM format.
#
#
#
#-------------------------------------------------------------------------------
#
# 4. 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.
#
#
#
#-------------------------------------------------------------------------------
#
# 5. 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
#
#
#
# [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.
#
#
#
#-------------------------------------------------------------------------------
#
# 6. 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 .
#
#
#
# [ssl_verify_file]
#
# <pathname>
#
# A file system path leading to the certificate verification file for
# HTTPS client requests.
#
#
#
# [ssl_verify_dir]
#
# <pathname>
#
#
# 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.
#
#
#
#-------------------------------------------------------------------------------
#
# 7. 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:
# <key> '=' <value>
# ...
#
# Examples:
# type=HyperLevelDB
# path=db/hyperldb
# compression=0
#
# Choices for 'type' (not case-sensitive)
# RocksDB Use Facebook's RocksDB database (preferred)
# HyperLevelDB Use an improved version of LevelDB
# SQLite Use SQLite
# LevelDB Use Google's LevelDB database (deprecated)
# none Use no backend
#
# Required keys:
# path Location to store the database (all types)
#
# Optional keys:
# compression 0 for none, 1 for Snappy compression
#
# 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.
#
#
#
#-------------------------------------------------------------------------------
#
# 8. 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
#
#-------------------------------------------------------------------------------
#
# 9. 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 = <drops>
#
# 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 = <drops>
#
# 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 = <drops>
#
# 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
#
#-------------------------------------------------------------------------------
# Allow other peers to connect to this server.
#
[peer_ip]
0.0.0.0
[peer_port]
51235
# Allow untrusted clients to connect to this server.
#
[websocket_public_ip]
0.0.0.0
[websocket_public_port]
5006
# Provide trusted websocket ADMIN access to the localhost.
#
[websocket_ip]
127.0.0.1
[websocket_port]
6006
# Provide trusted json-rpc ADMIN access to the localhost.
#
[rpc_ip]
127.0.0.1
[rpc_port]
5005
[rpc_allow_remote]
0
[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
[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
[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" }
# Configure SSL for WebSockets. Not enabled by default because not everybody
# has an SSL cert on their server, but if you uncomment the following lines and
# set the path to the SSL certificate and private key the WebSockets protocol
# will be protected by SSL/TLS.
#[websocket_secure]
#1
#[websocket_ssl_cert]
#/etc/ssl/certs/server.crt
#[websocket_ssl_key]
#/etc/ssl/private/server.key
# Defaults to 0 ("no") so that you can use self-signed SSL certificates for
# development, or internally.
#[ssl_verify]
#0