.. _operations_cli:
Command line options
====================
Envoy is driven both by a JSON configuration file as well as a set of command line options. The
following are the command line options that Envoy supports.
.. option:: -c <path string>, --config-path <path string>
*(optional)* The path to the v2 :ref:`JSON/YAML/proto3 configuration
file <config>`. If this flag is missing, :option:`--config-yaml` is required.
This will be parsed as a :ref:`v2 bootstrap configuration file
<config_overview_v2_bootstrap>`.
Valid extensions are ``.json``, ``.yaml``, ``.pb`` and ``.pb_text``, which indicate
JSON, YAML, `binary proto3
<https://developers.google.com/protocol-buffers/docs/encoding>`_ and `text
proto3
<https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.text_format>`_
formats respectively.
.. option:: --config-yaml <yaml string>
*(optional)* The YAML string for a v2 bootstrap configuration. If :option:`--config-path` is also set,
the values in this YAML string will override and merge with the bootstrap loaded from :option:`--config-path`.
Because YAML is a superset of JSON, a JSON string may also be passed to :option:`--config-yaml`.
Example overriding the node id on the command line:
.. code-block:: console
./envoy -c bootstrap.yaml --config-yaml "node: {id: 'node1'}"
.. option:: --mode <string>
*(optional)* One of the operating modes for Envoy:
* ``serve``: *(default)* Validate the JSON configuration and then serve traffic normally.
* ``validate``: Validate the JSON configuration and then exit, printing either an "OK" message (in
which case the exit code is 0) or any errors generated by the configuration file (exit code 1).
No network traffic is generated, and the hot restart process is not performed, so no other Envoy
process on the machine will be disturbed.
.. option:: --admin-address-path <path string>
*(optional)* The output file path where the admin address and port will be written.
.. option:: --local-address-ip-version <string>
*(optional)* The IP address version that is used to populate the server local IP address. This
parameter affects various headers including what is appended to the X-Forwarded-For (XFF) header.
The options are ``v4`` or ``v6``. The default is ``v4``.
.. option:: --base-id <integer>
*(optional)* The base ID to use when allocating shared memory regions. Envoy uses shared memory
regions during :ref:`hot restart <arch_overview_hot_restart>`. Most users will never have to
set this option. However, if Envoy needs to be run multiple times on the same machine, each
running Envoy will need a unique base ID so that the shared memory regions do not conflict.
.. option:: --concurrency <integer>
*(optional)* The number of :ref:`worker threads <arch_overview_threading>` to run. If not
specified defaults to the number of hardware threads on the machine.
.. option:: -l <string>, --log-level <string>
*(optional)* The logging level. Non developers should generally never set this option. See the
help text for the available log levels and the default.
.. option:: --component-log-level <string>
*(optional)* The comma separated list of logging level per component. Non developers should generally
never set this option. For example, if you want `upstream` component to run at `debug` level and
`connection` component to run at `trace` level, you should pass ``upstream:debug,connection:trace`` to
this flag. See ``ALL_LOGGER_IDS`` in :repo:`/source/common/common/logger.h` for a list of components.
.. option:: --cpuset-threads
*(optional)* This flag is used to control the number of worker threads if :option:`--concurrency` is
not set. If enabled, the assigned cpuset size is used to determine the number of worker threads on
Linux-based systems. Otherwise the number of worker threads is set to the number of hardware threads
on the machine. You can read more about cpusets in the
`kernel documentation <https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.txt>`_.
.. option:: --log-path <path string>
*(optional)* The output file path where logs should be written. This file will be re-opened
when SIGUSR1 is handled. If this is not set, log to stderr.
.. option:: --log-format <format string>
*(optional)* The format string to use for laying out the log message metadata. If this is not
set, a default format string ``"[%Y-%m-%d %T.%e][%t][%l][%n] %v"`` is used.
The supported format flags are (with example output):
:%v: The actual message to log ("some user text")
:%t: Thread id ("1232")
:%P: Process id ("3456")
:%n: Logger's name ("filter")
:%l: The log level of the message ("debug", "info", etc.)
:%L: Short log level of the message ("D", "I", etc.)
:%a: Abbreviated weekday name ("Tue")
:%A: Full weekday name ("Tuesday")
:%b: Abbreviated month name ("Mar")
:%B: Full month name ("March")
:%c: Date and time representation ("Tue Mar 27 15:25:06 2018")
:%C: Year in 2 digits ("18")
:%Y: Year in 4 digits ("2018")
:%D, %x: Short MM/DD/YY date ("03/27/18")
:%m: Month 01-12 ("03")
:%d: Day of month 01-31 ("27")
:%H: Hours in 24 format 00-23 ("15")
:%I: Hours in 12 format 01-12 ("03")
:%M: Minutes 00-59 ("25")
:%S: Seconds 00-59 ("06")
:%e: Millisecond part of the current second 000-999 ("008")
:%f: Microsecond part of the current second 000000-999999 ("008789")
:%F: Nanosecond part of the current second 000000000-999999999 ("008789123")
:%p: AM/PM ("AM")
:%r: 12-hour clock ("03:25:06 PM")
:%R: 24-hour HH:MM time, equivalent to %H:%M ("15:25")
:%T, %X: ISO 8601 time format (HH:MM:SS), equivalent to %H:%M:%S ("13:25:06")
:%z: ISO 8601 offset from UTC in timezone ([+/-]HH:MM) ("-07:00")
:%%: The % sign ("%")
.. option:: --restart-epoch <integer>
*(optional)* The :ref:`hot restart <arch_overview_hot_restart>` epoch. (The number of times
Envoy has been hot restarted instead of a fresh start). Defaults to 0 for the first start. This
option tells Envoy whether to attempt to create the shared memory region needed for hot restart,
or whether to open an existing one. It should be incremented every time a hot restart takes place.
The :ref:`hot restart wrapper <operations_hot_restarter>` sets the *RESTART_EPOCH* environment
variable which should be passed to this option in most cases.
.. option:: --hot-restart-version
*(optional)* Outputs an opaque hot restart compatibility version for the binary. This can be
matched against the output of the :http:get:`/hot_restart_version` admin endpoint to determine
whether the new binary and the running binary are hot restart compatible.
.. option:: --service-cluster <string>
*(optional)* Defines the local service cluster name where Envoy is running. The
local service cluster name is first sourced from the :ref:`Bootstrap node
<envoy_api_field_config.bootstrap.v2.Bootstrap.node>` message's :ref:`cluster
<envoy_api_field_core.Node.cluster>` field. This CLI option provides an alternative
method for specifying this value and will override any value set in bootstrap
configuration. It should be set if any of the following features are used:
:ref:`statsd <arch_overview_statistics>`, :ref:`health check cluster
verification <envoy_api_field_core.HealthCheck.HttpHealthCheck.service_name>`,
:ref:`runtime override directory <envoy_api_msg_config.bootstrap.v2.Runtime>`,
:ref:`user agent addition
<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.add_user_agent>`,
:ref:`HTTP global rate limiting <config_http_filters_rate_limit>`,
:ref:`CDS <config_cluster_manager_cds>`, and :ref:`HTTP tracing
<arch_overview_tracing>`, either via this CLI option or in the bootstrap
configuration.
.. option:: --service-node <string>
*(optional)* Defines the local service node name where Envoy is running. The
local service node name is first sourced from the :ref:`Bootstrap node
<envoy_api_field_config.bootstrap.v2.Bootstrap.node>` message's :ref:`id
<envoy_api_field_core.Node.id>` field. This CLI option provides an alternative
method for specifying this value and will override any value set in bootstrap
configuration. It should be set if any of the following features are used:
:ref:`statsd <arch_overview_statistics>`, :ref:`CDS
<config_cluster_manager_cds>`, and :ref:`HTTP tracing
<arch_overview_tracing>`, either via this CLI option or in the bootstrap
configuration.
.. option:: --service-zone <string>
*(optional)* Defines the local service zone where Envoy is running. The local
service zone is first sourced from the :ref:`Bootstrap node
<envoy_api_field_config.bootstrap.v2.Bootstrap.node>` message's :ref:`locality.zone
<envoy_api_field_core.Locality.zone>` field. This CLI option provides an
alternative method for specifying this value and will override any value set
in bootstrap configuration. It should be set if discovery service routing is
used and the discovery service exposes :ref:`zone data
<envoy_api_msg_endpoint.LocalityLbEndpoints>`, either via this CLI option or in
the bootstrap configuration. The meaning of zone is context dependent, e.g.
`Availability Zone (AZ)
<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html>`_
on AWS, `Zone <https://cloud.google.com/compute/docs/regions-zones/>`_ on GCP,
etc.
.. option:: --file-flush-interval-msec <integer>
*(optional)* The file flushing interval in milliseconds. Defaults to 10 seconds.
This setting is used during file creation to determine the duration between flushes
of buffers to files. The buffer will flush every time it gets full, or every time
the interval has elapsed, whichever comes first. Adjusting this setting is useful
when tailing :ref:`access logs <arch_overview_access_logs>` in order to
get more (or less) immediate flushing.
.. option:: --drain-time-s <integer>
*(optional)* The time in seconds that Envoy will drain connections during
a :ref:`hot restart <arch_overview_hot_restart>` or when individual listeners are being
modified or removed via :ref:`LDS <arch_overview_dynamic_config_lds>`.
Defaults to 600 seconds (10 minutes). Generally the drain time should be less than
the parent shutdown time set via the :option:`--parent-shutdown-time-s` option. How the two
settings are configured depends on the specific deployment. In edge scenarios, it might be
desirable to have a very long drain time. In service to service scenarios, it might be possible
to make the drain and shutdown ime much shorter (e.g., 60s/90s).
.. option:: --parent-shutdown-time-s <integer>
*(optional)* The time in seconds that Envoy will wait before shutting down the parent process
during a hot restart. See the :ref:`hot restart overview <arch_overview_hot_restart>` for more
information. Defaults to 900 seconds (15 minutes).
.. option:: --disable-hot-restart
*(optional)* This flag disables Envoy hot restart for builds that have it enabled. By default, hot
restart is enabled.
.. option:: --enable-mutex-tracing
*(optional)* This flag enables the collection of mutex contention statistics
(:ref:`MutexStats <envoy_api_msg_admin.v2alpha.MutexStats>`) as well as a contention endpoint
(:http:get:`/contention`). Mutex tracing is not enabled by default, since it incurs a slight performance
penalty for those Envoys which already experience mutex contention.
.. option:: --allow-unknown-fields
*(optional)* Deprecated alias for :option:`--allow-unknown-static-fields`.
.. option:: --allow-unknown-static-fields
*(optional)* This flag disables validation of protobuf configurations for unknown fields. By default, the
validation is enabled. For most deployments, the default should be used which ensures configuration errors
are caught upfront and Envoy is configured as intended. Warnings are logged for the first use of
any unknown field and these occurrences are counted in the :ref:`server.static_unknown_fields
<server_statistics>` statistic.
.. option:: --reject-unknown-dynamic-fields
*(optional)* This flag disables validation of protobuf configuration for unknown fields in
dynamic configuration. By default, this flag is set false, disabling validation for fields beyond
bootstrap. This allows newer xDS configurations to be delivered to older Envoys. This can be set
true for strict dynamic checking when this behavior is not wanted but the default should be
desirable for most Envoy deployments. Warnings are logged for the first use of any unknown field
and these occurrences are counted in the :ref:`server.dynamic_unknown_fields <server_statistics>`
statistic.
.. option:: --version
*(optional)* This flag is used to display Envoy version and build information, e.g.
``c93f9f6c1e5adddd10a3e3646c7e049c649ae177/1.9.0-dev/Clean/RELEASE/BoringSSL-FIPS``.
It consists of five slash-separated fields:
* source revision - git commit from which Envoy was built,
* release number - either release (e.g. ``1.9.0``) or a development build (e.g. ``1.9.0-dev``),
* status of the source tree at the build time - either ``Clean`` or ``Modified``,
* build mode - either ``RELEASE`` or ``DEBUG``,
* TLS library - either ``BoringSSL`` or ``BoringSSL-FIPS``.