update docs

Author: zhaohaifeng [赵海锋]

.vscode/.browse.VC.db

@@ -5,7 +5,7 @@
 -: README
 -: installation
 -: getting_started
+-: roadmap
 
 [faqs]
--: README
--: getting_started
+-: README

.vscode/.browse.VC.db-wal

@@ -2,5 +2,22 @@
 name: 常见问题
 ---
 
-## 巴拉巴拉
-霜期塔顶地
+## 常见问题
+### openresty的语法正确，却启动失败
+
+以下的错误原因为有些linux发布版本要求监听1024以下的端口的服务必须以root权限启动。
+```bash
+/usr/local/openresty/nginx/sbin/nginx -t
+nginx: [warn] the "user" directive makes sense only if the master process runs with super-user privileges, ignored in /usr/local/openresty/nginx/conf/nginx.conf:1
+nginx: the configuration file /usr/local/openresty/nginx/conf/nginx.conf syntax is ok
+nginx: [emerg] bind() to 0.0.0.0:80 failed (13: Permission denied)
+nginx: configuration file /usr/local/openresty/nginx/conf/nginx.conf test failed
+
+```
+解决方案：以root账户或用sudo命令执行。
+
+### 在waf admin中同步全部策略报错
+
+返回`{"Status":1,"Message":"reload nginx configure faild"}`错误的原因为waf admin是以普通用户权限启动的，在同步完策略后无法操作openresty的master进程完成策略加载的操作。
+
+解决方案：以root账户或用sudo命令启动waf admin。

TOC.ini

@@ -2,21 +2,24 @@
 name: 简介
 ---
 
-# xsec-waf
+# X-WAF
 
-xsec-waf是一款适用小企业的云waf系统。
+X-WAF是一款适用中、小企业的云WAF系统，让中、小企业也可以非常方便地拥有自己的免费云WAF。
 
 # 主要特性
 
-- 安装、部署与维护非常简单，小企业也可以非常方便地拥有自己的云WAF
-- 规则可以后台管理
-- 后端服务器可以后端管理
-- 支持IP和URL的黑白名单
+- 安装、部署与维护非常简单
+- 支持在线管理waf规则
+- 支持在线管理后端服务器
+- 支持IP和URL的黑、白名单
 - 支持对get\post\cookies\user_agent参数进行过滤
-- 多台waf的配置可自动同步
+- 支持多台waf的配置可自动同步
+- 跨平台，支持在linux\unix\mac和windows服务器中部署
 
-# 架构
-xsec-waf由waf与Waf管理后台组成：
+# 架构简介
+x-waf由waf主体与Waf管理后台组成：
 
-- waf是基于openresty + lua开发的
-- waf管理后台是采用golang + xorm + macrom开发的
+- [waf主体](https://github.com/xsec-lab/x-waf/tree/master/waf)：基于openresty + lua开发。
+- [waf管理后台](https://github.com/xsec-lab/x-waf/tree/master/waf-admin)：采用golang + xorm + macrom开发的，支持二进制的形式部署。
+
+waf和waf-admin必须同时部署在充当云waf的反向代理服务器中。

zh-CN/faqs/README.md

@@ -4,24 +4,33 @@ name: 开始使用
 
 ## 后端服务器管理
 当多台waf做负载均衡时，也只需登录其中一台进行管理即可，所有的配置信息会自动同步到所有的服务器中。
-管理地址为：http://ip:5000/login/，默认账户及口令为：admin，[email protected]，请管理员登录系统后第一时间修改密码。
+
+管理地址为：http://ip:5000/login/
+
+默认账户及口令为：admin，[email protected]请管理员登录系统后第一时间修改密码。
 
 ### 新增站点
+
 在`Site Manager`选项中，可以新增一个后端服务器，需要填写以下内容：
+
 - Site Name，表示要加入waf的网站的域名
 - 80表示该网站监听的端口
 - Backend，表示有多少个后台app server，可以写多个（换行分割），例如：
 ```bash
 1.1.1.1:80
 8.8.8.8:80
 ```
+
 - SSL Status，表示是否启用ssl，参数为on或off（如果要启用的话，需要在nginx中配置有效的证书）
 - Debug Level，表示日志级别，可选的参数有`debug, info, notice, warn, error, crit, alert, emerg`
 
 ### 站点配置同步
+
 新增站点后，需要在后台同步站点信息后方可生效，同步的方式有2种：
+
 1. 全部同步
 1. 针对某一新增的站点进行同步
 
 ## waf规则管理
+
 在`waf Rules`选项中，可以修改waf的规则，修改完后可以点击“同步全部策略”按钮，将最新的规则同步到所有的服务器并让openresty重新加载。

zh-CN/intro/README.md

@@ -64,9 +64,9 @@ make build && make install
 yum -y install sqlite sqlite-devel unzip 
 /usr/local/openresty/luajit/bin/luarocks install luafilesystem 
 ```
-## 安装waf管理后台xsec-waf-web
+## 安装waf管理后台x-waf-admin
 ### 二进制安装
-直接从github中下载二进制版本
+直接从github中下载对应操作系统的二进制版本
 
 ### 源码安装
 
@@ -86,14 +86,14 @@ go get github.com/go-xorm/xorm
 
 # 部署与配置
 ## waf部署与配置
-### nginx的配置
-- 将xsec-waf的代码目录`waf`放置到openresty的`/usr/local/openresty/nginx/conf`目录下；
-- 在nginx的conf的目录下新建vhosts目录
+### openresty的配置
+
+将x-waf的代码目录`waf`放置到openresty的`/usr/local/openresty/nginx/conf`目录下，并在openresty的conf的目录下新建vhosts目录
 
 ```bash
 mkdir -p /usr/local/openresty/nginx/conf/vhosts
 ```
-- nginx.conf的配置可以参考以下：
+以下为openresty的配置范例：
 
 ```ini
 user  nginx;
@@ -271,27 +271,31 @@ config_output_html=[[
 return _M
 ```
 
-- waf启动测试，如果测试返回ok则表示配置正确
+### waf测试
+
+使用root权限执行以下命令测试配置文件的正确性，如果测试结果返回ok则表示配置是正确的。
+
 ```bash
 $ sudo /usr/local/openresty/nginx/sbin/nginx -t
 [sudo] hartnett 的密码：
 nginx: the configuration file /usr/local/openresty/nginx/conf/nginx.conf syntax is ok
 nginx: configuration file /usr/local/openresty/nginx/conf/nginx.conf test is successful
 ```
 
-- 启动waf
+如果配置文件正常，可以通过以下命令正式启动waf
 
 ```bash
 $ sudo /usr/local/openresty/nginx/sbin/nginx
 ```
 
-- waf有效性测试。
+### WAF防御效果测试
 
 在服务器中提交`curl http://127.0.0.1/\?id\=1%20union%20select%201,2,3`，
-如果返回` 欢迎在遵守白帽子道德准则的情况下进行安全测试`就表示waf已经正常运行了。
+如果返回的内容中包含`欢迎在遵守白帽子道德准则的情况下进行安全测试`等字样就表示waf已经在正常运行了。
 
-## waf-admin的配置
-- waf-admin需要mysql的支持，事先需要准备一个mysql数据库的账户，以下为详细的配置信息
+
+## waf-admin配置
+- waf-admin需要mysql的支持，事先需要准备一个mysql数据库的账户，以下为app.ini的配置范例：
 
 ```ini
 RUN_MODE = dev
@@ -313,4 +317,6 @@ NAME = waf
 [waf]
 RULE_PATH = /usr/local/openresty/nginx/conf/waf/rules/
 ```
-- 然后在当前目录执行./server测试程序是否可以正常启动，如可以正常启动，则可能通过supversisor、nohup、systemd等将server跑在后台。
+配置完成后在当前目录执行./server测试程序是否可以正常启动，waf-admin需要操作nginx的master进程，所以需要以root权限启动。
+
+可以使用supversisor、nohup、systemd等将waf-admin跑在后台。

zh-CN/intro/getting_started.md

@@ -0,0 +1,7 @@
+---
+name: 开发计划
+---
+
+# 开发计划
+
+如果您发现bug或有一些期望的新功能，可以通过[发起工单](https://github.com/xsec-lab/xsec-waf-docs/issues) 的形式告知作者。