1#!/usr/local/bin/python3.8 2# -*- coding: utf-8 -*- 3 4# Copyright: (c) 2018, Micah Hunsberger (@mhunsber) 5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) 6 7DOCUMENTATION = r''' 8--- 9module: win_hosts 10short_description: Manages hosts file entries on Windows. 11description: 12 - Manages hosts file entries on Windows. 13 - Maps IPv4 or IPv6 addresses to canonical names. 14 - Adds, removes, or sets cname records for ip and hostname pairs. 15 - Modifies %windir%\\system32\\drivers\\etc\\hosts. 16options: 17 state: 18 description: 19 - Whether the entry should be present or absent. 20 - If only I(canonical_name) is provided when C(state=absent), then 21 all hosts entries with the canonical name of I(canonical_name) 22 will be removed. 23 - If only I(ip_address) is provided when C(state=absent), then all 24 hosts entries with the ip address of I(ip_address) will be removed. 25 - If I(ip_address) and I(canonical_name) are both omitted when 26 C(state=absent), then all hosts entries will be removed. 27 choices: 28 - absent 29 - present 30 default: present 31 type: str 32 canonical_name: 33 description: 34 - A canonical name for the host entry. 35 - required for C(state=present). 36 type: str 37 ip_address: 38 description: 39 - The ip address for the host entry. 40 - Can be either IPv4 (A record) or IPv6 (AAAA record). 41 - Required for C(state=present). 42 type: str 43 aliases: 44 description: 45 - A list of additional names (cname records) for the host entry. 46 - Only applicable when C(state=present). 47 type: list 48 elements: str 49 action: 50 choices: 51 - add 52 - remove 53 - set 54 description: 55 - Controls the behavior of I(aliases). 56 - Only applicable when C(state=present). 57 - If C(add), each alias in I(aliases) will be added to the host entry. 58 - If C(set), each alias in I(aliases) will be added to the host entry, 59 and other aliases will be removed from the entry. 60 default: set 61 type: str 62author: 63 - Micah Hunsberger (@mhunsber) 64notes: 65 - Each canonical name can only be mapped to one IPv4 and one IPv6 address. 66 If I(canonical_name) is provided with C(state=present) and is found 67 to be mapped to another IP address that is the same type as, but unique 68 from I(ip_address), then I(canonical_name) and all I(aliases) will 69 be removed from the entry and added to an entry with the provided IP address. 70 - Each alias can only be mapped to one canonical name. If I(aliases) is provided 71 with C(state=present) and an alias is found to be mapped to another canonical 72 name, then the alias will be removed from the entry and either added to or removed 73 from (depending on I(action)) an entry with the provided canonical name. 74seealso: 75 - module: ansible.windows.win_template 76 - module: ansible.windows.win_file 77 - module: ansible.windows.win_copy 78''' 79 80EXAMPLES = r''' 81- name: Add 127.0.0.1 as an A record for localhost 82 community.windows.win_hosts: 83 state: present 84 canonical_name: localhost 85 ip_address: 127.0.0.1 86 87- name: Add ::1 as an AAAA record for localhost 88 community.windows.win_hosts: 89 state: present 90 canonical_name: localhost 91 ip_address: '::1' 92 93- name: Remove 'bar' and 'zed' from the list of aliases for foo (192.168.1.100) 94 community.windows.win_hosts: 95 state: present 96 canonical_name: foo 97 ip_address: 192.168.1.100 98 action: remove 99 aliases: 100 - bar 101 - zed 102 103- name: Remove hosts entries with canonical name 'bar' 104 community.windows.win_hosts: 105 state: absent 106 canonical_name: bar 107 108- name: Remove 10.2.0.1 from the list of hosts 109 community.windows.win_hosts: 110 state: absent 111 ip_address: 10.2.0.1 112 113- name: Ensure all name resolution is handled by DNS 114 community.windows.win_hosts: 115 state: absent 116''' 117 118RETURN = r''' 119''' 120