View Source partisan_config (partisan v5.0.0-rc.16)
This module handles the validation, access and modification of Partisan configuration options. Some options will only take effect after a restart of the Partisan application, while other will take effect while the application is still running.
As per Erlang convention the options are given using the sys.config
file under the partisan
application section.
Example
[
...
{partisan, [
{listen_addrs, [
#{ip => {127, 0, 0, 1}, port => 12345}
]},
{channels, #{
data => #{parallelism => 4}
}},
{remote_ref_format, improper_list},
{tls, true},
{tls_server_options, [
{certfile, "config/_ssl/server/keycert.pem"},
{cacertfile, "config/_ssl/server/cacerts.pem"},
{keyfile, "config/_ssl/server/key.pem"},
{verify, verify_none}
]},
{tls_client_options, [
{certfile, "config/_ssl/client/keycert.pem"},
{cacertfile, "config/_ssl/client/cacerts.pem"},
{keyfile, "config/_ssl/client/key.pem"},
{verify, verify_none}
]}
]}
]
Options
The following is the list of all the options you can read using get/1
and get/2
, and modify using the sys.config
file and set/2
. Notice that most values will only take effect once you restart the Partisan application or the partisan_peer_service_manager
.
See Deprecated Options below.
binary_padding
A boolean value indicating whether to pad encoded messages whose external binary representation consumes less than 65 bytes.
broadcast
TBD
broadcast_mods
TBD
broadcast_mods
TBD
channels
Defines the channels to be used by Partisan. The option takes either a channels map where keys are channel names (partisan:channel()
) and values are channel options (partisan:channel_opts()
), or a list of values where each value can be any of the following types:
- a channel name (
partisan:channel()
) e.g. the atomfoo
- a channel with options:
{channel(), channel_opts()}
- a monotonic channel using the tuple
{monotonic, Name :: channel()}
e.g.{monotonic, bar}
. This is a legacy representation, the same can be achieved with{bar, #{monotonic => true}}
The list can habe a mix of types and during startup they are all coerced to channels map. Coercion works by defaulting the channel's parallelism
to the value of the global option parallelism
(which itself defaults to 1
), and the channel's monotonic
to false
.
Finally the list is transformed to a map where keys are channel names and values are channel map representation.
Example
Given the following option value:
[
foo,
{monotonic, bar},
{bar, #{parallelism => 4}}
]
The coerced representation will be the following map (which is a valid input and the final representation of this option after Partisan starts).
#{
foo => #{monotonic => false, parallelism => 1},
bar => #{monotonic => true, parallelism => 1},
baz => #{monotonic => false, parallelism => 4},
}
connect_disterl
A configuration that is intended solely for testing of the partisan_full_membership_strategy
(See membership_strategy
). It defines whether to use Distributed Erlang (disterl) in addition to Partisan channels. Defaults to false
.
Notice that this setting does not prevent you having both disterl and Partisan enabled for your release. However, you need to have special care to avoid mixing the two, for example by calling a partisan_gen_server
that uses Partisan for distribution with gen_server
that uses disterl.
connection_interval
Interval of time between peer connection attempts
connection_jitter
TBD
disable_fast_forward
TBD
disable_fast_receive
TBD
distance_enabled
TBD
egress_delay
TBD
exchange_selection
TBD
exchange_tick_period
TBD
gossip
If true
gossip is used to disseminate membership to peers. Default is true
. At the moment used only by partisan_full_membership_strategy
.
hyparview
The configuration for the partisan_hyparview_peer_service_manager
. A list with the following properties:
active_max_size
- Defaults to6
.active_min_size
- Defaults to3
.active_rwl
- Active View Random Walk Length. Defaults to6
.passive_max_size
- Defaults to30
.passive_rwl
- Passive View Random Walk Length. Defaults to6
.random_promotion
- A boolean indicating if random promotion is enabled. Defaultstrue
.random_promotion_interval
- Time after which the protocol attempts to promote a node in the passive view to the active view. Defaults to5000
.shuffle_interval
- Defaults to10000
.shuffle_k_active
- Number of peers to include in the shuffle exchange. Defaults to3
.shuffle_k_passive
- Number of peers to include in the shuffle exchange. Defaults to4
.
ingress_delay
TBD
lazy_tick_period
TBD
listen_addrs
A list of partisan:listen_addr()
objects. This overrides listen_ip
and listen_port
(see below) and its the way to configure the peer listener should you want to listen on multiple IP addresses. If this option is missing, the peer_ip
property will be used, unless is also missing, in which case the nodename's host part will be used to determine the IP address.
The partisan:listen_addr()
object can be represented using lists, binaries, tuples or maps as shown in the following example:
{listen_addrs, [
"127.0.0.1:12345",
<<"127.0.0.1:12345">>,
{"127.0.0.1", "12345"},
{{127, 0, 0, 1}, 12345},
#{ip => "127.0.0.1", port => "12345"},
#{ip => <<"127.0.0.1">>, port => <<"12345">>},
#{ip => {127, 0, 0, 1}, port => 12345}
]}
Notice the above example will result in the following, as equivalent terms are deduplicated.
{listen_addrs, [
#{ip => {127, 0, 0, 1}, port => 12345}
]}
This option also accepts IP addresses without a port e.g. "127.0.0.1". In this case the port will be the value listen_port
option. Notice listen_port
is also used by some peer discovery strategies that cannot detect in which port the peer is listening e.g. DNS.
See also listen_ip
for an alternative when using a single IP address.
listen_ip
The IP address to use for the peer connection listener when no partisan:listen_addr()
have been defined via option listen_addrs
. If a value is not defined (and listen_addrs
was not used), Partisan will attempt to resolve the IP address using the nodename's host i.e. the part to the right of the @
character in the nodename, and will default to {127,0,0,1}
if it can't.
listen_port
The port number to use for the peer connection listener when no partisan:listen_addr()
have been defined via option listen_addrs
. If a value is not defined (and listen_addrs
was not used), Partisan will use a randomly generated port. However, the random port will only work for clusters deployed within the same host i.e. used for testing. Moreover, the listen_port
value is also used by some peer discovery strategies that cannot detect in which port the peer is listening e.g. DNS. So for production environments we recommend always setting the same value on all peers, and having at least one partisan:listen_addr()
in each peer listen_addrs
option (when used) having the same port value.
membership_binary_compression
A boolean value or an integer in the range from 0..9
to be used with erlang:term_to_binary/2
when encoding the membership set for broadcast.
A value of true
is equivalent to integer 6
(equivalent to option compressed
in erlang:term_to_binary/2
). A value of false
is equivalent to 0
(no compression).
Default istrue
.
membership_strategy
The membership strategy to be used with partisan_pluggable_peer_service_manager
. Default is partisan_full_membership_strategy
membership_strategy_tracing
TBD
metadata
A custom mapping of keys to values.
name
The nodename to be used when one was not provided via the Erlang vm.args
configuration file or via the shell flag --name
. The value should be a longname e.g. {{Name}}{{HostOrIPAddress}}
.
When neither Erlang's nodename nor this value are defined, Partisan will generate a random nodename. This is primarily used for testing and you should always set the nodename when deploying to production, either via Erlang or using this option.
orchestration_strategy
TBD
parallelism
The default number of connections to use per channel, when a channel hasn't been given a specific parallelism
value via the channels
option. The default is 1
. For more information see option channels
.
peer_service_manager
The peer service manager to be used. An implementation of the partisan_peer_service_manager
behaviour which defines the overlay network topology and the membership view maintenance strategy. Default is partisan_pluggable_peer_service_manager
.
periodic_enabled
TBD
periodic_interval
TBD
pid_encoding
TBD
random_seed
TBD
ref_encoding
TBD
register_pid_for_encoding
TBD
remote_ref_format
Defines how partisan remote references pids, references and registered names will be encoded. See partisan_remote_ref
).
Accepts the following atom values:
uri
- remote references will be encoded as binary URIs.tuple
- remote references will be encoded as tuples (the format used by Partisan v1 to v4).improper_list
- remote references will be encoded as improper lists, similar to how aliases are encoded by the OTP modules.
This option exists to allow the user to tradeoff between memory and latency. In terms of memory uri
is the cheapest, followed by improper_list
. In terms of latency tuple
is the fastest followed by improper_list
. The default is improper_list
a if offers a good balance between memory and latency.
1> partisan_config:set(remote_ref_format, uri).
ok
2> partisan:self().
<<"partisan:pid:nonode@nohost:0.1062.0">>
3> partisan_config:set(remote_ref_format, tuple).
4> partisan:self().
{partisan_remote_reference,
nonode@nohost,
{partisan_process_reference,"<0.1062.0>"}}
5> partisan_config:set(remote_ref_format, improper_list).
6> partisan:self().
[nonode@nohost|<<"Pid#<0.1062.0>">>]
remote_ref_uri_padding
If true
and the URI encoding of a remote reference results in a binary smaller than 65 bytes, the URI will be padded. The default is false
.
1> partisan_config:set(remote_ref_binary_padding, false).
1> partisan:self().
<<"partisan:pid:nonode@nohost:0.1062.0">>
2> partisan_config:set(remote_ref_binary_padding, true).
ok
3> partisan:self().
<<"partisan:pid:nonode@nohost:0.1062.0:"...>>
replaying
TBD
reservations
TBD
retransmit_interval
When option retransmission
is set to true
in the partisan:forward_opts()
used in a call to partisan:forward_message/3
and message delivery fails, the Peer Service will enqueue the message for retransmission. This option is used to control the interval of time between retransmission attempts.
shrinking
TBD
tag
The role of this node when using the Client-Server topology implemented by {link partisan_client_server_peer_manager}.
Options
undefined
- The node acts as a normal peer in all other topologies. This the default valueclient
- The node acts as a client. To be used only in combination with{partisan_peer_manager, partisan_client_server_peer_manager}
server
- The node acts as a server. To be used only in combination with{partisan_peer_manager, partisan_client_server_peer_manager}
tls
A boolean value indicating whether channel connections should use TLS. If enabled, you have to provide a value for tls_client_options
and tls_server_options
. The default is false
.
tls_client_options
The TLS socket options used when establishing outgoing connections to peers. The configuration applies to all Partisan channels. The default is []
.
Example
{tls_client_options, [
{certfile, "config/_ssl/client/keycert.pem"},
{cacertfile, "config/_ssl/client/cacerts.pem"},
{keyfile, "config/_ssl/client/key.pem"},
{verify, verify_none}
]}
tls_server_options
The TLS socket options used when establishing incoming connections from peers. The configuration applies to all Partisan channels. The default is []
.
Example
{tls_server_options, [
{certfile, "config/_ssl/server/keycert.pem"},
{cacertfile, "config/_ssl/server/cacerts.pem"},
{keyfile, "config/_ssl/server/key.pem"},
{verify, verify_none}
]}
tracing
a boolean value. The default is false
.
xbot_interval
TBD
Deprecated Options
The following is the list of options have been deprecated. Some of them have been renamed and/or moved down a level in the configuration tree.
arwl
HyParView's Active View Random Walk Length. Defaults to 6
. Use active_rwl
in the hyparview
option instead.
fanout
The number of nodes that are contacted at each gossip interval.
max_active_size
HyParView's Active View Random Walk Length. Defaults to 6
. Use active_max_size
in the hyparview
option instead.
max_passive_size
HyParView's Active View Random Walk Length. Defaults to 30
. Use passive_max_size
in the hyparview
option instead.
mix_active_size
HyParView's Active View Random Walk Length. Defaults to 3
. Use active_min_size
in the hyparview
option instead.
passive_view_shuffle_period
Use shuffle_interval
in the hyparview
option instead.
peer_ip
Use listen_ip
instead.
peer_port
Use listen_port
instead.
peer_host
Use listen_addrs
instead.
partisan_peer_service_manager
Use peer_service_manager
instead.
prwl
HyParView's Passive View Random Walk Length. Defaults to 6
. Use passive_rwl
in the hyparview
option instead.
random_promotion
Use random_promotion
in the hyparview
option instead.
random_promotion_period
Use random_promotion_interval
in the hyparview
option instead.
remote_ref_as_uri
Use {remote_ref_format, uri}
instead
Summary
Functions
The name of the default channel.
The spec of the default channel.
Returns the value for Key
in Opts
, if found. Otherwise, calls get/1
.
Returns the value for Key
in Opts
, if found. Otherwise, calls get/2
.
Initialises the configuration from the application environment.
Return a random seed, either from the environment or one that's generated for the run.
Seed the process.
Seed the process.
Functions
-spec channel_opts(Name :: partisan:channel()) -> partisan:channel_opts().
-spec channels() -> #{partisan:channel() => partisan:channel_opts()}.
-spec default_channel() -> partisan:channel().
The name of the default channel.
-spec default_channel_opts() -> partisan:channel_opts().
The spec of the default channel.
Returns the value for Key
in Opts
, if found. Otherwise, calls get/1
.
Returns the value for Key
in Opts
, if found. Otherwise, calls get/2
.
Initialises the configuration from the application environment.
You should never call this function. This is used by Partisan itself during startup. The function is (and should be) idempotent, which is required for testing.
Return a random seed, either from the environment or one that's generated for the run.
Seed the process.
Seed the process.