模块文档

官方模块列表：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") '$6$DXBmlgG/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"