# Tomcat 服务器

### 自动化安装 <a href="#auto" id="auto"></a>

下载 `rasp-java.tar.gz` 或者 `rasp-java.zip` 并解压缩。之后进入到解压后的目录中，e.g **rasp-20181221**

**如果你要开启远程管理**，请先参考 [管理后台 - 添加主机](https://github.com/baidu-security/openrasp-docs-old/blob/main/setup/panel.html#add-host) 文档，找到 `app_id/app_secret/backend_url` 三个关键参数，然后执行如下命令，

```
java -jar RaspInstall.jar -install <tomcat_root> -backendurl http://XXX -appsecret XXX -appid XXX
```

**如果你只是运行单机版**，只需要指定 -install 参数，

```
java -jar RaspInstall.jar -install <tomcat_root>
```

这里的 `<tomcat_root>` 不是 `webapps` 目录，而是 tomcat 的根目录。没有错误表示安装成功，其他配置请参考 [其他配置](https://test-730.gitbook.io/openrasp-documents-old/main-1/others) 文档。安装后，需要重启 Tomcat 服务器生效。

**不重启安装（仅支持 JDK 6-8）**

以上方式安装成功之后需要重启服务器，如果在服务器启动的情况下，不重启安装 OpenRASP，需要在以上命令后面增加 `-pid` 参数指定运行的服务器进程ID:

```
# <server_pid> 为 tomcat 进程 id
# $JAVA_HOME 为 jdk 根目录环境变量，如果未指定该环境变量，替换为 jdk 的完整根目录
java -Xbootclasspath/a:$JAVA_HOME/lib/tools.jar -jar RaspInstall.jar -install <tomcat_root> -pid <server_pid>
```

在 Windows 下面请替换 `$JAVA_HOME` 为 `%JAVA_HOME%`

### RASP 升级方法 <a href="#upgrade" id="upgrade"></a>

在 Linux 下面，可以使用 `bin/catalina.sh stop` 来执行 `graceful stop`

你会在日志里看到类似下面的输出，这表明 Tomcat 将在处理完当前的HTTP后退出

```
Jan 12, 2018 6:11:55 PM org.apache.catalina.core.StandardWrapper unload
INFO: Waiting for 1 instance(s) to be deallocated for Servlet [jsp]
Jan 12, 2018 6:11:56 PM org.apache.catalina.core.StandardWrapper unload
INFO: Waiting for 1 instance(s) to be deallocated for Servlet [jsp]
Jan 12, 2018 6:11:57 PM org.apache.catalina.loader.WebappClassLoaderBase clearReferencesThreads
```

之后参考我们的自动或者手动安装文档，重新安装即可

### 手动安装 - Linux <a href="#linux" id="linux"></a>

**1. 安装软件**

进入到 tomcat 安装目录(绝对路径包含空格将导致启动失败)，e.g `/opt/apache-tomcat-8.5.6`，将 `rasp` 目录复制过来

```bash
cp -R ~/Downloads/rasp-20170721/rasp .
```

OpenRASP 需要在 rasp 目录下释放一些动态链接库，所以还需要修改 rasp 目录的权限，e.g

```
chmod 777 -R rasp
```

否则你可能在 catalina.out 里看到类似这样的错误，

```
com.baidu.openrasp.exception.ConfigLoadException: Fail to extract rasp-log4j.xml, because of: /usr/share/tomcat8/rasp/conf/rasp-log4j.xml (Permission denied)
	at com.baidu.openrasp.messaging.LogConfig.extractLogConfigFile(LogConfig.java:153)
	at com.baidu.openrasp.messaging.LogConfig.completeLogConfig(LogConfig.java:72)
	at com.baidu.openrasp.Agent.loadConfig(Agent.java:91)
	at com.baidu.openrasp.Agent.premain(Agent.java:66)
```

**2. 修改 Tomcat 启动脚本**

打开 `bin/catalina.sh`, 找到如下内容：

```bash
elif [ "$1" = "start" ] ; then
	if [ ! -z "$CATALINA_PID" ]; then
```

修改为如下（增加 `-javaagent` 项）

```bash
elif [ "$1" = "start" ]; then
	JAVA_OPTS="-javaagent:${CATALINA_HOME}/rasp/rasp.jar ${JAVA_OPTS}"
	if [ ! -z "$CATALINA_PID" ]; then
```

对于使用 yum 安装的 tomcat，你需要创建 `/etc/tomcat/conf.d/rasp.conf`，并写入以下内容

```bash
JAVA_OPTS="-javaagent:${CATALINA_HOME}/rasp/rasp.jar ${JAVA_OPTS}"
```

对于JDK9以上版本，还需要增加额外的JDK启动参数，e.g

```bash
JAVA_OPTS="--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED ${JAVA_OPTS}"
JAVA_OPTS="--add-opens=java.base/java.net=ALL-UNNAMED ${JAVA_OPTS}"
JAVA_OPTS="-javaagent:${CATALINA_HOME}/rasp/rasp.jar ${JAVA_OPTS}"
```

**3. 开启远程管理**

如果你不需要远程管理功能，请跳过这个步骤。

首先，请先参考 [管理后台 - 添加主机](https://github.com/baidu-security/openrasp-docs-old/blob/main/setup/panel.html#add-host) 文档，找到 `openrasp.yml` 配置文件内容。然后打开 `<tomcat_home>/rasp/conf/openrasp.yml`，添加或者修改如下内容:

```
# 云控配置
cloud.enable: true
cloud.backend_url: xxx
cloud.app_id: xxx
cloud.app_secret: xxx
cloud.heartbeat_interval: 180
```

**4. 验证安装是否成功**

首先重启tomcat服务器。如果安装了管理后台，在管理后台检查主机是否上线即可；如果是单机版，可以按照如下流程检查:

检查响应的请求头是否包含 `X-Protected-By` 字样，出现则表示安装成功:

```bash
%> curl -v 127.0.0.1:8080

...
X-Protected-By: OpenRASP
X-Request-ID: eb3b8e287de8406bb4bdb9d86bd31f99
...
```

如果使用了反向代理，可能不会看到上面的请求头。此时可以检查 `rasp/logs/rasp/rasp.log` 中是否出现 `OpenRASP Engine Initialized` 字样，出现也表示安装成功:

```bash
%> grep OpenRASP -ir rasp/logs/
rasp/logs/rasp/rasp.log:2018-05-22 16:13:25,842 INFO  [main][com.baidu.openrasp.Agent] OpenRASP Engine Initialized [1.0-SNAPSHOT (build: GitCommit=3da661734e3ad7641cd98e83f32950deaefcacac date=2017-08-14T03:34:41Z)]
```

如果服务器无法启动，请检查 tomcat 启动日志，看Java是否抛出异常，e.g `catalina.out`。如果你无法解决问题，请[请联系我们](https://github.com/baidu-security/openrasp-docs-old/blob/main/aboutus/support.html)。

### 手动安装 - Windows <a href="#windows" id="windows"></a>

**1. 安装软件**

进入到 tomcat 安装目录，e.g `D:\apache-tomcat-8.5.6`，将 `rasp` 目录复制过来

**2. 修改 tomcat 配置**

> 2.1 如果是下载的 "32-bit/64-bit Windows Service Installer" 安装包，

请参考[这篇文章](https://stackoverflow.com/questions/10962821/configure-tomcat-as-a-service-no-catalina-bat)，打开 `bin/tomcatXw.exe`

切换到 `Java` 标签页，

![tomcatw](https://4222974077-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmO3V0DYNdq501EE6igC%2Fuploads%2Fgit-blob-9b2c1856cd47fb77daeb4ed5fe76e8f75c3d6abe%2Ftomcatw.png?alt=media)

在 `Java Options` 下面增加启动参数，**注意替换下绝对路径**，e.g

```bat
-javaagent:C:\Program Files\Apache Software Foundation\Tomcat 7.0\rasp\rasp.jar
```

对于JDK9以上版本，还需要额外增加如下内容

```bat
--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED
--add-opens=java.base/java.net=ALL-UNNAMED
```

> 2.2 如果是下载的 "Windows zip" 安装包

打开 `bin\catalina.bat`, 找到 `:setArgs` 处：

```bat
:setArgs
if ""%1""=="""" goto doneSetArgs
set CMD_LINE_ARGS=%CMD_LINE_ARGS% %1
```

在 `:setArgs` 下增加新的 JAVA\_OPTS，e.g

```bat
:setArgs
if "%ACTION%" == "start" set JAVA_OPTS=-javaagent:%CATALINA_HOME%\rasp\rasp.jar %JAVA_OPTS%
if ""%1""=="""" goto doneSetArgs
set CMD_LINE_ARGS=%CMD_LINE_ARGS% %1
```

对于JDK9以上版本，还需要额外增加两个JDK启动参数，e.g

```bat
:setArgs
if "%ACTION%" == "start" set JAVA_OPTS=-javaagent:%CATALINA_HOME%\rasp\rasp.jar --add-opens=java.base/jdk.internal.loader=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED %JAVA_OPTS%
if ""%1""=="""" goto doneSetArgs
set CMD_LINE_ARGS=%CMD_LINE_ARGS% %1
```

**3. 开启远程管理**

方法同 Linux 版本，在 openrasp.yml 里增加相关配置即可。

**4. 验证安装是否成功**

重启 tomcat 服务器，然后检查日志文件，一般是 `rasp/logs/rasp/rasp.log`，如果出现 `OpenRASP Engine Initialized` 字样，出现则说明安装成功；或者访问一下服务器，检查是否存在 `X-Protected-By: OpenRASP` 响应头，存在即表示安装成功。

[安装中出现任何问题，请联系我们](https://github.com/baidu-security/openrasp-docs-old/blob/main/aboutus/support.html)

### 常见问题 <a href="#faq" id="faq"></a>

**1. Tomcat Windows Service Installer 版本，无法自动安装**

服务版本的安装包，没有提供 `catalina.sh`，只提供了 `tomcatX.exe` 作为启动工具

请参考[Windows 手动安装文档](#windows)，打开 `bin/tomcatXw.exe` 进行配置
