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