模块文档
官方模块列表：https://docs.ansible.com/ansible/latest/collections/index_module.html
# 查看支持的模块（小写 l）
ansible-doc -l
# 查看支持的模块个数-> 3387
ansible-doc -l | wc -l
# ansible-doc 模块名 或者 ansible-doc -s 模块名 获取指定模块帮助信息说明
ansible-doc command
ansible-doc -s command
command 模块
command 模块可以帮助我们在远程主机上执行命令。
使用 command 模块在远程主机中执行命令时，不会经过远程主机的 shell 处理，在使用 command 模块时，如果需要执行的命令中含有重定向、管道符等操作时，这些符号也会失效，比如"<", ">", "|", ";" 和 "&" 这些符号，如果你需要这些功能，可以参考后面介绍的 shell 模块。
注意：执行 ansible 时，不加-m 默认使用 command模块，可以在 /etc/ansible/ansible.cfg 中修改：
# default module name for /usr/bin/ansible
#module_name = command
shell 模块
使用 shell 模块，在远程命令通过/bin/sh 来执行；所以，我们在终端输入的各种命令方式，都可以使用。
ansible -i /etc/ansible/hosts web-servers -m shell -a "free -m"
注意：用户定义在~/.bashrc 或~/.bash_profile 中的环境变量，shell 模块不会加载，所以无法识别；如果需要使用自定义的环境变量，就需要在最开始执行加载自定义脚本的语句。
script 模块
如果在远程待执行的语句比较多，可写成一个脚本，通过 copy 模块传到远端，然后再执行；但这样就又涉及到两次 ansible 调用；对于这种需求，ansible 已经为我们考虑到了，script 模块可以帮助我们直接把脚本拷贝到远端执行。
# 使用 scripts 模块可以在本地写一个脚本
vim /etc/ansible/net.sh
-----------------------------------
#!/bin/bash
date && hostname
-----------------------------------
# 在远程服务器上执行
ansible -i /etc/ansible/hosts web_servers -m script -a "/etc/ansible/net.sh"
copy 模块
描述：实现主控端向目标主机拷贝文件或目录，类似 scp 功能
|----------------|---------------------------------------------------------------------------------------------------------------------------------|
| 参数 | 说明 |
| backup | 在覆盖之前将原文件备份，备份文件包含时间信息。有两个选项：yes|no |
| content | 用于替代"src",可以直接设定指定文件的值 |
| dest | 必选项。要将源文件复制到的远程主机的绝对路径，如果源文件是一个目录，那么该路径也必须是个目录 |
| directory_mode | 递归的设定目录的权限，默认为系统默认权限 |
| force | 如果目标主机包含该文件，但内容不同，如果设置为 yes，则强制覆盖，如果为 no，则只有当目标主机的目标位置不存在该文件时，才复制。默认为 yes |
| src | 要复制到远程主机的文件在本地的地址，可以是绝对路径，也可以是相对路径。如果路径是一个目录，它将递归复制。在这种情况下，**如果路径使用"/"**来结尾，则只复制目录里的内容，如果没有使用"/"来结尾，则包含目录在内的整个内容全部复制，类似于 rsync。 |
推送文件至远端主机
# 把 ansible 主机上的/etc/hosts 文件复制到主机组中机器的/tmp 目录下
ansible -i /etc/ansible/hosts web-servers -m copy \
-a "src=/etc/hosts dest=/tmp/ owner=root group=root mode=0755"
# 查看目标主机是否复制成功
ansible web-servers -m shell -a "ls -l /tmp/hosts"
写入数据至远端主机
ansible web_servers -m copy \
-a 'content="Hello ansible\nyou are clear!\n" dest=/tmp/ansible.txt'
# 查看是否写入成功
ansible web_servers -m shell -a "cat /tmp/ansible.txt"
file 模块
file 模块主要用于远程主机上的文件操作，如修改文件属性（权限、属主、属组） 和创建文件、目录、符号链接等。
|---------|-------------------------------------------------------------------------------------------------------------------------------|
| 参数 | 说明 |
| force | 需要在两种情况下强制创建软链接，一种是源文件不存在但之后会建立的情况下；另一种是目标软链接已存在,需要先取消之前的软链，然后创建新的软链， 有两个选项：yes|no |
| group | 定义文件/目录的属组 |
| mode | 定义文件/目录的权限 |
| owner | 定义文件/目录的属主 |
| path | 必选项，定义文件/目录的路径 |
| recurse | 递归的设置文件的属性，只对目录有效 |
| src | 要被链接的源文件的路径，只应用于 state=link 的情况 |
| dest | 被链接到的路径，只应用于 state=link 的情况 |
| state | directory：如果目录不存在，创建目录 file：即使文件不存在，也不会被创建 touch：文件不存在创建一个新文件，如果文件已存在，则更新其最后修改时间 link：创建软链接 hard：创建硬链接 absent：删除目录、文件或者取消链接文件 |
修改远端文件权限
# 修改 04，05 上/tmp/hosts 文件权限为 777
ansible -i /etc/ansible/hosts web-servers -m file -a "path=/tmp/hosts mode=0777"
# 查看更改权限是否成功
ansible web_servers -m shell -a "ls -l /tmp/hosts"
在远端创建文件
# 创建文件或目录
ansible web-servers -m file -a "path=/tmp/dir1 state=directory"
ansible web-servers -m file -a "path=/tmp/testfile1 state=touch"
# 将 12,13 上的/tmp/hosts 文件创建符号链接到/opt 目录下
ansible -i /etc/ansible/hosts web-servers -m file \
-a "src=/tmp/hosts dest=/opt/hosts state=link"
# 查看链接文件是否创建成功
ansible -i /etc/ansible/hosts web_servers -m shell -a "ls -l /opt/hosts"
删除远端主机文件
# 删除远端的软连接文件/opt/hosts
ansible -i /etc/ansible/hosts web_servers -m file -a "path=/opt/hosts state=absent"
stat 模块
stat 模块获取远程文件信息
# 获取远端/tmp/hosts 文件信息
ansible -i /etc/ansible/hosts web_servers -m stat -a "path=/tmp/hosts"
get_url 模块
get_url 模块实现远程主机下载指定 url 到本地，支持 sha256sum 文件校验
# 下载网络源到主机清单中的/tmp/目录下
ansible -i /etc/ansible/hosts web-servers -m get_url -a \
"url=http://mirrors.aliyun.com/repo/Centos-7.repo dest=/tmp/ mode=0440 force=yes"
如果 force=yes，当下载文件时，如果所下的内容和原目录下的文件内容不一样， 则替换原文件，如果一样，就不下载了。
# 测试force：node05 修改下载完的文件，node06 的文件不变
[root@node_05 ~] cp /etc/passwd /tmp/Centos-7.repo
# 重新执行命令测试force
ansible -i /etc/ansible/hosts web-servers -m get_url -a \
"url=http://mirrors.aliyun.com/repo/Centos-7.repo dest=/tmp/ mode=0440 force=yes"
当文件不一样时，会替换原来的文件,修改成功的显示黄色，没有修改显示绿色
yum 模块
yum 模块可以帮助我们在远程主机上通过 yum 源管理软件包。
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 模块选项 | 说明 |
| name 参数 | 必须参数，用于指定需要管理的软件包，比如 nginx。 |
| state 参数 | 用于指定软件包的状态 ，默认值为 present，表示确保软件包已经安装，除了 present，其他可用值有 installed、latest、absent、removed，其中 installed 与 present 等效， latest 表示安装 yum 中最新的版本， absent 和 removed 等效， 表示删除对应的软件包。 |
| disable_gpg_check | 用于禁用对 rpm 包的公钥 gpg 验证。默认值为 no， 表示不禁用验证，设置为 yes 表示禁用验证，即不验证包，直接安装。 |
| update_cache 参数 | 是否更新缓存，默认值时 no |
| enablerepo 参数 | 用于指定安装软件包时临时启用的 yum 源。假如你想要从 A 源中安装软件，但是你不确定 A 源是否启用了，你可以在安装软件包时将此参数的值设置为 yes，即使A源的设置是未启用，也可以在安装软件包时临时启用A源。 |
| disablerepo 参数 | 用于指定安装软件包时临时禁用的 yum 源。某些场景下需要此参数，比如，当多个 yum 源中同时存在要安装的软件包时，你可以使用此参数 临时禁用某个源，这样设置后，在安装软件包时则不会从对应的源中选择安装包。 senablerepo 参数和 disablerepo 参数可以同时使用。 |
# 在远端机器上安装httpd软件
ansible -i /etc/ansible/hosts web_servers -m yum -a "name=httpd state=latest"
cron 模块
配置远程主机 crontab
|---------|-----------------------------------------------------|
| 参数 | 说明 |
| minute | 分钟（0-59，*，*/2，......） |
| hour | 小时（0-23，*，*/2，......） |
| day | 日（1-31，*，*/2,......） |
| month | 月（1-12，*，*/2，......） |
| weekday | 周（0-7，*，......） |
| name | 任务的描述 |
| job | 任何计划要执行的命令，state 要等于 present |
| state | 确认该任务计划是创建还是删除，创建 cron 任务 present、删除 cron 任务 absent |
| user | 以哪个用户的身份执行 |
注意：
- 定时设置，指定值写入即可，没有设置的可以不写（默认是*）
- name 必须写
- state 有两个状态：present（添加（默认值））or absent（移除）
创建同步时间任务
基于 cron 模块，创建 crontab 任务计划，例如：让所有的后端服务器在每天的00:00 点从 ntp1.aliyun.com 主机上用 ntpdate 同步时间，任务名称为：Ntpdate server for sync time
ansible all -m cron -a "minute=0 hour=0 day=* month=* weekday=* name='Ntpdate server for sync time' job='ntpdate ntp1.aliyun.com'"
# 查看定时任务
ansible web_servers -m shell -a "crontab -l"
删除定时任务计划
ansible all -m cron -a "name='Ntpdate server for sync time' state=absent"
service 模块
Ansible service 模块主要用于远程客户端各种服务管理，包括启动、停止、重启、 重新加载等。
|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| 参数 | 说明 |
| name 参数 | 此参数用于指定需要操作的服务名称，比如 nginx，httpd。 |
| state 参数 | 此参数用于指定服务的状态，比如，我们想要启动远程主机中的 httpd， 则可以将 state 的值设置为 started； 如果想要停止远程主机中的服务，则可以将 state 的值设置为 stopped。 此参数的可用值有 started、stopped、restarted（重启）、 reloaded。 |
| enabled 参数 | 此参数用于指定是否将服务设置为开机启动项，设置为 yes 表示将对应服务设置为开机启动，设置为 no 表示不会开机启动。 |
| runlevel 参数 | 服务启动级别 |
| arguments 参数 | 服务命令行参数传递 |
注意：想使用 service 模块启动服务，被启动的服务，必须可以使用 service 命令启动或关闭
# 重启服务
ansible web_servers -m service -a "name=httpd state=restarted"
# 启动 httpd 服务并设置为开机自启
ansible web_servers -m service -a "enabled=yes name=httpd state=started"
sysctl 模块
当我们需要修改内核参数时，可以使用 sysctl 模块。sysctl 可以对内核参数值进行设置，如果需要查询可以使用 shell 模块。
|--------|---------------------------------|
| 参数 | 说明 |
| name | 变量名 |
| value | 值 |
| reload | 文件被更新时，是否使用 sysctl -p reload 文件 |
| state | 是在文件中移除(absent)或者设置(present) |
# 开启路由转发功能
ansible web_servers -m sysctl -a "name=net.ipv4.ip_forward value=1 reload=yes"
# 查看状态
ansible web_servers -m shell -a "cat /proc/sys/net/ipv4/ip_forward"
user 模块
user 模块可以帮助我们管理远程主机上的用户，比如创建用户、修改用户、删除用户、为用户创建密钥对等操作。
|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 参数 | 说明 |
| name 参数 | 必须参数，用于指定要操作的用户名称。 |
| group 参数 | 此参数用于指定用户所在的基本组。 |
| gourps 参数 | 此参数用于指定用户所在的附加组。注意，如果说用户已经存在并且已经拥有多个附加组，那么如果想要继续添加新的附加组，需要结合 append 参数使用，否则在默认情况下，当再次使用 groups 参数设置附加组时，用户原来的 附加组会被覆盖。 |
| append 参数 | 如果用户原本就存在多个附加组，那么当使用 groups 参数设置附加组时，当前设置会覆盖原来的附加组设置，如果不想覆盖原来的附加组设置，需要结合 append 参数，将 append 设置为 yes，表示追加附加组到现有的附加组设置，append 默认值为 no。 |
| shell 参数 | 此参数用于指定用户的默认 shell。 |
| uid 参数 | 此参数用于指定用户的 uid 号。 |
| expires 参数 | 此参数用于指定用户的过期时间 |
| comment 参数 | 此参数用于指定用户的注释信息。 |
| state 参数 | 此参数用于指定用户是否存在于远程主机中，可选值有 present、absent，默认值为 present，表示用户需要存在，当设置为 absent 时表示删除用户。 |
| remove 参数 | 当 state 的值设置为 absent 时，表示要删除远程主机中的用户。 但是在删除用户时，不会删除用户的家目录等信息，这是因为 remove 参数的默认值为 no，如果设置为 yes，在删除用户的同时，会删除用户的家目录。当 state=absent 并且 remove=yes 时，相当于执行 "userdel -r" 命令。 |
| password 参数 | 此参数用于指定用户的密码。但是这个密码不能是明文的密码，而是一个对明文密码"加密后"的字符串，相当于 /etc/shadow 文件中的密码字段,是一个对明文密码进行哈希后的字符串。 可以在 python 的命令提示符下输入如 下命令，生成明文密码对应的加密字符串。[root@cong11 ~]# python >>> import crypt >>> crypt.crypt("123456") '6DXBmlgG/CjVxfay5$YhsEsheXkG7kP78YZz0eWjEG1VnvwxwCtDJvJBIw7gptSzx0Vzr owdGaBGsuRvJ2iQ4VNgKZ2IcW0yIszTpIY/' |
| update_password | 此参数有两个值可选，always 和 on_create，当此参数的值设置为 always 时表示，如果 password 参数设置的值与用户当前的加密过的密码字符串不一致，则直接更新用户的密码，默认值即为 always，但是当此参数设置为 on_create 时，on_create 只为新用户设置密码。 |
| generate_ssh_key | 此参数默认值为 no，如果设置为 yes，表示为对应的用户生成 ssh 密钥对，默认在用户家目录的 ./ssh 目录中生成名为 id_rsa 的私钥和名为 id_rsa.pub 的公钥，如果同名的密钥已经存在与对应的目录中，原同名密钥并不会被覆盖(不做任何操作)。 |
在远端创建用户
# 创建用户 user2，登录 shell 为/sbin/nologin
ansible -i /etc/ansible/hosts web_servers -m user \
-a "name=user2 shell=/sbin/nologin state=present"
# 查看远端主机是否创建成功
ansible web_servers -m shell -a "cat /etc/passwd | grep user2"
在远端创建带密码的用户
# 创建带密码的用户
ansible web-servers -m user \
ansible -i /etc/ansible web_servers -m user -a 'name=user4 password="$6$cn.pXtToYu1VdHzq$55k2ZIy2U/LXbTvd.JZMvZ3ArrzUN8rjhDk/Cj7kk9hZlgL54oLczNP7EN5UPK59PsEVDWCQHdZZ7Am3FJiFU1"'
注意：密码要使用"双引号"，二不能使用"单引号"
删除远端用户及宿主目录
# 删除 user2 及其宿主目录
ansible -i /etc/ansible/hosts web_servers -m user -a "name=user2 state=absent remove=yes"
setup 模块
功能：setup 模块用于收集远程主机的一些基本信息。如操作系统版本、IP 地址等信息。
常用参数：
- filter 用于进行条件过滤。如果设置，仅返回匹配过滤条件的信息。
- --tree 将所有主机的输出信息保存到文件，以/etc/ansible/hosts 里的主机名为文件名
|------------------------------------|----------------------------|
| filter参数值 | 说明 |
| ansible_all_ipv4_addresses | 仅显示 ipv4 的信息。 |
| ansible_devices | 仅显示磁盘设备信息。 |
| ansible_distribution | 显示是什么系统，例：centos,suse 等。 |
| ansible_distribution_major_version | 显示是系统主版本。 |
| ansible_distribution_version | 仅显示系统版本。 |
| ansible_machine | 显示系统类型，例：32 位，还是 64 位。 |
| ansible_ens33 | 仅显示 ens33 的信息。 |
| ansible_hostname | 仅显示主机名。 |
| ansible_kernel | 仅显示内核版本。 |
| ansible_lvm | 显示 lvm 相关信息。 |
| ansible_memtotal_mb | 显示系统总内存。 |
| ansible_memfree_mb | 显示可用系统内存。 |
| ansible_memory_mb | 详细显示内存情况。 |
| ansible_swaptotal_mb | 显示总的 swap 内存。 |
| ansible_swapfree_mb | 显示 swap 内存的可用内存。 |
| ansible_mounts | 显示系统磁盘挂载情况。 |
| ansible_processor | 显示 cpu 个数(具体显示每个 cpu 的型号)。 |
| ansible_processor_vcpus | 显示 cpu 个数(只显示总的个数)。 |
# 获取远端主机信息
ansible 192.168.137.105 -m setup
返回的信息非常多，很多情况我们并不需要全部的信息，可以通过过滤获得指定的信息。
获取远端主机的IPv4地址
ansible 192.168.137.105 -m setup -a "filter=ansible_all_ipv4_addresses"
获取远端主机的内存信息
ansible 192.168.137.105 -m setup -a "filter=ansible_memory_mb"
模糊匹配
ansible 192.168.137.105 -m setup -a "filter=*mb"
保存远端主机信息至本地
# 将所有主机的输出信息保存到/tmp/目录下，以/etc/ansible/hosts 里的主机名为文件名
ansible all -m setup -a 'filter=ansible_memfree_mb' --tree /tmp/
fetch 模块
从远程主机拉取文件到本地
|------------|-----------------------|
| 常用参数 | 说明 |
| src参数 | 表示目标主机上要复制的文件路径 |
| dest参数 | 表示控制机上存储文件的目录路径 |
| flat参数 | 用于去除文件路径中的目录结构，只保留文件名 |
| validate参数 | 用于验证复制的文件是否正确 |
| backup参数 | 用于备份已存在的文件 |
| | |
# 从 node-05 主机上拉取文件/etc/hosts 到 ansible 本地的/tmp 目录
ansible 192.168.137.105 -m fetch -a "src=/etc/passwd dest=/tmp"
