You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
182 lines
9.1 KiB
182 lines
9.1 KiB
.. _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> |
|
|
|
*(required)* The path to the v1 or v2 :ref:`JSON/YAML/proto3 configuration |
|
file <config>`. This will be parsed as a :ref:`v2 bootstrap configuration file |
|
<config_overview_v2_bootstrap>` and on failure, subject to |
|
:option:`--v2-config-only`, will be considered as a :ref:`v1 JSON |
|
configuration file <config_overview_v1>`. For v2 configuration files, 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:: --v2-config-only |
|
|
|
*(optional)* This flag determines whether the configuration file should only |
|
be parsed as a :ref:`v2 bootstrap configuration file |
|
<config_overview_v2_bootstrap>`. If false (default), when a v2 bootstrap |
|
config parse fails, a second attempt to parse the config as a :ref:`v1 JSON |
|
configuration file <config_overview_v1>` will be made. |
|
|
|
.. 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:: --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:: --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 <config_cluster_manager_cluster_hc_service_name>`, |
|
:ref:`runtime override directory <config_runtime_override_subdirectory>`, |
|
:ref:`user agent addition <config_http_conn_man_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 |
|
<config_cluster_manager_sds_api_host_az>`, 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 hot restart. See the |
|
:ref:`hot restart overview <arch_overview_hot_restart>` for more information. 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 |
|
time 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:: --max-obj-name-len <uint64_t> |
|
|
|
*(optional)* The maximum name length (in bytes) of the name field in a cluster/route_config/listener. |
|
This setting is typically used in scenarios where the cluster names are auto generated, and often exceed |
|
the built-in limit of 60 characters. Defaults to 60. |
|
|
|
.. attention:: |
|
|
|
This setting affects the output of :option:`--hot-restart-version`. If you started envoy with this |
|
option set to a non default value, you should use the same option (and same value) for subsequent hot |
|
restarts. |
|
|
|
.. option:: --max-stats <uint64_t> |
|
|
|
*(optional)* The maximum number of stats that can be shared between hot-restarts. This setting |
|
affects the output of :option:`--hot-restart-version`; the same value must be used to hot |
|
restart. Defaults to 16384. |
|
|
|
.. option:: --disable-hot-restart |
|
|
|
*(optional)* This flag disables Envoy hot restart for builds that have it enabled. By default, hot |
|
restart is enabled.
|
|
|