From 7d144f6904544c1528c7c1c2ada1ed699308bbbd Mon Sep 17 00:00:00 2001 From: thefosk Date: Wed, 24 Aug 2016 12:24:55 -0700 Subject: [PATCH 1/2] documentation consistency --- app/docs/0.9.x/admin-api.md | 11 ++++++- app/plugins/acl.md | 18 ++++++----- app/plugins/basic-authentication.md | 26 ++++++++-------- app/plugins/bot-detection.md | 12 +++++--- app/plugins/correlation-id.md | 14 +++++---- app/plugins/cors.md | 22 ++++++++------ app/plugins/datadog.md | 18 ++++++----- app/plugins/dynamic-ssl.md | 16 +++++----- app/plugins/file-log.md | 14 +++++---- app/plugins/galileo.md | 37 +++++++++++++--------- app/plugins/hmac-authentication.md | 12 +++++--- app/plugins/http-log.md | 20 ++++++------ app/plugins/ip-restriction.md | 14 +++++---- app/plugins/jwt.md | 36 +++++++++++----------- app/plugins/key-authentication.md | 26 ++++++++-------- app/plugins/ldap-authentication.md | 28 +++++++++-------- app/plugins/loggly.md | 34 +++++++++++---------- app/plugins/oauth2-authentication.md | 44 ++++++++++++++------------- app/plugins/rate-limiting.md | 34 +++++++++++---------- app/plugins/request-size-limiting.md | 12 +++++--- app/plugins/request-transformer.md | 34 +++++++++++---------- app/plugins/response-rate-limiting.md | 40 ++++++++++++------------ app/plugins/response-transformer.md | 26 ++++++++-------- app/plugins/runscope.md | 25 +++++++++------ app/plugins/statsd.md | 23 +++++++++----- app/plugins/syslog.md | 23 ++++++++------ app/plugins/tcp-log.md | 20 ++++++------ app/plugins/udp-log.md | 18 ++++++----- 28 files changed, 369 insertions(+), 288 deletions(-) diff --git a/app/docs/0.9.x/admin-api.md b/app/docs/0.9.x/admin-api.md index a2b577441af4..800ff4b3d78b 100644 --- a/app/docs/0.9.x/admin-api.md +++ b/app/docs/0.9.x/admin-api.md @@ -612,13 +612,22 @@ When creating adding Plugin on top of an API, every request made by a client wil ### Add Plugin +You can add a plugin in four different ways: + +* For every API and Consumer. Don't set `api_id` and `consumer_id`. +* For every API and a specific Consumer. Only set `consumer_id`. +* For every Consumer and a specific API. Only set `api_id`. +* For a specific Consumer and API. Set both `api_id` and `consumer_id`. + +Note that not all plugins allow to specify `consumer_id`. Check the plugin documentation. + #### Endpoint
/apis/{name or id}/plugins/
Attributes | Description ---:| --- -`name or id`
**required** | The unique identifier **or** the name of the API on which to add a plugin configuration +`name or id`
**required** | The unique identifier **or** the name of the API on which to add a plugin configuration. If you are adding a plugin to every API use the `/plugins` endpoint instead without specifying an `api_id`. #### Request Body diff --git a/app/plugins/acl.md b/app/plugins/acl.md index 026f0d3be0ef..e62c4c07bff1 100644 --- a/app/plugins/acl.md +++ b/app/plugins/acl.md @@ -31,11 +31,13 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `acl` -`config.whitelist`
*semi-optional* | Comma separated list of arbitrary group names that are allowed to consume the API. At least one between `config.whitelist` or `config.blacklist` must be specified. -`config.blacklist`
*semi-optional* | Comma separated list of arbitrary group names that are not allowed to consume the API. At least one between `config.whitelist` or `config.blacklist` must be specified. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default| description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `acl` +`config.whitelist`
*semi-optional* | | Comma separated list of arbitrary group names that are allowed to consume the API. At least one between `config.whitelist` or `config.blacklist` must be specified. +`config.blacklist`
*semi-optional* | | Comma separated list of arbitrary group names that are not allowed to consume the API. At least one between `config.whitelist` or `config.blacklist` must be specified. ---- @@ -54,9 +56,9 @@ $ curl -X POST http://kong:8001/consumers/{consumer}/acls \ `consumer`: The `id` or `username` property of the [Consumer][consumer-object] entity to associate the credentials to. -form parameter | description ---- | --- -`group` | The arbitrary group name to associate to the consumer. +form parameter | default| description +--- | --- | --- +`group` | | The arbitrary group name to associate to the consumer. You can have more than one group associated to a consumer. diff --git a/app/plugins/basic-authentication.md b/app/plugins/basic-authentication.md index bbe358ca6adb..f3e00a696f7c 100644 --- a/app/plugins/basic-authentication.md +++ b/app/plugins/basic-authentication.md @@ -32,10 +32,12 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `basic-auth` -`config.hide_credentials` | Default `false`. An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `basic-auth` +`config.hide_credentials`
*optional* | `false` | An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request ---- @@ -51,10 +53,10 @@ You need to associate a credential to an existing [Consumer][consumer-object] ob curl -d "username=user123&custom_id=SOME_CUSTOM_ID" http://kong:8001/consumers/ ``` -parameter | description ---- | --- -`username`
*semi-optional* | The username of the consumer. Either this field or `custom_id` must be specified. -`custom_id`
*semi-optional* | A custom identifier used to map the consumer to another database. Either this field or `username` must be specified. +parameter | default | description +--- | --- | --- +`username`
*semi-optional* | | The username of the consumer. Either this field or `custom_id` must be specified. +`custom_id`
*semi-optional* | | A custom identifier used to map the consumer to another database. Either this field or `username` must be specified. A [Consumer][consumer-object] can have many credentials. @@ -70,10 +72,10 @@ $ curl -X POST http://kong:8001/consumers/{consumer}/basic-auth \ `consumer`: The `id` or `username` property of the [Consumer][consumer-object] entity to associate the credentials to. -form parameter | description ---- | --- -`username` | The username to use in the Basic Authentication -`password`
*optional* | The password to use in the Basic Authentication +form parameter | default | description +--- | --- | --- +`username` | | The username to use in the Basic Authentication +`password`
*optional* | | The password to use in the Basic Authentication ### Upstream Headers diff --git a/app/plugins/bot-detection.md b/app/plugins/bot-detection.md index b5e3a40ebdf6..b5d3d5333e2b 100644 --- a/app/plugins/bot-detection.md +++ b/app/plugins/bot-detection.md @@ -27,11 +27,13 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | required | description ---- |--- | --- -`name` | *required* | The name of the plugin to use, in this case: `bot-detection` -`config.whitelist` | *optional* | A comma separated array of regular expressions that should be whitelisted. The regular expressions will be checked against the `User-Agent` header. -`config.blacklist` | *optional* | A comma separated array of regular expressions that should be blacklisted. The regular expressions will be checked against the `User-Agent` header. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- |--- | --- +`name` | | The name of the plugin to use, in this case: `bot-detection` +`config.whitelist`
*optional* | | A comma separated array of regular expressions that should be whitelisted. The regular expressions will be checked against the `User-Agent` header. +`config.blacklist`
*optional* | | A comma separated array of regular expressions that should be blacklisted. The regular expressions will be checked against the `User-Agent` header. ---- diff --git a/app/plugins/correlation-id.md b/app/plugins/correlation-id.md index 7f6a0c7507b1..12f2146e35b4 100644 --- a/app/plugins/correlation-id.md +++ b/app/plugins/correlation-id.md @@ -34,12 +34,14 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | required | description ---- | --- | --- -`name` | *required* | The name of the plugin to use, in this case: `correlation-id` -`header_name` | *optional* | The HTTP header name to use for the correlation ID. Defaults to `Kong-Request-ID` -`generator ` | *optional* | The generator to use for the correlation ID. Accepted values are `uuid`, `uuid#counter` and `tracker` See [Generators](#generators). Defaults to `uuid#counter`. -`echo_downstream` | *optional* | Whether to echo the header back to downstream (the client). Defaults to `false`. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `correlation-id` +`header_name`
*optional* | `Kong-Request-ID` | The HTTP header name to use for the correlation ID. +`generator`
*optional* | `uuid#counter` | The generator to use for the correlation ID. Accepted values are `uuid`, `uuid#counter` and `tracker` See [Generators](#generators). +`echo_downstream`
*optional* | `false` | Whether to echo the header back to downstream (the client). [api-object]: /docs/latest/admin-api/#api-object diff --git a/app/plugins/cors.md b/app/plugins/cors.md index d216c70bcef8..bb9835f5c8d7 100644 --- a/app/plugins/cors.md +++ b/app/plugins/cors.md @@ -35,16 +35,18 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ----: | --- -`name` | Name of the plugin to use, in this case: `cors` -`config.origin`
*optional* | Value for the `Access-Control-Allow-Origin` header, expects a `String`. Defaults to `*` -`config.methods`
*optional* | Value for the `Access-Control-Allow-Methods` header, expects a comma delimited string (e.g. `GET,POST`). Defaults to `GET,HEAD,PUT,PATCH,POST,DELETE`. -`config.headers`
*optional* | Value for the `Access-Control-Allow-Headers` header, expects a comma delimited string (e.g. `Origin, Authorization`). Defaults to the value of the `Access-Control-Request-Headers` header. -`config.exposed_headers`
*optional* | Value for the `Access-Control-Expose-Headers` header, expects a comma delimited string (e.g. `Origin, Authorization`). If not specified, no custom headers are exposed. -`config.credentials`
*optional* | Flag to determine whether the `Access-Control-Allow-Credentials` header should be sent with `true` as the value. Defaults to `false`. -`config.max_age`
*optional* | Indicated how long the results of the preflight request can be cached, in `seconds`. -`config.preflight_continue`
*optional* | A boolean value that instructs the plugin to proxy the `OPTIONS` preflight request to the upstream API. Defaults to `false`. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +---: | --- | --- +`name` | | Name of the plugin to use, in this case: `cors` +`config.origin`
*optional* | `*` | Value for the `Access-Control-Allow-Origin` header, expects a `String`. +`config.methods`
*optional* | `GET,HEAD,PUT,PATCH,POST,DELETE` | Value for the `Access-Control-Allow-Methods` header, expects a comma delimited string (e.g. `GET,POST`). +`config.headers`
*optional* | Value of the `Access-Control-Request-Headers`
request header | Value for the `Access-Control-Allow-Headers` header, expects a comma delimited string (e.g. `Origin, Authorization`). +`config.exposed_headers`
*optional* | | Value for the `Access-Control-Expose-Headers` header, expects a comma delimited string (e.g. `Origin, Authorization`). If not specified, no custom headers are exposed. +`config.credentials`
*optional* | `false` | Flag to determine whether the `Access-Control-Allow-Credentials` header should be sent with `true` as the value. +`config.max_age`
*optional* | | Indicated how long the results of the preflight request can be cached, in `seconds`. +`config.preflight_continue`
*optional* | `false` | A boolean value that instructs the plugin to proxy the `OPTIONS` preflight request to the upstream API. ---- diff --git a/app/plugins/datadog.md b/app/plugins/datadog.md index ee33d4db071c..4f256a332e1d 100644 --- a/app/plugins/datadog.md +++ b/app/plugins/datadog.md @@ -32,14 +32,16 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `datadog` -`consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.host`
*optional* | Default `127.0.0.1`. The IP address or host name to send data to -`config.port`
*optional* | Default `8125`. The port to send data to on the upstream server -`config.metrics`
*optional* | The metrics to be logged, by default all are logged. Available values are described at [Metrics](#metrics). -`config.timeout`
*optional* | Default `10000`. An optional timeout in milliseconds when sending data to the upstream server +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `datadog` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.host`
*optional* | `127.0.0.1` | The IP address or host name to send data to +`config.port`
*optional* | `8125` | The port to send data to on the upstream server +`config.metrics`
*optional* | All metrics
are logged | The metrics to be logged. Available values are described at [Metrics](#metrics). +`config.timeout`
*optional* | `10000` | An optional timeout in milliseconds when sending data to the upstream server [api-object]: /docs/latest/admin-api/#api-object [configuration]: /docs/latest/configuration diff --git a/app/plugins/dynamic-ssl.md b/app/plugins/dynamic-ssl.md index e036f0b08554..433fa59dc1b4 100644 --- a/app/plugins/dynamic-ssl.md +++ b/app/plugins/dynamic-ssl.md @@ -33,13 +33,15 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ----: | --- -`name` | Name of the plugin to use, in this case: `ssl` -`config.cert` | Upload the data of the certificate to use. Note that is the the actual data of the key (not the path), so it should be sent in `multipart/form-data` upload request. -`config.key` | Upload the data of the certificate key to use. Note that is the the actual data of the key (not the path), so it should be sent in `multipart/form-data` upload request. -`config.only_https`
*optional* | Specify if the service should only be available through an `https` protocol. Defaults to `false`. -`config.accept_http_if_already_terminated`
*optional* | If `config.only_https` is `true`, accepts HTTPs requests that have already been terminated by a proxy or load balancer and the `x-forwarded-proto: https` header has been added to the request. Only enable this option if the Kong server cannot be publicly accessed and the only entry-point is such proxy or load balancer. Defaults to `false`. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +---: | --- | --- +`name` | | Name of the plugin to use, in this case: `ssl` +`config.cert` | | Upload the data of the certificate to use. Note that is the the actual data of the key (not the path), so it should be sent in `multipart/form-data` upload request. +`config.key` | | Upload the data of the certificate key to use. Note that is the the actual data of the key (not the path), so it should be sent in `multipart/form-data` upload request. +`config.only_https`
*optional* | `false` | Specify if the service should only be available through an `https` protocol. +`config.accept_http_if_already_terminated`
*optional* | `false` | If `config.only_https` is `true`, accepts HTTPs requests that have already been terminated by a proxy or load balancer and the `x-forwarded-proto: https` header has been added to the request. Only enable this option if the Kong server cannot be publicly accessed and the only entry-point is such proxy or load balancer. ---- diff --git a/app/plugins/file-log.md b/app/plugins/file-log.md index 94d4efa3b3b8..fbeb9950f363 100644 --- a/app/plugins/file-log.md +++ b/app/plugins/file-log.md @@ -31,11 +31,13 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `file-log` -`consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.path` | The file path of the output log file. The plugin will create the file if it doesn't exist yet. Make sure Kong has write permissions to this file. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `file-log` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.path` | | The file path of the output log file. The plugin will create the file if it doesn't exist yet. Make sure Kong has write permissions to this file. [api-object]: /docs/latest/admin-api/#api-object [configuration]: /docs/latest/configuration @@ -113,4 +115,4 @@ A few considerations on the above JSON object: ## Kong Process Errors -This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[nginx_working_dir](/docs/{{site.data.kong_latest.release}}/configuration/#nginx_working_dir)}/logs/error.log +This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log diff --git a/app/plugins/galileo.md b/app/plugins/galileo.md index 808e91899f6c..e9615161a8ec 100644 --- a/app/plugins/galileo.md +++ b/app/plugins/galileo.md @@ -15,6 +15,7 @@ nav: - label: How it works - label: Logging bodies - label: FAQ + - label: Kong Process Errors --- Logs request and response data to [Galileo][galileo], the analytics platform for monitoring, visualizing and inspecting API & microservice traffic. @@ -33,21 +34,22 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins/ \ `api`: The `id` or `name` of the API that this plugin configuration will target - -form parameter | required | description ---- | --- | --- -`name` | *required* | The name of the plugin to use, in this case: `galileo` -`consumer_id` | *optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`service_token` | *required* | The service token provided to you by [Galileo][galileo]. -`environment` | *optional* | Slug of your Galileo environment name. None by default. -`log_bodies` | *optional* | Capture and send request/response bodies. Defaults to `false`. -`retry_count` | *optional* | Number of retries in case of failure to send data to Galileo. Defaults to `10`. -`connection_timeout` | *optional* | Timeout in seconds before aborting a connection to Galileo. Defaults to `30`. -`flush_timeout` | *optional* | Timeout in seconds before flushing the current data to Galileo in case of inactivity. Defaults to `2`. -`queue_size` | *optional* | Number of calls to trigger a flush of the buffered data to Galileo. Defaults to `1000`. -`host` | *optional* | Host address of the Galileo collector. Defaults to `collector.galileo.mashape.com` -`port` | *optional* | Port of the Galileo collector. Defaults to `443`. -`https` | *optional* | Use of HTTPs to connect with the Galileo collector. Defaults to `true`. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `galileo` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`service_token` | | The service token provided to you by [Galileo][galileo]. +`environment`
*optional* | | Slug of your Galileo environment name. None by default. +`log_bodies`
*optional* | `false` | Capture and send request/response bodies. +`retry_count`
*optional* | `10` | Number of retries in case of failure to send data to Galileo. +`connection_timeout`
*optional* | `30` | Timeout in seconds before aborting a connection to Galileo. +`flush_timeout`
*optional* | `2` | Timeout in seconds before flushing the current data to Galileo in case of inactivity. +`queue_size`
*optional* | `1000` | Number of calls to trigger a flush of the buffered data to Galileo. +`host`
*optional* | `collector.galileo.mashape.com` | Host address of the Galileo collector. +`port`
*optional* | `443` | Port of the Galileo collector. +`https`
*optional* | `true` | Use of HTTPs to connect with the Galileo collector. [galileo]: https://getgalileo.io/ [api-object]: /docs/latest/admin-api/#api-object @@ -88,3 +90,8 @@ error_log logs/error.log debug; ``` Now, you should see logs telling you what the plugin is doing, as well as responses from the Galileo collector. If the collector is able to process your data, it means Galileo is correctly receiving it. You'll want to make sure you have configured your plugin to send your data to the right `environment`. + +## Kong Process Errors + +This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log + diff --git a/app/plugins/hmac-authentication.md b/app/plugins/hmac-authentication.md index 8af7360ea9fa..aa05ea7a6bb5 100644 --- a/app/plugins/hmac-authentication.md +++ b/app/plugins/hmac-authentication.md @@ -35,11 +35,13 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `hmac-auth` -`config.hide_credentials`
*optional* | Default `false`. An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request -`config.clock_skew`
*optional* | Default `300`. Clock Skew in seconds to prevent replay attacks. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `hmac-auth` +`config.hide_credentials`
*optional* | `false` | An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request +`config.clock_skew`
*optional* | `300` | Clock Skew in seconds to prevent replay attacks. ---- diff --git a/app/plugins/http-log.md b/app/plugins/http-log.md index 8c02d6c3ba44..c02bb28d411d 100644 --- a/app/plugins/http-log.md +++ b/app/plugins/http-log.md @@ -34,14 +34,16 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `http-log` -`consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.http_endpoint` | The HTTP endpoint (including the protocol to use) where to send the data to -`config.method` | Default `POST`. An optional method used to send data to the http server, other supported values are PUT, PATCH -`config.timeout` | Default `10000`. An optional timeout in milliseconds when sending data to the upstream server -`config.keepalive` | Default `60000`. An optional value in milliseconds that defines for how long an idle connection will live before being closed +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `http-log` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.http_endpoint` | | The HTTP endpoint (including the protocol to use) where to send the data to +`config.method`
*optional* | `POST` | An optional method used to send data to the http server, other supported values are PUT, PATCH +`config.timeout`
*optional* | `10000` | An optional timeout in milliseconds when sending data to the upstream server +`config.keepalive`
*optional*| `60000` | An optional value in milliseconds that defines for how long an idle connection will live before being closed [api-object]: /docs/latest/admin-api/#api-object [configuration]: /docs/latest/configuration @@ -119,4 +121,4 @@ A few considerations on the above JSON object: ## Kong Process Errors -This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[nginx_working_dir](/docs/{{site.data.kong_latest.release}}/configuration/#nginx_working_dir)}/logs/error.log +This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log diff --git a/app/plugins/ip-restriction.md b/app/plugins/ip-restriction.md index fb7a59058d0a..102c110ac79b 100644 --- a/app/plugins/ip-restriction.md +++ b/app/plugins/ip-restriction.md @@ -27,12 +27,14 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `ip-restriction` -`consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.whitelist`
*semi-optional* | Comma separated list of IPs or CIDR ranges to whitelist. At least one between `config.whitelist` or `config.blacklist` must be specified. -`config.blacklist`
*semi-optional* | Comma separated list of IPs or CIDR ranges to blacklist. At least one between `config.whitelist` or `config.blacklist` must be specified. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `ip-restriction` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.whitelist`
*semi-optional* | | Comma separated list of IPs or CIDR ranges to whitelist. At least one between `config.whitelist` or `config.blacklist` must be specified. +`config.blacklist`
*semi-optional* | | Comma separated list of IPs or CIDR ranges to blacklist. At least one between `config.whitelist` or `config.blacklist` must be specified. [cidr]: https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation [api-object]: /docs/latest/admin-api/#api-object diff --git a/app/plugins/jwt.md b/app/plugins/jwt.md index ab5827efafa4..f9044471cd11 100644 --- a/app/plugins/jwt.md +++ b/app/plugins/jwt.md @@ -45,13 +45,15 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | required | description ---- | --- | --- -`name` | *required* | The name of the plugin to use, in this case: `jwt` -`config.uri_param_names` | *optional* | A list of querystring parameters that Kong will inspect to retrieve JWTs. Defaults to `jwt`. -`config.claims_to_verify` | *optional* | A list of registered claims (according to [RFC 7519][rfc-jwt]) that Kong can verify as well. Accepted values: `exp`, `nbf`. -`config.key_claim_name` | *optional* | The name of the claim in which the `key` identifying the secret **must** be passed. Defaults to `iss`. -`config.secret_is_base64` | *optional* | If true, the plugin assumes the credential's `secret` to be base64 encoded. You will need to create a base64 encoded secret for your consumer, and sign your JWT with the original secret. Defaults to `false`. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `jwt` +`config.uri_param_names`
*optional* | `jwt` | A list of querystring parameters that Kong will inspect to retrieve JWTs. +`config.claims_to_verify`
*optional*| | A list of registered claims (according to [RFC 7519][rfc-jwt]) that Kong can verify as well. Accepted values: `exp`, `nbf`. +`config.key_claim_name`
*optional* | `iss` | The name of the claim in which the `key` identifying the secret **must** be passed. +`config.secret_is_base64`
*optional* | `false` | If true, the plugin assumes the credential's `secret` to be base64 encoded. You will need to create a base64 encoded secret for your consumer, and sign your JWT with the original secret. ---- @@ -70,10 +72,10 @@ $ curl -X POST http://kong:8001/consumers \ HTTP/1.1 201 Created ``` -form parameter | required | description ---- | --- | --- -`username` | *semi-optional* | The username for this Consumer. Either this field or `custom_id` must be specified. -`custom_id` | *semi-optional* | A custom identifier used to map the Consumer to an external database. Either this field or `username` must be specified. +form parameter | default | description +--- | --- | --- +`username`
*semi-optional* | | The username for this Consumer. Either this field or `custom_id` must be specified. +`custom_id`
*semi-optional* | | A custom identifier used to map the Consumer to an external database. Either this field or `username` must be specified. A [Consumer][consumer-object] can have many JWT credentials. @@ -96,12 +98,12 @@ HTTP/1.1 201 Created `consumer`: The `id` or `username` property of the [consumer][consumer-object] entity to associate the credentials to. -form parameter | required | description ---- | --- | --- -`key` | *optional* | A unique string identifying the credential. If left out, it will be auto-generated. However, usage of this key is **mandatory** while crafting your token, as specified in the next section. -`algorithm` | *optional* | The algorithm used to verify the token's signature. Can be `HS256` or `RS256`. Defaults to `HS256`. -`rsa_public_key` | *optional* | If `algorithm` is `RS256`, the public key (in PEM format) to use to verify the token's signature. -`secret` | *optional* | If `algorithm` is `HS256`, the secret used to sign JWTs for this credential. If left out, will be auto-generated. +form parameter | default | description +--- | --- | --- +`key`
*optional* | | A unique string identifying the credential. If left out, it will be auto-generated. However, usage of this key is **mandatory** while crafting your token, as specified in the next section. +`algorithm`
*optional* | `HS256` | The algorithm used to verify the token's signature. Can be `HS256` or `RS256`. +`rsa_public_key`
*optional* | | If `algorithm` is `RS256`, the public key (in PEM format) to use to verify the token's signature. +`secret`
*optional* | | If `algorithm` is `HS256`, the secret used to sign JWTs for this credential. If left out, will be auto-generated. ### Craft a JWT diff --git a/app/plugins/key-authentication.md b/app/plugins/key-authentication.md index 1b38b3db9595..170b880878fb 100644 --- a/app/plugins/key-authentication.md +++ b/app/plugins/key-authentication.md @@ -42,11 +42,13 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `key-auth` -`config.key_names`
*optional* | Default: `apikey`. Describes an array of comma separated parameter names where the plugin will look for a key. The client must send the authentication key in one of those key names, and the plugin will try to read the credential from a header or the querystring parameter with the same name. -`config.hide_credentials`
*optional* | Default `false`. An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `key-auth`. +`config.key_names`
*optional* | `apikey`| Describes an array of comma separated parameter names where the plugin will look for a key. The client must send the authentication key in one of those key names, and the plugin will try to read the credential from a header or the querystring parameter with the same name. +`config.hide_credentials`
*optional* | `false` | An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request. ---- @@ -65,10 +67,10 @@ $ curl -X POST http://kong:8001/consumers/ \ HTTP/1.1 201 Created ``` -parameter | description ---- | --- -`username`
*semi-optional* | The username of the Consumer. Either this field or `custom_id` must be specified. -`custom_id`
*semi-optional* | A custom identifier used to map the Consumer to another database. Either this field or `username` must be specified. +parameter | default | description +--- | --- | --- +`username`
*semi-optional* | | The username of the Consumer. Either this field or `custom_id` must be specified. +`custom_id`
*semi-optional* | | A custom identifier used to map the Consumer to another database. Either this field or `username` must be specified. A [Consumer][consumer-object] can have many credentials. @@ -90,9 +92,9 @@ HTTP/1.1 201 Created `consumer`: The `id` or `username` property of the [Consumer][consumer-object] entity to associate the credentials to. -form parameter | description ---- | --- -`key`
*optional* | You can optionally set your own unique `key` to authenticate the client. If missing, the plugin will generate one. +form parameter | default | description +--- | --- | --- +`key`
*optional* | | You can optionally set your own unique `key` to authenticate the client. If missing, the plugin will generate one.
Note: It is recommended to let Kong auto-generate the key. Only specify it yourself if you are migrating an existing system to Kong, and must re-use your keys to make the migration to Kong transparent to your consumers. diff --git a/app/plugins/ldap-authentication.md b/app/plugins/ldap-authentication.md index bc6a3006a2b4..20a631f7ce0c 100644 --- a/app/plugins/ldap-authentication.md +++ b/app/plugins/ldap-authentication.md @@ -35,19 +35,21 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `ldap-auth` -`config.hide_credentials` | Default `false`. An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request -`config.ldap_host` | Host on which the LDAP server is running -`config.ldap_port` | TCP port where the LDAP server is listening -`config.start_tls` | Default `false`. Set it to `true` to issue StartTLS (Transport Layer Security) extended operation over `ldap` connection -`config.base_dn` | Base DN as the starting point for the search -`config.verify_ldap_host` | Default `false`. Set it to `true` to authenticate LDAP server. The server certificate will be verified according to the CA certificates specified by the `lua_ssl_trusted_certificate` directive. -`config.attribute` | Attribute to be used to search the user -`config.cache_ttl` | Default is `60 seconds`. Cache expiry time -`config.timeout` | Default `10000`. An optional timeout in milliseconds when waiting for connection with LDAP server -`config.keepalive` | Default `60000`. An optional value in milliseconds that defines for how long an idle connection to LDAP server will live before being closed +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `ldap-auth`. +`config.hide_credentials`
*optional* | `false` | An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request. +`config.ldap_host` | | Host on which the LDAP server is running. +`config.ldap_port` | | TCP port where the LDAP server is listening. +`config.start_tls` | `false` | Set it to `true` to issue StartTLS (Transport Layer Security) extended operation over `ldap` connection. +`config.base_dn` | | Base DN as the starting point for the search. +`config.verify_ldap_host` | `false` | Set it to `true` to authenticate LDAP server. The server certificate will be verified according to the CA certificates specified by the `lua_ssl_trusted_certificate` directive. +`config.attribute` | | Attribute to be used to search the user. +`config.cache_ttl` | `60` | Cache expiry time in seconds. +`config.timeout`
*optional* | `10000` | An optional timeout in milliseconds when waiting for connection with LDAP server. +`config.keepalive`
*optional* | `60000` | An optional value in milliseconds that defines for how long an idle connection to LDAP server will live before being closed. ---- ## Usage diff --git a/app/plugins/loggly.md b/app/plugins/loggly.md index 70d2d6835558..ba709773763a 100644 --- a/app/plugins/loggly.md +++ b/app/plugins/loggly.md @@ -12,7 +12,7 @@ nav: - label: Usage items: - label: Log Format - - label: Notes + - label: Kong Process Errors --- Log request and response data over UDP to [Loggly](https://www.loggly.com). @@ -31,19 +31,21 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `loggly` -`consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.host`
*optional* | Default `logs-01.loggly.com`. The IP address or host name of Loggly server -`config.port`
*optional* | Default `514`. The UDP port to send data to on the Loggly server -`config.key` | Loggly [customer token](https://www.loggly.com/docs/customer-token-authentication-token/). -`config.tags`
*optional* | Default `kong`. An optional list of [tags](https://www.loggly.com/docs/tags/) to support segmentation & filtering of logs. -`config.timeout`
*optional* | Default `10000`. An optional timeout in milliseconds when sending data to the Loggly server -`config.successful_severity`
*optional* | Default `info`. An optional logging severity assigned to the all successful requests with response status code 400 . -`config.client_errors_severity`
*optional* | Default `info`. An optional logging severity assigned to the all failed requests with response status code 400 or higher but less than 500. -`config.server_errors_severity`
*optional* | Default `info`. An optional logging severity assigned to the all failed requests with response status code 500 or higher. -`config.log_level`
*optional* | Default `info`. An optional logging severity, any request with equal or higher severity will be logged to Loggly. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `loggly` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.host`
*optional* | `logs-01.loggly.com` | The IP address or host name of Loggly server +`config.port`
*optional* |`514` | The UDP port to send data to on the Loggly server +`config.key` | | Loggly [customer token](https://www.loggly.com/docs/customer-token-authentication-token/). +`config.tags`
*optional* | `kong` | An optional list of [tags](https://www.loggly.com/docs/tags/) to support segmentation & filtering of logs. +`config.timeout`
*optional* | `10000` | An optional timeout in milliseconds when sending data to the Loggly server +`config.successful_severity`
*optional* | `info` | An optional logging severity assigned to the all successful requests with response status code 400 . +`config.client_errors_severity`
*optional* | `info` | An optional logging severity assigned to the all failed requests with response status code 400 or higher but less than 500. +`config.server_errors_severity`
*optional* | `info` | An optional logging severity assigned to the all failed requests with response status code 500 or higher. +`config.log_level`
*optional* | `info` | An optional logging severity, any request with equal or higher severity will be logged to Loggly. [api-object]: /docs/latest/admin-api/#api-object [configuration]: /docs/latest/configuration @@ -119,6 +121,6 @@ A few considerations on the above JSON object: ---- -## Notes +## Kong Process Errors -This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[nginx_working_dir](/docs/{{site.data.kong_latest.release}}/configuration/#nginx_working_dir)}/logs/error.log +This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log diff --git a/app/plugins/oauth2-authentication.md b/app/plugins/oauth2-authentication.md index 81aeab0ffe4c..745b07b9d9c7 100644 --- a/app/plugins/oauth2-authentication.md +++ b/app/plugins/oauth2-authentication.md @@ -38,7 +38,9 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ --data "config.mandatory_scope=true" ``` -`api`: The `id` or `name` of the API that this plugin configuration will target +`api`: The `id` or `name` of the API that this plugin configuration will target. + +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. form parameter | default | description --- | --- | --- @@ -46,7 +48,7 @@ form parameter | default | description `config.scopes` | | Describes an array of comma separated scope names that will be available to the end user `config.mandatory_scope`
*optional* | `false` | An optional boolean value telling the plugin to require at least one scope to be authorized by the end user `config.token_expiration`
*optional* | `7200` | An optional integer value telling the plugin how long should a token last, after which the client will need to refresh the token. Set to `0` to disable the expiration. -`config.enable_authorization_code`
*optional* | `true` | An optional boolean value to enable the three-legged Authorization Code flow ([RFC 6742 Section 4.1][authorization-code-grant]) +`config.enable_authorization_code`
*optional* | `false` | An optional boolean value to enable the three-legged Authorization Code flow ([RFC 6742 Section 4.1][authorization-code-grant]) `config.enable_client_credentials`
*optional* | `false` | An optional boolean value to enable the Client Credentials Grant flow ([RFC 6742 Section 4.4][client-credentials]) `config.enable_implicit_grant`
*optional* | `false` | An optional boolean value to enable the Implicit Grant flow which allows to provision a token as a result of the authorization process ([RFC 6742 Section 4.2][implicit-grant]) `config.enable_password_grant`
*optional* | `false` | An optional boolean value to enable the Resource Owner Password Credentials Grant flow ([RFC 6742 Section 4.3][password-grant]) @@ -80,10 +82,10 @@ $ curl -X POST http://kong:8001/consumers/ \ --data "custom_id=SOME_CUSTOM_ID" ``` -parameter | required | description ---- | --- | --- -`username`
*semi-optional* | Either this field or `custom_id` must be specified. | The username of the consumer. -`custom_id`
*semi-optional* | Either this field or `username` must be specified. | A custom identifier used to map the consumer to another database. +parameter | default | description +--- | --- | --- +`username`
*semi-optional* | | The username of the consumer. Either this field or `custom_id` must be specified. +`custom_id`
*semi-optional* | | A custom identifier used to map the consumer to another database. Either this field or `username` must be specified. A [Consumer][consumer-object] can have many credentials. @@ -101,12 +103,12 @@ $ curl -X POST http://kong:8001/consumers/{consumer_id}/oauth2 \ `consumer_id`: The [Consumer][consumer-object] entity to associate the credentials to -form parameter | description ---- | --- -`name` | The name to associate to the credential. In OAuth 2.0 this would be the application name. -`client_id`
*optional* | You can optionally set your own unique `client_id`. If missing, the plugin will generate one. -`client_secret`
*optional* | You can optionally set your own unique `client_secret`. If missing, the plugin will generate one. -`redirect_uri` | The URL in your app where users will be sent after authorization ([RFC 6742 Section 3.1.2][redirect-uri]) +form parameter | default | description +--- | --- | --- +`name` | | The name to associate to the credential. In OAuth 2.0 this would be the application name. +`client_id`
*optional* | | You can optionally set your own unique `client_id`. If missing, the plugin will generate one. +`client_secret`
*optional* | | You can optionally set your own unique `client_secret`. If missing, the plugin will generate one. +`redirect_uri` | | The URL in your app where users will be sent after authorization ([RFC 6742 Section 3.1.2][redirect-uri]) ## Migrating Access Tokens @@ -124,15 +126,15 @@ $ curl -X POST http://kong:8001/oauth2_tokens \ --data "expires_in=3600" ``` -form parameter | description ---- | --- -`credential_id` | The ID of the OAuth 2.0 application created on Kong. -`token_type` | The [token type][token-types]. By default is `bearer`. -`access_token`
*optional* | You can optionally set your own access token value, otherwise a random string will be generated. -`refresh_token`
*optional* | You can optionally set your own refresh token value, otherwise a random string will be generated. -`expires_in` | The expiration time (in seconds) of the access token. -`scope`
*optional* | The authorized scope associated with the token. -`authenticated_userid`
*optional* | The custom ID of the user who authorized the application. +form parameter | default | description +--- | --- | --- +`credential_id` | | The ID of the OAuth 2.0 application created on Kong. +`token_type`
*optional* | `bearer`| The [token type][token-types]. +`access_token`
*optional* | | You can optionally set your own access token value, otherwise a random string will be generated. +`refresh_token`
*optional* | | You can optionally set your own refresh token value, otherwise a random string will be generated. +`expires_in` | | The expiration time (in seconds) of the access token. +`scope`
*optional* | | The authorized scope associated with the token. +`authenticated_userid`
*optional* | | The custom ID of the user who authorized the application. ## Upstream Headers diff --git a/app/plugins/rate-limiting.md b/app/plugins/rate-limiting.md index c6ce6dca30ea..cf0a28af413e 100644 --- a/app/plugins/rate-limiting.md +++ b/app/plugins/rate-limiting.md @@ -31,22 +31,24 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | required | description ---- | --- | --- -`name` | *required* | The name of the plugin to use, in this case: `rate-limiting` -`consumer_id` | *optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.second` | *semi-optional* | The amount of HTTP requests the developer can make per second. At least one limit must exist. -`config.minute` | *semi-optional* | The amount of HTTP requests the developer can make per minute. At least one limit must exist. -`config.hour` | *semi-optional* | The amount of HTTP requests the developer can make per hour. At least one limit must exist. -`config.day` | *semi-optional* | The amount of HTTP requests the developer can make per day. At least one limit must exist. -`config.month` | *semi-optional* | The amount of HTTP requests the developer can make per month. At least one limit must exist. -`config.year` | *semi-optional* | The amount of HTTP requests the developer can make per year. At least one limit must exist. -`config.limit_by`| *optional* | The entity that will be used when aggregating the limits: `consumer`, `credential`, `ip`. Default is `consumer`. If the `consumer` or the `credential` cannot be determined, the system will always fallback to `ip`. -`config.policy`| *optional* | The rate-limiting policies to use for retrieving and incrementing the limits. Available values are `local` (counters will be stored locally in-memory on the node), `cluster` (counters are stored in the datastore and shared across the nodes) and `redis` (counters are stored on a Redis server and will be shared across the nodes). Default is `cluster`. -`config.fault_tolerant` | *optional* | A boolean value that determines if the requests should be proxied even if Kong has troubles connecting a third-party datastore. If `true` requests will be proxied anyways effectively disabling the rate-limiting function until the datastore is working again. If `false` then the clients will see `500` errors. By default is `true`. -`config.redis_host` | *semi-optional* | When using the `redis` policy, this property specifies the address to the Redis server. -`config.redis_port` | *optional* | When using the `redis` policy, this property specifies the port of the Redis server. By default is `6379`. -`config.redis_timeout` | *optional* | When using the `redis` policy, this property specifies the timeout in milliseconds of any command submitted to the Redis server. By default is `2000`. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `rate-limiting` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.second`
*semi-optional* | | The amount of HTTP requests the developer can make per second. At least one limit must exist. +`config.minute`
*semi-optional* | | The amount of HTTP requests the developer can make per minute. At least one limit must exist. +`config.hour`
*semi-optional* | | The amount of HTTP requests the developer can make per hour. At least one limit must exist. +`config.day`
*semi-optional* | | The amount of HTTP requests the developer can make per day. At least one limit must exist. +`config.month`
*semi-optional* | | The amount of HTTP requests the developer can make per month. At least one limit must exist. +`config.year`
*semi-optional* | | The amount of HTTP requests the developer can make per year. At least one limit must exist. +`config.limit_by`
*optional* | `consumer` | The entity that will be used when aggregating the limits: `consumer`, `credential`, `ip`. If the `consumer` or the `credential` cannot be determined, the system will always fallback to `ip`. +`config.policy`
*optional* | `cluster` | The rate-limiting policies to use for retrieving and incrementing the limits. Available values are `local` (counters will be stored locally in-memory on the node), `cluster` (counters are stored in the datastore and shared across the nodes) and `redis` (counters are stored on a Redis server and will be shared across the nodes). +`config.fault_tolerant`
*optional* | `true` | A boolean value that determines if the requests should be proxied even if Kong has troubles connecting a third-party datastore. If `true` requests will be proxied anyways effectively disabling the rate-limiting function until the datastore is working again. If `false` then the clients will see `500` errors. +`config.redis_host`
*semi-optional* | | When using the `redis` policy, this property specifies the address to the Redis server. +`config.redis_port`
*optional* | `6379` | When using the `redis` policy, this property specifies the port of the Redis server. By default is `6379`. +`config.redis_timeout`
*optional* | `2000` | When using the `redis` policy, this property specifies the timeout in milliseconds of any command submitted to the Redis server. ---- diff --git a/app/plugins/request-size-limiting.md b/app/plugins/request-size-limiting.md index f20eeaf47d8f..dc921b44a5d5 100644 --- a/app/plugins/request-size-limiting.md +++ b/app/plugins/request-size-limiting.md @@ -31,11 +31,13 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | required | description ---- | --- | --- -`name` | *required* | The name of the plugin to use, in this case: `request-size-limiting` -`consumer_id` | *optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.allowed_payload_size` | *optional* | Allowed request payload size in megabytes, default is `128` (128000000 Bytes) +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `request-size-limiting` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.allowed_payload_size`
*optional* | `128` | Allowed request payload size in megabytes, default is `128` (128000000 Bytes) [api-object]: /docs/latest/admin-api/#api-object [configuration]: /docs/latest/configuration diff --git a/app/plugins/request-transformer.md b/app/plugins/request-transformer.md index ee4ebe83eb55..189adea75d6d 100644 --- a/app/plugins/request-transformer.md +++ b/app/plugins/request-transformer.md @@ -35,22 +35,24 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ----: | --- -`name` | Name of the plugin to use, in this case: `request-transformer` -`consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.remove.headers`
*optional* | List of header names. Unset the headers with the given name. -`config.remove.querystring`
*optional* | List of querystring names. Remove the querystring if it is present. -`config.remove.body`
*optional* | List of parameter names. Remove the parameter if and only if content-type is one the following [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`] and parameter is present. -`config.replace.headers`
*optional* | List of headername:value pairs. If and only if the header is already set, replace its old value with the new one. Ignored if the header is not already set. -`config.replace.querystring`
*optional* | List of queryname:value pairs. If and only if the header is already set, replace its old value with the new one. Ignored if the header is not already set. -`config.replace.body`
*optional* | List of paramname:value pairs. If and only if content-type is one the following [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`] and the parameter is already present, replace its old value with the new one. Ignored if the parameter is not already present. -`config.add.headers`
*optional* | List of headername:value pairs. If and only if the header is not already set, set a new header with the given value. Ignored if the header is already set. -`config.add.querystring`
*optional* | List of queryname:value pairs. If and only if the querystring is not already set, set a new querystring with the given value. Ignored if the header is already set. -`config.add.body`
*optional* | List of pramname:value pairs. If and only if content-type is one the following [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`] and the parameter is not present, add a new parameter with the given value to form-encoded body. Ignored if the parameter is already present. -`config.append.headers`
*optional* | List of headername:value pairs. If the header is not set, set it with the given value. If it is already set, a new header with the same name and the new value will be set. -`config.append.querystring`
*optional* | List of queryname:value pairs. If the querystring is not set, set it with the given value. If it is already set, a new querystring with the same name and the new value will be set. -`config.append.body`
*optional* | List of paramname:value pairs. If the content-type is one the following [`application/json`, `application/x-www-form-urlencoded`], add a new parameter with the given value if the parameter is not present, otherwise if it is already present, the two values (old and new) will be aggregated in an array. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +---: | --- | --- +`name` | | Name of the plugin to use, in this case: `request-transformer` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.remove.headers`
*optional* | | List of header names. Unset the headers with the given name. +`config.remove.querystring`
*optional* | | List of querystring names. Remove the querystring if it is present. +`config.remove.body`
*optional* | | List of parameter names. Remove the parameter if and only if content-type is one the following [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`] and parameter is present. +`config.replace.headers`
*optional* | | List of headername:value pairs. If and only if the header is already set, replace its old value with the new one. Ignored if the header is not already set. +`config.replace.querystring`
*optional* | | List of queryname:value pairs. If and only if the header is already set, replace its old value with the new one. Ignored if the header is not already set. +`config.replace.body`
*optional* | | List of paramname:value pairs. If and only if content-type is one the following [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`] and the parameter is already present, replace its old value with the new one. Ignored if the parameter is not already present. +`config.add.headers`
*optional* | | List of headername:value pairs. If and only if the header is not already set, set a new header with the given value. Ignored if the header is already set. +`config.add.querystring`
*optional* | | List of queryname:value pairs. If and only if the querystring is not already set, set a new querystring with the given value. Ignored if the header is already set. +`config.add.body`
*optional* | | List of pramname:value pairs. If and only if content-type is one the following [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`] and the parameter is not present, add a new parameter with the given value to form-encoded body. Ignored if the parameter is already present. +`config.append.headers`
*optional* | | List of headername:value pairs. If the header is not set, set it with the given value. If it is already set, a new header with the same name and the new value will be set. +`config.append.querystring`
*optional* | | List of queryname:value pairs. If the querystring is not set, set it with the given value. If it is already set, a new querystring with the same name and the new value will be set. +`config.append.body`
*optional* | | List of paramname:value pairs. If the content-type is one the following [`application/json`, `application/x-www-form-urlencoded`], add a new parameter with the given value if the parameter is not present, otherwise if it is already present, the two values (old and new) will be aggregated in an array. ## Order of execution diff --git a/app/plugins/response-rate-limiting.md b/app/plugins/response-rate-limiting.md index 649e5153a95b..4685f06b72e6 100644 --- a/app/plugins/response-rate-limiting.md +++ b/app/plugins/response-rate-limiting.md @@ -34,25 +34,27 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | required | description ---- | --- | --- -`name` | *required* | The name of the plugin to use, in this case: `response-ratelimiting` -`consumer_id` | *optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.limits.{limit_name}` | *required* | This is a list of custom objects that you can set on the API, with arbitrary names set in the `{limit_name`} placeholder, like `config.limits.sms.minute=20` if your object is called "SMS". -`config.limits.{limit_name}.second` | *semi-optional* | The amount of HTTP requests the developer can make per second. At least one limit must exist. -`config.limits.{limit_name}.minute` | *semi-optional* | The amount of HTTP requests the developer can make per minute. At least one limit must exist. -`config.limits.{limit_name}.hour` | *semi-optional* | The amount of HTTP requests the developer can make per hour. At least one limit must exist. -`config.limits.{limit_name}.day` | *semi-optional* | The amount of HTTP requests the developer can make per day. At least one limit must exist. -`config.limits.{limit_name}.month` | *semi-optional* | The amount of HTTP requests the developer can make per month. At least one limit must exist. -`config.limits.{limit_name}.year` | *semi-optional* | The amount of HTTP requests the developer can make per year. At least one limit must exist. -`config.header_name` | *optional* | The name of the response header used to increment the counters. By default is `X-Kong-Limit`. -`config.block_on_first_violation` | *optional* | A boolean value that determines if the requests should be blocked as soon as one limit is being exceeded. This will block requests that are supposed to consume other limits too. By default is `false`. -`config.limit_by`| *optional* | The entity that will be used when aggregating the limits: `consumer`, `credential`, `ip`. Default is `consumer`. If the `consumer` or the `credential` cannot be determined, the system will always fallback to `ip`. -`config.policy`| *optional* | The rate-limiting policies to use for retrieving and incrementing the limits. Available values are `local` (counters will be stored locally in-memory on the node), `cluster` (counters are stored in the datastore and shared across the nodes) and `redis` (counters are stored on a Redis server and will be shared across the nodes). Default is `cluster`. -`config.fault_tolerant` | *optional* | A boolean value that determines if the requests should be proxied even if Kong has troubles connecting a third-party datastore. If `true` requests will be proxied anyways effectively disabling the rate-limiting function until the datastore is working again. If `false` then the clients will see `500` errors. By default is `true`. -`config.redis_host` | *semi-optional* | When using the `redis` policy, this property specifies the address to the Redis server. -`config.redis_port` | *optional* | When using the `redis` policy, this property specifies the port of the Redis server. By default is `6379`. -`config.redis_timeout` | *optional* | When using the `redis` policy, this property specifies the timeout in milliseconds of any command submitted to the Redis server. By default is `2000`. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `response-ratelimiting` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.limits.{limit_name}` | | This is a list of custom objects that you can set on the API, with arbitrary names set in the `{limit_name`} placeholder, like `config.limits.sms.minute=20` if your object is called "SMS". +`config.limits.{limit_name}.second`
*semi-optional* | | The amount of HTTP requests the developer can make per second. At least one limit must exist. +`config.limits.{limit_name}.minute`
*semi-optional* | | The amount of HTTP requests the developer can make per minute. At least one limit must exist. +`config.limits.{limit_name}.hour`
*semi-optional* | | The amount of HTTP requests the developer can make per hour. At least one limit must exist. +`config.limits.{limit_name}.day`
*semi-optional* | | The amount of HTTP requests the developer can make per day. At least one limit must exist. +`config.limits.{limit_name}.month`
*semi-optional* | | The amount of HTTP requests the developer can make per month. At least one limit must exist. +`config.limits.{limit_name}.year`
*semi-optional* | | The amount of HTTP requests the developer can make per year. At least one limit must exist. +`config.header_name`
*optional* | `X-Kong-Limit` | The name of the response header used to increment the counters. +`config.block_on_first_violation`
*optional* | `false` | A boolean value that determines if the requests should be blocked as soon as one limit is being exceeded. This will block requests that are supposed to consume other limits too. +`config.limit_by`
*optional* | `consumer` | The entity that will be used when aggregating the limits: `consumer`, `credential`, `ip`. If the `consumer` or the `credential` cannot be determined, the system will always fallback to `ip`. +`config.policy`
*optional* | `cluster` | The rate-limiting policies to use for retrieving and incrementing the limits. Available values are `local` (counters will be stored locally in-memory on the node), `cluster` (counters are stored in the datastore and shared across the nodes) and `redis` (counters are stored on a Redis server and will be shared across the nodes). +`config.fault_tolerant`
*optional* | `true` | A boolean value that determines if the requests should be proxied even if Kong has troubles connecting a third-party datastore. If `true` requests will be proxied anyways effectively disabling the rate-limiting function until the datastore is working again. If `false` then the clients will see `500` errors. +`config.redis_host`
*semi-optional* | | When using the `redis` policy, this property specifies the address to the Redis server. +`config.redis_port`
*optional* | `6379` | When using the `redis` policy, this property specifies the port of the Redis server. +`config.redis_timeout`
*optional* | `2000` | When using the `redis` policy, this property specifies the timeout in milliseconds of any command submitted to the Redis server. ---- diff --git a/app/plugins/response-transformer.md b/app/plugins/response-transformer.md index 85463a4f6fa9..3f1302df3895 100644 --- a/app/plugins/response-transformer.md +++ b/app/plugins/response-transformer.md @@ -37,18 +37,20 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ----: | --- -`name` | Name of the plugin to use, in this case: `response-transformer` -`consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.remove.headers`
*optional* | List of header names. Unset the header(s) with the given name. -`config.remove.json`
*optional* | List of property names. Remove the property from the JSON body if it is present. -`config.replace.headers`
*optional* | List of headername:value pairs. If and only if the header is already set, replace its old value with the new one. Ignored if the header is not already set. -`config.replace.json`
*optional* | List of property:value pairs. If and only if the parameter is already present, replace its old value with the new one. Ignored if the parameter is not already present. -`config.add.headers`
*optional* | List of headername:value pairs. If and only if the header is not already set, set a new header with the given value. Ignored if the header is already set. -`config.add.json`
*optional* | List of property:value pairs. If and only if the property is not present, add a new property with the given value to the JSON body. Ignored if the property is already present. -`config.append.headers`
*optional* | List of headername:value pairs. If the header is not set, set it with the given value. If it is already set, a new header with the same name and the new value will be set. -`config.append.json`
*optional* | List of property:value pairs. If the property is not present in the JSON body, add it with the given value. If it is already present, the two values (old and new) will be aggregated in an array. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +---: | --- | --- +`name` | | Name of the plugin to use, in this case: `response-transformer` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.remove.headers`
*optional* | | List of header names. Unset the header(s) with the given name. +`config.remove.json`
*optional* | | List of property names. Remove the property from the JSON body if it is present. +`config.replace.headers`
*optional* | | List of headername:value pairs. If and only if the header is already set, replace its old value with the new one. Ignored if the header is not already set. +`config.replace.json`
*optional* | | List of property:value pairs. If and only if the parameter is already present, replace its old value with the new one. Ignored if the parameter is not already present. +`config.add.headers`
*optional* | | List of headername:value pairs. If and only if the header is not already set, set a new header with the given value. Ignored if the header is already set. +`config.add.json`
*optional* | | List of property:value pairs. If and only if the property is not present, add a new property with the given value to the JSON body. Ignored if the property is already present. +`config.append.headers`
*optional* | | List of headername:value pairs. If the header is not set, set it with the given value. If it is already set, a new header with the same name and the new value will be set. +`config.append.json`
*optional* | | List of property:value pairs. If the property is not present in the JSON body, add it with the given value. If it is already present, the two values (old and new) will be aggregated in an array. ## Order of execution diff --git a/app/plugins/runscope.md b/app/plugins/runscope.md index 310269588107..06c4980aa9ca 100644 --- a/app/plugins/runscope.md +++ b/app/plugins/runscope.md @@ -10,6 +10,7 @@ nav: items: - label: How it works - label: Configuration + - label: Kong Process Errors --- Logs request and response data to [Runscope][runscope]. Using the Runscope Traffic Inspector, each API call can be fully viewed in it's entirety. All traffic can be searched by keyword (headers and bodies are indexed) and attribute (i.e. status code, response size, response time, etc.). Using Runscope [Live Traffic Alerts][live-traffic-alerts], API failures and exceptions can be caught, notifying your team about problems before your customers find out. Trigger alerts based on any part of the HTTP request or resopnse, including header values, JSON or XML data, connection details and more. Alerts can be sent to Slack, HipChat, PagerDuty, email, or webhook notifications. Live Traffic Alerts is available on all medium and larger plans. @@ -37,15 +38,21 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins/ \ `api`: The `id` or `name` of the API that this plugin configuration will target -parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `runscope` -`config.access_token` | The Runscope [access token][generate-access-token] (or personal access token) for the Runscope API. -`config.bucket_key` | Your Runscope [bucket][runscope-buckets] ID where traffic data will be stored. -`config.log_body` | Default: `false`. Whether or not the request and response bodies should be sent to Runscope. -`config.api_endpoint` | Default: `https://api.runscope.com`. URL for the Runscope API. -`config.timeout` | Default: `10000`. An optional timeout in milliseconds when sending data to Runscope. -`config.keepalive` | Default: `30`. An optional value in milliseconds that defines for how long an idle connection will live before being closed. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `runscope` +`config.access_token` | | The Runscope [access token][generate-access-token] (or personal access token) for the Runscope API. +`config.bucket_key` | | Your Runscope [bucket][runscope-buckets] ID where traffic data will be stored. +`config.log_body`
*optional* | `false` | Whether or not the request and response bodies should be sent to Runscope. +`config.api_endpoint`
*optional* | `https://api.runscope.com` | URL for the Runscope API. +`config.timeout`
*optional* | `10000` | An optional timeout in milliseconds when sending data to Runscope. +`config.keepalive`
*optional* | `30` | An optional value in milliseconds that defines for how long an idle connection will live before being closed. + +## Kong Process Errors + +This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log [runscope]: https://www.runscope.com/?utm_source=getkong&utm_content=plugin [live-traffic-alerts]: https://www.runscope.com/docs/alerts diff --git a/app/plugins/statsd.md b/app/plugins/statsd.md index 92f57e255da2..757182546ae0 100644 --- a/app/plugins/statsd.md +++ b/app/plugins/statsd.md @@ -12,6 +12,7 @@ nav: - label: Usage items: - label: Metrics + - label: Kong Process Errors --- Log API metrics like request count, request size, response status and latency to the StatsD daemon. @@ -33,14 +34,16 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `statsd` -`consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.host`
*optional* | Default `127.0.0.1`. The IP address or host name to send data to -`config.port`
*optional* | Default `8125`. The port to send data to on the upstream server -`config.metrics`
*optional* | The metrics to be logged, by default all are logged. Available values are described at [Metrics](#metrics). -`config.timeout`
*optional* | Default `10000`. An optional timeout in milliseconds when sending data to the upstream server +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `statsd` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.host`
*optional* | `127.0.0.1` | The IP address or host name to send data to +`config.port`
*optional* | `8125` | The port to send data to on the upstream server +`config.metrics`
*optional* | All metrics
are logged | The metrics to be logged. Available values are described at [Metrics](#metrics). +`config.timeout`
*optional* | `10000` | An optional timeout in milliseconds when sending data to the upstream server [api-object]: /docs/latest/admin-api/#api-object [configuration]: /docs/latest/configuration @@ -62,3 +65,7 @@ Metric | description | namespace `status_count` | For each status code returned, increment its counter by 1 | kong.\.\.count `unique_users` | count of users made a request to the api | kong.\.user.uniques `request_per_user` | For each request by the user, increment its counter by 1 | kong.\.\.count + +## Kong Process Errors + +This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log \ No newline at end of file diff --git a/app/plugins/syslog.md b/app/plugins/syslog.md index 54e49177fd23..7c1143ff29c3 100644 --- a/app/plugins/syslog.md +++ b/app/plugins/syslog.md @@ -13,6 +13,7 @@ nav: items: - label: Log Format - label: Notes + - label: Kong Process Errors --- Log request and response data to Syslog. @@ -30,14 +31,16 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `syslog` -`consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.successful_severity`
*optional* | Default `info`. An optional logging severity assigned to the all successful requests with response status code less then 400 . -`config.client_errors_severity`
*optional* | Default `info`. An optional logging severity assigned to the all failed requests with response status code 400 or higher but less than 500. -`config.server_errors_severity`
*optional* | Default `info`. An optional logging severity assigned to the all failed requests with response status code 500 or higher. -`config.log_level`
*optional* | Default `info`. An optional logging severity, any request with equal or higher severity will be logged to System log. +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `syslog` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.successful_severity`
*optional* | `info` | An optional logging severity assigned to the all successful requests with response status code less then 400 . +`config.client_errors_severity`
*optional* | `info` | An optional logging severity assigned to the all failed requests with response status code 400 or higher but less than 500. +`config.server_errors_severity`
*optional* | `info` | An optional logging severity assigned to the all failed requests with response status code 500 or higher. +`config.log_level`
*optional* | `info` | An optional logging severity, any request with equal or higher severity will be logged to System log. [api-object]: /docs/latest/admin-api/#api-object [configuration]: /docs/latest/configuration @@ -117,4 +120,6 @@ A few considerations on the above JSON object: * Make sure Syslog daemon is running on the instance and it's configured with logging level severity same as or lower than the set `config.log_level`. -* This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[nginx_working_dir](/docs/{{site.data.kong_latest.release}}/configuration/#nginx_working_dir)}/logs/error.log +## Kong Process Errors + +This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log diff --git a/app/plugins/tcp-log.md b/app/plugins/tcp-log.md index da773a2e5988..f1b89c33a144 100644 --- a/app/plugins/tcp-log.md +++ b/app/plugins/tcp-log.md @@ -34,14 +34,16 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -form parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `tcp-log` -`consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.host` | The IP address or host name to send data to -`config.port` | The port to send data to on the upstream server -`config.timeout` | Default `10000`. An optional timeout in milliseconds when sending data to the upstream server -`config.keepalive` | Default `60000`. An optional value in milliseconds that defines for how long an idle connection will live before being closed +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +form parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `tcp-log` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.host` | | The IP address or host name to send data to +`config.port` | | The port to send data to on the upstream server +`config.timeout`
*optional* | `10000` | An optional timeout in milliseconds when sending data to the upstream server +`config.keepalive`
*optional* | `60000` | An optional value in milliseconds that defines for how long an idle connection will live before being closed [api-object]: /docs/latest/admin-api/#api-object [configuration]: /docs/latest/configuration @@ -114,4 +116,4 @@ A few considerations on the above JSON object: ## Kong Process Errors -This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[nginx_working_dir](/docs/{{site.data.kong_latest.release}}/configuration/#nginx_working_dir)}/logs/error.log +This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log diff --git a/app/plugins/udp-log.md b/app/plugins/udp-log.md index f6f7d3e65b4a..94086a09f1b2 100644 --- a/app/plugins/udp-log.md +++ b/app/plugins/udp-log.md @@ -33,13 +33,15 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ `api`: The `id` or `name` of the API that this plugin configuration will target -parameter | description ---- | --- -`name` | The name of the plugin to use, in this case: `udp-log` -`consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. -`config.host` | The IP address or host name to send data to -`config.port` | The port to send data to on the upstream server -`config.timeout` | Default `10000`. An optional timeout in milliseconds when sending data to the upstream server +You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information. + +parameter | default | description +--- | --- | --- +`name` | | The name of the plugin to use, in this case: `udp-log` +`consumer_id`
*optional* | | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. +`config.host` | | The IP address or host name to send data to +`config.port` | | The port to send data to on the upstream server +`config.timeout`
*optional* | `10000` | An optional timeout in milliseconds when sending data to the upstream server [api-object]: /docs/latest/admin-api/#api-object [configuration]: /docs/latest/configuration @@ -117,4 +119,4 @@ A few considerations on the above JSON object: ## Kong Process Errors -This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[nginx_working_dir](/docs/{{site.data.kong_latest.release}}/configuration/#nginx_working_dir)}/logs/error.log +This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log From 854c8bec64a6db819759e3bc5e954090baf4842d Mon Sep 17 00:00:00 2001 From: thefosk Date: Wed, 24 Aug 2016 14:06:33 -0700 Subject: [PATCH 2/2] indentation --- app/docs/0.9.x/cli.md | 70 +++++++++++++++++++++--------------------- app/install/docker.md | 2 ++ app/plugins/galileo.md | 1 - app/plugins/statsd.md | 2 +- 4 files changed, 38 insertions(+), 37 deletions(-) diff --git a/app/docs/0.9.x/cli.md b/app/docs/0.9.x/cli.md index 17dfbe5456f1..bcddab24b91b 100644 --- a/app/docs/0.9.x/cli.md +++ b/app/docs/0.9.x/cli.md @@ -62,16 +62,16 @@ Usage: kong cluster COMMAND [OPTIONS] Manage Kong's clustering capabilities. The available commands are: - keygen -c Generate an encryption key for intracluster traffic. - See 'cluster_encrypt_key' setting - members -p Show members of this cluster and their state. - reachability -p Check if the cluster is reachable. - force-leave -p Forcefully remove a node from the cluster (useful - if the node is in a failed state). + keygen -c Generate an encryption key for intracluster traffic. + See 'cluster_encrypt_key' setting + members -p Show members of this cluster and their state. + reachability -p Check if the cluster is reachable. + force-leave -p Forcefully remove a node from the cluster (useful + if the node is in a failed state). Options: - -c,--conf (optional string) configuration file - -p,--prefix (optional string) prefix Kong is running at + -c,--conf (optional string) configuration file + -p,--prefix (optional string) prefix Kong is running at ``` [Back to TOC](#table-of-contents) @@ -91,21 +91,21 @@ Compile the Nginx configuration file containing Kong's servers contexts from a given Kong configuration file. Example usage: - kong compile -c kong.conf > /usr/local/openresty/nginx-kong.conf + kong compile -c kong.conf > /usr/local/openresty/nginx-kong.conf - This file can then be included in an OpenResty configuration: + This file can then be included in an OpenResty configuration: - http { - # ... - include 'nginx-kong.conf'; - } + http { + # ... + include 'nginx-kong.conf'; + } Note: - Third-party services such as Serf and dnsmasq need to be properly configured - and started for Kong to be fully compatible while embedded. + Third-party services such as Serf and dnsmasq need to be properly configured + and started for Kong to be fully compatible while embedded. Options: - -c,--conf (optional string) configuration file + -c,--conf (optional string) configuration file ``` [Back to TOC](#table-of-contents) @@ -120,7 +120,7 @@ Usage: kong health [OPTIONS] Check if the necessary services are running for this node. Options: - -p,--prefix (optional string) prefix at which Kong should be running + -p,--prefix (optional string) prefix at which Kong should be running ``` [Back to TOC](#table-of-contents) @@ -135,12 +135,12 @@ Usage: kong migrations COMMAND [OPTIONS] Manage Kong's database migrations. The available commands are: - list List migrations currently executed. - up Execute all missing migrations up to the latest available. - reset Reset the configured database (irreversible). + list List migrations currently executed. + up Execute all missing migrations up to the latest available. + reset Reset the configured database (irreversible). Options: - -c,--conf (optional string) configuration file + -c,--conf (optional string) configuration file ``` [Back to TOC](#table-of-contents) @@ -161,8 +161,8 @@ If the timeout delay is reached, the node will be forcefully stopped (SIGTERM). Options: - -p,--prefix (optional string) prefix Kong is running at - -t,--timeout (default 10) timeout before forced shutdown + -p,--prefix (optional string) prefix Kong is running at + -t,--timeout (default 10) timeout before forced shutdown ``` [Back to TOC](#table-of-contents) @@ -183,9 +183,9 @@ and stop the old ones when they have finished processing current requests. Options: - -c,--conf (optional string) configuration file - -p,--prefix (optional string) prefix Kong is running at - --nginx-conf (optional string) custom Nginx configuration template + -c,--conf (optional string) configuration file + -p,--prefix (optional string) prefix Kong is running at + --nginx-conf (optional string) custom Nginx configuration template ``` [Back to TOC](#table-of-contents) @@ -204,9 +204,9 @@ This command is equivalent to doing both 'kong stop' and 'kong start'. Options: - -c,--conf (optional string) configuration file - -p,--prefix (optional string) prefix at which Kong should be running - --nginx-conf (optional string) custom Nginx configuration template + -c,--conf (optional string) configuration file + -p,--prefix (optional string) prefix at which Kong should be running + --nginx-conf (optional string) custom Nginx configuration template ``` [Back to TOC](#table-of-contents) @@ -222,9 +222,9 @@ Start Kong (Nginx and other configured services) in the configured prefix directory. Options: - -c,--conf (optional string) configuration file - -p,--prefix (optional string) override prefix directory - --nginx-conf (optional string) custom Nginx configuration template + -c,--conf (optional string) configuration file + -p,--prefix (optional string) override prefix directory + --nginx-conf (optional string) custom Nginx configuration template ``` [Back to TOC](#table-of-contents) @@ -242,7 +242,7 @@ prefix directory. This command sends a SIGTERM signal to Nginx. Options: - -p,--prefix (optional string) prefix Kong is running at + -p,--prefix (optional string) prefix Kong is running at ``` [Back to TOC](#table-of-contents) @@ -258,7 +258,7 @@ Print Kong's version. With the -a option, will print the version of all underlying dependencies. Options: - -a,--all get version of all dependencies + -a,--all get version of all dependencies ``` [Back to TOC](#table-of-contents) diff --git a/app/install/docker.md b/app/install/docker.md index e1ba6d18164d..d7224a9b740d 100644 --- a/app/install/docker.md +++ b/app/install/docker.md @@ -39,6 +39,8 @@ Here is a quick example showing how to link a Kong container to a Cassandra or P $ docker run -d --name kong \ --link kong-database:kong-database \ -e "KONG_DATABASE=cassandra" \ + -e "KONG_CASSANDRA_CONTACT_POINTS=kong-database" \ + -e "KONG_PG_HOST=kong-database" \ -p 8000:8000 \ -p 8443:8443 \ -p 8001:8001 \ diff --git a/app/plugins/galileo.md b/app/plugins/galileo.md index e9615161a8ec..7bb565a20ebf 100644 --- a/app/plugins/galileo.md +++ b/app/plugins/galileo.md @@ -94,4 +94,3 @@ Now, you should see logs telling you what the plugin is doing, as well as respon ## Kong Process Errors This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log - diff --git a/app/plugins/statsd.md b/app/plugins/statsd.md index 757182546ae0..03246e462772 100644 --- a/app/plugins/statsd.md +++ b/app/plugins/statsd.md @@ -68,4 +68,4 @@ Metric | description | namespace ## Kong Process Errors -This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log \ No newline at end of file +This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log