Ansible 角色：安装 Apache Tomcat Java 应用服务器（可选使用 Hugepages）

安装 Apache Tomcat Java 应用服务器。最完整的 Tomcat 安装，支持 init.d 脚本、应用命名、Hugepages、安全加固、美观的错误页面、sha512 哈希密码、JMX 配置、多种 Tomcat 版本、分离的 catalina_home 和 catalina_base。

目录

1. [要求]
2. [安装]
3. [角色变量]
4. [依赖]
5. [示例剧本]
6. [许可]
7. [作者信息]
8. [支持]
9. [贡献]
10. [捐赠]

要求

无。

安装

ansible-galaxy install kami911.tomcat

角色变量

可用变量列在下面，并附有默认值（请查看 defaults/main.yml）：

安装相关选项

tomcat_manage_java_pkg: False

Tomcat 是否管理 Java 安装，是否安装 OpenJDK。

tomcat_installer_force_download: true

始终下载安装文件。如果已下载，尝试重新下载。

tomcat_download_mirror: https://archive.apache.org

下载安装文件的镜像。

tomcat_download_url: '{{ tomcat_download_mirror }}/dist/tomcat/tomcat-{{ tomcat_majorversion }}/v{{ tomcat_majorversion }}.{{ tomcat_minorversion }}.{{ tomcat_patchversion }}/bin/{{ tomcat_download_file }}'

安装文件的完整 URL。

tomcat_installer_force_overwrite: true

始终覆盖目标机器上的安装文件。

tomcat_installer_keep: true

成功安装后不删除安装程序。

tomcat_installer_local: false

将安装文件直接下载到 Ansible 主机（不下载到目标机器）。Ansible 将从主机上下载并复制安装文件。

tomcat_download_validate_certs: false

下载外部安装文件时验证证书。

tomcat_force_update: false

当相同版本已安装时强制更新。旧版本始终更新。

版本相关选项

tomcat_majorversion: 8

Tomcat 主版本。

tomcat_minorversion: 5

Tomcat 次版本。

tomcat_patchversion: 4

Tomcat 微版本。

tomcat_java_version: 11

配置 Tomcat 使用指定版本的 Java。

Hugepages 使用相关选项

tomcat_use_huge_pages: True

使用 Huge Pages（Java称其为：UseLargePages）以提高 Java 应用程序性能。当进程使用一些内存时，CPU 会将 RAM 标记为该进程使用的。为了提高效率，CPU 以 4K 字节的块分配 RAM（这是许多平台上的默认值）。这些块被称为页面。页面可以被交换到磁盘等。

由于进程地址空间是虚拟的，CPU 和操作系统必须记住哪些页面属于哪个进程，以及它们存储在哪里。显然，页面越多，找到内存映射位置所需的时间就越长。当进程使用 1GB 的内存时，这需要查找 262144 个条目（1GB / 4K）。如果一个页面表项消耗 8 字节，那么查找需要 2MB（262144 * 8）。

Debian Wiki: Hugepages

启用后使用 KAMI911:hugepages 在 Linux 中配置 Huge Pages。

端口、连接和防火墙相关选项

tomcat_manage_firewalld: true

角色管理所需端口的 firewalld 设置。

tomcat_enable_firewalld: false

强制安装和启用 firewalld 服务。

tomcat_manage_firewalld_use_zone: true

Tomcat firewalld 使用区域（默认）或使用源地址。

“连接器”代表接收请求和返回响应的端点。文档参见：

• Java HTTP 连接器: /docs/config/http.html
• Java AJP 连接器: /docs/config/ajp.html
• APR（HTTP/AJP）连接器: /docs/apr.html

定义一个非 SSL/TLS HTTP/1.1 连接器

所有与连接器、端口和防火墙相关的配置都收集在名为 tomcat_server 的变量下：

tomcat_server:
  - port: 8080  # Tomcat 监听的 http 连接端口。
    connector:
      protocol: 'HTTP/1.1'
      connectionTimeout: 20000
      redirectPort: 8444
      Server: ' '
      URIEncoding: UTF-8
      Secure: false
      compressibleMimeType: 'text/html,text/xml,text/css,text/javascript,application/x-javascript,application/javascript,text/plain'  # Tomcat http 连接压缩的 MIME 类型。
      compression: on  # 启用/禁用 Tomcat http 连接压缩内容。
      compressionMinSize: 256  # Tomcat http 连接最小压缩文件大小。
      noCompressionUserAgents: ''  # 对于这些浏览器用户代理，Tomcat http 连接必须不压缩。
    source: []  # 根据您的网络进行调整
    #  - '192.168.10.0/24'
    #  - '172.20.10.0/23'
    executor:  # 如果您想使用，请指定执行器。请勿忘记在连接器设置中使用 'executor' 键。
      name: tomcatHTTPThreadPool
      namePrefix: catalina-exec-http-
      maxThreads: 300
      minSpareThreads: 5
  - port: 8009  # Tomcat 监听的 http 连接端口。
    connector:
      protocol: 'AJP/1.3'
      redirectPort: 8444
    source: []  # 根据您的网络进行调整
    #  - '0.0.0.0/0'
    #  - '60.60.60.60/0'
    executor:    # 如果您想使用，请指定执行器。请勿忘记在连接器设置中使用 'executor' 键。
      name: tomcatAJPThreadPool
      namePrefix: catalina-exec-ajp-
      maxThreads: 900
      minSpareThreads: 20

Tomcat “连接器”可以使用名为 executor 的共享线程池来处理 http/ajp/https 连接。

编码相关选项

tomcat_file_encoding: UTF-8

Tomcat 文件编码参数：UTF-8

tomcat_page_encoding: UTF-8

Tomcat 页面编码参数：UTF-8

区域相关选项

区域标识特定语言和地理区域。

有关 Java 的区域设置更多信息，请访问： https://www.oracle.com/technical-resources/articles/javase/locale.html

tomcat_locale_language: en

语言代码由 ISO 639 定义，这是一个国际标准，为世界上大多数语言分配两位和三位代码。区域使用两位代码来标识目标语言。

tomcat_locale_country: EN

国家代码由 ISO 3166 定义，另一国际标准。它为世界上每个国家或主要地区定义两位和三位缩写。与语言代码不同，国家代码使用大写字母。

tomcat_locale_region:

国家代码和地区由 ISO 3166 定义，另一个国际标准。

tomcat_locale_variant:

操作系统、浏览器和其他软件供应商可以使用该代码提供额外功能或自定义，这些功能仅凭语言和国家标识无法实现。例如，软件公司可能需要为特定操作系统指明区域设置，因此其开发人员可能会为西班牙客户创建 es_ES_MAC 或 es_ES_WIN 区域。

内存配置相关选项

tomcat_java_heap_min: 4096

Java 最小堆大小。内存大小以兆字节（m）为单位。

tomcat_java_heap_max: 4096

Java 最大堆大小。内存大小以兆字节（m）为单位。

tomcat_java_permsize_min: 384

Java 最小永久代大小。内存大小以兆字节（m）为单位。仅适用于 Java 7 或更早版本。

tomcat_java_permsize_max: 384

Java 最小永久代大小。内存大小以兆字节（m）为单位。仅适用于 Java 7 或更早版本。

tomcat_java_thread_stack_size: 512

Java 线程栈大小，以千字节（k）为单位。

其他 Java 参数

查看各版本的 Java 参数

本地库相关选项

tomcat_native_library_enable: false

尝试使用 Tomcat Native Library。Apache Tomcat Native Library 是与 Apache Tomcat 一起使用的一个可选组件，允许 Tomcat 使用某些本地资源以提高性能和兼容性等。

更多信息：Tomcat Native

日志相关选项

tomcat_catalina_logs_directory_mode: "u=rwx,g=rwx,o="

Tomcat catalina 日志目录模式。

tomcat_access_log_filename: '{{ tomcat_system_name }}_access'

设置 Tomcat 的访问日志默认文件名。

tomcat_access_log_extension: '.log'

设置 Tomcat 的访问日志默认文件扩展名。

tomcat_access_log_pattern: "%{yyyy-MM-dd}tT%{HH:mm:ss.SSSXXXZ}t ${shortSystemName} %v %h (%{X-Forwarded-For}i) %A:%p %I %u "%r" %s %b %D %{Referer}i %{User-Agent}i"

Tomcat 访问日志的模式字符串。Tomcat 访问日志记录：

模式属性的值由文本字符串与前缀为 "%" 的模式标识符组成，以便用当前请求和响应中的对应变量值替换。支持以下模式代码：

%a - 远程 IP 地址
%A - 本地 IP 地址
%b - 发送的字节数，不包括 HTTP 头；如果为零则为 '-'
%B - 发送的字节数，不包括 HTTP 头
%h - 远程主机名（如果连接器的 enableLookups 为 false，则返回 IP 地址）
%H - 请求协议
%l - 来自 identd 的远程逻辑用户名（始终返回 '-'）
%m - 请求方法（GET，POST 等）
%p - 接收该请求的本地端口。另见 %{xxx}p。
%q - 查询字符串（如果存在，则以 '?' 开头）
%r - 请求的第一行（方法和请求 URI）
%s - 响应的 HTTP 状态码
%S - 用户会话 ID
%t - 日期和时间，以通用日志格式
%u - 被认证的远程用户（如果有），否则为 '-'
%U - 请求的 URL 路径
%v - 本地服务器名称
%D - 处理请求所需的时间（毫秒）。注意：在 httpd 中 %D 是微秒。从 Tomcat 10 开始行为将与 httpd 对齐。
%T - 处理请求所需的时间（秒）。注意：此值具有毫秒分辨率，而在 httpd 中则具有秒分辨率。从 Tomcat 10 开始行为将与 httpd 对齐。
%F - 提交响应所需的时间（毫秒）
%I - 当前请求线程名称（可以与堆栈跟踪进行比较）
%X - 响应完成时的连接状态：
    X = 在响应完成之前中止连接。
    + = 发送响应后连接可能保持活动状态。
    - = 发送响应后连接将关闭。

此外，还支持记录传入或传出的标头、cookie、会话或请求属性和特殊时间戳格式。其模式类似于 Apache HTTP 服务器日志配置语法。它们可以用不同的 xxx 键多次使用：

%{xxx}i 记录名称为 xxx 的传入标头的值
%{xxx}o 记录名称为 xxx 的传出标头的值
%{xxx}c 记录名称为 xxx 的 cookie 的值
%{xxx}r 记录名称为 xxx 的 ServletRequest 属性的值
%{xxx}s 记录名称为 xxx 的 HttpSession 属性的值
%{xxx}p 记录本地（服务器）端口（xxx==local）或远程（客户端）端口（xxx=remote）
%{xxx}t 记录格式化后的请求结束时间的时间戳，使用增强的 SimpleDateFormat 模式 xxx

支持 SimpleDateFormat 所有格式。在此基础上，还添加了以下扩展：

sec - 自纪元起的秒数
msec - 自纪元起的毫秒数
msec_frac - 毫秒小数部分

这些格式不能与 SimpleDateFormat 格式混合在同一格式标记中。

此外，可以定义是否记录请求开始时间或响应结束时间的时间戳：

begin 或前缀 begin：选择请求开始时间
end 或前缀 end：选择响应结束时间

通过向模式添加多个 %{xxx}t 标记，还可以记录两个时间戳。

快捷模式 pattern="common" 对应于通用日志格式，定义为 '%h %l %u %t "%r" %s %b'。

快捷模式 pattern="combined" 会把 Referer 和 User-Agent 头的值（每个值用双引号括起来）附加到通用模式后面。

tomcat_juli_logging_format: "%1$tY.%1$tm.%1$tdT%1$tT.%1$tL%1$tz ${shortSystemName} %4$-4s %5$s [%2$s]%6$s%n"

Tomcat 日志的通用日志格式。

时间戳格式如下： https://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html#dt https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html

格式如下： https://docs.oracle.com/javase/7/docs/api/java/util/logging/SimpleFormatter.html#format(java.util.logging.LogRecord)

tomcat_juli_logging_handler: "AsyncFileHandler" # TODO: Tomcat 6-7 仅使用 FileHandler

在 Tomcat 8-9 中使用 AsyncFileHandler。

tomcat_juli_logging_level: "FINE"

将 [1catalina|2localhost|3manager|4host-manager].org.apache.juli.AsyncFileHandler.level 和 java.util.logging.ConsoleHandler.level 设置为此日志级别。可能的值有： SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST 或 ALL。默认值为 FINE。

tomcat_java_gc_log: "-Xlog:gc*=debug,heap*=debug,safepoint=debug,age*=debug,stringdedup*=debug,gc+heap=trace:'${CATALINA_BASE}/logs/gc/gc_%t_%p.log':time,uptimenanos,pid,tid,level,tags:filecount=200,filesize=1G"

设置 GC 日志的格式和位置。

tomcat_java_gc_log_old: "-Xloggc:'${CATALINA_BASE}/logs/gc/gc_$(date +%Y-%m-%d_%H%M).log' -XX:+PrintGC -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCApplicationStoppedTime -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=200 -XX:GCLogFileSize=1G -XX:+PrintHeapAtGC -XX:+PrintTenuringDistribution -XX:+PrintStringDeduplicationStatistics"

为 Java 9 之前的版本设置 GC 日志的格式和位置。

Tomcat 加固相关选项

tomcat_use_secure_flag: True

如果希望调用 request.isSecure() 对于通过此连接器接收的请求返回 true，请将此属性设置为 True。您希望在 SSL 连接器或从 SSL 加速器（如加密卡、SSL 设备或甚至网络服务器）接收数据的非 SSL 连接器上启用此功能。默认值为 False。

tomcat_session_http_only: True

强制 Tomcat 仅通过 http 使用 JSESSIONID cookie。

tomcat_session_secure: True

强制 Tomcat 使用安全的 JSESSIONID cookie。

命名、文件夹、服务相关选项

tomcat_system_name: "tomcat_app_sys"

可选：为此 Tomcat 实例使用此文件夹名称。

tomcat_short_system_name: 'TT'

可选：为标签相关文件（如日志）使用此标识符。

tomcat_service_enabled: true

启用或禁用系统启动时 Tomcat 服务。

tomcat_system_home: "{{ tomcat_base_folder }}/{{ tomcat_system_user }}"

Tomcat 二进制文件的文件夹。

# tomcat_system_home: "{{ tomcat_base_folder }}/{{ tomcat_system_name }}" # 这是一个可选设置，使用 tomcat_system_name。

使用 tomcat_system_home 变量定义 Tomcat 二进制文件的文件夹。

tomcat_catalina_home: "{{ tomcat_system_home }}/tomcat"

Tomcat Catalina 主文件夹。

tomcat_catalina_base: "{{ tomcat_catalina_home }}"

Tomcat Catalina 基础文件夹。

Tomcat JMX 访问配置

tomcat_jmx_authenticate: true

启用或禁用 JMX 身份验证。

tomcat_jmx_users:
- user: monitoring
    pass: IAGeqqIFpLEiSxWpIhnASaDI31ds
    type: readonly
- user: administrator
    pass: fYHKXKa68MKQcaq9S8BUEFP8dSN7
    type: readwrite

定义 JMX 用户及其角色和密码。

Tomcat LDAP 身份验证配置相关选项

tomcat_ldap_enable: false

启用 Tomcat LDAP 身份验证。默认禁用。

tomcat_ldap_debug_level: 99

Tomcat LDAP 身份验证调试级别。默认值为 99。

tomcat_ldap_url: 'ldap://ldap.cloud.department.ca:389'

Tomcat LDAP 身份验证 URL。请根据您的设置调整此值。

tomcat_ldap_user: 'technicaluser@cloud.department.ca'

访问 LDAP 服务器的 Tomcat LDAP 用户。请根据您的设置调整此值。

tomcat_ldap_pass: 'password'

访问 LDAP 服务器的 Tomcat LDAP 用户密码。请根据您的设置调整此值。

tomcat_ldap_user_ou: 'ou=Users,dc=cloud,dc=department,dc=ca'

Tomcat LDAP 身份验证的有效用户的组织单位。请根据您的设置调整此值。

tomcat_ldap_user_name: "(sAMAccountName={0})"

Tomcat LDAP 身份验证的用户名称。默认设置为 (sAMAccountName={0})，对此于 Windows Active Directory 非常适合。

tomcat_ldap_user_referrals: 'follow'

引用允许一个目录树在多个 LDAP 服务器之间分区和分布，这意味着 LDAP 服务器可能不会存储整个 DIT，同时仍然能够包含对其他 LDAP 服务器的引用，这些服务器提供请求的信息。因此，当您浏览目录时，LDAP 服务器可以通过返回引用来将您指向另一个服务器。引用是具有引用对象类的条目，其中至少包含一个属性，属性名称为 ref，值为 LDAP 服务器上被引用条目的 LDAP URL。 https://www.ldapadministrator.com/resources/english/help/la20121/ch05s05.html

tomcat_ldap_user_subtree: true

Tomcat LDAP 用户可以位于组织单位的子树中。

tomcat_ldap_role_ou: 'ou=TomcatAdmin,ou=Groups,dc=cloud,dc=department,dc=ca'

Tomcat LDAP 身份验证的用户组的组织单位。请根据您的设置调整此值。在此创建具有 Tomcat 角色名称的安全组，如 "manager-gui"。

tomcat_ldap_role_name: 'name'

用户安全组名称作为 Tomcat 角色名称，如 "manager-gui"。默认值适合用于 Tomcat 角色名称。

tomcat_ldap_role_subtree: true

Tomcat LDAP 组可以位于组织单位的子树中。

tomcat_ldap_role_search: '(member={0})'

每个匹配安全组名称的成员都可以根据角色的规定访问服务器。

调试端口相关选项

tomcat_debug_enable: false

启用 Tomcat 调试端口。

tomcat_debug_port: 8000

指定 Tomcat 调试端口。

tomcat_debug_sever: '{{ ansible_hostname }}' # 或 127.0.0.1

允许来自所有位置连接或仅允许来自本地连接。

tomcat_debug_parameter: '-agentlib:jdwp=transport=dt_socket,address={{ tomcat_debug_sever }}:{{ tomcat_debug_port }},server=y,suspend=n'

指定 Tomcat 调试参数。

第三方分析器相关选项

tomcat_profiler_enable: false

启用 Tomcat 分析。

tomcat_profiler_parameter: '-agentpath:/opt/profiler/libyjpagent.so=port=8200-8220,listen=all,delay=10000'

为 Tomcat 指定外部分析器参数。

Tomcat 日志压缩选项

tomcat_log_rotate_minsize: 20K

日志文件在超过指定大小（字节）时旋转，但在额外指定的时间间隔（每日、每周、每月或每年）之前不会旋转。相关的大小选项与时间间隔选项相互排斥，并且会导致日志文件在不考虑上次旋转时间的情况下进行旋转。当使用 minsize 时，会同时考虑日志文件的大小和时间戳。

tomcat_log_compress_command: '/usr/bin/xz'

压缩程序的程序位置。默认是 xz，因此默认值为 '/usr/bin/xz'。您还可以使用例如：'/usr/bin/gzip'。

tomcat_log_compress_options: '-3'

压缩程序的选项。对于 xz，默认是 '-3'，这意味着良好的平衡压缩。对于 gzip，您可以使用例如：'-9'。

tomcat_log_compress_extension: '.xz'

日志旋转规则的文件扩展名。xz 为 '.xz'，而 gzip 为 'gz'。

Tomcat 安全设置

tomcat_security_random_device: random

在Linux上有两个常规随机设备：/dev/random 和 /dev/urandom。最优质的随机性来自 /dev/random，因为它是一个阻塞设备，将等待直到有足够的熵继续提供输出。假设熵充足，您应该看到来自 /dev/urandom 的随机性与之相当；然而，由于它是一个非阻塞设备，即使熵池耗尽，它也会继续生成“随机”数据。这可能导致较低质量的随机数据，因为先前数据的重复概率大大增加。当可用的熵在生产服务器上低时，可能会发生许多不良情况，尤其是当该服务器执行加密功能时。 如果您的硬件支持基于硬件的随机设备，您可以使用 rngd 并使用 rng-tools 包中的 rngtest 工具检查随机性。 如果您的硬件不支持基于硬件的随机设备，您可以使用来自 haveged 包的 haveged。这两种软件包都可以降低 Tomcat 启动时间和与加密相关的操作的时间。 默认设置提供了 "-Djava.security.egd=file:///dev/./random"，这是在启用 rngd 或 haveged 时加密设置的最佳选择。

依赖

无。

示例剧本

- hosts: all
  roles:
    - tomcat

许可

Tomcat Ansible 角色应用程序和文档根据 MIT / BSD 的条款进行授权，您将在源包中找到此许可的副本 LICENSE 文件中。

作者信息

此角色由 Kálmán Szalai - KAMI 创建，时间为 2016-2020。

支持

如果您有任何问题，请随时与我联系。 如果您发现 bug，或有功能请求，可以 填写问题。

作为 AWX 剧本的子模块使用

添加为子模块

git submodule add --force [email protected]:KAMI911/ansible-role-tomcat.git roles/tomcat

更新子模块

仅更新此子模块

git submodule update --remote roles/tomcat/

更新所有子模块：

git submodule foreach git pull origin master

贡献

有很多方法可以为 ansible-role-tomcat 做出贡献——无论是发送补丁、测试、报告错误，还是审查和更新文档。每一份贡献都备受赞赏！

请继续阅读 贡献章节。

在 Github 上 Fork 我

https://github.com/KAMI911/ansible-role-tomcat

将此存储库添加为新的远程 upstream。

git remote add upstream https://github.com/KAMI911/ansible-role-tomcat.git

您可以将更新拉取到您 Fork 的主分支：

git fetch --all
git pull upstream HEAD

捐赠

如果您觉得这个项目有用，请考虑捐赠：