[Spread-cvs] commit: r872 - trunk/docs
jschultz at spread.org
jschultz at spread.org
Tue Nov 22 14:55:45 EST 2016
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 spread at spread.org
+# 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 spread at spread.org.
+#
+# 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
More information about the Spread-cvs
mailing list