├── hosts ├── create-ansible-webdoc.yml ├── templates └── ansible-docs.j2 ├── library └── ansible_docstring ├── README.md └── web └── ansiblefilesdoc.md /hosts: -------------------------------------------------------------------------------- 1 | # can't have empty hosts file 2 | localhost -------------------------------------------------------------------------------- /create-ansible-webdoc.yml: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | - name: create local markdown doc 4 | hosts: localhost 5 | connection: local 6 | gather_facts: no 7 | 8 | vars: 9 | heading: 'Ansible FILES modules' 10 | subheading: 'Local copy of files modules' 11 | requirements: 12 | - See official Ansible docs 13 | 14 | tasks: 15 | 16 | - name: get docs and examples for modules 17 | ansible_docstring: path=/usr/share/ansible/files/ 18 | register: modules 19 | 20 | - name: build web/markdown ansible docs 21 | template: src=templates/ansible-docs.j2 dest=web/ansiblefilesdoc.md -------------------------------------------------------------------------------- /templates/ansible-docs.j2: -------------------------------------------------------------------------------- 1 | {% if heading is defined %} 2 | # {{ heading }} 3 | {% endif %} 4 | {% if subheading is defined %} 5 | ### *{{ subheading }}* 6 | {% endif %} 7 | 8 | --- 9 | ### Requirements 10 | {% if requirements is defined %} 11 | {% for req in requirements %} 12 | * {{ req }} 13 | {% endfor %} 14 | {% endif %} 15 | 16 | --- 17 | ### Modules 18 | 19 | {% for doc in modules.results %} 20 | * [{{ doc['module'] }} - {{ doc['short_description'].lower() }}](#{{ doc['module'] }}) 21 | {% endfor %} 22 | 23 | --- 24 | {% for doc in modules.results %} 25 | 26 | ## {{ doc['module'] }} 27 | {{ doc['short_description'] }} 28 | 29 | * Synopsis 30 | * Options 31 | * Examples 32 | 33 | #### Synopsis 34 | {% for each in doc['description'] %} {{ each }} 35 | {% endfor %} 36 | 37 | #### Options 38 | 39 | | Parameter | required | default | choices | comments | 40 | | ------------- |-------------| ---------|----------- |--------- | 41 | {% for k,v in doc.iteritems() %} 42 | {% if k == 'options' %} 43 | {% for option,values in v.iteritems() %} 44 | | {{ option }} | {% if values.get('required') != None %} {{ values['required'] | replace('True','yes') | replace('False','no') }} {% endif %} | {% if values.get('default') != None %} {{ values['default'] | replace('None','')}} {% endif %} |{% if values.get('choices') != None %} {% endif %} | {% if values.get('description') != None %}{% for each in values['description'] %} {{ each }} {% endfor %}{% endif %} | 45 | {% endfor %} 46 | {% endif %} 47 | {% endfor %} 48 | 49 | 50 | {% if doc['examples'] is defined %} 51 | 52 | #### Examples 53 | 54 | ``` 55 | {% for each in doc['examples'] %} 56 | {{ each | replace('{#','{{') | replace('#}','}}') }} 57 | {% endfor %} 58 | ``` 59 | {% endif %} 60 | 61 | 62 | {% for k,v in doc.iteritems() %} 63 | {% if k == 'notes' %} 64 | #### Notes 65 | 66 | {% for note in v %} 67 | - {{ note }} 68 | 69 | {% endfor %} 70 | {% endif %} 71 | {% endfor %} 72 | 73 | --- 74 | 75 | {% endfor %} 76 | 77 | --- 78 | Created by Network to Code, LLC 79 | For: 80 | 2015 81 | -------------------------------------------------------------------------------- /library/ansible_docstring: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # 3 | 4 | DOCUMENTATION = ''' 5 | --- 6 | 7 | module: ansible_docstring 8 | short_description: Create markdown file for a modules docs 9 | description: 10 | - Offers ability to dynamically create local markdown files 11 | (web docs) to be used offline for custom modules without 12 | requiring use of 'make webdocs'. Also works on Core modules. 13 | - Only a single dir is supported in this release (no recursive dirs) 14 | author: Jason Edelman (@jedelman8) 15 | requirements: 16 | - Ansible must be installed 17 | - Modules must have proper Ansible doc and example strings 18 | - 'modules' must be the variable name that is registered in the playbook 19 | - The Jinja template called ansible-docs.j2 is required 20 | notes: 21 | - This module uses module_docs that that is part of the Ansible project 22 | to extract the required strings from Ansible modules 23 | options: 24 | path: 25 | description: 26 | - absolute path to a directory where the Ansible module(s) are stored 27 | required: true 28 | default: null 29 | choices: [] 30 | aliases: [] 31 | ''' 32 | 33 | EXAMPLES = ''' 34 | # FULL PLAYBOOK EXAMPLE 35 | - name: get docs and examples for modules 36 | ansible_docstring: path=/usr/share/ansible/files/ 37 | register: modules 38 | 39 | - name: build web/markdown ansible docs 40 | template: src=templates/ansible-docs.j2 dest=web/ansiblefilesdoc.md 41 | ''' 42 | 43 | from os import walk 44 | from ansible.utils import module_docs 45 | 46 | 47 | def main(): 48 | 49 | module = AnsibleModule( 50 | argument_spec=dict( 51 | path=dict(required=True), 52 | ), 53 | supports_check_mode=False 54 | ) 55 | 56 | path = module.params['path'] 57 | if path[-1] != '/': 58 | path = path + '/' 59 | 60 | all_docs = [] 61 | errors = [] 62 | for (dirpath, dirnames, ansible_modules) in walk(path): 63 | if dirpath == path: 64 | for mod in ansible_modules: 65 | try: 66 | try: 67 | doc, plainexamples, returndocs = module_docs.get_docstring(path+mod) 68 | except ValueError: 69 | doc, plainexamples = module_docs.get_docstring(path+mod) 70 | except Exception as e: 71 | module.fail_json(msg='error', error=str(e)) 72 | 73 | try: 74 | examples_list = plainexamples.split('\n') 75 | doc['examples'] = examples_list 76 | except: 77 | errors.append(doc) 78 | errors.append('error-examples') 79 | continue 80 | 81 | all_docs.append(doc) 82 | except: 83 | errors.append(mod) 84 | errors.append('unknown') 85 | continue 86 | 87 | module.exit_json(results=all_docs, errors=errors) 88 | 89 | from ansible.module_utils.basic import * 90 | main() 91 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Dynamically Generate Markdown Docs for Ansible Modules 2 | The module `ansible_docstring` was built to assist in the generation of Ansible-like web docs mainly for the purpose of having offline web docs for custom modules. However, it can also be used to generate web docs for Ansible core modules as can be seen from the example. 3 | 4 | Unlike Ansible's `make webdocs` functionality, this can generate a single markdown file for just ONE module. There is no need to generate complete web docs for every module when they aren't needed. 5 | 6 | There are more error checks that could be built into the module and Jinja2 template to possibly make this more user friendly and more robust. If there are any suggestions, please feel free to open an issue or PR. 7 | 8 | More background here: http://www.jedelman.com/home/generating-web-docs-for-ansible-modules 9 | 10 | ### Example Playbook (as can also be seen in the playbook in this repo): 11 | ``` 12 | --- 13 | 14 | - name: create local markdown doc 15 | hosts: localhost 16 | connection: local 17 | gather_facts: no 18 | 19 | vars: 20 | heading: 'Ansible FILES modules' 21 | subheading: 'Local copy of files modules' 22 | requirements: 23 | - See official Ansible docs 24 | 25 | tasks: 26 | 27 | - name: get docs and examples for modules 28 | ansible_docstring: path=/usr/share/ansible/files/ 29 | register: modules 30 | 31 | - name: build web/markdown ansible docs 32 | template: src=templates/ansible-docs.j2 dest=web/ansiblefilesdoc.md 33 | ``` 34 | 35 | ###Running this playbook: 36 | 37 | ``` 38 | jason@ansible:~/ansible/gendoc$ ansible-playbook -i hosts create-ansible-webdoc.yml 39 | 40 | PLAY [create local markdown doc] ********************************************** 41 | 42 | TASK: [get docs and examples for modules] ************************************* 43 | ok: [localhost] 44 | 45 | TASK: [build web/markdown ansible docs] *************************************** 46 | changed: [localhost] 47 | 48 | PLAY RECAP ******************************************************************** 49 | localhost : ok=2 changed=1 unreachable=0 failed=0 50 | 51 | jason@ansible:~/ansible/gendoc$ 52 | ``` 53 | 54 | 55 | ### Generates the following markdown file: 56 | * Slight modifications made for the Examples section to be able to show the markdown in a markdown file, i.e. Examples section is actual markdown. backticks removed. 57 | * Also only a snippet is being shown - only the first four modules in the list are documented here (rest can be seen in the web dir in the repo) 58 | ``` 59 | # Ansible FILES modules 60 | ### *Local copy of files modules* 61 | 62 | --- 63 | ### Requirements 64 | * See official Ansible docs 65 | 66 | --- 67 | ### Modules 68 | 69 | * [template - templates a file out to a remote server](#template) 70 | * [unarchive - copies an archive to a remote location and unpack it](#unarchive) 71 | * [replace - replace all instances of a particular string in a file using a back-referenced regular expression](#replace) 72 | * [copy - copies files to remote locations](#copy) 73 | * [lineinfile - ensure a particular line is in a file, or replace an existing line using a back-referenced regular expression](#lineinfile) 74 | * [acl - sets and retrieves file acl information](#acl) 75 | * [synchronize - uses rsync to make synchronizing file paths in your playbooks quick and easy](#synchronize) 76 | * [assemble - assembles a configuration file from fragments](#assemble) 77 | * [xattr - set/retrieve extended attributes](#xattr) 78 | * [stat - retrieve file or file system status](#stat) 79 | * [file - sets attributes of files](#file) 80 | * [ini_file - tweak settings in ini files](#ini_file) 81 | * [fetch - fetches a file from remote nodes](#fetch) 82 | --- 83 | 84 | #### template 85 | Templates a file out to a remote server 86 | 87 | * Synopsis 88 | * Options 89 | * Examples 90 | 91 | #### Synopsis 92 | Templates are processed by the Jinja2 templating language (U(http://jinja.pocoo.org/docs/)) - documentation on the template formatting can be found in the Template Designer Documentation (U(http://jinja.pocoo.org/docs/templates/)). 93 | Six additional variables can be used in templates: C(ansible_managed) (configurable via the C(defaults) section of C(ansible.cfg)) contains a string which can be used to describe the template name, host, modification time of the template file and the owner uid, C(template_host) contains the node name of the template's machine, C(template_uid) the owner, C(template_path) the absolute path of the template, C(template_fullpath) is the absolute path of the template, and C(template_run_date) is the date that the template was rendered. Note that including a string that uses a date in the template will result in the template being marked 'changed' each time. 94 | 95 | #### Options 96 | 97 | | Parameter | required | default | choices | comments | 98 | | ------------- |-------------| ---------|----------- |--------- | 99 | | dest | yes | | | Location to render the template to on the remote machine. | 100 | | src | yes | | | Path of a Jinja2 formatted template on the local server. This can be a relative or absolute path. | 101 | | validate | no | | | The validation command to run before copying into place. The path to the file to validate is passed in via '%s' which must be present as in the visudo example below. validation to run before copying into place. The command is passed securely so shell features like expansion and pipes won't work. | 102 | | backup | no | | | Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. | 103 | 104 | #### Examples 105 | 106 | # Example from Ansible Playbooks 107 | - template: src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644 108 | 109 | # Copy a new "sudoers" file into place, after passing validation with visudo 110 | - template: src=/mine/sudoers dest=/etc/sudoers validate='visudo -cf %s' 111 | 112 | 113 | #### Notes 114 | - Since Ansible version 0.9, templates are loaded with C(trim_blocks=True). 115 | 116 | 117 | --- 118 | 119 | 120 | #### unarchive 121 | Copies an archive to a remote location and unpack it 122 | 123 | * Synopsis 124 | * Options 125 | * Examples 126 | 127 | #### Synopsis 128 | The M(unarchive) module copies an archive file from the local machine to a remote and unpacks it. 129 | 130 | #### Options 131 | 132 | | Parameter | required | default | choices | comments | 133 | | ------------- |-------------| ---------|----------- |--------- | 134 | | dest | yes | | | Remote absolute path where the archive should be unpacked | 135 | | src | yes | | | Local path to archive file to copy to the remote server; can be absolute or relative. | 136 | | copy | no | | | Should the file be copied from the local to the remote machine? | 137 | | creates | no | | | a filename, when it already exists, this step will B(not) be run. | 138 | 139 | #### Examples 140 | 141 | # Example from Ansible Playbooks 142 | - unarchive: src=foo.tgz dest=/var/lib/foo 143 | 144 | # Unarchive a file that is already on the remote machine 145 | - unarchive: src=/tmp/foo.zip dest=/usr/local/bin copy=no 146 | 147 | 148 | #### Notes 149 | - requires C(tar)/C(unzip) command on target host 150 | 151 | - can handle I(gzip), I(bzip2) and I(xz) compressed as well as uncompressed tar files 152 | 153 | - detects type of archive automatically 154 | 155 | - uses tar's C(--diff arg) to calculate if changed or not. If this C(arg) is not supported, it will always unpack the archive 156 | 157 | - does not detect if a .zip file is different from destination - always unzips 158 | 159 | - existing files/directories in the destination which are not in the archive are not touched. This is the same behavior as a normal archive extraction 160 | 161 | - existing files/directories in the destination which are not in the archive are ignored for purposes of deciding if the archive should be unpacked or not 162 | 163 | 164 | --- 165 | 166 | 167 | #### replace 168 | Replace all instances of a particular string in a file using a back-referenced regular expression 169 | 170 | * Synopsis 171 | * Options 172 | * Examples 173 | 174 | #### Synopsis 175 | This module will replace all instances of a pattern within a file. 176 | It is up to the user to maintain idempotence by ensuring that the same pattern would never match any replacements made. 177 | 178 | #### Options 179 | 180 | | Parameter | required | default | choices | comments | 181 | | ------------- |-------------| ---------|----------- |--------- | 182 | | dest | yes | | | The file to modify. | 183 | | replace | no | | | The string to replace regexp matches. May contain backreferences that will get expanded with the regexp capture groups if the regexp matches. If not set, matches are removed entirely. | 184 | | others | no | | | All arguments accepted by the M(file) module also work here. | 185 | | regexp | yes | | | The regular expression to look for in the contents of the file. Uses Python regular expressions; see U(http://docs.python.org/2/library/re.html). Uses multiline mode, which means C(^) and C($) match the beginning and end respectively of I(each line) of the file. | 186 | | validate | no | | | validation to run before copying into place | 187 | | backup | no | | | Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. | 188 | 189 | #### Examples 190 | 191 | - replace: dest=/etc/hosts regexp='(\s+)old\.host\.name(\s+.*)?$' replace='\1new.host.name\2' backup=yes 192 | 193 | - replace: dest=/home/jdoe/.ssh/known_hosts regexp='^old\.host\.name[^\n]*\n' owner=jdoe group=jdoe mode=644 194 | 195 | - replace: dest=/etc/apache/ports regexp='^(NameVirtualHost|Listen)\s+80\s*$' replace='\1 127.0.0.1:8080' validate='/usr/sbin/apache2ctl -f %s -t' 196 | 197 | 198 | --- 199 | 200 | 201 | #### copy 202 | Copies files to remote locations 203 | 204 | * Synopsis 205 | * Options 206 | * Examples 207 | 208 | #### Synopsis 209 | The M(copy) module copies a file on the local box to remote locations. 210 | 211 | #### Options 212 | 213 | | Parameter | required | default | choices | comments | 214 | | ------------- |-------------| ---------|----------- |--------- | 215 | | src | no | | | Local path to a file to copy to the remote server; can be absolute or relative. If path is a directory, it is copied recursively. In this case, if path ends with "/", only inside contents of that directory are copied to destination. Otherwise, if it does not end with "/", the directory itself with all contents is copied. This behavior is similar to Rsync. | 216 | | directory_mode | no | | | When doing a recursive copy set the mode for the directories. If this is not set we will default the system defaults. | 217 | | force | no | | | the default is C(yes), which will replace the remote file when contents are different than the source. If C(no), the file will only be transferred if the destination does not exist. | 218 | | dest | yes | | | Remote absolute path where the file should be copied to. If src is a directory, this must be a directory too. | 219 | | selevel | no | | | level part of the SELinux file context. This is the MLS/MCS attribute, sometimes known as the C(range). C(_default) feature works as for I(seuser). | 220 | | seuser | no | | | user part of SELinux file context. Will default to system policy, if applicable. If set to C(_default), it will use the C(user) portion of the policy if available | 221 | | recurse | no | | | Copy all contents in the source directory recursively. This will be slightly inefficient compared to the 'synchronize' module and should not be used for large directory trees. | 222 | | serole | no | | | role part of SELinux file context, C(_default) feature works as for I(seuser). | 223 | | group | no | | | name of the group that should own the file/directory, as would be fed to I(chown) | 224 | | content | no | | | When used instead of 'src', sets the contents of a file directly to the specified value. | 225 | | setype | no | | | type part of SELinux file context, C(_default) feature works as for I(seuser). | 226 | | mode | no | | | mode the file or directory should be, such as 0644 as would be fed to I(chmod). As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)). | 227 | | owner | no | | | name of the user that should own the file/directory, as would be fed to I(chown) | 228 | | follow | no | | | This flag indicates that filesystem links, if they exist, should be followed. | 229 | | validate | no | | | The validation command to run before copying into place. The path to the file to validate is passed in via '%s' which must be present as in the visudo example below. The command is passed securely so shell features like expansion and pipes won't work. | 230 | | backup | no | | | Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. | 231 | 232 | #### Examples 233 | 234 | # Example from Ansible Playbooks 235 | - copy: src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644 236 | 237 | # Copy a new "ntp.conf file into place, backing up the original if it differs from the copied version 238 | - copy: src=/mine/ntp.conf dest=/etc/ntp.conf owner=root group=root mode=644 backup=yes 239 | 240 | # Copy a new "sudoers" file into place, after passing validation with visudo 241 | - copy: src=/mine/sudoers dest=/etc/sudoers validate='visudo -cf %s' 242 | 243 | 244 | #### Notes 245 | - The "copy" module recursively copy facility does not scale to lots (>hundreds) of files. For alternative, see synchronize module, which is a wrapper around rsync. 246 | 247 | --- 248 | --- 249 | Created by Jason Edelman. February 2015. 250 | ``` 251 | 252 | ## Viewing the results in a Browser 253 | Check out the web directory in this repo. -------------------------------------------------------------------------------- /web/ansiblefilesdoc.md: -------------------------------------------------------------------------------- 1 | # Ansible FILES modules 2 | ### *Local copy of files modules* 3 | 4 | --- 5 | ### Requirements 6 | * See official Ansible docs 7 | 8 | --- 9 | ### Modules 10 | 11 | * [template - templates a file out to a remote server.](#template) 12 | * [unarchive - copies an archive to a remote location and unpack it](#unarchive) 13 | * [replace - replace all instances of a particular string in a file using a back-referenced regular expression.](#replace) 14 | * [copy - copies files to remote locations.](#copy) 15 | * [lineinfile - ensure a particular line is in a file, or replace an existing line using a back-referenced regular expression.](#lineinfile) 16 | * [acl - sets and retrieves file acl information.](#acl) 17 | * [synchronize - uses rsync to make synchronizing file paths in your playbooks quick and easy.](#synchronize) 18 | * [assemble - assembles a configuration file from fragments](#assemble) 19 | * [xattr - set/retrieve extended attributes](#xattr) 20 | * [stat - retrieve file or file system status](#stat) 21 | * [file - sets attributes of files](#file) 22 | * [ini_file - tweak settings in ini files](#ini_file) 23 | * [fetch - fetches a file from remote nodes](#fetch) 24 | 25 | --- 26 | 27 | ## template 28 | Templates a file out to a remote server. 29 | 30 | * Synopsis 31 | * Options 32 | * Examples 33 | 34 | #### Synopsis 35 | Templates are processed by the Jinja2 templating language (U(http://jinja.pocoo.org/docs/)) - documentation on the template formatting can be found in the Template Designer Documentation (U(http://jinja.pocoo.org/docs/templates/)). 36 | Six additional variables can be used in templates: C(ansible_managed) (configurable via the C(defaults) section of C(ansible.cfg)) contains a string which can be used to describe the template name, host, modification time of the template file and the owner uid, C(template_host) contains the node name of the template's machine, C(template_uid) the owner, C(template_path) the absolute path of the template, C(template_fullpath) is the absolute path of the template, and C(template_run_date) is the date that the template was rendered. Note that including a string that uses a date in the template will result in the template being marked 'changed' each time. 37 | 38 | #### Options 39 | 40 | | Parameter | required | default | choices | comments | 41 | | ------------- |-------------| ---------|----------- |--------- | 42 | | dest | yes | | | Location to render the template to on the remote machine. | 43 | | src | yes | | | Path of a Jinja2 formatted template on the local server. This can be a relative or absolute path. | 44 | | validate | no | | | The validation command to run before copying into place. The path to the file to validate is passed in via '%s' which must be present as in the visudo example below. validation to run before copying into place. The command is passed securely so shell features like expansion and pipes won't work. | 45 | | backup | no | | | Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. | 46 | 47 | #### Examples 48 | ``` 49 | # Example from Ansible Playbooks 50 | - template: src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644 51 | 52 | # Copy a new "sudoers" file into place, after passing validation with visudo 53 | - template: src=/mine/sudoers dest=/etc/sudoers validate='visudo -cf %s' 54 | 55 | ``` 56 | 57 | #### Notes 58 | - Since Ansible version 0.9, templates are loaded with C(trim_blocks=True). 59 | 60 | 61 | --- 62 | 63 | 64 | ## unarchive 65 | Copies an archive to a remote location and unpack it 66 | 67 | * Synopsis 68 | * Options 69 | * Examples 70 | 71 | #### Synopsis 72 | The M(unarchive) module copies an archive file from the local machine to a remote and unpacks it. 73 | 74 | #### Options 75 | 76 | | Parameter | required | default | choices | comments | 77 | | ------------- |-------------| ---------|----------- |--------- | 78 | | dest | yes | | | Remote absolute path where the archive should be unpacked | 79 | | src | yes | | | Local path to archive file to copy to the remote server; can be absolute or relative. | 80 | | copy | no | | | Should the file be copied from the local to the remote machine? | 81 | | creates | no | | | a filename, when it already exists, this step will B(not) be run. | 82 | 83 | #### Examples 84 | ``` 85 | # Example from Ansible Playbooks 86 | - unarchive: src=foo.tgz dest=/var/lib/foo 87 | 88 | # Unarchive a file that is already on the remote machine 89 | - unarchive: src=/tmp/foo.zip dest=/usr/local/bin copy=no 90 | 91 | ``` 92 | 93 | #### Notes 94 | - requires C(tar)/C(unzip) command on target host 95 | 96 | - can handle I(gzip), I(bzip2) and I(xz) compressed as well as uncompressed tar files 97 | 98 | - detects type of archive automatically 99 | 100 | - uses tar's C(--diff arg) to calculate if changed or not. If this C(arg) is not supported, it will always unpack the archive 101 | 102 | - does not detect if a .zip file is different from destination - always unzips 103 | 104 | - existing files/directories in the destination which are not in the archive are not touched. This is the same behavior as a normal archive extraction 105 | 106 | - existing files/directories in the destination which are not in the archive are ignored for purposes of deciding if the archive should be unpacked or not 107 | 108 | 109 | --- 110 | 111 | 112 | ## replace 113 | Replace all instances of a particular string in a file using a back-referenced regular expression. 114 | 115 | * Synopsis 116 | * Options 117 | * Examples 118 | 119 | #### Synopsis 120 | This module will replace all instances of a pattern within a file. 121 | It is up to the user to maintain idempotence by ensuring that the same pattern would never match any replacements made. 122 | 123 | #### Options 124 | 125 | | Parameter | required | default | choices | comments | 126 | | ------------- |-------------| ---------|----------- |--------- | 127 | | dest | yes | | | The file to modify. | 128 | | replace | no | | | The string to replace regexp matches. May contain backreferences that will get expanded with the regexp capture groups if the regexp matches. If not set, matches are removed entirely. | 129 | | others | no | | | All arguments accepted by the M(file) module also work here. | 130 | | regexp | yes | | | The regular expression to look for in the contents of the file. Uses Python regular expressions; see U(http://docs.python.org/2/library/re.html). Uses multiline mode, which means C(^) and C($) match the beginning and end respectively of I(each line) of the file. | 131 | | validate | no | | | validation to run before copying into place | 132 | | backup | no | | | Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. | 133 | 134 | #### Examples 135 | ``` 136 | - replace: dest=/etc/hosts regexp='(\s+)old\.host\.name(\s+.*)?$' replace='\1new.host.name\2' backup=yes 137 | 138 | - replace: dest=/home/jdoe/.ssh/known_hosts regexp='^old\.host\.name[^\n]*\n' owner=jdoe group=jdoe mode=644 139 | 140 | - replace: dest=/etc/apache/ports regexp='^(NameVirtualHost|Listen)\s+80\s*$' replace='\1 127.0.0.1:8080' validate='/usr/sbin/apache2ctl -f %s -t' 141 | 142 | ``` 143 | 144 | 145 | --- 146 | 147 | 148 | ## copy 149 | Copies files to remote locations. 150 | 151 | * Synopsis 152 | * Options 153 | * Examples 154 | 155 | #### Synopsis 156 | The M(copy) module copies a file on the local box to remote locations. 157 | 158 | #### Options 159 | 160 | | Parameter | required | default | choices | comments | 161 | | ------------- |-------------| ---------|----------- |--------- | 162 | | src | no | | | Local path to a file to copy to the remote server; can be absolute or relative. If path is a directory, it is copied recursively. In this case, if path ends with "/", only inside contents of that directory are copied to destination. Otherwise, if it does not end with "/", the directory itself with all contents is copied. This behavior is similar to Rsync. | 163 | | directory_mode | no | | | When doing a recursive copy set the mode for the directories. If this is not set we will default the system defaults. | 164 | | force | no | | | the default is C(yes), which will replace the remote file when contents are different than the source. If C(no), the file will only be transferred if the destination does not exist. | 165 | | dest | yes | | | Remote absolute path where the file should be copied to. If src is a directory, this must be a directory too. | 166 | | selevel | no | | | level part of the SELinux file context. This is the MLS/MCS attribute, sometimes known as the C(range). C(_default) feature works as for I(seuser). | 167 | | seuser | no | | | user part of SELinux file context. Will default to system policy, if applicable. If set to C(_default), it will use the C(user) portion of the policy if available | 168 | | recurse | no | | | Copy all contents in the source directory recursively. This will be slightly inefficient compared to the 'synchronize' module and should not be used for large directory trees. | 169 | | serole | no | | | role part of SELinux file context, C(_default) feature works as for I(seuser). | 170 | | group | no | | | name of the group that should own the file/directory, as would be fed to I(chown) | 171 | | content | no | | | When used instead of 'src', sets the contents of a file directly to the specified value. | 172 | | setype | no | | | type part of SELinux file context, C(_default) feature works as for I(seuser). | 173 | | mode | no | | | mode the file or directory should be, such as 0644 as would be fed to I(chmod). As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)). | 174 | | owner | no | | | name of the user that should own the file/directory, as would be fed to I(chown) | 175 | | follow | no | | | This flag indicates that filesystem links, if they exist, should be followed. | 176 | | validate | no | | | The validation command to run before copying into place. The path to the file to validate is passed in via '%s' which must be present as in the visudo example below. The command is passed securely so shell features like expansion and pipes won't work. | 177 | | backup | no | | | Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. | 178 | 179 | #### Examples 180 | ``` 181 | # Example from Ansible Playbooks 182 | - copy: src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644 183 | 184 | # Copy a new "ntp.conf file into place, backing up the original if it differs from the copied version 185 | - copy: src=/mine/ntp.conf dest=/etc/ntp.conf owner=root group=root mode=644 backup=yes 186 | 187 | # Copy a new "sudoers" file into place, after passing validation with visudo 188 | - copy: src=/mine/sudoers dest=/etc/sudoers validate='visudo -cf %s' 189 | 190 | ``` 191 | 192 | #### Notes 193 | - The "copy" module recursively copy facility does not scale to lots (>hundreds) of files. For alternative, see synchronize module, which is a wrapper around rsync. 194 | 195 | 196 | --- 197 | 198 | 199 | ## lineinfile 200 | Ensure a particular line is in a file, or replace an existing line using a back-referenced regular expression. 201 | 202 | * Synopsis 203 | * Options 204 | * Examples 205 | 206 | #### Synopsis 207 | This module will search a file for a line, and ensure that it is present or absent. 208 | This is primarily useful when you want to change a single line in a file only. For other cases, see the M(copy) or M(template) modules. 209 | 210 | #### Options 211 | 212 | | Parameter | required | default | choices | comments | 213 | | ------------- |-------------| ---------|----------- |--------- | 214 | | insertbefore | no | | | Used with C(state=present). If specified, the line will be inserted before the specified regular expression. A value is available; C(BOF) for inserting the line at the beginning of the file. May not be used with C(backrefs). | 215 | | dest | yes | | | The file to modify. | 216 | | create | no | | | Used with C(state=present). If specified, the file will be created if it does not already exist. By default it will fail if the file is missing. | 217 | | backrefs | no | | | Used with C(state=present). If set, line can contain backreferences (both positional and named) that will get populated if the C(regexp) matches. This flag changes the operation of the module slightly; C(insertbefore) and C(insertafter) will be ignored, and if the C(regexp) doesn't match anywhere in the file, the file will be left unchanged. If the C(regexp) does match, the last matching line will be replaced by the expanded line parameter. | 218 | | state | no | | | Whether the line should be there or not. | 219 | | others | no | | | All arguments accepted by the M(file) module also work here. | 220 | | insertafter | no | | | Used with C(state=present). If specified, the line will be inserted after the specified regular expression. A special value is available; C(EOF) for inserting the line at the end of the file. May not be used with C(backrefs). | 221 | | regexp | no | | | The regular expression to look for in every line of the file. For C(state=present), the pattern to replace if found; only the last line found will be replaced. For C(state=absent), the pattern of the line to remove. Uses Python regular expressions; see U(http://docs.python.org/2/library/re.html). | 222 | | line | no | | | Required for C(state=present). The line to insert/replace into the file. If C(backrefs) is set, may contain backreferences that will get expanded with the C(regexp) capture groups if the regexp matches. The backreferences should be double escaped (see examples). | 223 | | backup | no | | | Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. | 224 | | validate | no | | | validation to run before copying into place. Use %s in the command to indicate the current file to validate. The command is passed securely so shell features like expansion and pipes won't work. | 225 | 226 | #### Examples 227 | ``` 228 | - lineinfile: dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled 229 | 230 | - lineinfile: dest=/etc/sudoers state=absent regexp="^%wheel" 231 | 232 | - lineinfile: dest=/etc/hosts regexp='^127\.0\.0\.1' line='127.0.0.1 localhost' owner=root group=root mode=0644 233 | 234 | - lineinfile: dest=/etc/httpd/conf/httpd.conf regexp="^Listen " insertafter="^#Listen " line="Listen 8080" 235 | 236 | - lineinfile: dest=/etc/services regexp="^# port for http" insertbefore="^www.*80/tcp" line="# port for http by default" 237 | 238 | # Add a line to a file if it does not exist, without passing regexp 239 | - lineinfile: dest=/tmp/testfile line="192.168.1.99 foo.lab.net foo" 240 | 241 | # Fully quoted because of the ': ' on the line. See the Gotchas in the YAML docs. 242 | - lineinfile: "dest=/etc/sudoers state=present regexp='^%wheel' line='%wheel ALL=(ALL) NOPASSWD: ALL'" 243 | 244 | - lineinfile: dest=/opt/jboss-as/bin/standalone.conf regexp='^(.*)Xms(\d+)m(.*)$' line='\1Xms${xms}m\3' backrefs=yes 245 | 246 | # Validate a the sudoers file before saving 247 | - lineinfile: dest=/etc/sudoers state=present regexp='^%ADMIN ALL\=' line='%ADMIN ALL=(ALL) NOPASSWD:ALL' validate='visudo -cf %s' 248 | 249 | ``` 250 | 251 | 252 | --- 253 | 254 | 255 | ## acl 256 | Sets and retrieves file ACL information. 257 | 258 | * Synopsis 259 | * Options 260 | * Examples 261 | 262 | #### Synopsis 263 | Sets and retrieves file ACL information. 264 | 265 | #### Options 266 | 267 | | Parameter | required | default | choices | comments | 268 | | ------------- |-------------| ---------|----------- |--------- | 269 | | name | yes | | | The full path of the file or object. | 270 | | default | no | | | if the target is a directory, setting this to yes will make it the default acl for entities created inside the directory. It causes an error if name is a file. | 271 | | entity | no | | | actual user or group that the ACL applies to when matching entity types user or group are selected. | 272 | | state | no | | | defines whether the ACL should be present or not. The C(query) state gets the current acl without changing it, for use in 'register' operations. | 273 | | entry | no | | | DEPRECATED. The acl to set or remove. This must always be quoted in the form of '::'. The qualifier may be empty for some types, but the type and perms are always requried. '-' can be used as placeholder when you do not care about permissions. This is now superceeded by entity, type and permissions fields. | 274 | | etype | no | |
  • user
  • group
  • mask
  • other
| the entity type of the ACL to apply, see setfacl documentation for more info. | 275 | | follow | no | |
  • yes
  • no
| whether to follow symlinks on the path if a symlink is encountered. | 276 | | permissions | no | | | Permissions to apply/remove can be any combination of r, w and x (read, write and execute respectively) | 277 | 278 | #### Examples 279 | ``` 280 | # Grant user Joe read access to a file 281 | - acl: name=/etc/foo.conf entity=joe etype=user permissions="r" state=present 282 | 283 | # Removes the acl for Joe on a specific file 284 | - acl: name=/etc/foo.conf entity=joe etype=user state=absent 285 | 286 | # Sets default acl for joe on foo.d 287 | - acl: name=/etc/foo.d entity=joe etype=user permissions=rw default=yes state=present 288 | 289 | # Same as previous but using entry shorthand 290 | - acl: name=/etc/foo.d entry="default:user:joe:rw-" state=present 291 | 292 | # Obtain the acl for a specific file 293 | - acl: name=/etc/foo.conf 294 | register: acl_info 295 | 296 | ``` 297 | 298 | #### Notes 299 | - The "acl" module requires that acls are enabled on the target filesystem and that the setfacl and getfacl binaries are installed. 300 | 301 | 302 | --- 303 | 304 | 305 | ## synchronize 306 | Uses rsync to make synchronizing file paths in your playbooks quick and easy. 307 | 308 | * Synopsis 309 | * Options 310 | * Examples 311 | 312 | #### Synopsis 313 | This is a wrapper around rsync. Of course you could just use the command action to call rsync yourself, but you also have to add a fair number of boilerplate options and host facts. You still may need to call rsync directly via C(command) or C(shell) depending on your use case. The synchronize action is meant to do common things with C(rsync) easily. It does not provide access to the full power of rsync, but does make most invocations easier to follow. 314 | 315 | #### Options 316 | 317 | | Parameter | required | default | choices | comments | 318 | | ------------- |-------------| ---------|----------- |--------- | 319 | | dirs | no | |
  • yes
  • no
| Transfer directories without recursing | 320 | | src | yes | | | Path on the source machine that will be synchronized to the destination; The path can be absolute or relative. | 321 | | delete | no | |
  • yes
  • no
| Delete files that don't exist (after transfer, not before) in the C(src) path. This option requires C(recursive=yes). | 322 | | group | no | |
  • yes
  • no
| Preserve group | 323 | | existing_only | no | |
  • yes
  • no
| Skip creating new files on receiver. | 324 | | links | no | |
  • yes
  • no
| Copy symlinks as symlinks. | 325 | | copy_links | no | |
  • yes
  • no
| Copy symlinks as the item that they point to (the referent) is copied, rather than the symlink. | 326 | | dest | yes | | | Path on the destination machine that will be synchronized from the source; The path can be absolute or relative. | 327 | | recursive | no | |
  • yes
  • no
| Recurse into directories. | 328 | | compress | no | |
  • yes
  • no
| Compress file data during the transfer. In most cases, leave this enabled unless it causes problems. | 329 | | rsync_timeout | no | | | Specify a --timeout for the rsync command in seconds. | 330 | | rsync_path | no | | | Specify the rsync command to run on the remote machine. See C(--rsync-path) on the rsync man page. | 331 | | perms | no | |
  • yes
  • no
| Preserve permissions. | 332 | | rsync_opts | no | | | Specify additional rsync options by passing in an array. | 333 | | checksum | no | |
  • yes
  • no
| Skip based on checksum, rather than mod-time & size; Note that that "archive" option is still enabled by default - the "checksum" option will not disable it. | 334 | | owner | no | |
  • yes
  • no
| Preserve owner (super user only) | 335 | | set_remote_user | | | | put user@ for the remote paths. If you have a custom ssh config to define the remote user for a host that does not match the inventory user, you should set this parameter to "no". | 336 | | times | no | |
  • yes
  • no
| Preserve modification times | 337 | | mode | no | |
  • push
  • pull
| Specify the direction of the synchroniztion. In push mode the localhost or delegate is the source; In pull mode the remote host in context is the source. | 338 | | archive | no | |
  • yes
  • no
| Mirrors the rsync archive flag, enables recursive, links, perms, times, owner, group flags and -D. | 339 | | dest_port | | | | Port number for ssh on the destination host. The ansible_ssh_port inventory var takes precedence over this value. | 340 | 341 | #### Examples 342 | ``` 343 | # Synchronization of src on the control machine to dest on the remote hosts 344 | synchronize: src=some/relative/path dest=/some/absolute/path 345 | 346 | # Synchronization without any --archive options enabled 347 | synchronize: src=some/relative/path dest=/some/absolute/path archive=no 348 | 349 | # Synchronization with --archive options enabled except for --recursive 350 | synchronize: src=some/relative/path dest=/some/absolute/path recursive=no 351 | 352 | # Synchronization with --archive options enabled except for --times, with --checksum option enabled 353 | synchronize: src=some/relative/path dest=/some/absolute/path checksum=yes times=no 354 | 355 | # Synchronization without --archive options enabled except use --links 356 | synchronize: src=some/relative/path dest=/some/absolute/path archive=no links=yes 357 | 358 | # Synchronization of two paths both on the control machine 359 | local_action: synchronize src=some/relative/path dest=/some/absolute/path 360 | 361 | # Synchronization of src on the inventory host to the dest on the localhost in 362 | pull mode 363 | synchronize: mode=pull src=some/relative/path dest=/some/absolute/path 364 | 365 | # Synchronization of src on delegate host to dest on the current inventory host 366 | synchronize: > 367 | src=some/relative/path dest=/some/absolute/path 368 | delegate_to: delegate.host 369 | 370 | # Synchronize and delete files in dest on the remote host that are not found in src of localhost. 371 | synchronize: src=some/relative/path dest=/some/absolute/path delete=yes 372 | 373 | # Synchronize using an alternate rsync command 374 | synchronize: src=some/relative/path dest=/some/absolute/path rsync_path="sudo rsync" 375 | 376 | # Example .rsync-filter file in the source directory 377 | - var # exclude any path whose last part is 'var' 378 | - /var # exclude any path starting with 'var' starting at the source directory 379 | + /var/conf # include /var/conf even though it was previously excluded 380 | 381 | # Synchronize passing in extra rsync options 382 | synchronize: src=/tmp/helloworld dest=/var/www/helloword rsync_opts=--no-motd,--exclude=.git 383 | 384 | ``` 385 | 386 | #### Notes 387 | - Inspect the verbose output to validate the destination user/host/path are what was expected. 388 | 389 | - The remote user for the dest path will always be the remote_user, not the sudo_user. 390 | 391 | - Expect that dest=~/x will be ~/x even if using sudo. 392 | 393 | - To exclude files and directories from being synchronized, you may add C(.rsync-filter) files to the source directory. 394 | 395 | 396 | --- 397 | 398 | 399 | ## assemble 400 | Assembles a configuration file from fragments 401 | 402 | * Synopsis 403 | * Options 404 | * Examples 405 | 406 | #### Synopsis 407 | Assembles a configuration file from fragments. Often a particular program will take a single configuration file and does not support a C(conf.d) style structure where it is easy to build up the configuration from multiple sources. M(assemble) will take a directory of files that can be local or have already been transferred to the system, and concatenate them together to produce a destination file. Files are assembled in string sorting order. Puppet calls this idea I(fragments). 408 | 409 | #### Options 410 | 411 | | Parameter | required | default | choices | comments | 412 | | ------------- |-------------| ---------|----------- |--------- | 413 | | src | yes | | | An already existing directory full of source files. | 414 | | remote_src | no | |
  • True
  • False
| If False, it will search for src at originating/master machine, if True it will go to the remote/target machine for the src. Default is True. | 415 | | dest | yes | | | A file to create using the concatenation of all of the source files. | 416 | | delimiter | no | | | A delimiter to separate the file contents. | 417 | | others | no | | | all arguments accepted by the M(file) module also work here | 418 | | regexp | no | | | Assemble files only if C(regex) matches the filename. If not set, all files are assembled. All "\" (backslash) must be escaped as "\\" to comply yaml syntax. Uses Python regular expressions; see U(http://docs.python.org/2/library/re.html). | 419 | | backup | no | |
  • yes
  • no
| Create a backup file (if C(yes)), including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. | 420 | 421 | #### Examples 422 | ``` 423 | # Example from Ansible Playbooks 424 | - assemble: src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf 425 | 426 | # When a delimiter is specified, it will be inserted in between each fragment 427 | - assemble: src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf delimiter='### START FRAGMENT ###' 428 | 429 | ``` 430 | 431 | 432 | --- 433 | 434 | 435 | ## xattr 436 | set/retrieve extended attributes 437 | 438 | * Synopsis 439 | * Options 440 | * Examples 441 | 442 | #### Synopsis 443 | Manages filesystem user defined extended attributes, requires that they are enabled on the target filesystem and that the setfattr/getfattr utilities are present. 444 | 445 | #### Options 446 | 447 | | Parameter | required | default | choices | comments | 448 | | ------------- |-------------| ---------|----------- |--------- | 449 | | follow | no | |
  • yes
  • no
| if yes, dereferences symlinks and sets/gets attributes on symlink target, otherwise acts on symlink itself. | 450 | | state | no | |
  • read
  • present
  • all
  • keys
  • absent
| defines which state you want to do. C(read) retrieves the current value for a C(key) (default) C(present) sets C(name) to C(value), default if value is set C(all) dumps all data C(keys) retrieves all keys C(absent) deletes the key | 451 | | value | no | | | The value to set the named name/key to, it automatically sets the C(state) to 'set' | 452 | | name | yes | | | The full path of the file/object to get the facts of | 453 | | key | no | | | The name of a specific Extended attribute key to set/retrieve | 454 | 455 | #### Examples 456 | ``` 457 | # Obtain the extended attributes of /etc/foo.conf 458 | - xattr: name=/etc/foo.conf 459 | 460 | # Sets the key 'foo' to value 'bar' 461 | - xattr: path=/etc/foo.conf key=user.foo value=bar 462 | 463 | # Removes the key 'foo' 464 | - xattr: name=/etc/foo.conf key=user.foo state=absent 465 | 466 | ``` 467 | 468 | 469 | --- 470 | 471 | 472 | ## stat 473 | retrieve file or file system status 474 | 475 | * Synopsis 476 | * Options 477 | * Examples 478 | 479 | #### Synopsis 480 | Retrieves facts for a file similar to the linux/unix 'stat' command. 481 | 482 | #### Options 483 | 484 | | Parameter | required | default | choices | comments | 485 | | ------------- |-------------| ---------|----------- |--------- | 486 | | path | yes | | | The full path of the file/object to get the facts of | 487 | | get_md5 | no | | | Whether to return the md5 sum of the file | 488 | | follow | no | | | Whether to follow symlinks | 489 | 490 | #### Examples 491 | ``` 492 | # Obtain the stats of /etc/foo.conf, and check that the file still belongs 493 | # to 'root'. Fail otherwise. 494 | - stat: path=/etc/foo.conf 495 | register: st 496 | - fail: msg="Whoops! file ownership has changed" 497 | when: st.stat.pw_name != 'root' 498 | 499 | # Determine if a path exists and is a directory. Note we need to test 500 | # both that p.stat.isdir actually exists, and also that it's set to true. 501 | - stat: path=/path/to/something 502 | register: p 503 | - debug: msg="Path exists and is a directory" 504 | when: p.stat.isdir is defined and p.stat.isdir == true 505 | 506 | # Don't do md5 checksum 507 | - stat: path=/path/to/myhugefile get_md5=no 508 | 509 | ``` 510 | 511 | 512 | --- 513 | 514 | 515 | ## file 516 | Sets attributes of files 517 | 518 | * Synopsis 519 | * Options 520 | * Examples 521 | 522 | #### Synopsis 523 | Sets attributes of files, symlinks, and directories, or removes files/symlinks/directories. Many other modules support the same options as the M(file) module - including M(copy), M(template), and M(assemble). 524 | 525 | #### Options 526 | 527 | | Parameter | required | default | choices | comments | 528 | | ------------- |-------------| ---------|----------- |--------- | 529 | | src | no | |
    | path of the file to link to (applies only to C(state=link)). Will accept absolute, relative and nonexisting paths. Relative paths are not expanded. | 530 | | force | no | |
    • yes
    • no
    | force the creation of the symlinks in two cases: the source file does not exist (but will appear later); the destination exists and is a file (so, we need to unlink the "path" file and create symlink to the "src" file in place of it). | 531 | | selevel | no | |
      | level part of the SELinux file context. This is the MLS/MCS attribute, sometimes known as the C(range). C(_default) feature works as for I(seuser). | 532 | | seuser | no | |
        | user part of SELinux file context. Will default to system policy, if applicable. If set to C(_default), it will use the C(user) portion of the policy if available | 533 | | recurse | no | |
        • yes
        • no
        | recursively set the specified file attributes (applies only to state=directory) | 534 | | state | no | |
        • file
        • link
        • directory
        • hard
        • touch
        • absent
        | If C(directory), all immediate subdirectories will be created if they do not exist, since 1.7 they will be created with the supplied permissions. If C(file), the file will NOT be created if it does not exist, see the M(copy) or M(template) module if you want that behavior. If C(link), the symbolic link will be created or changed. Use C(hard) for hardlinks. If C(absent), directories will be recursively deleted, and files or symlinks will be unlinked. If C(touch) (new in 1.4), an empty file will be created if the c(path) does not exist, while an existing file or directory will receive updated file access and modification times (similar to the way `touch` works from the command line). | 535 | | serole | no | |
          | role part of SELinux file context, C(_default) feature works as for I(seuser). | 536 | | follow | no | |
          • yes
          • no
          | This flag indicates that filesystem links, if they exist, should be followed. | 537 | | mode | no | |
            | mode the file or directory should be, such as 0644 as would be fed to I(chmod). As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)). | 538 | | path | yes | | | path to the file being managed. Aliases: I(dest), I(name) | 539 | | owner | no | |
              | name of the user that should own the file/directory, as would be fed to I(chown) | 540 | | group | no | |
                | name of the group that should own the file/directory, as would be fed to I(chown) | 541 | | setype | no | |
                  | type part of SELinux file context, C(_default) feature works as for I(seuser). | 542 | 543 | #### Examples 544 | ``` 545 | - file: path=/etc/foo.conf owner=foo group=foo mode=0644 546 | - file: src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link 547 | - file: src=/tmp/{{ item.path }} dest={{ item.dest }} state=link 548 | with_items: 549 | - { path: 'x', dest: 'y' } 550 | - { path: 'z', dest: 'k' } 551 | 552 | ``` 553 | 554 | #### Notes 555 | - See also M(copy), M(template), M(assemble) 556 | 557 | 558 | --- 559 | 560 | 561 | ## ini_file 562 | Tweak settings in INI files 563 | 564 | * Synopsis 565 | * Options 566 | * Examples 567 | 568 | #### Synopsis 569 | Manage (add, remove, change) individual settings in an INI-style file without having to manage the file as a whole with, say, M(template) or M(assemble). Adds missing sections if they don't exist. 570 | Comments are discarded when the source file is read, and therefore will not show up in the destination file. 571 | 572 | #### Options 573 | 574 | | Parameter | required | default | choices | comments | 575 | | ------------- |-------------| ---------|----------- |--------- | 576 | | option | no | | | if set (required for changing a I(value)), this is the name of the option. May be omitted if adding/removing a whole I(section). | 577 | | dest | yes | | | Path to the INI-style file; this file is created if required | 578 | | section | yes | | | Section name in INI file. This is added if C(state=present) automatically when a single value is being set. | 579 | | value | no | | | the string value to be associated with an I(option). May be omitted when removing an I(option). | 580 | | others | no | | | all arguments accepted by the M(file) module also work here | 581 | | backup | no | |
                  • yes
                  • no
                  | Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. | 582 | 583 | #### Examples 584 | ``` 585 | # Ensure "fav=lemonade is in section "[drinks]" in specified file 586 | - ini_file: dest=/etc/conf section=drinks option=fav value=lemonade mode=0600 backup=yes 587 | 588 | - ini_file: dest=/etc/anotherconf 589 | section=drinks 590 | option=temperature 591 | value=cold 592 | backup=yes 593 | 594 | ``` 595 | 596 | #### Notes 597 | - While it is possible to add an I(option) without specifying a I(value), this makes no sense. 598 | 599 | - A section named C(default) cannot be added by the module, but if it exists, individual options within the section can be updated. (This is a limitation of Python's I(ConfigParser).) Either use M(template) to create a base INI file with a C([default]) section, or use M(lineinfile) to add the missing line. 600 | 601 | 602 | --- 603 | 604 | 605 | ## fetch 606 | Fetches a file from remote nodes 607 | 608 | * Synopsis 609 | * Options 610 | * Examples 611 | 612 | #### Synopsis 613 | This module works like M(copy), but in reverse. It is used for fetching files from remote machines and storing them locally in a file tree, organized by hostname. Note that this module is written to transfer log files that might not be present, so a missing remote file won't be an error unless fail_on_missing is set to 'yes'. 614 | 615 | #### Options 616 | 617 | | Parameter | required | default | choices | comments | 618 | | ------------- |-------------| ---------|----------- |--------- | 619 | | dest | yes | | | A directory to save the file into. For example, if the I(dest) directory is C(/backup) a I(src) file named C(/etc/profile) on host C(host.example.com), would be saved into C(/backup/host.example.com/etc/profile) | 620 | | src | yes | | | The file on the remote system to fetch. This I(must) be a file, not a directory. Recursive fetching may be supported in a later release. | 621 | | validate_md5 | no | |
                  • yes
                  • no
                  | Verify that the source and destination md5sums match after the files are fetched. | 622 | | fail_on_missing | no | |
                  • yes
                  • no
                  | Makes it fails when the source file is missing. | 623 | | flat | | | | A l l o w s y o u t o o v e r r i d e t h e d e f a u l t b e h a v i o r o f p r e p e n d i n g h o s t n a m e / p a t h / t o / f i l e t o t h e d e s t i n a t i o n . I f d e s t e n d s w i t h ' / ' , i t w i l l u s e t h e b a s e n a m e o f t h e s o u r c e f i l e , s i m i l a r t o t h e c o p y m o d u l e . O b v i o u s l y t h i s i s o n l y h a n d y i f t h e f i l e n a m e s a r e u n i q u e . | 624 | 625 | #### Examples 626 | ``` 627 | # Store file into /tmp/fetched/host.example.com/tmp/somefile 628 | - fetch: src=/tmp/somefile dest=/tmp/fetched 629 | 630 | # Specifying a path directly 631 | - fetch: src=/tmp/somefile dest=/tmp/prefix-{{ ansible_hostname }} flat=yes 632 | 633 | # Specifying a destination path 634 | - fetch: src=/tmp/uniquefile dest=/tmp/special/ flat=yes 635 | 636 | # Storing in a path relative to the playbook 637 | - fetch: src=/tmp/uniquefile dest=special/prefix-{{ ansible_hostname }} flat=yes 638 | 639 | ``` 640 | 641 | 642 | --- 643 | 644 | 645 | --- 646 | Created by Jason Edelman. February 2015. 647 | --------------------------------------------------------------------------------