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"}, %% Authenticate peers with a cert signed by the cluster CA. %% verify_none would encrypt but NOT authenticate (MITM-able). {verify, verify_peer}, {fail_if_no_peer_cert, true} ]}, {tls_client_options, [ {certfile, "config/_ssl/client/keycert.pem"}, {cacertfile, "config/_ssl/client/cacerts.pem"}, {keyfile, "config/_ssl/client/key.pem"}, {verify, verify_peer} ]} ]} ]. ``` ## Options The following is the list of all the options you can read usingget/1andget/2, and modify using thesys.configfile andset/2. Notice that most values will only take effect once you restart the Partisan application or them:partisan_peer_service_manager. See [Deprecated Options](#deprecated-options) below. #### binary_padding A boolean value indicating whether to pad encoded messages whose external binary representation consumes less than 65 bytes. #### broadcast Enables tree-based transitive forwarding. Whentrue, a message addressed to a peer this node has no connection to is forwarded over the broadcast tree instead of failing, provided the caller passedtransitive => truein the forward options. Also starts a periodic tree refresh, whose period is thetree_refreshoption (default1000ms). Defaults tofalse. #### broadcast_mods The broadcast handler modules to start, as a list of modules implementingm:partisan_plumtree_broadcast_handler. Defaults to[partisan_plumtree_backend], Partisan's own membership handler. Each module listed here gets its own broadcast group: its own process, mailbox, spanning tree and outstanding-lazy table. Handlers therefore do not share a tree or block one another. Use [broadcast_groups](#broadcast_groups) instead when you need several handlers to share one group, an explicit group name, a dedicated channel, or per-group tick periods. #### channels Defines the channels to be used by Partisan. The option takes either a channels map where keys are channel names ({@link partisan:channel()}) and values are channel options ({@link partisan:channel_opts()}), or a list of values where each value can be any of the following types: * a channel name ({@link 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 optionparallelism' (which itself defaults to 1'), and the channel'smonotonic' 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 {@link partisan_full_membership_strategy} (Seemembership_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 {@link partisan_gen_server} that uses Partisan for distribution with {@link gen_server} that uses disterl. #### connection_interval Interval of time between peer connection attempts #### connection_jitter The delay in milliseconds a node waits before opening a connection, so that a cluster forming or healing at once does not produce a simultaneous rush of connections. Defaults to1000. With thejitteroption enabled the delay is randomised between1and this value; otherwise it is used as a fixed sleep. #### connection_ping A map containing the following keys: -{enabled, boolean()}- Whether pings are enabled. Default:true-{idle_timeout, non_neg_integer()}- time in milliseconds -{timeout, pos_integer()}- time in milliseconds -{max_attempts, pos_integer()}- Max number of retry attempts. #### disable_fast_forward Forces outbound messages through the peer service manager instead of the direct-to-connection path. Defaults tofalse. The fast path hands an encoded message straight to a connection process and does not run interposition functions, so fault injection that needs to observe, delay or drop outbound messages sets this totrue. It costs throughput and exists for testing. #### disable_fast_receive Forces inbound messages through the peer service manager instead of being delivered concurrently. Defaults tofalseunderm:partisan_pluggable_peer_service_managerandtrueunderm:partisan_hyparview_peer_service_manager. The receive-side counterpart of [disable_fast_forward](#disable_fast_forward): serialising delivery lets interposition functions observe every inbound message in order, at the cost of concurrency. #### distance_enabled Enables periodic distance measurement between peers. Defaults tofalse. The measurement interval is thedistance_intervaloption (default10000ms). #### egress_delay Milliseconds a connection process waits before writing a message to its socket. Defaults to0. An artificial latency injector for testing behaviour under a slow network. Leave at0in production. #### exchange_selection How a broadcast group picks the peer for an anti-entropy exchange. One of: *optimized(the default) — picks from members the tree does not already reach, i.e. excluding the eager and lazy peer sets for that tree. Exchanging with a peer the tree already covers is unlikely to find a difference, so this concentrates anti-entropy where divergence can actually be. *normal— picks from all members. #### exchange_tick_period Milliseconds between anti-entropy exchange attempts in a broadcast group. Defaults to10000. A group may override it in its own spec via the [broadcast_groups](#broadcast_groups) option. #### gossip Iftrue' gossip is used to disseminate membership to peers. Default is true'. At the moment used only by {@link partisan_full_membership_strategy}. #### hyparview The configuration for the {@link partisan_hyparview_peer_service_manager}. A list with the following properties: *active_max_size' - Defaults to 6'. *active_min_size' - Defaults to 3'. *active_rwl' - Active View Random Walk Length. Defaults to 6'. *passive_max_size' - Defaults to 30'. *passive_rwl' - Passive View Random Walk Length. Defaults to 6'. *random_promotion' - A boolean indicating if random promotion is enabled. Defaults true'. *random_promotion_interval' - Time after which the protocol attempts to promote a node in the passive view to the active view. Defaults to 5000'. *shuffle_interval' - Defaults to 10000'. *shuffle_k_active' - Number of peers to include in the shuffle exchange. Defaults to 3'. *shuffle_k_passive' - Number of peers to include in the shuffle exchange. Defaults to 4'. #### ingress_delay Milliseconds a connection process waits before handing a received message to the peer service manager. Defaults to0. The receive-side counterpart of [egress_delay](#egress_delay), and likewise for testing only. #### lazy_tick_period Milliseconds between flushes of a broadcast group's outstanding lazy pushes, each of which is sent as ani_haveannouncement. Defaults to1000. A group may override it in its own spec via the [broadcast_groups](#broadcast_groups) option. Lazy pushes are the repair half of the epidemic broadcast: a peer that receives ani_havefor a message it does not hold responds with a graft, which retrieves it. A longer period reduces announcement traffic and lengthens the window in which a missed message stays missed. #### listen_addrs A list of {@link partisan:listen_addr()} objects. This overrides [listen_ip](#listen_ip) and [listen_port](#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, thepeer_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 {@link 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 {@link 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 {@link 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. 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 {@link partisan:listen_addr()} in each peer [listen_addrs](#listen_addrs) option (when used) having the same port value. #### membership_binary_compression A boolean value or an integer in the range from0..9' to be used with {@link erlang:term_to_binary/2} when encoding the membership set for broadcast. A value of true' is equivalent to integer6' (equivalent to option compressed' in {@link erlang:term_to_binary/2}). A value offalse' is equivalent to 0' (no compression). Default istrue'.

membership_strategy

The membership strategy to be used with {@link partisan_pluggable_peer_service_manager}. Default is {@link partisan_full_membership_strategy}

membership_strategy_tracing

Enables tracing inside the membership strategy for the trace orchestrator. Defaults to false. Used by the fault-injection test suites; it has no purpose in production.

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 The module implementing peer discovery against an external orchestrator, for examplem:partisan_kubernetes_orchestration_strategy. Defaults toundefined, meaning no orchestration — peers are joined explicitly throughm:partisan_peer_service. #### parallelism The default number of connections to use per channel, when a channel hasn't been given a specificparallelism' value via the channels' option. The default is1'. For more information see option channels'. #### peer_service_manager The peer service manager to be used. An implementation of the {@link partisan_peer_service_manager} behaviour which defines the overlay network topology and the membership view maintenance strategy. Default is {@link partisan_pluggable_peer_service_manager}. #### periodic_enabled Enables the peer service manager's periodic maintenance tick, which drives connection retries and membership upkeep. Defaults totrue. The interval is [periodic_interval](#periodic_interval). #### periodic_interval Milliseconds between periodic maintenance ticks when [periodic_enabled](#periodic_enabled) is set. Defaults to10000. #### pid_encoding Whether a pid placed in a message is encoded as at:partisan_remote_ref:p/0before it goes on the wire. Defaults totrue. Encoding is what makes a pid meaningful on the receiving node: Partisan does not use Erlang distribution, so a raw pid term is not resolvable there. Disable it only when every pid in your messages is already an encoded reference, or when messages carry no pids at all. #### random_seed The seed for Partisan's randomness, as accepted byrand:seed/1. Defaults to a value generated at startup. Set it to make a test run reproducible. #### ref_encoding Whether a reference placed in a message is encoded as at:partisan_remote_ref:r/0before it goes on the wire. Defaults totrue. The reference counterpart of [pid_encoding](#pid_encoding). #### register_pid_for_encoding Registers a process under a generated name when its pid is encoded, so the resulting reference resolves by name rather than by pid. Defaults tofalse. This exists for deployments that restart processes and need a reference to survive the restart. It adds a registration per encoded pid, so it is off by default. #### remote_ref_format Defines how partisan remote references pids, references and registered names will be encoded. See {@link 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 byimproper_list'. In terms of latency tuple' is the fastest followed byimproper_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 Iftrue' 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 Set by the trace orchestrator while it replays a recorded trace. Defaults tofalse. Not intended to be set by hand. #### reservations Active-view slots reserved for peers carrying a given tag, as a list of tags — for example[server]. Defaults to[]. Used bym:partisan_hyparview_peer_service_managerto guarantee that peers of a particular role keep a place in the active view even as it churns. The list may not be longer than the HyParViewactive_max_size; the manager refuses to start withreservation_limit_exceededif it is. #### retransmit_interval When optionretransmission' is set to true' in thepartisan:forward_opts()' used in a call to {@link 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

Set by the property-based test harness while it shrinks a counterexample. Defaults to false. Not intended to be set by hand.

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 value *client' - 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}' #### max_message_size Maximum size in bytes of an inbound peer message frame. Frames larger than this are rejected before they are assembled or decoded, guarding against pre-authentication memory exhaustion and decompression bombs on the peer plane. The default is67108864' (64 MB).

tls

A boolean value indicating whether peer connections should use TLS. If enabled you must provide tls_client_options' andtls_server_options'. The default is false'. NOTE: for authenticated (non-MITM-able) clustering set{verify, verify_peer}' with a cluster CA on BOTH sides; verify_none' only encrypts and does NOT authenticate the peer. #### 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_peer} ]} ''' #### tls_handshake_timeout Timeout in milliseconds for the server-side TLS handshake on an inbound peer connection. Bounds a stalled handshake so it cannot pin an acceptor. The default is `5000'. #### 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_peer}, {fail_if_no_peer_cert, true} ]} '''

tracing

a boolean value. The default is false'. #### xbot_interval Milliseconds between rounds of the X-BOT active-view optimisation inm:partisan_hyparview_peer_service_manager, which tries to replace an active-view peer with a closer one. ## Deprecated options The following options are deprecated. Some have been renamed, or moved down a level in the configuration tree. #### arwl HyParView's Active View Random Walk Length. Defaults to6'. Use active_rwl' in thehyparview' 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'. Useactive_max_size' in the hyparview' option instead. #### max_passive_size HyParView's Active View Random Walk Length. Defaults to30'. Use passive_max_size' in thehyparview' option instead.

mix_active_size

HyParView's Active View Random Walk Length. Defaults to 3'. Useactive_min_size' in the hyparview' option instead. #### passive_view_shuffle_period Useshuffle_interval' in the hyparview' option instead. #### peer_ip Use [listen_ip](#listen_ip) instead. #### peer_port Use [listen_port](#listen_port) instead. #### peer_host Use [listen_addrs](#listen_addrs) instead. #### partisan_peer_service_manager Usepeer_service_manager' instead.

prwl

HyParView's Passive View Random Walk Length. Defaults to 6'. Usepassive_rwl' in the hyparview' option instead. #### random_promotion Userandom_promotion' in the hyparview' option instead. #### random_promotion_period Userandom_promotion_interval' in the hyparview' option instead. #### remote_ref_as_uri Use{remote_ref_format, uri}' instead