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.

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

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
 

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)

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

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(,).
+

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.
+
+

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.

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.

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. 
+