ansible.builtin.service 模块 – 管理服务

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 集合关键字，您也可以使用简短的模块名称 service。但是，我们建议您使用 完全限定集合名称 (FQCN) ansible.builtin.service，以便轻松链接到模块文档并避免与可能具有相同模块名称的其他集合发生冲突。

摘要

  • 控制远程主机上的服务。支持的初始化系统包括 BSD init、OpenRC、SysV、Solaris SMF、systemd、upstart。

  • 此模块充当底层服务管理器模块的代理。虽然所有参数都将传递到底层模块，但并非所有模块都支持相同的参数。本文档仅涵盖所有服务管理器模块都支持的模块参数的最小交集。

  • 此模块是多个更具体的服务管理器模块（例如 ansible.builtin.systemd 和 ansible.builtin.sysvinit）的代理。这允许管理异构的机器环境，而无需为每个服务管理器创建特定的任务。要执行的模块由 use 选项确定，该选项默认为 ansible.builtin.setup 发现的服务管理器。如果尚未运行 ansible.builtin.setup，则此模块可能会运行它。

  • 对于 Windows 目标，请改用 ansible.windows.win_service 模块。

注意

此模块具有相应的 操作插件。

参数

参数

注释

arguments

别名：args

字符串

在命令行上提供的其他参数。

在使用带有 systemd 的远程主机时，此设置将被忽略。

默认值： ""

enabled

布尔值

服务是否应在启动时启动。

至少需要 state 和 enabled 之一。

选项

  • false

  • true

name

字符串 / 必需

服务的名称。

pattern

字符串

如果服务未响应状态命令，请命名一个子字符串，该子字符串将在 ps 命令的输出中找到，作为状态结果的替代。

如果找到该字符串，则假定服务已启动。

在使用带有 systemd 的远程主机时，此设置将被忽略。

runlevel

字符串

仅适用于 OpenRC 初始化脚本（例如 Gentoo）。

此服务所属的运行级别。

在使用带有 systemd 的远程主机时，此设置将被忽略。

默认值： "default"

sleep

整数

如果服务正在 restarted，则在停止和启动命令之间休眠这么多秒。

这有助于解决在发出停止进程信号后立即退出的行为不佳的初始化脚本。

并非所有服务管理器都支持休眠，即使用 systemd 时，此设置将被忽略。

state

字符串

started/stopped 是幂等操作，除非必要，否则不会运行命令。

restarted 将始终重启服务。

reloaded 将始终重新加载。

至少需要 state 和 enabled 之一。

请注意，即使您选择的初始化系统通常不会这样做，reloaded 也会在服务未启动时启动服务。

选项

  • "reloaded"

  • "restarted"

  • "started"

  • "stopped"

use

字符串

服务模块实际上使用特定于系统的模块，通常通过自动检测，此设置可以强制使用特定模块。

通常它使用 ansible_service_mgr 事实的 value，并且在未找到匹配项时回退到 ansible.legacy.service 模块。

“旧服务模块”仍然使用自动检测，并且它与 service 命令没有任何对应关系。

默认值： "auto"

属性

属性

支持

描述

action

支持：完全支持

指示此操作具有相应的操作插件，因此可以在控制器上执行某些选项。

async

支持：完全支持

支持与 async 关键字一起使用

bypass_host_loop

支持：不支持

强制执行一个不按主机执行的“全局”任务，这会绕过按主机模板化以及串行、节流和其他循环注意事项

条件将按使用 run_once 的方式工作，使用的变量将来自第一个可用的主机

此操作在非锁步策略之外通常无法正常工作

check_mode

支持： N/A

支持取决于调用的底层插件

可以在检查模式下运行并返回更改状态预测，而无需修改目标，如果不支持，则操作将被跳过。

diff_mode

支持： N/A

支持取决于调用的底层插件

在差异模式下时，将返回有关已更改内容（或可能需要在检查模式下更改的内容）的详细信息

platform

平台： 所有

支持取决于每个平台的特定插件的可用性以及事实收集是否能够检测到它

可以对其进行操作的目标操作系统/系列

备注

注意

  • 对于 AIX，可以使用组子系统名称。

  • service 命令行实用程序不是任何服务管理器系统的一部分，而是一种便利工具。它在各个系统之间没有标准的实现，此操作无法直接使用它。尽管它可能在某些情况下被使用，但检测到的系统服务管理器通常更受青睐。

另请参阅

另请参阅

ansible.windows.win_service

有关 ansible.windows.win_service 模块的官方文档。

示例

- name: Start service httpd, if not started
  ansible.builtin.service:
    name: httpd
    state: started

- name: Stop service httpd, if started
  ansible.builtin.service:
    name: httpd
    state: stopped

- name: Restart service httpd, in all cases
  ansible.builtin.service:
    name: httpd
    state: restarted

- name: Reload service httpd, in all cases
  ansible.builtin.service:
    name: httpd
    state: reloaded

- name: Enable service httpd, and not touch the state
  ansible.builtin.service:
    name: httpd
    enabled: yes

- name: Start service foo, based on running process /usr/bin/foo
  ansible.builtin.service:
    name: foo
    pattern: /usr/bin/foo
    state: started

- name: Restart network service for interface eth0
  ansible.builtin.service:
    name: network
    state: restarted
    args: eth0

作者

  • Ansible Core 团队

  • Michael DeHaan