4. 升级

4.1. 通用指南

只需将新版本安装到与已安装版本相同的位置即可升级Suricata。从源码安装时，这意味着向``configure``传递相同的``--prefix``、--sysconfdir、--localstatedir``和--datadir``选项。

$ suricata --build-info|grep -A 3 '\-\-prefix'
    --prefix                                 /usr
    --sysconfdir                             /etc
    --localstatedir                          /var
    --datarootdir                            /usr/share

4.1.1. 配置更新

新版本Suricata偶尔会包含更新的配置文件：classification.config``和``reference.config。由于Suricata安装时若这些文件已存在则不会覆盖，因此需要手动更新。如果无本地修改，可直接用Suricata提供的文件覆盖。

重大更新包含新功能、新默认设置，通常也会移除某些功能。本升级指南涵盖可能影响从旧版本迁移并保留配置的变更。我们鼓励您同时查阅所有新增但未在本指南中覆盖的功能。这些功能要么默认未启用，要么需要专门的新配置。

4.2. 从7.0升级至8.0

4.2.1. 重大变更

  • SIP解析器已更新，可同时检测TCP承载的流量。SIP关键字仍可匹配各自字段，此外还有这些改进。 无论使用哪种传输协议承载负载，事务日志均采用相同模式记录。 此外，SIP协议检测现采用模式匹配，而不仅依赖解析器探测。

  • suricata.yaml中引入了``SIP_PORTS``变量

  • 应用层的``sip``计数器已拆分为``sip_tcp``和``sip_udp``，用于``stats``事件。

  • EVE日志中现可隐藏值为0的统计计数器。默认行为仍会记录这些（配置设置参见 EVE输出 - 统计）。

  • 引入了SDP解析器、日志记录器和粘性缓冲区。 由于SDP封装在其他协议（如SIP）中，无法直接启用或禁用。 相反，SDP解析器和日志记录器需由其他解析器（或日志记录器）调用。

  • 引入了ARP解码器和日志记录器。 由于ARP可能非常冗长并产生大量事件，日志记录器默认禁用。

  • 如果使用大量流/负载规则，由于Suricata更早触发TCP流重组，可能会看到相同规则集的警报增加。

  • 新增转换函数``from_base64``，可对缓冲区进行base64解码并传递解码后的缓冲区。建议使用``from_base64``而非``base64_decode``

  • 字符串类型的数据集现在包含字符串长度以确定是否达到memcap值。这可能导致未考虑此因素的旧设置触发memcap限制。 详情参见 https://redmine.openinfosecfoundation.org/issues/3910

  • DNS日志记录已修改，以在请求、响应和警报间保持更一致。参见 8.0版DNS日志变更。

  • PF_RING支持已移至插件。参见 PF_RING插件。

  • 引入了LDAP解析器和日志记录器。

  • 已实现以下用于匹配SIP头的粘性缓冲区：

    • sip.via

    • sip.from

    • sip.to

    • sip.content_type

    • sip.content_length

  • Napatech支持已移至捕获插件。参见 Napatech插件。

  • ``requires``关键字中的未知需求现将被视为未满足需求，导致规则不被加载。参见 requires。

  • 控制流校验和检查的配置设置不再影响校验和关键字验证。在Suricata 7.0中，当``stream.checksum-validation``设为``no``时，校验和关键字（如``ipv4-csum``、``tcpv4-csum``等）将始终视为有效；例如，``tcpv4-csum: invalid``永远不会匹配。在Suricata 8.0中，``stream.checksum-validation``不再影响校验和规则关键字。例如，``ipv4-csum: valid``仅在校验和有效时匹配，即使引擎校验和验证被禁用。

  • Lua检测脚本（规则）现在在沙盒环境中运行。参见 lua-detection。

  • Lua输出脚本无默认模块搜索路径，需在加载外部模块前设置搜索路径。参见新默认配置文件或 YAML配置 获取详情。

  • 若配置值``ftp.memcap``无效，Suricata会将其设为``0``，表示无限制。在之前的Suricata版本中，Suricata会终止执行。发生此情况时将显示警告消息`Invalid value <value> for ftp.memcap`。

  • 实用程序``suricatasc``和``suricatactl``已用Rust重写。对大多数终端用户而言这是透明变更，但若从源码目录运行这些工具、对其进行补丁或将其作为Python模块使用，可能需要调整工作流程。

  • 数据集现在默认哈希大小的最大限制为65536。可通过``datasets.limits``选项配置。

  • 对于检测检查递归限制，若未提供值，默认现设为3000。

  • AF_PACKET现在有更好的默认值：

    • AF_PACKET在联机模式下默认关闭碎片整理，使用``cluster_flow``，因为不建议用于联机模式。但仍可通过``defrag``配置参数启用。

    • AF_PACKET在非联机模式下默认使用tpacket-v3，联机模式下仍禁用。要在非联机模式下保留tpacket-v2，可将现有``tpacket-v3``配置参数设为``false``。

    • AF_PACKET的TPACKET_V2和TPACKET_V3默认块大小从32k增至128k，以允许完整大小的碎片整理数据包。对于TPACKET_V3，如需可改用现有``block-size``参数将其改回旧默认值32768。对于TPACKET_V2，新增配置参数``v2-block-size``可用于调整此值。由于块大小增加，内存使用量增加，但在大多数情况下不应成为问题。

  • DPDK接口设置现在可通过将``auto``设为``mempool-size``、mempool-cache-size、rx-descriptors、``tx-descriptors``自动配置。参见 自动接口配置。

  • DPDK接口内存池现在按线程而非端口分配。此变更提升性能，从用户配置角度看应无影响。

  • DPDK支持链路状态检查，允许Suricata仅在链路启动时启动。这对Intel E810（ice）网卡特别有用，因为它们需要几秒钟才能准备好接收数据包。禁用此检查时，Suricata报告为已启动，但仅在上述间隔后开始处理数据包。未观察到其他网卡有此问题。此功能默认禁用。 参见 链路状态变更超时。

  • 加密流量绕过已与stream.bypass设置解耦。这意味着可绕过加密流量，同时跟踪/完全检查其他流量。

  • 加密SSH流量绕过现在通过``app-layer.protocols.ssh.encryption-handling``设置独立控制。该设置可为``bypass``、track-only``或``full。 要保留先前加密流量绕过与流深度绕过结合的行为，将``app-layer.protocols.ssh.encryption-handling``设为``bypass``（同时将``app-layer.protocols.tls.encryption-handling``设为``bypass``，stream.bypass``设为``true）。

  • HTTP1 URI中现接受空格而非协议版本中的空格。即：GET /a b HTTP/1.1`现在URI为/a b`，协议为`HTTP/1.1`，而过去URI为`/a`，协议为`b HTTP/1.1`

  • ``threading.cpu-affinity``的配置结构已从列表格式改为字典格式。此外，*-cpu-set`节点的成员属性已上移一级。 仍支持列表项如- worker-cpu-set`、- management-cpu-set`等。 要转换为新配置格式，请遵循以下示例或 :ref:`suricata-yaml-threading 中的描述。

      threading:
    cpu-affinity:
-     - worker-cpu-set:
-         cpu: [0, 1]
+     worker-cpu-set:
+       cpu: [0, 1]

  • 除FTP和HTTP外，所有应用层协议现在在各自方向的请求/响应完成后触发检查。这意味着之前仅因落入检查块而匹配的内容，若不完全属于任何请求/响应，可能不再匹配。

4.2.2. 移除项

  • 移除了SSH关键字``ssh.protoversion``和``ssh.softwareversion``。

4.2.3. 弃用项

  • ``http-log``输出现已弃用，将在Suricata 9.0中移除。

  • ``tls-log``输出现已弃用，将在Suricata 9.0中移除。

  • ``syslog``输出现已弃用，将在Suricata 9.0中移除。注意这是独立的``syslog``输出，不影响``eve``输出发送至syslog的能力。

  • ``app-layer.protocols.tls.encryption-handling``中的``default``选项现已弃用，将在Suricata 9.0中移除。应改用``track-only``选项。

4.2.4. 关键字变更

  • ``ja3.hash``和``ja3s.hash``不再接受非十六进制字符的内容，因为它们永远不会匹配。

4.2.5. 日志变更

  • RFB安全结果现在一致记录为``security_result``，而过去有时用破折号而非下划线记录。

  • 应用层元数据默认仅对使用应用层关键字的规则记录警报。对于其他规则，可使用配置参数``detect.guess-applayer-tx``强制检测引擎猜测事务，但不保证是预期的事务。在此情况下，若有多个活动事务，引擎不会记录任何事务元数据，以减少记录无关数据的机会。 这可能导致看似行为退化，但这是经过考虑的选择。

4.2.6. 其他变更

  • libhtp已被Rust版本替代。这意味着libhtp不再作为共享库构建和链接，libhtp依赖现在直接构建到suricata中。

4.3. 从6.0升级至7.0

4.3.1. 重大变更

  • 从PCRE1升级至PCRE2。详情参见 pcre-update-v1-to-v2。

  • IPS用户：默认情况下，各种新的"异常策略"设置为DROP流量。有关设置及其范围的详情，请参见 异常策略。故障排除请查看 升级至Suricata 7后流量被阻止。

  • 默认启用的新协议：bittorrent-dht、quic、http2。

  • telnet协议也默认启用，但仅用于``app-layer``。

4.3.2. 安全变更

  • suricata.yaml现在默认通过`security.limit-noproc`阻止Suricata创建进程。需更新suricata.yaml配置文件以启用此功能。 更多信息参见 suricata-yaml-config-hardening。

  • 默认情况下，数据集在规则中指定文件名时不再允许绝对文件名和包含父目录遍历的文件名。参见 数据集安全 和 数据集文件位置 获取更多信息。

  • Lua规则现在默认禁用（此变更也引入于6.0.13），参见 lua-detection。

4.3.3. 移除项

  • 移除了libprelude输出插件。

  • 移除了EVE DNS v1日志支持。若仍使用EVE DNS v1日志，请参阅DNS日志配置手册部分获取当前配置选项： DNS EVE配置

4.3.4. 日志变更

  • IKEv2 Eve日志变更，event_type变为``ike``，覆盖两个协议版本。字段``errors``和``notify``移至``ike.ikev2.errors``和``ike.ikev2.notify``。

  • 警报的FTP DATA元数据现在记录在``ftp_data``而非根目录。

  • 警报``xff``字段现在记录为``alert.xff``而非根目录。

  • 协议值及其名称现在内置到Suricata中，而非使用系统的``/etc/protocols``文件。``eve.json``日志条目中的``proto``值及其他包含协议名称和值的日志中的某些名称和大小写可能已变更。 参见 https://redmine.openinfosecfoundation.org/issues/4267 获取更多信息。

  • 通过EVE ``http.custom``选项配置的额外HTTP头现在分别记录在``request_headers``和/或``response_headers``中，而非合并到现有的``http``对象中。在Suricata 6.0中，类似配置：:

    http:
  custom: [Server]

    会产生类似日志条目：:

    "http": {
  "hostname": "suricata.io",
  "http_method": "GET",
  "protocol": "HTTP/1/1",
  "server": "nginx",
  ...
}

    这种自定义头与``http``对象的合并可能导致自定义头覆盖``http``对象中的标准字段，或响应头覆盖请求头。

    为防止字段被覆盖，**所有**自定义头现在记录到``request_headers``和``response_headers``数组中以避免任何冲突。这也便于记录可能多次出现的头，未来版本中每次出现都会被记录（参见下文注释）。

    这些数组在Suricata 7.0中并非新功能，但之前仅用于``dump-all-headers``选项。

    在Suricata 7.0中，上述配置示例现在会记录为：:

    "http": {
  "hostname": "suricata.io",
  "http_method": "GET",
  "protocol": "HTTP/1/1",
  "response_headers": [
    { "name": "Server", "value": "nginx" }
  ]
}

    实际上使``custom``选项成为``dump-all-headers``选项的子集。

    若您一直在使用``custom``选项，这可能是一个破坏性变更。但若未使用，输出将无变化。

  • 引擎日志/输出现在对``console``和``file``使用单独的默认值，以在控制台上提供更清晰的输出。

    默认值为：

    • console: %D: %S: %M

    • file: [%i - %m] %z %d: %S: %M

    ``console``输出也根据详细级别变化。

4.3.5. 弃用项

  • 配置文件中多个"include"字段现在会发出警告，Suricata 8.0中将不再支持。参见 includes 获取包含多个文件的文档。

  • 对于AF-Packet，cluster_rollover`设置不再支持。使用``cluster_rollover``的配置设置将导致警告消息，并视为指定了`cluster_flow。请更新配置设置。

4.3.6. 其他变更

  • 实验性关键字`http2.header`已移除。应使用`http.header`、http.request_header`和`http.response_header。

  • 不再需要NSS。文件哈希和JA3现在可在无NSS编译时依赖的情况下使用。

  • 若安装Suricata时不捆绑Suricata-Update，default-rule-path``已从/etc/suricata/rules``改为``/var/lib/suricata/rules``，以与通过Suricata-Update安装的Suricata保持一致。

  • FTP已更新，最大命令请求和响应行长度为4096字节。要更改默认值，参见 suricata-yaml-configure-ftp。

  • HTTP中的SWF解压缩默认禁用。要更改默认值，参见 suricata-yaml-configure-libhtp。有先前版本配置的用户可能希望修改配置以匹配新默认值。 参见 https://redmine.openinfosecfoundation.org/issues/5632 获取更多信息。

  • 新选项`livedev`默认启用，use-for-tracking`设为`true。若使用多个实时设备从同一网络捕获流量，应禁用此选项。

4.4. 从5.0升级至6.0

  • SIP现在默认启用

  • RDP现在默认启用

  • ERSPAN Type I默认启用。

4.4.1. 重大变更

  • 默认启用的新协议：mqtt、rfb

  • SSH客户端指纹识别

  • 条件日志记录

  • 初始HTTP/2支持

  • DCERPC日志记录

  • 改进的EVE日志性能

4.4.2. 移除项

  • 移除了文件存储v1。若使用文件提取，需将文件存储配置更新至版本2。参见 filestore-update-v1-to-v2。

  • 移除了单独的Eve（JSON）日志记录器。例如，stats-json、``dns-json``等。若仍需此行为，请使用多个Eve日志记录器实例。参见 多记录器实例。

  • 移除了Unified2。参见 Unified2输出功能移除。

4.4.3. 性能

4.5. 从4.1升级至5.0

4.5.1. 重大变更

  • 默认启用的新协议：snmp（仅新配置）

  • 默认禁用的新协议：rdp、sip

  • 协议的新默认值：nfs、smb、tftp、krb5 ntp均默认启用（仅新配置）

  • VXLAN解码器默认启用。要禁用，将``decoder.vxlan.enabled``设为``false``。

  • HTTP LZMA支持默认启用。要禁用，将使用的每个``libhtp``配置中的``lz