commit: r872 - trunk/docs
[email protected] Tue, 22 Nov 2016 14:55:45 -0500
| Newsgroups | gmane.network.spread.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: jschultz Date: 2016-11-22 14:55:44 -0500 (Tue, 22 Nov 2016) New Revision: 872 Modified: trunk/docs/sample.spread.conf Log: Significant update to docs/sample.spread.conf Modified: trunk/docs/sample.spread.conf =================================================================== --- trunk/docs/sample.spread.conf 2016-11-22 19:54:41 UTC (rev 871) +++ trunk/docs/sample.spread.conf 2016-11-22 19:55:44 UTC (rev 872) @@ -1,111 +1,359 @@ -# Blank lines are permitted in this file. # spread.conf sample file # -# questions to [email protected] +# Blank lines are permitted in this file. White space is generally +# ignored beyond separating parsing tokens. Comments can be added +# with a '#' character, which will cause the rest of the line to be +# ignored. # +# Please send any questions to [email protected]. +# +# A Spread configuration file consists primarily of one or more +# segments (Spread_Segment) that specify the LANs of daemons in the +# deployment and their associated naming and addressing. +# +# Within a configuration, every daemon should be able to unicast send +# to and receive from every other daemon through their respective +# daemon addresses. Within a segment, every daemon should be able to +# send to and receive from every other daemon in that same segment +# through their segment address. If these conditions are violated +# (e.g. - firewalls unexpectedly block some traffic, broken segment +# address, etc.), then, depending on the violation, Spread may not be +# able to function properly or may incur significant overhead in +# trying to overcome these issues. +# +# The configuration file of every daemon in a Spread deployment must +# have the same segments listed in the same order and each segment +# must respectively contain the same daemons listed in the same order +# with the same associated addressing. All daemons in a deployment +# must also be configured to run the same ring protocol. If any of +# these conditions are violated, then the disagreeing daemons will +# refuse to communicate with one another due to computing different +# configuration hashes. Other parameters can vary from daemon to +# daemon within the same configuration. +# +# When a daemon first runs, it outputs its configuration hash. This +# configuration hash should be checked to be the same across all +# daemons in a deployment manually or through use of the spmonitor +# program. -#MINIMAL REQUIRED FILE +# MINIMAL REQUIRED FILE # # Spread should work fine on one machine with just the uncommented # lines below. The rest of the file documents all the options and # more complex network setups. # -# This configures one spread daemon running on port 4803 on localhost. +# This configures one spread daemon running on default port 4803 on +# the local host loopback that supports IPv4. -Spread_Segment 127.0.0.255:4803 { - +Spread_Segment 127.0.0.255 +{ localhost 127.0.0.1 } +# This configures one spread deamon running on port 5000 on the local +# host loopback that supports IPv6. +# +#Spread_Segment [::1]:5000 +#{ +# localhost ::1 +#} +###################################################################### +# +# A Spread_Segment describes a LAN of daemons that can and should all +# intercommunicate primarily using a multicast (or IPv4 broadcast) +# address over at most one router hop. The port is optional. If a +# port is not specified, then the default 4803 port is used. The +# syntax is: +# +# Spread_Segment <multicast address>:<port> { +# +# For example: +#Spread_Segment 227.1.2.3:5000 { +# +# For IPv6, you must surround the address with brackets if you specify a port: +#Spread_Segment [ff02::1:2:3]:5000 { +# +# Otherwise, don't use brackets: +#Spread_Segment ff02::1:2:3 { +# +# For IPv6, you can also specify the interface to use if necessary. +# Interface portions of addresses are interpreted locally by each +# daemon they affect and can differ for each daemon's configuration +# file in a deployment. For example: +# +#Spread_Segment [ff02::1:2:3%eth30]:5000 { +# +# Within a segment, you list the daemons that should intercommunicate +# using the segment address. Note, that a daemon must only appear +# once in a configuration file, even if it could sit in multiple +# segments. +# +# Daemon specification: usually a daemon name and address, but can +# also be either just an address or just a name. +# +# If both name and address are given, then the name is taken as is, +# and the IP address is used for that name. +# +# If only an address is given, then the address will also be used as +# the daemon's name. +# +# If only a name is given, then a name lookup is done to find the +# associated address. The first address returned by the lookup of the +# proper type (see ActiveIPVersion) is used. All the daemons in a +# configuration must find the same address for that name, or they will +# refuse to communicate with one another. If multiple addresses are +# associated with a name, then this form is strongly discouraged as +# the ambiguity may cause daemons to disagree on the address to use. +# +# Daemon names will be truncated down to MAX_PROC_NAME - 1 characters +# (see spread_params.h) in spread user names, log files and other +# reporting. +# +# For examples: +# ewok 192.168.10.23 +# or +# 192.168.10.23 +# or +# ewok # address looked up by name -- all daemons must lookup same address! +# +# Once you are done specifying all the daemons in a segment, you must +# close it with a bracket. +# +#} +# +# Repeat this process for all the segments and daemons in your +# deployment. +# +# A daemon will send many messages through its segment address. If +# you do not want this to happen, then you should specify your daemons +# each in their own segment, which will force only unicast messaging +# to be used instead. In singleton segments, the segment address is +# largely ignored / has no significant effect. Note, putting each +# daemon in its own segment has scalability problems for larger +# configurations as the time to send a logical multicast message +# scales linearly with the number of daemons in the configuration. +# Here's an example of a potentially problematic segment. The problem +# is that extra white space between tokens is largely ignored in +# Spread's configuration file, so the parser will associate the name +# 'other3.my.com' with the address 128.2.2.13 even though they are on +# different lines. +# +#Spread_Segment 227.2.2.255 +#{ +# other1 128.2.2.10 +# 128.2.2.11 +# other3.my.com +# 128.2.2.13 # Woops? other3.my.com is going to be associated with 128.2.2.13. Was that intended? +#} +# +# If that is not what is intended and these were meant to be distinct +# daemons, then they have to be separated by an optional semicolon +# (delimited by whitespace), interface specification (see below) or +# VirtualID specification (see below): +# +#Spread_Segment 227.2.2.255 { +# +# other1 128.2.2.10 +# 128.2.2.11 +# other3.my.com ; +# 128.2.2.13 # other3.my.com's address is going to be looked up, while 128.2.2.13 is a distinct daemon. +#} +# Multi-homed host configuration +# +# If you run Spread on hosts with multiple interfaces you may want to +# control which interfaces Spread uses for client connections and for +# the daemon-to-daemon (and monitor control) messages. This can be +# done by adding an optional bracketed stanza to each configured +# machine. For example: +# +#Spread_Segment 225.0.1.1 { +# multihomed1 1.2.3.4 { +# D 1.2.3.4 +# C 192.168.0.4 } +# multihomed2 1.2.3.5 { +# D 1.2.3.5 +# C 192.168.0.5 +# C 127.0.0.1 } +# multihomed3 1.2.3.6 { +# 192.168.0.6 +# 1.2.3.6 } +# multihomed4 1.2.3.7 { +# D 1.2.3.7 +# C 0.0.0.0 } +#} +# +# This configuration sets up four multihomed daemons in a segment. +# The first host has a primary IP address of 1.2.3.4. All +# daemon-to-daemon UDP multicasts and the tokens and any monitor +# messages must use the 1.2.3.4 interface. Meanwhile, client +# connections will only be accepted on the 192.168.0.4 interface. +# +# The second host has a similar setup, except it also listens for +# client connections on its loopback interface as well. +# +# The third host uses a shorthand form of omitting the D or C option +# and just listens for all types of traffic and events on both the +# 192.168.0.5 and 1.2.3.4 intefaces. If no letter is listed before +# the interface address, then ALL types of events are handled on that +# interface. This daemon can also receive daemon and monitoring +# traffic if it arrives on its 192.168.0.6 interface somehow. +# +# The fourth host uses the unspecified address, which will cause the +# daemon to bind to all interfaces (e.g. - INADDR_ANY) for accepting +# client connections. +# +# If you make any use of the extra interface stanza, then you must +# explicitly configure *ALL* interfaces you want as Spread removes all +# defaults when you use the explicit notation. Also, you must specify +# a daemon interface that matches (explicitly or implicity) the +# daemon's primary address. + +# At a very low level, each daemon uses a unique ID, called a +# VirtualID, that is derived from a hash of its name. In the highly +# unlikely event that two daemon names hash to the same VirtualID, +# then the configuration must be manually changed to eliminate the +# ambiguity. This can be done by either using a different name for +# one of the daemons involved in the hash collision or by explicitly +# picking a VirtualID that doesn't have any conflicts. In the latter +# case, a VirtualID is a non-zero, positive integer. For maximum +# forward comptability of your configuration files, VirtualIDs should +# be less than 255. For example: +# +#Spread_Segment 227.2.2.255 { +# other1 128.2.2.10 +# other2 128.2.2.11 VirtualID = 5 +# other3 128.2.2.12 +#} + +###################################################################### # Spread options -#--------------------------------------------------------------------------- -#--------------------------------------------------------------------------- -#Set what internal Spread events are logged to the screen or file + +# WideAreaNetwork lets you specify whether a deployment is running +# across a WAN or is more local area in nature. If left unspecified, +# then it defaults to true, except for when your configuration +# consists solely of a single segment, in which case it defaults to +# false. This parameter affects default choices for timeouts and +# which ring protocol to run, both of which can have significant +# impacts on performance. +# +#WideAreaNetwork = false + +# AcceleratedRing lets you specify which ring protocol to use. If +# false, then the regular Spread ring protocol is used. If true, then +# the accelerated ring protocol is used. If left unspecified, then +# the choice defaults depending on the WideAreaNetwork parameter. If +# WideAreaNetwork is true, then Spread defaults to using the original +# ring protocol. If WideAreaNetwork is false, then Spread defaults to +# using the accelerated ring protocol. +# +# Note that daemons can only communicate with daemons that run the +# same protocol - they will refuse to talk with daemons that run a +# different protocol. The accelerated ring protocol uses a flow +# control algorithm similar to the normal protocol, with the exception +# that the token is sent before up to AcceleratedWindow packets of the +# PersonalWindow (the token still reflects these packets). In +# general, the closer AcceleratedWindow is to PersonalWindow the more +# acceleration can be expected -- up to a point. In our testing on +# 1Gb/s and 10Gb/s networks, raising AcceleratedWindow above 20 had +# significant negative side effects and actually lowered throughput. +# +#AcceleratedRing = true + +# ActiveIPVersion lets you specify what kind of addresses the daemons +# will use for their intercommunication. Currently, all daemons in a +# configuration must all use only IPv4 or IPv6 addresses. Spread does +# not yet support automatic translation between IPv4 and IPv6, even if +# the network supports that. All daemon and segment addresses must be +# of the same IP type. +# +# If used, then this option should come before any segments in the +# configuration file. Otherwise, Spread will default to the type of +# address configured for the first daemon in the file. Note, that if +# the first daemon only specifies a name (i.e. - no explicit address +# is configured), then whichever type of address record the name +# lookup returns first is what Spread will default to use. Use this +# option to force one type of address or the other if you don't +# specify daemon addresses. +# +#ActiveIPVersion = IPv4 # IPv6 + +# Set what internal Spread events are logged to the screen or file # (see EventLogFile). # Default setting is to enable PRINT and EXIT events only. -#The PRINT and EXIT types should always be enabled. The names of others are: +# The PRINT and EXIT types should always be enabled. The names of others are: # EXIT PRINT DEBUG DATA_LINK NETWORK PROTOCOL SESSION # CONFIGURATION MEMBERSHIP FLOW_CONTROL STATUS EVENTS -# GROUPS MEMORY SKIPLIST ALL NONE -# ALL and NONE are special and represent either enabling every type -# or enabling none of them. +# GROUPS MEMORY SKIPLIST ALL NONE +# +# ALL and NONE are special and represent either enabling every type +# or enabling none of them. +# # You can also use a "!" sign to negate a type, # so { ALL !DATA_LINK } means log all events except data_link ones. - +# #DebugFlags = { PRINT EXIT } # Set priority level of events to output to log file or screen # The possible levels are: # pDEBUG INFO WARNING ERROR CRITICAL FATAL -# Once selected all events tagged with that priority or higher will -# be output. FATAL events are always output and cause the daemon to -# shut down. Some Events are tagged with a priority of PRINT which -# causes them to print out no matter what priority level is set. # +# Once selected all events tagged with that priority or higher will be +# output. FATAL events are always output and cause the daemon to shut +# down. Some events are tagged with a priority of PRINT which causes +# them to print out no matter what priority level is set. +# # The default level used if nothing is set is INFO. - -#EventPriority = INFO +# +#EventPriority = INFO -#Set whether to log to a file as opposed to stdout/stderr and what -# file to log to. -# Default is to log to stdout. +# Set whether to log to a file as opposed to stdout/stderr and what +# file to log to. Default is to log to stdout. # -#If option is not set then logging is to stdout. -#If option is set then logging is to the filename specified. -# The filename can include a %h or %H escape that will be replaced at runtime -# by the hostname of the machine upon which the daemon is running. -# For example "EventLogFile = spreadlog_%h.log" with 2 machines -# running Spread (machine1.mydomain.com and machine2.mydomain.com) will -# cause the daemons to log to "spreadlog_machine1.mydomain.com.log" and +# If option is set then logging is to the filename specified. The +# filename can include a %h or %H escape that will be replaced at +# runtime by the hostname of the machine upon which the daemon is +# running. For example "EventLogFile = spreadlog_%h.log" with 2 +# machines running Spread (machine1.mydomain.com and +# machine2.mydomain.com) will cause the daemons to log to +# "spreadlog_machine1.mydomain.com.log" and # "spreadlog_machine2.mydomain.com.log" respectively. - +# #EventLogFile = testlog.out -#Set whether to add a timestamp in front of all logged events or not. +# Set whether to add a timestamp in front of all logged events or not. # Default is no timestamps. Default format is "[%a %d %b %Y %H:%M:%S]". -#If option is commented out then no timestamp is added. -#If option is enabled then a timestamp is added with the default format -#If option is enabled and set equal to a string, then that string is used +# If option is commented out then no timestamp is added. +# If option is enabled then a timestamp is added with the default format +# If option is enabled and set equal to a string, then that string is used # as the format string for the timestamp. The string must be a valid time # format string as used by the strftime() function. - +# #EventTimeStamp # or #EventTimeStamp = "[%a %d %b %Y %H:%M:%S]" -#Set whether to add a precise (microsecond) resolution timestamp to all logged +# Set whether to add a precise (microsecond) resolution timestamp to all logged # events or not. This option requires that EventTimeStamp is also enabled. # If the option is commented out then the microsecond timestamp is not added # If the option is uncommented then a microsecond time will print in addition -# to the H:M:S resolution timestamp provided by EventTimeStamp. - +# to the H:M:S resolution timestamp provided by EventTimeStamp. +# #EventPreciseTimeStamp -# Set to initialize daemon sequence numbers to a 'large' number for testing -# this is purely a debugging capability and should never be enabled on -# production systems (note one side effect of enabling this is that -# your system will experience an extra daemon membership every few messages -# so you REALLY do not want this turned on) -# If you want to change the initial value the sequence number is set to -# you need to edit the #define INITIAL_SEQUENCE_NEAR_WRAP at the top -# of configuration.h - -#DebugInitialSequence - -#Set whether to allow dangerous monitor commands +# Set whether to allow dangerous monitor commands # like "partition, flow_control, or kill" # Default setting is FALSE. -#If option is set to false then only "safe" monitor commands are allowed +# If option is set to false then only "safe" monitor commands are allowed # (such as requesting a status update). -#If option is set to true then all monitor commands are enabled. +# If option is set to true then all monitor commands are enabled. # THIS IS A SECURTIY RISK IF YOUR NETWORK IS NOT PROTECTED! - +# #DangerousMonitor = true -#Set handling of SO_REUSEADDR socket option for the daemon's TCP +# Set handling of SO_REUSEADDR socket option for the daemon's TCP # listener. This is useful for facilitating quick daemon restarts (OSes # often hold onto the interface/port combination for a short period of time # after daemon shut down). @@ -114,32 +362,33 @@ # ON - Always active, regardless of interface. # SECURITY RISK FOR ANY OS WHICH ALLOW DOUBLE BINDS BY DIFFERENT USERS # OFF - Always off. - +# #SocketPortReuse = AUTO -#Set what the maximum per-session queue should be for messages before disconnecting -# a session. Spread will buffer upto that number of messages that are destined to the -# session, but that can not be delivered currently because the session is not reading fast enough. -# The compiled in default is usually 1000 if you havn't changed it in the spread_params.h file. - +# Set what the maximum per-session queue should be for messages before +# disconnecting a session. Spread will buffer upto that number of +# messages that are destined to the session, but that can not be +# delivered currently because the session is not reading fast enough. +# The compiled in default is usually 1000 if you haven't changed it in +# the spread_params.h file. +# #MaxSessionMessages = 5000 -#Sets the runtime directory used when the Spread daemon is run as root +# Sets the runtime directory used when the Spread daemon is run as root # as the directory to chroot to. Defaults to the value of the # compile-time preprocessor define SP_RUNTIME_DIR, which is generally # "/var/run/spread". - +# #RuntimeDir = /var/run/spread -#Sets the unix user that the Spread daemon runs as (when launched as +# Sets the unix user that the Spread daemon runs as (when launched as # the "root" user). Not effective on a Windows system. Defaults to # the user and group "spread". - +# #DaemonUser = spread #DaemonGroup = spread - -#Set the list of authentication methods that the daemon will allow +# Set the list of authentication methods that the daemon will allow # and those which are required in all cases. # All of the methods listed in "RequiredAuthMethods" will be checked, # irregardless of what methods the client chooses. @@ -153,107 +402,19 @@ # for older clients. If you enable methods that require interaction, # then essentially all older clients will be locked out. # -#The current choices are: +# The current choices are: # NULL for default, allow anyone authentication # IP for IP based checks using the spread.access_ip file - +# #RequiredAuthMethods = " " #AllowedAuthMethods = "NULL" -#Set the current access control policy. +# Set the current access control policy. # This is only needed if you want to establish a customized policy. # The default policy is to allow any actions by authenticated clients. +# #AccessControlPolicy = "PERMIT" - -# network description line. -# Spread_Segment <multicast address for subnet> <port> { -# port is optional, if not specified the default 4803 port is used. - -#Spread_Segment 127.0.0.255:4803 { - -# either a name or IP address. If both are given, than the name is taken -# as-is, and the IP address is used for that name. - -# localhost 127.0.0.1 -#} -# repeat for next sub-network - -#Spread_Segment x.2.2.255 { - -# other1 128.2.2.10 -# 128.2.2.11 -# other3.my.com -#} -# Spread will feel free to use broadcast messages within a sub-network. -# if you do not want this to happen, you should specify your machines on -# different logical sub-networks. - -# IP-Multicast addresses can also be used as the multicast address for -# the logical sub-network as in this example. If IP-multicast is supported -# by the operating system, then the messages will only be received -# by those machines who are in the group and not by all others in the same -# sub-network as happens with broadcast addresses - -#Spread_Segment 225.0.1.1:3333 { -# mcast1 1.2.3.4 -# mcast2 1.2.3.6 -#} - -# Multi-homed host setup -# -# If you run Spread on hosts with multiple interfaces you may want to -# control which interfaces Spread uses for client connections and for -# the daemon-to-daemon (and monitor control) messages. This can be done -# by adding an extra stanza to each configured machine. -# -#Sample: -# -#Spread_Segment 225.0.1.1 { -# multihomed1 1.2.3.4 { -# D 192.168.0.4 -# C 1.2.3.4 } -# multihomed2 1.2.3.5 { -# D 192.168.0.5 -# C 1.2.3.5 -# C 127.0.0.1 } -# multihomed3 1.2.3.6 { -# 192.168.0.6 -# 1.2.3.6 } -#} -# This configuration sets up three multihomed machines into a Spread segment. -# The first host has a 'main' IP address of 1.2.3.4 and listens for client -# connections only on that interface. All daemon-to-daemon UDP multicasts and -# the tokens and any monitor messages must use the 192.168.0.4 interface. -# The second host multihomed2 has a similar setup, except it also listens for -# client connections on the localhost interface as well as the 1.2.3.5 interface. -# If you make any use of the extra interface stanza ( a { } block ) then you must -# explicitly configure ALL interfaces you want as Spread removes all defaults when -# you use the explicit notation. -# The third multihomed3 host uses a shorthand form of omitting the D or C option and -# just listening for all types of traffic and events on both the 192.168.0 and 1.2.3 -# networks. If no letter is listed before the interface address then ALL types of -# events are handled on that interface. - -# AcceleratedRing indicates which protocol to use. If false, then the regular Spread -# ring protocol is used. If true, then the accelerated ring protocol is used. If left -# unspecified, then Spread tries to guess if you are running on a WAN or LAN and uses -# the more appropriate protocol: the regular protocol on WANs and the accelerated protocol -# on LANs. Spread uses the heuristic that if all your daemon addresses are within the -# same /16 network then it assumes it is a LAN, otherwise it is a WAN. This same heurstic -# is used to pick the default timeouts (WAN or LAN) for the protocols too. -# -# Note that daemons can only talk with daemons that run the same protocol - they -# will refuse to talk with daemons that run the other protocol. The accelerated ring -# protocol uses a flow control algorithm similar to the normal protocol, with the -# exception that the token is sent before up to AcceleratedWindow packets of the -# PersonalWindow (the token still reflects these packets). In general, the closer -# AcceleratedWindow is to PersonalWindow the more acceleration can be expected -- up to -# a point. In our testing on 1Gb/s and 10Gb/s networks, raising AcceleratedWindow -# above 20 had significant negative side effects and actually lowered throughput. -# -#AcceleratedRing = true - # Flow Control Parameters # #Window = 160 @@ -273,16 +434,4 @@ #SegTimeout = 500 #GatherTimeout = 1250 #FormTimeout = 1250 -#LookupTimeout = 30000 - -# If you don't specify membership timeouts, then Spread will use one -# of two sets of default membership timeouts based on whether or not -# your configuration is for a LAN or a WAN. The WideAreaNetwork -# parameter forces the daemon to either use the WAN timeouts (true) or -# the LAN timeouts (false). If this parameter is also not specified, -# then LAN timeouts will only be used if your configuration has a -# single segment. All other configurations will use the longer WAN -# timeouts instead. -# -# WideAreaNetwork = false - +#LookupTimeout = 30000 \ No newline at end of file