From 7a733ce45896f17f34c29fd259fc3ae184d5897f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=90=B4=E6=99=9F=20Wu=20Sheng?= Date: Mon, 2 Apr 2018 17:18:17 +0800 Subject: [PATCH] Provide advanced features document (#1014) * Provide document for TLS * Provide direct uplink doc. * Add namespace document. * Provide token auth doc. * Provide setting override document. * Fix two typo. * Fix more typos. --- .../src/main/resources/application.yml | 1 + apm-sniffer/config/agent.config | 3 ++ docs/README.md | 6 +++ docs/en/Deploy-skywalking-agent.md | 3 -- docs/en/Direct-uplink.md | 32 +++++++++++++ docs/en/Namespace.md | 39 ++++++++++++++++ docs/en/Setting-override.md | 24 ++++++++++ docs/en/TLS.md | 46 +++++++++++++++++++ docs/en/Token-auth.md | 46 +++++++++++++++++++ 9 files changed, 197 insertions(+), 3 deletions(-) create mode 100644 docs/en/Direct-uplink.md create mode 100644 docs/en/Namespace.md create mode 100644 docs/en/Setting-override.md create mode 100644 docs/en/TLS.md create mode 100644 docs/en/Token-auth.md diff --git a/apm-collector/apm-collector-boot/src/main/resources/application.yml b/apm-collector/apm-collector-boot/src/main/resources/application.yml index bcaa653160..a3a33ea9f4 100644 --- a/apm-collector/apm-collector-boot/src/main/resources/application.yml +++ b/apm-collector/apm-collector-boot/src/main/resources/application.yml @@ -70,6 +70,7 @@ storage: # user_name: sa configuration: default: + # namespace: xxxxx application_apdex_threshold: 2000 service_error_rate_threshold: 10.00 service_average_response_time_threshold: 2000 diff --git a/apm-sniffer/config/agent.config b/apm-sniffer/config/agent.config index 24f1ec9cb5..dcf6aface5 100644 --- a/apm-sniffer/config/agent.config +++ b/apm-sniffer/config/agent.config @@ -14,6 +14,9 @@ # See the License for the specific language governing permissions and # limitations under the License. +# The agent namespace +# agent.namespace=default-namespace + # The application name in UI agent.application_code=Your_ApplicationName diff --git a/docs/README.md b/docs/README.md index 22e54898b6..a3bb22fbe7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,6 +5,12 @@ * [Quick start](en/Quick-start.md) * [Supported middlewares, frameworks and libraries](Supported-list.md) * [How to disable plugins?](en/How-to-disable-plugin.md) + * Advanced Features + * [Override settings through System.properties or System.env](en/Setting-override.md) + * [Direct uplink and disable naming discovery](en/Direct-uplink.md) + * [Open TLS](en/TLS.md) + * [Namespace Isolation](en/Namespace.md) + * [Token Authentication](en/Token-auth.md) * Application Toolkit * [Overview](en/Applicaton-toolkit.md) * [OpenTracing Tracer](en/Opentracing.md) diff --git a/docs/en/Deploy-skywalking-agent.md b/docs/en/Deploy-skywalking-agent.md index 900c39f9cb..ae6eaac4ca 100644 --- a/docs/en/Deploy-skywalking-agent.md +++ b/docs/en/Deploy-skywalking-agent.md @@ -27,9 +27,6 @@ New agent package looks like this： # Advanced features - All plugins are in `/plugin` folder. The plugin jar is active when it is in there. Remove the plugin jar, it disabled. -- Besides set config through `/config/agent.config`, you can use System.Env and System.Properties(-D) to set config. - - Key of env and properties = `skywalking.` + key in `agent.config` file - - Priority: System.Env > System.Properties(-D) > `/config/agent.config` - The default logging output folder is `/log`. # Deploy agent in Tomcat FAQ diff --git a/docs/en/Direct-uplink.md b/docs/en/Direct-uplink.md new file mode 100644 index 0000000000..11f49bbf2e --- /dev/null +++ b/docs/en/Direct-uplink.md @@ -0,0 +1,32 @@ +# Direct uplink +## Supported version +5.0.0-beta + + +## What is direct uplink? +In default, SkyWalking agent uses naming service to find all collector addresses. Then connect to gRPC services. + +In **direct updalink**, mean no naming service available or don't work well, set the gRPC addresses in agent directly. +The agent uses theses addresses to connect gRPC services. + +## Why need this? +Agent uplink data through the following network +1. VPCs in Cloud +1. Internet +1. Different subnet. +1. IPs and Ports proxy + +## Set the agent config +1. Remove `collector.servers` config item. +2. You can find the following settings in `agent.config` +``` +# Collector agent_gRPC/grpc service addresses. +# Secondary address setting, only effect when "collector.servers" is empty. +# By using this, no discovery mechanism provided. The agent only uses these addresses to uplink data. +# Recommend to use this only when collector cluster IPs are unreachable from agent side. Such as: +# 1. Agent and collector cluster are in different VPC in Cloud. +# 2. Agent uplinks data to collector cluster through Internet. +# collector.direct_servers=www.skywalking.service.io +``` + +3. Set `collector.direct_servers` to a domain name, IP:PORTs, with split by comma(,). + diff --git a/docs/en/Namespace.md b/docs/en/Namespace.md new file mode 100644 index 0000000000..d5e9fa5b7c --- /dev/null +++ b/docs/en/Namespace.md @@ -0,0 +1,39 @@ +# Namespace +## Supported version +5.0.0-beta + + +## Background +SkyWalking is a monitoring tool, which collects metrics from a distributed system. In the real world, a very large distributed system +includes hundreds of application, thousands of application instance. In that case, more likely, more than one group, +even than one company are maintaining and monitoring the distributed system. Each one of them takes charge of different parts, +don't or can't share there metrics. + +Namespace is proposal from this.It is used for tracing and monitoring isolation. + +## Set the namespace +### Set agent.namespace in agent config +```properties +# The agent namespace +# agent.namespace=default-namespace +``` + +The default value of `agent.namespace` is empty. + +**Influence** +The default header key of SkyWalking is `sw3`, more in this [document](Skywalking-Cross-Process-Propagation-Headers-Protocol-v1.md). +After `agent.namespace` set, the key changes to `namespace:sw3`. + +The across process propagation chain breaks, when the two sides are using different namespace. + +### Set namespace in collector +```yml +configuration: + default: + namespace: xxxxx +``` + +**Influences** +1. If cluster model is active, with zookeeper implementation, The path in zookeeper is changed to include namespace prefix path. +1. If use Elasticsearch as storage implementation, all type names are changed to include namespace prefix. + + diff --git a/docs/en/Setting-override.md b/docs/en/Setting-override.md new file mode 100644 index 0000000000..41770e0d8e --- /dev/null +++ b/docs/en/Setting-override.md @@ -0,0 +1,24 @@ +# Setting Override +## Supported version +5.0.0-beta + + +_Agent setting override supported since 3.2.5_ + +## What is setting override? +In default, SkyWalking provide `agent.config` for client, and `application.yml` for server settings. + +Setting override means end user can override the settings in these config file, by using system properties, or system environment variables. + +## Override priority +System.Env > System.Properties(-D) > Config file + +## Override +### Agent +Use `skywalking.` + key in config file as system properties and envs key, to override the value. + +- Why need this prefix? + + The agent system properites and env share with target application, this prefix can avoid variable conflict. + +### Collector +Use key in config file as system properties and envs key, to override the value. \ No newline at end of file diff --git a/docs/en/TLS.md b/docs/en/TLS.md new file mode 100644 index 0000000000..d67654f384 --- /dev/null +++ b/docs/en/TLS.md @@ -0,0 +1,46 @@ +# Support Transport Layer Security (TLS) +Transport Layer Security (TLS) is a very common security way when transport data through Internet. +In some use cases, end users report the background: + +> Target(under monitoring) applications are in a region, which also named VPC, +at the same time, the SkyWalking backend is in another region (VPC). +> +> Because of that, security requirement is very obvious. + +## Requirement +Enable **direct uplink**, by following this [document](direct-uplink.md). + +Because of uplink through internet, with security concern, the naming mechanism didn't fit. +So we didn't support TLS in naming service of HTTP service. + +## Supported version +5.0.0-beta + + +## Authentication Mode +Only support **no mutual auth**. +- Use this [script](../../tools/TLS/tls_key_generate.sh) if you are not familiar with how to generate key files. +- Find `ca.crt`, and use it at client side +- Find `server.crt` and `server.pem`. Use them at server side. + +## Open and config TLS + +### Agent config +- Place `ca.crt` into `/ca` folder in agent package. Notice, `/ca` is not created in distribution, please create it by yourself. + +Agent open TLS automatically after the `/ca/ca.crt` file detected. + +### Collector config +Module `agent_gRPC/gRPC` supports TLS. And only this module for now. + +- Uncomment the `ssl_cert_chain_file` and `ssl_private_key_file` settings in `application.yml` +- `ssl_cert_chain_file` value is the absolute path of `server.crt` +- `ssl_private_key_file` value is the absolute path of `server.pem` + +## Avoid port share +In most cases, we recommend sharing port for all gRPC services in `agent_gRPC/gRPC` and `remote/gRPC` modules. +But don't do this when you open TLS in `agent_gRPC/gRPC`, the obvious reason is you can't listen a port with and without TLS. + +The solution is, change the `remote/gRPC/port`. + +## How about other listening ports +Please use other security ways to make sure can't access other ports out of region (VPC), such as firewall, proxy. \ No newline at end of file diff --git a/docs/en/Token-auth.md b/docs/en/Token-auth.md new file mode 100644 index 0000000000..27c754325e --- /dev/null +++ b/docs/en/Token-auth.md @@ -0,0 +1,46 @@ +# Token Authentication +## Supported version +5.0.0-beta + + +## How need token authentication after we have TLS? +TLS is about transport security, which makes sure the network can be trusted. +The token authentication is about monitoring application data **can be trusted**. + +## Token +In current version, Token is considered as a simple string. + +### Set Token +1. Set token in agent.config file +```properties +# Authentication active is based on backend setting, see application.yml for more details. +agent.authentication = xxxx +``` + +2. Set token in application.yml file +```yaml +agent_gRPC: + gRPC: + host: localhost + port: 11800 + + #Set your own token to active auth + authentication: xxxxxx +``` + +## Authentication fails +The Collector verifies every request from agent, allowed only the token match. + +If the token is not right, you will see the following log in agent +``` +org.apache.skywalking.apm.dependencies.io.grpc.StatusRuntimeException: PERMISSION_DENIED +``` + +## FAQ +### Can I use token authentication instead of TLS? +No, you shouldn't. In tech way, you can of course, but token and TLS are used for untrusted network env. In that circumstance, +TLS has higher priority than this. Token can be trusted only under TLS protection.Token can be stolen easily if you +send it through a non-TLS network. + +### Do you support other authentication mechanisms? Such as ak/sk? +For now, no. But we appreciate someone contributes this feature. + -- GitLab