doc: update ansible.md (#23)

docs/ansible.md

@@ -1,26 +1,37 @@
 Ansible 备忘清单
 ====
 
-此快速参考备忘单提供了使用 Ansible 的各种方法。
+此快速参考备忘单提供了使用 [Ansible](https://ansible.com) 的各种方法。
 
 入门
 ---
+
 ### 安装
+
 安装命令 | 环境
 :-|-
 `brew install ansible`   | macos
 `yum install -y ansible` | centos
 `pip install ansible`    | python
 
+---
+
+- [Ansible 官方文档](https://docs.ansible.com)
+
+
 ### 配置位置
+
 文件路径 | 说明
 :-|-
 `/etc/ansible/ansible.cfg`  | 系统范围的配置
 `~/ansible.cfg`             | 用户特定的配置
 `$pwd/ansible.cfg`          | 当前目录下的配置
 
+
 ### Inventory文件(hosts列表)
+
 #### 静态Inventory
+
 `/etc/ansible/hosts`
 ```INI
 mail.example.com
@@ -31,41 +42,318 @@ bar.example.com
 ```
 
 ## 命令行(ad-hoc)
+
 ### ansible
+
 检查Inventory是否生效
+
 ```shell
 ansible all --list-hosts
 ```
 ping所有目标
+
 ```shell
 $ ansible all -m ping
 ```
+
 ping本地(不使用SSH连接)
+
 ```shell
 $ ansible all -i localhost, -e '{"ansible_connection": "local"}' -m ping
 ```
 <!--rehype:className=wrap-text -->
 本地执行命令
+
 ```shell
 $ ansible all -i localhost, -e '{"ansible_connection": "local"}' -a 'hostname'
 ```
 <!--rehype:className=wrap-text -->
 获取本地主机的信息
+
 ```shell
 $ ansible all -i localhost, -e '{"ansible_connection": "local"}' -m setup
 ``` 
 <!--rehype:className=wrap-text -->
 获取远程到本地
+
 ```shell
 $ ansible target -m fetch -a "src=/tmp/seq dest=/tmp/seq"
 ``` 
 <!--rehype:className=wrap-text -->
 拷贝本地到远程
+
 ```shell
 $ ansible target -m copy -a "src=/tmp/seq dest=/tmp/seq"
 ``` 
 <!--rehype:className=wrap-text -->
 
+### Ansible 命令帮助
+<!--rehype:wrap-class=col-span-2 row-span-3-->
+
+```bash
+$ ansible
+$ ansible <host-pattern> [options]
+```
+
+----
+
+:- | -
+:- | -
+`-a MODULE_ARGS`, `--args=MODULE_ARGS` | 模块参数
+`--ask-vault-pass` | 询问保险库密码
+`-B SECONDS`, `--background=SECONDS` | 异步运行，X 秒后失败 (默认=N/A)
+`-C`, `--check` | 不要做任何改变；相反，尝试预测可能发生的一些变化
+`-D`, `--diff` | 更改(小)文件和模板时，显示这些文件中的差异； 与 `--check` 配合使用效果很好
+`-e EXTRA_VARS`, `--extra-vars=EXTRA_VARS` | 将附加变量设置为 key=value 或 YAML/JSON
+`-f FORKS`, `--forks=FORKS` | 指定要使用的并行进程数 (default=5)
+`-h`, `--help` | 显示此帮助信息并退出
+`-i INVENTORY`, `--inventory-file=INVENTORY` | 指定清单主机路径(默认=/etc/ansible/hosts)或逗号分隔的主机列表
+`-l SUBSET`, `--limit=SUBSET` | 进一步将选定主机限制为其他模式
+`--list-hosts` | 输出匹配主机列表；不执行任何其他操作
+`-m MODULE_NAME`, `--module-name=MODULE_NAME` | 要执行的模块名称 (default=command)
+`-M MODULE_PATH`, `--module-path=MODULE_PATH` | 指定模块库的路径 (default=None)
+`--new-vault-password-file=NEW_VAULT_PASSWORD_FILE` | 用于重新生成密钥的新保管库密码文件
+`-o`, `--one-line` | 压缩输出
+`--output=OUTPUT_FILE` | 用于加密或解密的输出文件名； 使用 - 用于标准输出
+`-P POLL_INTERVAL`, `--poll=POLL_INTERVAL` | 如果使用 -B 则设置轮询间隔(default=15)
+`--syntax-check` | 对 playbook 执行语法检查，但不要执行它
+`-t TREE`, `--tree=TREE` | 将输出记录到此目录
+`--vault-password-file=VAULT_PASSWORD_FILE` | 保险库密码文件
+`-v`, `--verbose` | 详细模式(-vvv 更多，-vvvv 启用连接调试)
+`--version` | 显示程序的版本号并退出
+
+控制谁以及如何连接到主机，连接选项：
+
+:- | -
+:- | -
+`-k`, `--ask-pass` | 询问连接密码
+`--private-key=PRIVATE_KEY_FILE`, `--key-file=PRIVATE_KEY_FILE` | 使用此文件来验证连接
+`-u REMOTE_USER`, `--user=REMOTE_USER` | 以此用户身份连接(default=None)
+`-c CONNECTION`, `--connection=CONNECTION` | 要使用的连接类型 (default=smart)
+`-T TIMEOUT`, `--timeout=TIMEOUT` | 以秒为单位覆盖连接超时 (default=10)
+`--ssh-common-args=SSH_COMMON_ARGS` | 指定要传递给 sftp/scp/ssh 的常用参数 (e.g. ProxyCommand)
+`--sftp-extra-args=SFTP_EXTRA_ARGS` | 指定仅传递给 sftp 的额外参数 (e.g. -f, -l)
+`--scp-extra-args=SCP_EXTRA_ARGS` | 指定仅传递给 `scp` 的额外参数 (e.g. -l)
+`--ssh-extra-args=SSH_EXTRA_ARGS` | 指定仅传递给 `ssh` 的额外参数 (e.g. -R)
+
+控制您成为目标主机上的用户的方式和用户，特权升级选项：
+
+:- | -
+:- | -
+`-s`, `--sudo` | 使用 sudo (nopasswd) 运行操作(已弃用，使用 become)
+`-U SUDO_USER`, `--sudo-user=SUDO_USER` | 所需的 sudo 用户(默认=root)(已弃用，使用 become)
+`-S`, `--su` | 使用 su 运行操作(已弃用，使用 become)
+`-R SU_USER`, `--su-user=SU_USER` | 以该用户身份使用 su 运行操作(默认 = root)(已弃用，使用 become)
+`-b`, `--become` | 使用 become 运行操作(不暗示密码提示)
+`--become-method=BECOME_METHOD` | 要使用的权限提升方法(默认=sudo)，有效选择：[ sudo | su | pbrun | pfexec | runas | doas | dzdo ]
+`--become-user=BECOME_USER` | 以该用户身份运行操作(默认=root)
+`--ask-sudo-pass` | 询问 sudo 密码(已弃用，使用 become)
+`--ask-su-pass` | 询问 su 密码(已弃用，使用 become)
+`-K`, `--ask-become-pass` | 要求提权密码
+
+### Ansible Galaxy 工具
+
+```bash
+$ ansible-galaxy [delete|import|info|init|install|list|login|remove|search|setup] [--help] [options] ...
+```
+<!--rehype:className=wrap-text-->
+
+---
+
+:- | -
+:- | -
+`-h`, `--help` | 显示此帮助信息并退出
+`-v`, `--verbose` | 详细模式(-vvv 更多，-vvvv 启用连接调试)
+`--version` | 显示程序的版本号并退出
+<!--rehype:className=style-list-->
+
+---
+
+```bash
+$ ansible-galaxy search --author <AUTHOR>
+$ ansible-galaxy search --platforms <PLATFORM>
+$ ansible-galaxy search --galaxy-tags <TAG>
+$ ansible-galaxy info <ROLE>
+$ ansible-galaxy install <ROLE> -p <ROLE_DIRECTORY>
+$ ansible-galaxy install -r <ROLE1> <ROLE2> <ROLE3> ...
+$ ansible-galaxy list
+$ ansible-galaxy remove <ROLE>
+$ ansible-galaxy init <ROLE>
+$ ansible-galaxy init --offline <ROLE>
+```
+<!--rehype:className=wrap-text-->
+
+
+### ansible-doc
+
+在本地访问文档
+
+```bash
+$ ansible-doc
+$ ansible-doc [options] [module...]
+```
+
+---
+
+:- | -
+:- | -
+`-h`, `--help` | 显示此帮助信息并退出
+`-l`, `--list` | 列出可用模块
+`-M MODULE_PATH`, `--module-path=MODULE_PATH` | 指定模块库的路径 (default=None)
+`-s`, `--snippet` | 显示指定模块的剧本片段
+`-v`, `--verbose` | 详细模式(-vvv 更多，-vvvv 启用连接调试)
+`--version` | 显示程序的版本号并退出
+<!--rehype:className=style-list-->
+
+
+### ansible-vault
+
+```bash
+$ ansible-vault
+$ ansible-vault [create|decrypt|edit|encrypt|rekey|view] [--help] [options] vaultfile.yml
+```
+---
+
+:- | -
+:- | -
+`--ask-vault-pass` | 询问保险库密码
+`-h`, `--help` | 显示此帮助信息并退出
+`--new-vault-password-file=NEW_VAULT_PASSWORD_FILE` | 用于重新生成密钥的新保管库密码文件
+`--output=OUTPUT_FILE` | 用于加密或解密的输出文件名； 使用 - 用于标准输出
+`--vault-password-file=VAULT_PASSWORD_FILE` | 保险库密码文件
+`-v`, `--verbose` | 详细模式(-vvv 更多，-vvvv 启用连接调试)
+`--version` | 显示程序的版本号并退出
+<!--rehype:className=style-list-->
+
+### ansible-playbook
+<!--rehype:wrap-class=row-span-2-->
+
+```bash
+$ ansible-playbook
+$ ansible-playbook playbook.yml
+```
+---
+
+:- | -
+:- | -
+`--ask-vault-pass` | 询问保险库密码
+`-C`, `--check` | 不要做任何改变；相反，尝试预测可能发生的一些变化
+`-D`, `--diff` | 更改（小）文件和模板时，显示这些文件中的差异；与 `--check` 配合使用效果很好
+`-e EXTRA_VARS`, `--extra-vars=EXTRA_VARS` | 将附加变量设置为 key=value 或 YAML/JSON
+`--flush-cache` | 清除事实缓存
+`--force-handlers` | 即使任务失败也运行处理程序
+`-f FORKS`, `--forks=FORKS` | 指定要使用的并行进程数（默认值=5）
+`-h`, `--help` | 显示此帮助信息并退出
+`-i INVENTORY`, `--inventory-file=INVENTORY` | 指定清单主机路径（默认=/etc/ansible/hosts）或逗号分隔的主机列表
+`-l SUBSET`, `--limit=SUBSET` | 进一步将选定主机限制为其他模式
+`--list-hosts` | 输出匹配主机列表；不执行任何其他操作
+`--list-tags` | 列出所有可用的标签
+`--list-tasks` | 列出所有将要执行的任务
+`-M MODULE_PATH`, `--module-path=MODULE_PATH` | 指定模块库的路径（默认=无）
+`--new-vault-password-file=NEW_VAULT_PASSWORD_FILE` | 用于重新生成密钥的新保管库密码文件
+`--output=OUTPUT_FILE` | 用于加密或解密的输出文件名；使用 - 用于标准输出
+`--skip-tags=SKIP_TAGS` | 只运行标签与这些值不匹配的播放和任务
+`--start-at-task=START_AT_TASK` | 在匹配此名称的任务处启动剧本
+`--step` | 一步一步：在运行前确认每个任务
+`--syntax-check` | 对 playbook 执行语法检查，但不要执行它
+`-t TAGS`, `--tags=TAGS` | 只运行带有这些值标记的播放和任务
+`--vault-password-file=VAULT_PASSWORD_FILE` | 保险库密码文件
+`-v`, `--verbose` | 详细模式（-vvv 更多，-vvvv 启用连接调试）
+`--version` | 显示程序的版本号并退出
+<!--rehype:className=style-list-->
+
+连接选项：
+
+:- | -
+:- | -
+`-k`, `--ask-pass` | 询问连接密码
+`--private-key=PRIVATE_KEY_FILE`, `--key-file=PRIVATE_KEY_FILE` | 使用此文件来验证连接
+`-u REMOTE_USER`, `--user=REMOTE_USER` | 以此用户身份连接(默认=None)
+`-c CONNECTION`, `--connection=CONNECTION` | 要使用的连接类型(默认=smart)
+`-T TIMEOUT`, `--timeout=TIMEOUT` | 以秒为单位覆盖连接超时(默认值 = 10)
+`--ssh-common-args=SSH_COMMON_ARGS` | 指定要传递给 sftp/scp/ssh 的常用参数(例如 ProxyCommand)
+`--sftp-extra-args=SFTP_EXTRA_ARGS` | 指定仅传递给 sftp 的额外参数(例如 -f、-l)
+`--scp-extra-args=SCP_EXTRA_ARGS` | 指定仅传递给 scp 的额外参数(例如 -l)
+`--ssh-extra-args=SSH_EXTRA_ARGS` | 指定仅传递给 ssh 的额外参数(例如 -R)
+<!--rehype:className=style-list-->
+
+特权升级选项：
+
+:- | -
+:- | -
+`-s`, `--sudo` | 使用 sudo (nopasswd) 运行操作(已弃用，使用 become)
+`-U SUDO_USER`, `--sudo-user=SUDO_USER` | 所需的 sudo 用户(默认=root)(已弃用，使用become)
+`-S`, `--su` | 使用 su 运行操作(已弃用，使用 become)
+`-R SU_USER`, `--su-user=SU_USER` | 以该用户身份使用 su 运行操作(默认 = root)(已弃用，使用become)
+`-b`, `--become` | 使用 become 运行操作(不暗示密码提示)
+`--become-method=BECOME_METHOD` | 要使用的权限提升方法(默认=sudo)，有效选择：[ sudo \| su \| pbrun \| pfexec \| runas \| doas \| dzdo ]
+`--become-user=BECOME_USER` | 以该用户身份运行操作(默认=root)
+`--ask-sudo-pass` | 询问 sudo 密码(已弃用，使用 become)
+`--ask-su-pass` | 询问 su 密码(已弃用，使用 become)
+`-K`, `--ask-become-pass` | 要求提权密码
+<!--rehype:className=style-list-->
+
+### ansible-pull 
+<!--rehype:wrap-class=row-span-2-->
+
+```bash
+$ ansible-pull 
+$ ansible-pull -U <repository> [options]
+```
+---
+
+:- | -
+:- | -
+`--accept-host-key` | 如果尚未添加，则添加 repo url 的主机密钥
+`--ask-vault-pass` | 询问保险库密码
+`-C CHECKOUT`, `--checkout=CHECKOUT` | 分支/标签/提交结帐。默认为存储库模块的行为。
+`-d DEST`, `--directory=DEST` | 签出存储库的目录
+`-e EXTRA_VARS`, `--extra-vars=EXTRA_VARS` | 将附加变量设置为 key=value 或 YAML/JSON
+`-f`, `--force` | 即使无法更新存储库也运行 playbook
+`--full` | 做一个完整的克隆，而不是一个浅的
+`-h`, `--help` | 显示此帮助信息并退出
+`-i INVENTORY`, `--inventory-file=INVENTORY` | 指定清单主机路径(默认=/etc/ansible/hosts)或逗号分隔的主机列表
+`-l SUBSET`, `--limit=SUBSET` | 进一步将选定主机限制为其他模式
+`--list-hosts` | 输出匹配主机列表；不执行任何其他操作
+`-m MODULE_NAME`, `--module-name=MODULE_NAME` | 存储库模块名称，ansible 将使用它来签出 repo。默认是 git
+`-M MODULE_PATH`, `--module-path=MODULE_PATH` | 指定模块库的路径(默认=无)
+`--new-vault-password-file=NEW_VAULT_PASSWORD_FILE` | 用于重新生成密钥的新保管库密码文件
+`-o`, `--only-if-changed` | 仅在存储库已更新时才运行 playbook
+`--output=OUTPUT_FILE` | 用于加密或解密的输出文件名；使用 - 用于标准输出
+`--purge` | 剧本运行后清除结帐
+`--skip-tags=SKIP_TAGS` | 只运行标签与这些值不匹配的播放和任务
+`-s SLEEP`, `--sleep=SLEEP` | 在开始之前休眠随机间隔(在 0 到 n 秒之间)。这是分散 git 请求的有用方法
+`-t TAGS`, `--tags=TAGS` | 只运行带有这些值标记的播放和任务
+`-U URL`, `--url=URL` | 剧本存储库的 URL
+`--vault-password-file=VAULT_PASSWORD_FILE` | 保险库密码文件
+`-v`, `--verbose` | 详细模式(-vvv 更多，-vvvv 启用连接调试)
+`--verify-commit` | 验证签出提交的 GPG 签名，如果失败则中止运行 playbook。这就需要对应的VCS模块来支持这样的操作
+`--version` | 显示程序的版本号并退出
+<!--rehype:className=style-list-->
+
+连接选项：
+
+:- | -
+:- | -
+`-k`, `--ask-pass` | 询问连接密码
+`--private-key=PRIVATE_KEY_FILE`, `--key-file=PRIVATE_KEY_FILE` | 使用此文件来验证连接
+`-u REMOTE_USER`, `--user=REMOTE_USER` | 以此用户身份连接(默认=无)
+`-c CONNECTION`, `--connection=CONNECTION` | 要使用的连接类型(默认=智能)
+`-T TIMEOUT`, `--timeout=TIMEOUT` | 以秒为单位覆盖连接超时(默认值 = 10)
+`--ssh-common-args=SSH_COMMON_ARGS` | 指定要传递给 sftp/scp/ssh 的常用参数(例如 ProxyCommand)
+`--sftp-extra-args=SFTP_EXTRA_ARGS` | 指定仅传递给 sftp 的额外参数(例如 -f、-l)
+`--scp-extra-args=SCP_EXTRA_ARGS` | 指定仅传递给 scp 的额外参数(例如 -l)
+`--ssh-extra-args=SSH_EXTRA_ARGS` | 指定仅传递给 ssh 的额外参数(例如 -R)
+<!--rehype:className=style-list-->
+
+特权升级选项：
+
+:- | -
+:- | -
+`--ask-sudo-pass` | 询问 sudo 密码(已弃用，使用become)
+`--ask-su-pass` | 询问 su 密码(已弃用，使用become)
+`-K`, `--ask-become-pass` | 要求提权密码
+<!--rehype:className=style-list-->
 
 <!-- ### ansible-playbook -->
 <!-- todo -->
@@ -75,4 +363,4 @@ $ ansible target -m copy -a "src=/tmp/seq dest=/tmp/seq"
 另见
 ---
 [Getting started with Ansible](https://docs.ansible.com/ansible/latest/getting_started/index.html)  
-[Introduction to ad hoc commands](https://docs.ansible.com/ansible/latest/user_guide/intro_adhoc.html)
+[Introduction to ad hoc commands](https://docs.ansible.com/ansible/latest/user_guide/intro_adhoc.html)

scripts/assets/ansible.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" height="1em" width="1em" viewBox="0 0 65 65">
+<path fill="currentColor" d="M32,0 C49.672,0 64,14.328 64,32 C64,49.674 49.674,64 32,64 C14.326,64 0,49.674 0,32 C0,14.326 14.328,0 32,0 Z M32.539,12.688 C31.666,12.688 30.875,13.156 30.511,14.04 L16.52,47.664 L21.303,47.664 L26.837,33.801 L43.352,47.144 C44.016,47.681 44.496,47.924 45.119,47.924 C46.367,47.924 47.457,46.988 47.457,45.638 C47.457,45.418 47.379,45.068 47.239,44.694 L34.512,14.04 C34.148,13.156 33.412,12.688 32.539,12.688 Z M32.54,19.548 L40.82,39.986 L28.312,30.133 L32.54,19.548 Z" transform="translate(.38 .76)"/>
+</svg>

scripts/style/style.css

@@ -237,6 +237,7 @@ table thead {
 table td:first-child > code {
   --text-opacity: 1;
   color: rgb(5 150 105 / var(--text-opacity));
+  white-space: pre-wrap;
 }
 table td > del,
 table td:first-child > del > code,