If you're new to Mesos
See the getting started page for more information about downloading, building, and deploying Mesos.
If you'd like to get involved or you're looking for support
See our community page for more details.
Mesos Configuration
The Mesos master and agent can take a variety of configuration options
through command-line arguments, or environment variables. A list of
the available options can be seen by running mesos-master --help
or
mesos-agent --help
. Each option can be set in two ways:
By passing it to the binary using
--option_name=value
, either specifying the value directly, or specifying a file in which the value resides (--option_name=file://path/to/file
). The path can be absolute or relative to the current working directory.By setting the environment variable
MESOS_OPTION_NAME
(the option name with aMESOS_
prefix added to it).
Configuration values are searched for first in the environment, then on the command-line.
Important Options
If you have special compilation requirements, please refer to
./configure --help
when configuring Mesos. Additionally, this
documentation lists only a recent snapshot of the options in Mesos. A
definitive source for which flags your version of Mesos supports can
be found by running the binary with the flag --help
, for example
mesos-master --help
.
Master and Agent Options
These options can be supplied to both masters and agents.
Flag | Explanation |
---|---|
--advertise_ip=VALUE | IP address advertised to reach this Mesos master/agent. The master/agent does not bind to this IP address. However, this IP address may be used to access this master/agent. |
--advertise_port=VALUE |
Port advertised to reach this Mesos master/agent (along with
advertise_ip ). The master/agent does not bind using this port.
However, this port (along with advertise_ip ) may be used to
access Mesos master/agent.
|
--[no-]authenticate_http_readonly |
If true , only authenticated requests for read-only HTTP endpoints
supporting authentication are allowed. If false , unauthenticated
requests to such HTTP endpoints are also allowed.
|
--[no-]authenticate_http_readwrite |
If true , only authenticated requests for read-write HTTP endpoints
supporting authentication are allowed. If false , unauthenticated
requests to such HTTP endpoints are also allowed.
|
--firewall_rules=VALUE |
The value could be a JSON-formatted string of rules or a
file path containing the JSON-formatted rules used in the endpoints
firewall. Path must be of the form file:///path/to/file
or /path/to/file .
See the Firewall message in flags.proto for the expected format.
Example:
|
--[no-]help | Show the help message and exit. (default: false) |
--http_authenticators=VALUE |
HTTP authenticator implementation to use when handling requests to
authenticated endpoints. Use the default
basic , or load an alternate
HTTP authenticator module using --modules .
(default: basic, or basic and JWT if executor authentication is enabled)
|
--ip=VALUE |
IP address to listen on. This cannot be used in conjunction
with --ip_discovery_command . (master default: 5050; agent default: 5051)
|
--ip_discovery_command=VALUE |
Optional IP discovery binary: if set, it is expected to emit
the IP address which the master/agent will try to bind to.
Cannot be used in conjunction with --ip .
|
--modules_dir=VALUE |
Directory path of the module manifest files. The manifest files are processed in
alphabetical order. (See --modules for more information on module
manifest files) Cannot be used in conjunction with --modules .
|
--port=VALUE | Port to listen on. |
--[no-]version | Show version and exit. (default: false) |
--hooks=VALUE | A comma-separated list of hook modules to be installed inside master/agent. |
--hostname=VALUE |
The hostname the agent node should report, or that the master
should advertise in ZooKeeper.
If left unset, the hostname is resolved from the IP address
that the master/agent binds to; unless the user explicitly prevents
that, using --no-hostname_lookup , in which case the IP itself
is used.
|
--[no-]hostname_lookup |
Whether we should execute a lookup to find out the server's hostname,
if not explicitly set (via, e.g., --hostname ).
True by default; if set to false it will cause Mesos
to use the IP address, unless the hostname is explicitly set. (default: true)
|
--modules=VALUE |
List of modules to be loaded and be available to the internal
subsystems.
Use --modules=filepath to specify the list of modules via a
file containing a JSON-formatted string. filepath can be
of the form file:///path/to/file or /path/to/file .
Use --modules="{...}" to specify the list of modules inline.
Example:
Cannot be used in conjunction with --modules_dir.
|
These logging options can also be supplied to both masters and agents. For more about logging, see the logging documentation.
Flag | Explanation |
---|---|
--[no-]quiet | Disable logging to stderr (default: false) |
--log_dir=VALUE | Location to put log files. By default, nothing is written to disk. Does not affect logging to stderr. If specified, the log file will appear in the Mesos WebUI. NOTE: 3rd party log messages (e.g. ZooKeeper) are only written to stderr! |
--logbufsecs=VALUE | Maximum number of seconds that logs may be buffered for. By default, logs are flushed immediately. (default: 0) |
--logging_level=VALUE |
Log message at or above this level.
Possible values: INFO , WARNING , ERROR .
If --quiet is specified, this will only affect the logs
written to --log_dir , if specified. (default: INFO)
|
--[no-]initialize_driver_logging | Whether the master/agent should initialize Google logging for the Mesos scheduler and executor drivers, in same way as described here. The scheduler/executor drivers have separate logs and do not get written to the master/agent logs. This option has no effect when using the HTTP scheduler/executor APIs. (default: true) |
--external_log_file=VALUE |
Location of the externally managed log file. Mesos does not write to
this file directly and merely exposes it in the WebUI and HTTP API.
This is only useful when logging to stderr in combination with an
external logging mechanism, like syslog or journald.
This option is meaningless when specified along with --quiet .
This option takes precedence over --log_dir in the WebUI.
However, logs will still be written to the --log_dir if
that option is specified.
|
Master Options
Required Flags
Flag | Explanation |
---|---|
--quorum=VALUE |
The size of the quorum of replicas when using replicated_log based
registry. It is imperative to set this value to be a majority of
masters i.e., quorum > (number of masters)/2 .
NOTE: Not required if master is run in standalone mode (non-HA).
|
--work_dir=VALUE |
Path of the master work directory. This is where the persistent
information of the cluster will be stored. Note that locations like
/tmp which are cleaned automatically are not suitable for the work
directory when running in production, since long-running masters could
lose data when cleanup occurs. (Example: /var/lib/mesos/master )
|
--zk=VALUE |
ZooKeeper URL (used for leader election amongst masters)
May be one of:
NOTE: Not required if master is run in standalone mode (non-HA).
|
Optional Flags
Flag | Explanation |
---|---|
--acls=VALUE |
The value could be a JSON-formatted string of ACLs
or a file path containing the JSON-formatted ACLs used
for authorization. Path could be of the form file:///path/to/file
or /path/to/file .
Note that if the flag --authorizers is provided with a value
different than local , the ACLs contents will be
ignored.
See the ACLs protobuf in acls.proto for the expected format.
Example:
|
--agent_ping_timeout=VALUE, --slave_ping_timeout=VALUE |
The timeout within which an agent is expected to respond to a
ping from the master. Agents that do not respond within
max_agent_ping_timeouts ping retries will be asked to shutdown.
NOTE: The total ping timeout (agent_ping_timeout multiplied by
max_agent_ping_timeouts ) should be greater than the ZooKeeper
session timeout to prevent useless re-registration attempts.
(default: 15secs)
|
--agent_removal_rate_limit=VALUE --slave_removal_rate_limit=VALUE |
The maximum rate (e.g., 1/10mins , 2/3hrs , etc) at which agents
will be removed from the master when they fail health checks.
By default, agents will be removed as soon as they fail the health
checks. The value is of the form (Number of agents)/(Duration) .
|
--agent_reregister_timeout=VALUE --slave_reregister_timeout=VALUE | The timeout within which an agent is expected to re-register. Agents re-register when they become disconnected from the master or when a new master is elected as the leader. Agents that do not re-register within the timeout will be marked unreachable in the registry; if/when the agent re-registers with the master, any non-partition-aware tasks running on the agent will be terminated. NOTE: This value has to be at least 10mins. (default: 10mins) |
--allocation_interval=VALUE | Amount of time to wait between performing (batch) allocations (e.g., 500ms, 1sec, etc). (default: 1secs) |
--allocator=VALUE |
Allocator to use for resource allocation to frameworks.
Use the default HierarchicalDRF allocator, or
load an alternate allocator module using --modules .
(default: HierarchicalDRF)
|
--[no-]authenticate_agents, --[no-]authenticate_slaves |
If true only authenticated agents are allowed to register.
If false unauthenticated agents are also allowed to register. (default: false)
|
--[no-]authenticate_frameworks, --[no-]authenticate |
If true , only authenticated frameworks are allowed to register. If
false , unauthenticated frameworks are also allowed to register. For
HTTP based frameworks use the --authenticate_http_frameworks flag. (default: false)
|
--[no-]authenticate_http_frameworks |
If true , only authenticated HTTP based frameworks are allowed to
register. If false , HTTP frameworks are not authenticated. (default: false)
|
--authenticators=VALUE |
Authenticator implementation to use when authenticating frameworks
and/or agents. Use the default crammd5 , or
load an alternate authenticator module using --modules . (default: crammd5)
|
--authorizers=VALUE |
Authorizer implementation to use when authorizing actions that
require it.
Use the default local , or
load an alternate authorizer module using --modules .
Note that if the flag --authorizers is provided with a value
different than the default local , the ACLs
passed through the --acls flag will be ignored.
Currently there's no support for multiple authorizers. (default: local)
|
--cluster=VALUE | Human readable name for the cluster, displayed in the webui. |
--credentials=VALUE |
Path to a JSON-formatted file containing credentials.
Path can be of the form file:///path/to/file or /path/to/file .
Example:
|
--fair_sharing_excluded_resource_names=VALUE | A comma-separated list of the resource names (e.g. 'gpus') that will be excluded from fair sharing constraints. This may be useful in cases where the fair sharing implementation currently has limitations. E.g. See the problem of "scarce" resources: msg35631 MESOS-5377 |
--framework_sorter=VALUE | Policy to use for allocating resources between a given user's frameworks. Options are the same as for user_allocator. (default: drf) |
--http_framework_authenticators=VALUE |
HTTP authenticator implementation to use when authenticating HTTP frameworks.
Use the basic authenticator or load an alternate HTTP authenticator
module using --modules . This must be used in conjunction with
--authenticate_http_frameworks .
Currently there is no support for multiple HTTP authenticators.
|
--[no-]log_auto_initialize | Whether to automatically initialize the [replicated log](/documentation/latest/./replicated-log-internals/) used for the registry. If this is set to false, the log has to be manually initialized when used for the very first time. (default: true) |
--master_contender=VALUE |
The symbol name of the master contender to use. This symbol should exist in a
module specified through the --modules flag. Cannot be used in
conjunction with --zk . Must be used in conjunction with
--master_detector .
|
--master_detector=VALUE |
The symbol name of the master detector to use. This symbol should exist in a
module specified through the --modules flag. Cannot be used in
conjunction with --zk . Must be used in conjunction with
--master_contender .
|
--max_agent_ping_timeouts=VALUE, --max_slave_ping_timeouts=VALUE |
The number of times an agent can fail to respond to a
ping from the master. Agents that do not respond within
max_agent_ping_timeouts ping retries will be asked to shutdown.
(default: 5)
|
--max_completed_frameworks=VALUE | Maximum number of completed frameworks to store in memory. (default: 50) |
--max_completed_tasks_per_framework=VALUE | Maximum number of completed tasks per framework to store in memory. (default: 1000) |
--max_unreachable_tasks_per_framework=VALUE | Maximum number of unreachable tasks per framework to store in memory. (default: 1000) |
--offer_timeout=VALUE | Duration of time before an offer is rescinded from a framework. This helps fairness when running frameworks that hold on to offers, or frameworks that accidentally drop offers. If not set, offers do not timeout. |
--rate_limits=VALUE |
The value could be a JSON-formatted string of rate limits
or a file path containing the JSON-formatted rate limits used
for framework rate limiting.
Path could be of the form file:///path/to/file
or /path/to/file .
See the RateLimits protobuf in mesos.proto for the expected format.
Example:
|
--recovery_agent_removal_limit=VALUE, --recovery_slave_removal_limit=VALUE | For failovers, limit on the percentage of agents that can be removed from the registry *and* shutdown after the re-registration timeout elapses. If the limit is exceeded, the master will fail over rather than remove the agents. This can be used to provide safety guarantees for production environments. Production environments may expect that across master failovers, at most a certain percentage of agents will fail permanently (e.g. due to rack-level failures). Setting this limit would ensure that a human needs to get involved should an unexpected widespread failure of agents occur in the cluster. Values: [0%-100%] (default: 100%) |
--registry=VALUE |
Persistence strategy for the registry; available options are
replicated_log , in_memory (for testing). (default: replicated_log)
|
--registry_fetch_timeout=VALUE | Duration of time to wait in order to fetch data from the registry after which the operation is considered a failure. (default: 1mins) |
--registry_store_timeout=VALUE | Duration of time to wait in order to store data in the registry after which the operation is considered a failure. (default: 20secs) |
--roles=VALUE | A comma-separated list of the allocation roles that frameworks in this cluster may belong to. This flag is deprecated; if it is not specified, any role name can be used. |
--[no-]root_submissions | Can root submit frameworks? (default: true) |
--user_sorter=VALUE | Policy to use for allocating resources between users. May be one of: dominant_resource_fairness (drf) (default: drf) |
--webui_dir=VALUE | Directory path of the webui files/assets (default: /usr/local/share/mesos/webui) |
--weights=VALUE |
A comma-separated list of role/weight pairs of the form
role=weight,role=weight . Weights can be used to control the
relative share of cluster resources that is offered to different roles. This
flag is deprecated. Instead, operators should configure weights dynamically
using the /weights HTTP endpoint.
|
--whitelist=VALUE |
Path to a file which contains a list of agents (one per line) to
advertise offers for. The file is watched, and periodically re-read to
refresh the agent whitelist. By default there is no whitelist / all
machines are accepted. Path could be of the form
file:///path/to/file or /path/to/file .
|
--zk_session_timeout=VALUE | ZooKeeper session timeout. (default: 10secs) |
Flags available when configured with --with-network-isolator
Flag | Explanation |
---|---|
--max_executors_per_agent=VALUE, --max_executors_per_slave=VALUE | Maximum number of executors allowed per agent. The network monitoring/isolation technique imposes an implicit resource acquisition on each executor (# ephemeral ports), as a result one can only run a certain number of executors on each agent. |
Agent Options
Required Flags
Flag | Explanation |
---|---|
--master=VALUE |
May be one of:
host:port
zk://host1:port1,host2:port2,.../path
zk://username:password@host1:port1,host2:port2,.../path
file:///path/to/file (where file contains one of the above)
|
--work_dir=VALUE |
Path of the agent work directory. This is where executor sandboxes
will be placed, as well as the agent's checkpointed state in case of
failover. Note that locations like /tmp which are cleaned
automatically are not suitable for the work directory when running in
production, since long-running agents could lose data when cleanup
occurs. (Example: /var/lib/mesos/agent )
|
Optional Flags
Flags available when configured with --with-network-isolator
Flag | Explanation |
---|---|
--ephemeral_ports_per_container=VALUE |
Number of ephemeral ports allocated to a container by the network
isolator. This number has to be a power of 2. This flag is used
for the network/port_mapping isolator. (default: 1024)
|
--eth0_name=VALUE |
The name of the public network interface (e.g., eth0 ). If it is
not specified, the network isolator will try to guess it based
on the host default gateway. This flag is used for the
network/port_mapping isolator.
|
--lo_name=VALUE |
The name of the loopback network interface (e.g., lo). If it is
not specified, the network isolator will try to guess it. This
flag is used for the network/port_mapping isolator.
|
--egress_rate_limit_per_container=VALUE |
The limit of the egress traffic for each container, in Bytes/s.
If not specified or specified as zero, the network isolator will
impose no limits to containers' egress traffic throughput.
This flag uses the Bytes type (defined in stout) and is used for
the network/port_mapping isolator.
|
--[no-]egress_unique_flow_per_container |
Whether to assign an individual flow for each container for the
egress traffic. This flag is used for the network/port_mapping
isolator. (default: false)
|
--egress_flow_classifier_parent=VALUE |
When egress_unique_flow_per_container is enabled, we need to install
a flow classifier (fq_codel) qdisc on egress side. This flag specifies
where to install it in the hierarchy. By default, we install it at root.
|
--[no-]network_enable_socket_statistics_summary |
Whether to collect socket statistics summary for each container.
This flag is used for the network/port_mapping isolator.
(default: false)
|
--[no-]network_enable_socket_statistics_details |
Whether to collect socket statistics details (e.g., TCP RTT) for
each container. This flag is used for the network/port_mapping
isolator. (default: false)
|
--[no-]network_enable_snmp_statistics | Whether to collect SNMP statistics details (e.g., TCPRetransSegs) for each container. This flag is used for the 'network/port_mapping' isolator. (default: false) |
XFS disk isolator flags available when configured with
--enable-xfs-disk-isolator
Flag | Explanation |
---|---|
--xfs_project_range=VALUE | The ranges of XFS project IDs that the isolator can use to track disk quotas for container sandbox directories. Valid project IDs range from 1 to max(uint32). (default `[5000-10000]`) |
Libprocess Options
The bundled libprocess library can be controlled with the following environment variables.
Variable | Explanation |
---|---|
LIBPROCESS_IP | Sets the IP address for communication to and from libprocess. |
LIBPROCESS_PORT | Sets the port for communication to and from libprocess. |
LIBPROCESS_ADVERTISE_IP | If set, this provides the IP address that will be advertised to the outside world for communication to and from libprocess. This is useful, for example, for containerized tasks in which communication is bound locally to a non-public IP that will be inaccessible to the master. |
LIBPROCESS_ADVERTISE_PORT | If set, this provides the port that will be advertised to the outside world for communication to and from libprocess. Note that this port will not actually be bound (the local LIBPROCESS_PORT will be), so redirection to the local IP and port must be provided separately. |
LIBPROCESS_ENABLE_PROFILER |
To enable the profiler, this variable must be set to 1. Note that this
variable will only work if Mesos has been configured with
--enable-perftools .
|
LIBPROCESS_METRICS_SNAPSHOT_ENDPOINT_RATE_LIMIT |
If set, this variable can be used to configure the rate limit
applied to the /metrics/snapshot endpoint. The format is
` |
LIBPROCESS_NUM_WORKER_THREADS | If set to an integer value in the range 1 to 1024, it overrides the default setting of the number of libprocess worker threads, which is the maximum of 8 and the number of cores on the machine. |
Mesos Autotools Build Configuration Options
Autotools configure
script options
Flag | Explanation |
---|---|
--enable-static[=PKGS] | Build static libraries. [default=yes] |
--enable-dependency-tracking | Do not reject slow dependency extractors. |
--disable-dependency-tracking | Speeds up one-time build. |
--enable-silent-rules | Less verbose build output (undo: "make V=1"). |
--disable-silent-rules | Verbose build output (undo: "make V=0"). |
--disable-maintainer-mode | Disable make rules and dependencies not useful (and sometimes confusing) to the casual installer. |
--enable-shared[=PKGS] | Build shared libraries. [default=yes] |
--enable-fast-install[=PKGS] | Optimize for fast installation. [default=yes] |
--disable-libtool-lock | Avoid locking. Note that this might break parallel builds. |
--disable-bundled | Configures Mesos to build against preinstalled dependencies instead of bundled libraries. |
--disable-bundled-pip |
Excludes building and using the bundled pip package in lieu of an
installed version in PYTHONPATH .
|
--disable-bundled-setuptools |
Excludes building and using the bundled setuptools package in lieu of an
installed version in PYTHONPATH .
|
--disable-bundled-wheel |
Excludes building and using the bundled wheel package in lieu of an
installed version in PYTHONPATH .
|
--enable-debug | Whether debugging is enabled. If CFLAGS/CXXFLAGS are set, this option won't change them. [default=no] |
--disable-java | Don't build Java bindings. |
--enable-libevent | Use libevent instead of libev for the libprocess event loop. Note that the libevent version 2+ development package is required. [default=no] |
--enable-install-module-dependencies | Install third-party bundled dependencies required for module development. [default=no] |
--enable-optimize | Whether optimizations are enabled. If CFLAGS/CXXFLAGS are set, this option won't change them. [default=no] |
--enable-perftools | Whether profiling with Google perftools is enabled. [default=no] |
--disable-python | Don't build Python bindings. |
--disable-python-dependency-install | When the python packages are installed during make install, no external dependencies will be downloaded or installed. |
--enable-ssl |
Enable SSL for libprocess
communication. Note that --enable-libevent is currently
required for SSL functionality. [default=no]
|
--enable-static-unimplemented | Generate static assertion errors for unimplemented functions. [default=no] |
--enable-tests-install | Build and install tests and their helper tools. [default=no] |
--enable-xfs-disk-isolator | Builds the XFS disk isolator. [default=no] |
--disable-zlib | Disables zlib compression, which means the webui will be far less responsive; not recommended. |
Autotools configure
script optional package flags
Flag | Explanation |
---|---|
--with-gnu-ld |
Assume the C compiler uses GNU ld . [default=no]
|
--with-sysroot=DIR |
Search for dependent libraries within DIR
(or the compiler's sysroot if not specified).
|
--with-apr=[=DIR] | Specify where to locate the apr-1 library. |
--with-boost[=DIR] | Excludes building and using the bundled Boost package in lieu of an installed version at a location prefixed by the given path. |
--with-curl=[=DIR] | Specify where to locate the curl library. |
--with-elfio[=DIR] | Excludes building and using the bundled ELFIO package in lieu of an installed version at a location prefixed by the given path. |
--with-glog[=DIR] | excludes building and using the bundled glog package in lieu of an installed version at a location prefixed by the given path. |
--with-gmock[=DIR] | Excludes building and using the bundled gmock package in lieu of an installed version at a location prefixed by the given path. |
--with-http-parser[=DIR] | Excludes building and using the bundled http-parser package in lieu of an installed version at a location prefixed by the given path. |
--with-leveldb[=DIR] | Excludes building and using the bundled LevelDB package in lieu of an installed version at a location prefixed by the given path. |
--with-libev[=DIR] | Excludes building and using the bundled libev package in lieu of an installed version at a location prefixed by the given path. |
--with-libevent=[=DIR] | Specify where to locate the libevent library. |
--with-libprocess=[=DIR] | Specify where to locate the libprocess library. |
--with-network-isolator | Builds the network isolator. |
--with-nl=[DIR] | Specify where to locate the libnl3 library, which is required for the network isolator. |
--with-nvml[=DIR] | Excludes building and using the bundled NVML headers in lieu of an installed version at a location prefixed by the given path. |
--with-picojson[=DIR] | Excludes building and using the bundled picojson package in lieu of an installed version at a location prefixed by the given path. |
--with-protobuf[=DIR] | Excludes building and using the bundled protobuf package in lieu of an installed version at a location prefixed by the given path. |
--with-sasl=[=DIR] | Specify where to locate the sasl2 library. |
--with-ssl=[=DIR] | Specify where to locate the ssl library. |
--with-stout=[=DIR] | Specify where to locate stout library. |
--with-svn=[=DIR] | Specify where to locate the svn-1 library. |
--with-zlib=[=DIR] | Specify where to locate the zlib library. |
--with-zookeeper[=DIR] | Excludes building and using the bundled ZooKeeper package in lieu of an installed version at a location prefixed by the given path. |
Environment variables which affect the Autotools configure
script
Use these variables to override the choices made by configure
or to help
it to find libraries and programs with nonstandard names/locations.
Variable | Explanation |
---|---|
JAVA_HOME | Location of Java Development Kit (JDK). |
JAVA_CPPFLAGS | Preprocessor flags for JNI. |
JAVA_JVM_LIBRARY |
Full path to libjvm.so .
|
MAVEN_HOME |
Looks for mvn at MAVEN_HOME/bin/mvn .
|
PROTOBUF_JAR | Full path to protobuf jar on prefixed builds. |
PYTHON | Which Python interpreter to use. |
PYTHON_VERSION | The installed Python version to use, for example '2.3'. This string will be appended to the Python interpreter canonical name. |