SkyeYoung commented on code in PR #7262: URL: https://github.com/apache/apisix/pull/7262#discussion_r917478300
########## docs/en/latest/configuration/config-default.md: ########## @@ -0,0 +1,1028 @@ +--- +title: Configuration Options +--- + +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +This page describes the configuration options defined in the `conf/config-default.yaml`. + +## `apisix` + +Configuration options for `apisix`. + +### `admin_api_mtls` + +```yaml +# Depends on `port_admin` and `https_admin`. +admin_api_mtls: + + # (string) Path of your self-signed server side cert. + admin_ssl_cert: "" + + # (string) Path of your self-signed server side key. + admin_ssl_cert_key: "" + + # (string) Path of your self-signed ca cert.The CA is used to sign all admin api callers' certificates. + admin_ssl_ca_cert: "" +``` + +### `admin_listen` + +```yaml +# The address of the admin api. Use a separate port for admin to listen on. This configuration is disabled by default. +admin_listen: + + # (ip address) Specific IP address to listen on. If not set then the server will listen on all interfaces i.e 0.0.0.0 + ip: 127.0.0.1 + + # (port number) Specific port to listen on. + port: 9180 +``` + +### `allow_admin` + +```yaml +# (ip address list) Allow admin only on specific IP addresses. If not set, then admin is allowed on all IP addresses. Put valid IP addresses only. fore more reference see: http://nginx.org/en/docs/http/ngx_http_access_module.html#allow +allow_admin: + - 127.0.0.0/24 + # - "::/64" +``` + +### `config_center` + +```yaml +# (string) Use config from YAML file or store config in etcd. Possible values: etcd, yaml. +config_center: etcd +``` + +### `control` + +```yaml +# The address of the control api. Use a separate port for control to listen on. This configuration is disabled by default. +control: + + # (ip address) Specific IP address to listen on. + ip: 127.0.0.1 + + # (port number) Specific port to listen on. + port: 9090 +``` + +### `delete_uri_tail_slash` + +```yaml +# (boolean) Enabling this will remove the trailing slash from the request URI. +delete_uri_tail_slash: false +``` + +### `disable_sync_configuration_during_start` + +```yaml +# (boolean) Disable sync configuration during start. +disable_sync_configuration_during_start: false +``` + +### `dns_resolver` + +```yaml +# (ip address list) The list of DNS resolvers to use. If not set, then the system default resolver will be used i.e reads from /etc/resolv.conf. This configuration is disabled by default. +dns_resolver: + - 1.1.1.1 + - 8.8.8.8 +``` + +### `dns_resolver_valid` + +```yaml +# (integer) The number of seconds to override the TTL of valid records. If not set, then the system default TTL will be used. This configuration is disabled by default. +dns_resolver_valid: 30 +``` + +### `enable_admin` + +```yaml +# (boolean) Enable admin mode. +enable_admin: true +``` + +### `enable_admin_cors` + +```yaml +# (boolean) Enable CORS response header for admin. +enable_admin_cors: true +``` + +### `enable_control` + +```yaml +# (boolean) Enable control mode. +enable_control: true +``` + +### `enable_dev_mode` + +```yaml +# (boolean) Sets nginx worker_processes to 1 when set true. This is useful for development. +enable_dev_mode: false +``` + +### `enable_ipv6` + +```yaml +# (boolean) Enable ipv6. +enable_ipv6: true +``` + +### `enable_resolv_search_opt` + +```yaml +# (boolean) Enables search option in resolv.conf. +enable_resolv_search_opt: true +``` + +### `enable_reuseport` + +```yaml +# (boolean) Enables nginx SO_RESUEPORT switch if set true. +enable_reuseport: true +``` + +### `enable_server_tokens` + +```yaml +# (boolean) Enables the APISIX version number in the server header. +enable_server_tokens: true +``` + +### `extra_lua_cpath` + +```yaml +# (string) Load third party lua code by extending lua_package_cpath. It can override the built-in lua code. +extra_lua_cpath: "" +``` + +### `extra_lua_path` + +```yaml +# (string) Load third party lua code by extending lua_package_path. It can override the built-in lua code. +extra_lua_path: "" +``` + +### `https_admin` + +```yaml +# (boolean) Enables HTTPS when using a separate port for admin API. Admin API will use conf/apisix_admin_api.crt and conf/apisix_admin_api.key as HTTPS certificate and key. +https_admin: true +``` + +### `lua_module_hook` + +```yaml +# (string) The hook module used to inject third party lua code. The format is "my_project.my_hook". This configuration is disabled by default. +lua_module_hook: "" +``` + +### `node_listen` + +```yaml +# APISIX will listen on this port. This configuration has two forms. +# (port numbers) It can accept a list of ports if no other child configuration is set. This form is the default configuration. +node_listen: + - 9080 + +# (ip, port, protocol) Or it can also accept a list of (ip address, port, protocol). This is useful when you want to specify ip address, port and protocol. This form is disabled by default. +node_listen: + + # (ip address) Specific IP address to listen on. If not set then the server will listen on all interfaces i.e 0.0.0.0 + ip: 127.0.0.2 + + # (port number) Specific port to listen on. + port: 9080 + + # (boolean) Enable http2. + http2: false +``` + +### `normalize_uri_like_servlet` + +```yaml +# (boolean) Enables compatibility with servlet when matching the URI path. +normalize_uri_like_servlet: false +``` + +### `port_admin` + +```yaml +# (port number) The port for the admin to listen on. This configuration is deprecated. Set this parameter using admin_listen instead. +port_admin: 9180 +``` + +### `proxy_cache` + +```yaml +# The proxy caching configuration. +proxy_cache: + + # (time) The default caching time in the disk. Uses cache time defined in the upstream by default. + cache_ttl: 10s + + # The parameters used for setting the cache. + zones: + + # (string) The name of the cache. Administrator can specify which cache to use by name in the admin api. Options are disk or memory. + - name: disk_cache_one + + # (integer) The size of the shared memory to store the cache index for disk or memory strategy. + memory_size: 50m + + # (integer) The size of the disk space dedicated to store the cache data. + disk_size: 1G + + # (string) The absolute path of the directory to store the cache data. + disk_path: /tmp/disk_cache_one + + # (ratio) The hierarchy level of the cache. The higher the level, the more the cache will be shared with other caches. + cache_level: 1:2 + + # Given below is the default memory cache configuration. + - name: memory_cache + memory_size: 50m +``` + +### `proxy_protocol` + +```yaml +# Proxy protocol configuration. This configuration is disabled by default. +proxy_protocol: + + # (port number) The port with proxy protocol for http. Must be set to receive http request with proxy protocol. This port can only receive request with proxy protocol. Must be different from node_listen and port_admin. + listen_http_port: 9181 + + # (port number) The port with proxy protocol for https. Must be set to receive https request with proxy protocol. + listen_https_port: 9182 + + # (boolean) Enables the proxy protocol for tcp proxy, it works with stream_proxy.tcp option. + enable_tcp_pp: true + + # (boolean) Enables the proxy protocol to the upstream server. + enable_tcp_pp_to_upstream: true +``` + +### `resolver_timeout` + +```yaml +# (time) The timeout for DNS resolver in seconds. +resolver_timeout: 5 +``` + +### `show_upstream_status_in_response_header` + +```yaml +# (boolean) Enables the upstream status in the response header. +show_upstream_status_in_response_header: false +``` + +### `ssl` + +```yaml +# SSL related configuration. +ssl: + + # (boolean) Enables SSL. + enable: true + + # (port numbers or (port, ip , protocol)) The listen configuration can be a list of ports or a list of (port, ip, protocol). It accepts a list of ports by default. + listen: + - 9443 + + # (port, ip, protocol) It can also accept a list of (port, ip, protocol). This is useful when you want to specify ip address, port and protocol. This form is disabled by default. + # (port number) Specific port to listen on. + - port: 9444 + + # (ip address) Specific IP address to listen on. If not set then the server will listen on all interfaces i.e 0.0.0.0 + ip: 127.0.0.3 + + # (boolean) Enable http2. + enable_http2: true + + # (boolean) Enables http2. This configuration is deprecated. Set this parameter using listen instead. + enable_http2: true + + # (port number) The port to listen on. This configuration is deprecated. Set this parameter using listen instead. + listen_port: 9443 + + # (string) Specifies a file path with trusted CA certificate in the PEM format. This is only used to verify the certificate when APISIX needs to do SSL/TLS handshaking with external services e.g. etcd. This configuration is disabled by default. + ssl_trusted_certificate: /path/to/ca-cert + + # (string) List of SSL protocols to be used separated by space. + ssl_protocols: TLSv1.2 TLSv1.3 + + # (string) List of SSL cipher to be used separated by hyphen. + ssl_ciphers: ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384 + + # (boolean) Enables Perfect Forward Secrecy. See here for more reference: https://github.com/mozilla/server-side-tls/issues/135 + ssl_session_tickets: false + + # (string) Encrypt SSL keys with AES-128-CBC on set. Must be of length 16. If not set, saves origin keys into etcd. CAUTION: Do not change it after saving SSL keys. It won't be able to decrypt. + key_encrypt_salt: edd1c9f0985e76a2 + + # (string) If set, when the client doesn't send SNI during handshake, this will be used instead. This configuration is disabled by default. + fallback_sni: "" +``` + +### `stream_proxy` + +```yaml +# TCP/UDP proxy configuration. This configuration is disabled by default. +stream_proxy: + + # (boolean) If enabled, uses stream proxy only and disables HTTP related stuffs. + only: true + + # TCP proxy address list + tcp: + + # (ip address:port number) Address for tcp stream proxy. Can take port number or ip address and port number combined e.g. "127.0.0.1:9101" + addr: 9100 + + # (boolean) Enables TLS on the specified port + tls: true + + # UDP proxy address list + udp: + + # (ip address:port number) Address for udp stream proxy. Can take port number or ip address and port number combined e.g. "127.0.0.1:9201" + - 9200 +``` + +## `nginx_config` + +Configurations for the rendering of the template to generate `nginx.conf`. + +### `enable_cpu_affinity` + +```yaml +# (boolean) Enables CPU affinity. This is useful only on physical machines. +enable_cpu_affinity: true +``` + +### `error_log` + +```yaml +# (string) The path to the error log file. +error_log: logs/error.log +``` + +### `error_log_level` + +```yaml +# (string) The error log level. Options are: warn, error. +error_log_level: warn +``` + +### `envs` + +```yaml +# (string) This allows to get list of specific environment variables. This configuration is disabled by default. +envs: + - TEST_ENV +``` + +### `event` + +```yaml +# Set number of event workers. +event: + # (integer) The number of worker connections. + worker_connections: 10620 +``` + +### `http` + +```yaml +# HTTP related nginx configuration. +http: + + # (boolean) Enable HTTP access log. + enable_access_log: true + + # (string) The path to the http access log file. + access_log: logs/access.log + + # (string) The http access log format. + access_log_format: "$remote_addr - $remote_user [$time_local] $http_host \"$request\" $status $body_bytes_sent $request_time \"$http_referer\" \"$http_user_agent\" $upstream_addr $upstream_status $upstream_response_time \"$upstream_scheme://$upstream_host$upstream_uri\"" + + # (string) Allows escaping json or default characters escaping in logs. + access_log_format_escape: default + + # (time) Timeout for keep-alive client connection that will stay open on the server side. + keepalive_timeout: 60s + + # (time) Timeout for reading client request header. After this 408 (Request Timeout) response will be sent to the client. + client_header_timeout: 60s + + # (time) Timeout for reading client request body. After this 408 (Request Timeout) response will be sent to the client. + client_body_timeout: 60s + + # (integer) the maximum allowed size of client request body. + client_max_body_size: 0 + + # (time) Timeout for transmitting a response to the client before closing the connection. + send_timeout: 10s + + # (string) Enable the use of underscores in client request header field names. + underscores_in_headers: "on" + + # (string) Defines the request header field whose value will be used to replace the client address. See here: http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header + real_ip_header: X-Real-IP + + # (string) If recursive search is disabled, the original client address that matches one of the trusted addresses is replaced by the last address sent in the request header field defined by the real_ip_header directive. If recursive search is enabled, the original client address that matches one of the trusted addresses is replaced by the last non-trusted address sent in the request header field. See here: http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive + real_ip_recursive: "off" + + # (string) Defines trusted addresses that are known to send correct replacement addresses. If the special value unix: is specified, all UNIX-domain sockets will be trusted. Trusted addresses may also be specified using a hostname. See here: http://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from + set_real_ip_from: + - 127.0.0.1 + - "unix:" + + # Add custom shared cache to nginx.conf. Set the cache as "cache-key: cache-size". This configuration is disabled by default. + custom_lua_shared_dict: + + # (integer) The size of the ipc shared dictionary. + ipc_shared_dict: 100m + + # (boolean) Enables passing of the server name through TLS Server Name Indication extension (SNI, RFC 6066) when establishing a connection with the proxied HTTPS server. + proxy_ssl_server_name: true + + # Upstream related configuration + upstream: + + # (string) The upstream type. Options are: http, tcp, udp. + type: http + + # (integer) The maximum number of idle keep-alive connections to the upstream server that are preserved in the cache of each worker process. If the number of connections exceeds this value, the least recently used connections will be closed. + keepalive: 320 + + # (integer) The maximum number of request that can be served through one keep-alive connection. If the number of requests exceeds this value, the connection will be closed. + keepalive_requests: 1000 + + # (integer) Timeout for closing an idle keep-alive connection to the upstream server. + keepalive_timeout: 60s + + # (string) Adds the specified charset to the Content-Type response header field. See here: http://nginx.org/en/docs/http/ngx_http_charset_module.html#charset + charset: utf-8 + + # (integer) The maximum size of the variable hash table. + variables_hash_max_size: 2048 + + # Lua shared dict configuration + lua_shared_dict: + internal-status: 10m + plugin-limit-req: 10m + plugin-limit-count: 10m + prometheus-metrics: 10m + plugin-limit-conn: 10m + upstream-healthcheck: 10m + worker-events: 10m + lrucache-lock: 10m + balancer-ewma: 10m + balancer-ewma-locks: 10m + balancer-ewma-last-touched-at: 10m + plugin-limit-count-redis-cluster-slot-lock: 1m + tracing_buffer: 10m + plugin-api-breaker: 10m + etcd-cluster-health-check: 10m + discovery: 1m + jwks: 1m + introspection: 10m + access-tokens: 1m + ext-plugin: 1m + kubernetes: 1m + tars: 1m +``` + +### `http_admin_configuration_snippet` + +```yaml +# Add well indented custom Nginx admin server configuration. Please check for conflicts with APISIX snippets. +http_admin_configuration_snippet: | Review Comment: It looks as if we need the help of this plugin https://github.com/kevin940726/remark-code-import 🤔 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@apisix.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
