docs: update apisix section in config-default.yaml

conf/config-default.yaml

@@ -14,122 +14,128 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-# PLEASE DO NOT UPDATE THIS FILE!
-# If you want to set the specified configuration value, you can set the new
-# value in the conf/config.yaml file.
+# CAUTION: DO NOT MODIFY DEFAULT CONFIGURATIONS IN THIS FILE.
+# Keep the custom configurations in conf/config.yaml.
 #
 
 apisix:
-  # node_listen: 9080               # APISIX listening port
-  node_listen:                      # This style support multiple ports
+  # node_listen: 9080          # APISIX listening port.
+  node_listen:                 # APISIX listening ports.
     - 9080
-  #   - port: 9081
-  #     enable_http2: true          # If not set, the default value is `false`.
-  #   - ip: 127.0.0.2               # Specific IP, If not set, the default value is `0.0.0.0`.
-  #     port: 9082
-  #     enable_http2: true
-  enable_admin: true
-  enable_dev_mode: false            # Sets nginx worker_processes to 1 if set to true
-  enable_reuseport: true            # Enable nginx SO_REUSEPORT switch if set to true.
-  show_upstream_status_in_response_header: false # when true all upstream status write to `X-APISIX-Upstream-Status` otherwise only 5xx code
+    # - port: 9081
+    #   enable_http2: true     # If not set, default to `false`.
+    # - ip: 127.0.0.2          # If not set, default to `0.0.0.0`
+    #   port: 9082
+    #   enable_http2: true
+  enable_admin: true           # Admin API
+  enable_dev_mode: false       # If true, set nginx `worker_processes` to 1.
+  enable_reuseport: true       # If true, enable nginx SO_REUSEPORT option.
+  show_upstream_status_in_response_header: false  # If true, include the upstream HTTP status code in
+                                                  # the response header `X-APISIX-Upstream-Status`.
+                                                  # If false, show `X-APISIX-Upstream-Status` only if
+                                                  # the upstream response code is 5xx.
   enable_ipv6: true
 
-  #proxy_protocol:                  # Proxy Protocol configuration
-  #  listen_http_port: 9181         # The port with proxy protocol for http, it differs from node_listen and admin_listen.
-                                    # This port can only receive http request with proxy protocol, but node_listen & admin_listen
-                                    # can only receive http request. If you enable proxy protocol, you must use this port to
-                                    # receive http request with proxy protocol
-  #  listen_https_port: 9182        # The port with proxy protocol for https
-  #  enable_tcp_pp: true            # Enable the proxy protocol for tcp proxy, it works for stream_proxy.tcp option
-  #  enable_tcp_pp_to_upstream: true # Enables the proxy protocol to the upstream server
-  enable_server_tokens: true        # Whether the APISIX version number should be shown in Server header.
-                                    # It's enabled by default.
-
-  # configurations to load third party code and/or override the builtin one.
-  extra_lua_path: ""                # extend lua_package_path to load third party code
-  extra_lua_cpath: ""               # extend lua_package_cpath to load third party code
-  #lua_module_hook: "my_project.my_hook"  # the hook module which will be used to inject third party code into APISIX
-
-  proxy_cache:                      # Proxy Caching configuration
-    cache_ttl: 10s                  # The default caching time in disk if the upstream does not specify the cache time
-    zones:                          # The parameters of a cache
-      - name: disk_cache_one        # The name of the cache, administrator can specify
-                                    # which cache to use by name in the admin api (disk|memory)
-        memory_size: 50m            # The size of shared memory, it's used to store the cache index for
-                                    # disk strategy, store cache content for memory strategy (disk|memory)
-        disk_size: 1G               # The size of disk, it's used to store the cache data (disk)
-        disk_path: /tmp/disk_cache_one  # The path to store the cache data (disk)
-        cache_levels: 1:2           # The hierarchy levels of a cache (disk)
-      #- name: disk_cache_two
+  # proxy_protocol:                    # PROXY Protocol configuration
+  #   listen_http_port: 9181           # APISIX listening port for HTTP traffic with PROXY protocol.
+  #   listen_https_port: 9182          # APISIX listening port for HTTPS traffic with PROXY protocol.
+  #   enable_tcp_pp: true              # Enable the PROXY protocol when stream_proxy.tcp is set.
+  #   enable_tcp_pp_to_upstream: true  # Enable the PROXY protocol.
+
+  enable_server_tokens: true           # If true, show APISIX version in the `Server` response header.
+  extra_lua_path: ""                   # Extend lua_package_path to load third-party code.
+  extra_lua_cpath: ""                  # Extend lua_package_cpath to load third-party code.
+  # lua_module_hook: "my_project.my_hook"  # Hook module used to inject third-party code into APISIX.
+
+  proxy_cache:      # Proxy Caching configuration
+    cache_ttl: 10s  # The default caching time on disk if the upstream does not specify a caching time.
+    zones:
+      - name: disk_cache_one    # Name of the cache.
+        memory_size: 50m        # Size of the memory to store the cache index.
+        disk_size: 1G           # Size of the disk to store the cache data.
+        disk_path: /tmp/disk_cache_one  # Path to the cache file for disk cache.
+        cache_levels: 1:2               # Cache hierarchy levels of disk cache.
+      # - name: disk_cache_two
       #  memory_size: 50m
       #  disk_size: 1G
       #  disk_path: "/tmp/disk_cache_two"
       #  cache_levels: "1:2"
       - name: memory_cache
         memory_size: 50m
 
-  delete_uri_tail_slash: false    # delete the '/' at the end of the URI
-  # The URI normalization in servlet is a little different from the RFC's.
-  # See https://github.com/jakartaee/servlet/blob/master/spec/src/main/asciidoc/servlet-spec-body.adoc#352-uri-path-canonicalization,
-  # which is used under Tomcat.
-  # Turn this option on if you want to be compatible with servlet when matching URI path.
-  normalize_uri_like_servlet: false
+  delete_uri_tail_slash: false        # Delete the '/' at the end of the URI
+  normalize_uri_like_servlet: false   # If true, use the same path normalization rules as the Java
+                                      # servlet specification. See https://github.com/jakartaee/servlet/blob/master/spec/src/main/asciidoc/servlet-spec-body.adoc#352-uri-path-canonicalization, which is used in Tomcat.
+
   router:
-    http: radixtree_host_uri      # radixtree_uri: match route by uri(base on radixtree)
-                                  # radixtree_host_uri: match route by host + uri(base on radixtree)
-                                  # radixtree_uri_with_parameter: like radixtree_uri but match uri with parameters,
-                                  #   see https://github.com/api7/lua-resty-radixtree/#parameters-in-path for
-                                  #   more details.
-    ssl: radixtree_sni          # radixtree_sni: match route by SNI(base on radixtree)
-  #stream_proxy:                  # TCP/UDP proxy
-  #  only: true                   # use stream proxy only, don't enable HTTP stuff
-  #  tcp:                         # TCP proxy port list
-  #    - addr: 9100
-  #      tls: true
-  #    - addr: "127.0.0.1:9101"
-  #  udp:                         # UDP proxy port list
-  #    - 9200
-  #    - "127.0.0.1:9201"
-  #dns_resolver:                  # If not set, read from `/etc/resolv.conf`
-  #  - 1.1.1.1
-  #  - 8.8.8.8
-  #dns_resolver_valid: 30         # if given, override the TTL of the valid records. The unit is second.
-  resolver_timeout: 5             # resolver timeout
-  enable_resolv_search_opt: true  # enable search option in resolv.conf
+    http: radixtree_host_uri    # radixtree_host_uri: match route by host and URI
+                                # radixtree_uri: match route by URI
+                                # radixtree_uri_with_parameter: similar to radixtree_uri but match URI with parameters. See https://github.com/api7/lua-resty-radixtree/#parameters-in-path for more details.
+    ssl: radixtree_sni          # radixtree_sni: match route by SNI
+
+  # stream_proxy:                 # TCP/UDP L4 proxy
+  #   only: true                  # Enable L4 proxy only without L7 proxy.
+  #   tcp:
+  #     - addr: 9100              # Set the TCP proxy listening ports.
+  #       tls: true
+  #     - addr: "127.0.0.1:9101"
+  #   udp:                        # Set the UDP proxy listening ports.
+  #     - 9200
+  #     - "127.0.0.1:9201"
+
+  # dns_resolver:                 # If not set, read from `/etc/resolv.conf`
+  #   - 1.1.1.1
+  #   - 8.8.8.8
+  # dns_resolver_valid: 30        # Override the default TTL of the DNS records.
+  resolver_timeout: 5             # Set the time in seconds that the server will wait for a response from the
+                                  # DNS resolver before timing out.
+  enable_resolv_search_opt: true  # If true, use search option in the resolv.conf file in DNS lookups.
+
   ssl:
     enable: true
-    listen:                       # APISIX listening port in https.
+    listen:                                       # APISIX listening port for HTTPS traffic.
       - port: 9443
         enable_http2: true
-    #   - ip: 127.0.0.3           # Specific IP, If not set, the default value is `0.0.0.0`.
-    #     port: 9445
-    #     enable_http2: true
-    #ssl_trusted_certificate: /path/to/ca-cert  # Specifies a file path with trusted CA certificates in the PEM format
-                                                # used to verify the certificate when APISIX needs to do SSL/TLS handshaking
-                                                # with external services (e.g. etcd)
-    ssl_protocols: TLSv1.2 TLSv1.3
+      # - ip: 127.0.0.3                           # If not set, default to `0.0.0.0`.
+      #   port: 9445
+      #   enable_http2: true
+    # ssl_trusted_certificate: /path/to/ca-cert   # Set the path to CA certificates used to verify client
+                                                  # certificates in the PEM format.
+    ssl_protocols: TLSv1.2 TLSv1.3                # TLS versions supported.
     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
-    ssl_session_tickets: false              #  disable ssl_session_tickets by default for 'ssl_session_tickets' would make Perfect Forward Secrecy useless.
-                                            #  ref: https://github.com/mozilla/server-side-tls/issues/135
-
-    key_encrypt_salt:             #  If not set, will save origin ssl key into etcd.
-      - edd1c9f0985e76a2          #  If set this, the key_encrypt_salt should be an array whose elements are string, and the size is also 16, and it will encrypt ssl key with AES-128-CBC
-                                  #  !!! So do not change it after saving your ssl, it can't decrypt the ssl keys have be saved if you change !!
-                                  #  Only use the first key to encrypt, and decrypt in the order of the array.
-
-    #fallback_sni: "my.default.domain"      # If set this, when the client doesn't send SNI during handshake, the fallback SNI will be used instead
-  enable_control: true
-  #control:
+    ssl_session_tickets: false  # If true, session tickets are used for SSL/TLS connections.
+                                # Disabled by default because it renders Perfect Forward Secrecy (FPS)
+                                # useless. See https://github.com/mozilla/server-side-tls/issues/135.
+
+    key_encrypt_salt:           # Set the encryption key for AES-128-CBC. It should be a
+      - edd1c9f0985e76a2        # hexadecimal string of length 16.
+                                # If not set, APISIX saves the original data into etcd.
+                                # CAUTION: If you would like to update the key, add the new key as the
+                                # first item in the array and keep the older keys below the newly added
+                                # key, so that data can be decrypted with the older keys and encrypted
+                                # with the new key. Removing the old keys directly can render the data
+                                # unrecoverable.
+
+    # fallback_sni: "my.default.domain"      # Fallback SNI to be used if the client does not send SNI during
+    #                                        # the handshake.
+
+  enable_control: true  # Control API
+  # control:
   #  ip: 127.0.0.1
   #  port: 9090
-  disable_sync_configuration_during_start: false  # safe exit. Remove this once the feature is stable
-  data_encryption:                # add `encrypt_fields = { $field },` in plugin schema to enable encryption
-    enable: false                 # if not set, the default value is `false`.
-    keyring:
-      - qeddd145sfvddff3          # If not set, will save origin value into etcd.
-                                  # If set this, the keyring should be an array whose elements are string, and the size is also 16, and it will encrypt fields with AES-128-CBC
-                                  # !!! So do not change it after encryption, it can't decrypt the fields have be saved if you change !!
-                                  # Only use the first key to encrypt, and decrypt in the order of the array.
+
+  disable_sync_configuration_during_start: false  # Safe exit. TO BE REMOVED.
+
+  data_encryption:                # Encrypt fields specified in `encrypt_fields` in plugin schema.
+    enable: false
+    keyring:                      # Set the encryption key for AES-128-CBC. It should be a
+      - qeddd145sfvddff3          # hexadecimal string of length 16.
+                                  # If not set, APISIX saves the original data into etcd.
+                                  # CAUTION: If you would like to update the key, add the new key as the
+                                  # first item in the array and keep the older keys below the newly added
+                                  # key, so that data can be decrypted with the older keys and encrypted
+                                  # with the new key. Removing the old keys directly can render the data
+                                  # unrecoverable.
 
 nginx_config:                     # config for render the template to generate nginx.conf
   #user: root                     # specifies the execution user of the worker process.