From a4a14917892b6ef8d16ec1c3eddca6fddd613c2f Mon Sep 17 00:00:00 2001 From: Manuel de Brito Fontes Date: Tue, 31 May 2016 14:21:31 -0400 Subject: [PATCH] Add description for options in custom configuration --- controllers/nginx/README.md | 216 ++++++++++++++++++++++++++++++++++++ 1 file changed, 216 insertions(+) diff --git a/controllers/nginx/README.md b/controllers/nginx/README.md index 357e2dfcc..b4d2321d3 100644 --- a/controllers/nginx/README.md +++ b/controllers/nginx/README.md @@ -273,6 +273,222 @@ Using this two headers is possible to use a custom backend service like [this on | | |The secret must be created in the same namespace than the Ingress rule|| |ingress.kubernetes.io/auth-realm|string| | + +### Custom configuration options + +Running `/nginx-ingress-controller --dump-nginx-configuration` is possible to get the value of the options that can be changed. +The next table shows the options, the default value and a description + +|name |default| +|---------------------------|------| +|body-size|1m| +|custom-http-errors|" "| +|enable-sticky-sessions|"false"| +|enable-vts-status|"false"| +|error-log-level|notice| +|gzip-types|| +|hsts|"true"| +|hsts-include-subdomains|"true"| +|hsts-max-age|"15724800"| +|keep-alive|"75"| +|max-worker-connections|"16384"| +|proxy-connect-timeout|"5"| +|proxy-read-timeout|"60"| +|proxy-real-ip-cidr|0.0.0.0/0| +|proxy-send-timeout|"60"| +|retry-non-idempotent|"false"| +|server-name-hash-bucket-size|"64"| +|server-name-hash-max-size|"512"| +|ssl-buffer-size|4k| +|ssl-ciphers|| +|ssl-protocols|TLSv1 TLSv1.1 TLSv1.2| +|ssl-session-cache|"true"| +|ssl-session-cache-size|10m| +|ssl-session-tickets|"true"| +|ssl-session-timeout|10m| +|use-gzip|"true"| +|use-http2|"true"| +|vts-status-zone-size|10m| +|worker-processes|| + + +**Description:** + +*body-size:* + +Sets the maximum allowed size of the client request body. See NGINX [client_max_body_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) + + +*custom-http-errors:* + +Enables which HTTP codes should be passed for processing with the [error_page directive](http://nginx.org/en/docs/http/ngx_http_core_module.html#error_page) +Setting at least one code this also enables [proxy_intercept_errors](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_intercept_errors) (required to process error_page) + + +*enable-sticky-sessions:* + +Enables sticky sessions using cookies. This is provided by [nginx-sticky-module-ng](https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng) module + + +*enable-vts-status:* + +Allows the replacement of the default status page with a third party module named [nginx-module-vts](https://github.com/vozlt/nginx-module-vts) + + +*error-log-level:* + +Configures the logging level of errors. Log levels above are listed in the order of increasing severity +http://nginx.org/en/docs/ngx_core_module.html#error_log + + +*retry-non-idempotent:* + +Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error in the upstream server. +The previous behavior can be restored using the value "true" + + +*hsts:* + +Enables or disables the header HSTS in servers running SSL. +HTTP Strict Transport Security (often abbreviated as HSTS) is a security feature (HTTP header) that tell browsers that it should only be communicated with using HTTPS, instead of using HTTP. +https://developer.mozilla.org/en-US/docs/Web/Security/HTTP_strict_transport_security +Why HSTS is important? + + +*hsts-include-subdomains:* + +Enables or disables the use of HSTS in all the subdomains of the servername + + +*hsts-max-age:* + +Sets the time, in seconds, that the browser should remember that this site is only to be accessed using HTTPS. + + +*keep-alive:* + +Sets the time during which a keep-alive client connection will stay open on the server side. +The zero value disables keep-alive client connections +http://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout + + +*max-worker-connections:* + +Sets the maximum number of simultaneous connections that can be opened by each [worker process](http://nginx.org/en/docs/ngx_core_module.html#worker_connections) + + +*proxy-connect-timeout*: + +Sets the timeout for [establishing a connection with a proxied server](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout). It should be noted that this timeout cannot usually exceed 75 seconds. + + +*proxy-read-timeout:* + +Sets the timeout in seconds for [reading a response from the proxied server](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout). The timeout is set only between two successive read operations, not for the transmission of the whole response + + +*proxy-send-timeout:* + +Sets the timeout in seconds for [transmitting a request to the proxied server](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout). The timeout is set only between two successive write operations, not for the transmission of the whole request. + + +*resolver:* + +Configures name servers used to [resolve](http://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) names of upstream servers into addresses + + +*server-name-hash-max-size:* + +Sets the maximum size of the [server names hash tables](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size) used in server names, map directive’s values, MIME types, names of request header strings, etc. +http://nginx.org/en/docs/hash.html + + +*server-name-hash-bucket-size:* + +Sets the size of the bucker for the server names hash tables +http://nginx.org/en/docs/hash.html +http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size + +*ssl-buffer-size:* + +Sets the size of the [SSL buffer](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_buffer_size) used for sending data. +4k helps NGINX to improve TLS Time To First Byte (TTTFB) +https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/ + +*ssl-ciphers:* + +Sets the [ciphers](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers) list to enable. The ciphers are specified in the format understood by the OpenSSL library + + +*ssl-dh-param:* + +Base64 string that contains Diffie-Hellman key to help with "Perfect Forward Secrecy" +https://www.openssl.org/docs/manmaster/apps/dhparam.html +https://wiki.mozilla.org/Security/Server_Side_TLS#DHE_handshake_and_dhparam +http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam + +*ssl-protocols:* + +Sets the [SSL protocols](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols) to use + + +*ssl-session-cache:* + +Enables or disables the use of shared [SSL cache](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache) among worker processes. + + +*ssl-session-cache-size:* + +Sets the size of the [SSL shared session cache](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache) between all worker processes. + + +*ssl-session-tickets:* + +Enables or disables session resumption through [TLS session tickets](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets) + + +*ssl-session-timeout:* + +Sets the time during which a client may [reuse the session](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_timeout) parameters stored in a cache. + + +*upstream-max-fails:* + +Sets the number of unsuccessful attempts to communicate with the [server](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream) that should happen in the duration set by the fail_timeout parameter to consider the server unavailable + + +*upstream-fail-timeout:* + +Sets the time during which the specified number of unsuccessful attempts to communicate with the [server](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream) should happen to consider the server unavailable + + +*use-proxy-protocol:* + +Enables or disables the use of the [PROXY protocol](https://www.nginx.com/resources/admin-guide/proxy-protocol/) to receive client connection (real IP address) information passed through proxy servers and load balancers such as HAproxy and Amazon Elastic Load Balancer (ELB). + + +*use-gzip:* + +Enables or disables the use of the nginx module that compresses responses using the ["gzip" module](http://nginx.org/en/docs/http/ngx_http_gzip_module.html) + + +*use-http2:* + +Enables or disables the [HTTP/2](http://nginx.org/en/docs/http/ngx_http_v2_module.html) support in secure connections + + +*gzip-types:* + +MIME types in addition to "text/html" to compress. The special value "*"" matches any MIME type. +Responses with the "text/html" type are always compressed if `use-gzip` is enabled + + +*worker-processes:* + +Sets the number of [worker processes](http://nginx.org/en/docs/ngx_core_module.html#worker_processes). By default "auto" means number of available CPU cores + + + ## Troubleshooting Problems encountered during [1.2.0-alpha7 deployment](https://github.com/kubernetes/kubernetes/blob/master/docs/getting-started-guides/docker.md):