356 lines
14 KiB
ReStructuredText
356 lines
14 KiB
ReStructuredText
.. _ansible.windows.win_regedit_module:
|
|
|
|
|
|
***************************
|
|
ansible.windows.win_regedit
|
|
***************************
|
|
|
|
**Add, change, or remove registry keys and values**
|
|
|
|
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 1
|
|
|
|
|
|
Synopsis
|
|
--------
|
|
- Add, modify or remove registry keys and values.
|
|
- More information about the windows registry from Wikipedia https://en.wikipedia.org/wiki/Windows_Registry.
|
|
|
|
|
|
|
|
|
|
Parameters
|
|
----------
|
|
|
|
.. raw:: html
|
|
|
|
<table border=0 cellpadding=0 class="documentation-table">
|
|
<tr>
|
|
<th colspan="1">Parameter</th>
|
|
<th>Choices/<font color="blue">Defaults</font></th>
|
|
<th width="100%">Comments</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>data</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">raw</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>Value of the registry entry <code>name</code> in <code>path</code>.</div>
|
|
<div>If not specified then the value for the property will be null for the corresponding <code>type</code>.</div>
|
|
<div>Binary and None data should be expressed in a yaml byte array or as comma separated hex values.</div>
|
|
<div>An easy way to generate this is to run <code>regedit.exe</code> and use the <em>export</em> option to save the registry values to a file.</div>
|
|
<div>In the exported file, binary value will look like <code>hex:be,ef,be,ef</code>, the <code>hex:</code> prefix is optional.</div>
|
|
<div>DWORD and QWORD values should either be represented as a decimal number or a hex value.</div>
|
|
<div>Multistring values should be passed in as a list.</div>
|
|
<div>See the examples for more details on how to format this data.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>delete_key</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">boolean</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<ul style="margin: 0; padding: 0"><b>Choices:</b>
|
|
<li>no</li>
|
|
<li><div style="color: blue"><b>yes</b> ←</div></li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
<div>When <code>state</code> is 'absent' then this will delete the entire key.</div>
|
|
<div>If <code>no</code> then it will only clear out the '(Default)' property for that key.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>hive</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">path</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>A path to a hive key like C:\Users\Default\NTUSER.DAT to load in the registry.</div>
|
|
<div>This hive is loaded under the HKLM:\ANSIBLE key which can then be used in <em>name</em> like any other path.</div>
|
|
<div>This can be used to load the default user profile registry hive or any other hive saved as a file.</div>
|
|
<div>Using this function requires the user to have the <code>SeRestorePrivilege</code> and <code>SeBackupPrivilege</code> privileges enabled.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>name</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>Name of the registry entry in the above <code>path</code> parameters.</div>
|
|
<div>If not provided, or empty then the '(Default)' property for the key will be used.</div>
|
|
<div style="font-size: small; color: darkgreen"><br/>aliases: entry, value</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>path</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
/ <span style="color: red">required</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>Name of the registry path.</div>
|
|
<div>Should be in one of the following registry hives: HKCC, HKCR, HKCU, HKLM, HKU.</div>
|
|
<div style="font-size: small; color: darkgreen"><br/>aliases: key</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>state</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<ul style="margin: 0; padding: 0"><b>Choices:</b>
|
|
<li>absent</li>
|
|
<li><div style="color: blue"><b>present</b> ←</div></li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
<div>The state of the registry entry.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>type</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<ul style="margin: 0; padding: 0"><b>Choices:</b>
|
|
<li>none</li>
|
|
<li>binary</li>
|
|
<li>dword</li>
|
|
<li>expandstring</li>
|
|
<li>multistring</li>
|
|
<li><div style="color: blue"><b>string</b> ←</div></li>
|
|
<li>qword</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
<div>The registry value data type.</div>
|
|
<div style="font-size: small; color: darkgreen"><br/>aliases: datatype</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br/>
|
|
|
|
|
|
Notes
|
|
-----
|
|
|
|
.. note::
|
|
- Check-mode ``-C/--check`` and diff output ``-D/--diff`` are supported, so that you can test every change against the active configuration before applying changes.
|
|
- Beware that some registry hives (``HKEY_USERS`` in particular) do not allow to create new registry paths in the root folder.
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
.. seealso::
|
|
|
|
:ref:`ansible.windows.win_reg_stat_module`
|
|
The official documentation on the **ansible.windows.win_reg_stat** module.
|
|
:ref:`ansible.windows.win_regmerge_module`
|
|
The official documentation on the **ansible.windows.win_regmerge** module.
|
|
|
|
|
|
Examples
|
|
--------
|
|
|
|
.. code-block:: yaml
|
|
|
|
- name: Create registry path MyCompany
|
|
ansible.windows.win_regedit:
|
|
path: HKCU:\Software\MyCompany
|
|
|
|
- name: Add or update registry path MyCompany, with entry 'hello', and containing 'world'
|
|
ansible.windows.win_regedit:
|
|
path: HKCU:\Software\MyCompany
|
|
name: hello
|
|
data: world
|
|
|
|
- name: Add or update registry path MyCompany, with dword entry 'hello', and containing 1337 as the decimal value
|
|
ansible.windows.win_regedit:
|
|
path: HKCU:\Software\MyCompany
|
|
name: hello
|
|
data: 1337
|
|
type: dword
|
|
|
|
- name: Add or update registry path MyCompany, with dword entry 'hello', and containing 0xff2500ae as the hex value
|
|
ansible.windows.win_regedit:
|
|
path: HKCU:\Software\MyCompany
|
|
name: hello
|
|
data: 0xff2500ae
|
|
type: dword
|
|
|
|
- name: Add or update registry path MyCompany, with binary entry 'hello', and containing binary data in hex-string format
|
|
ansible.windows.win_regedit:
|
|
path: HKCU:\Software\MyCompany
|
|
name: hello
|
|
data: hex:be,ef,be,ef,be,ef,be,ef,be,ef
|
|
type: binary
|
|
|
|
- name: Add or update registry path MyCompany, with binary entry 'hello', and containing binary data in yaml format
|
|
ansible.windows.win_regedit:
|
|
path: HKCU:\Software\MyCompany
|
|
name: hello
|
|
data: [0xbe,0xef,0xbe,0xef,0xbe,0xef,0xbe,0xef,0xbe,0xef]
|
|
type: binary
|
|
|
|
- name: Add or update registry path MyCompany, with expand string entry 'hello'
|
|
ansible.windows.win_regedit:
|
|
path: HKCU:\Software\MyCompany
|
|
name: hello
|
|
data: '%appdata%\local'
|
|
type: expandstring
|
|
|
|
- name: Add or update registry path MyCompany, with multi string entry 'hello'
|
|
ansible.windows.win_regedit:
|
|
path: HKCU:\Software\MyCompany
|
|
name: hello
|
|
data: ['hello', 'world']
|
|
type: multistring
|
|
|
|
- name: Disable keyboard layout hotkey for all users (changes existing)
|
|
ansible.windows.win_regedit:
|
|
path: HKU:\.DEFAULT\Keyboard Layout\Toggle
|
|
name: Layout Hotkey
|
|
data: 3
|
|
type: dword
|
|
|
|
- name: Disable language hotkey for current users (adds new)
|
|
ansible.windows.win_regedit:
|
|
path: HKCU:\Keyboard Layout\Toggle
|
|
name: Language Hotkey
|
|
data: 3
|
|
type: dword
|
|
|
|
- name: Remove registry path MyCompany (including all entries it contains)
|
|
ansible.windows.win_regedit:
|
|
path: HKCU:\Software\MyCompany
|
|
state: absent
|
|
delete_key: yes
|
|
|
|
- name: Clear the existing (Default) entry at path MyCompany
|
|
ansible.windows.win_regedit:
|
|
path: HKCU:\Software\MyCompany
|
|
state: absent
|
|
delete_key: no
|
|
|
|
- name: Remove entry 'hello' from registry path MyCompany
|
|
ansible.windows.win_regedit:
|
|
path: HKCU:\Software\MyCompany
|
|
name: hello
|
|
state: absent
|
|
|
|
- name: Change default mouse trailing settings for new users
|
|
ansible.windows.win_regedit:
|
|
path: HKLM:\ANSIBLE\Control Panel\Mouse
|
|
name: MouseTrails
|
|
data: 10
|
|
type: string
|
|
state: present
|
|
hive: C:\Users\Default\NTUSER.dat
|
|
|
|
|
|
|
|
Return Values
|
|
-------------
|
|
Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module:
|
|
|
|
.. raw:: html
|
|
|
|
<table border=0 cellpadding=0 class="documentation-table">
|
|
<tr>
|
|
<th colspan="1">Key</th>
|
|
<th>Returned</th>
|
|
<th width="100%">Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>data_changed</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">boolean</span>
|
|
</div>
|
|
</td>
|
|
<td>success</td>
|
|
<td>
|
|
<div>Whether this invocation changed the data in the registry value.</div>
|
|
<br/>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>data_type_changed</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">boolean</span>
|
|
</div>
|
|
</td>
|
|
<td>success</td>
|
|
<td>
|
|
<div>Whether this invocation changed the datatype of the registry value.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">True</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br/><br/>
|
|
|
|
|
|
Status
|
|
------
|
|
|
|
|
|
Authors
|
|
~~~~~~~
|
|
|
|
- Adam Keech (@smadam813)
|
|
- Josh Ludwig (@joshludwig)
|
|
- Jordan Borean (@jborean93)
|