cdillc.splunk.splunk_user module – Manage Splunk user accounts

Note

This module is part of the cdillc.splunk collection (version 0.26.1).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install cdillc.splunk. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: cdillc.splunk.splunk_user.

New in cdillc.splunk 0.9.0

Synopsis

• Create, delete, and update local Splunk user accounts with Ansible.

• This module uses the Python Splunk SDK and requires access to the splunkd administrative port.

• Authentication can be handled via either username and password or via token.

Requirements

The below requirements are needed on the host that executes this module.

• splunk-sdk

Parameters

Parameter	Comments
append_roles boolean	When true, the specified roles will be appended to the user’s existing roles. Choices: false ← (default) true
defaultapp aliases: defaultApp string	The default Splunk application the user sees when they login to Splunk Web.
email string	Email address associated with the Splunk user.
force_change_pass boolean	Force user to change password. This field is set when the user is first created or when update_password=true. Choices: false true
password string	The password for username/password authentication to Splunkd. Must be provided if username is provided.
realname aliases: fullname, comment string	The full name (comment) of the user account.
roles list / elements=string / required	List of roles associated with the Splunk user. By default this will override any users existing role membership. Use append_roles=true to change this behavior to be additive. Default: ["user"]
splunk_home string	Path to Splunk installation. This is used if the splunk-sdk is not installed for all users.
splunk_pass string	Password for the Splunk user account being created or modified. See the notes regarding changing passwords under the update_password option. This option is required when state=present.
splunk_user aliases: name string / required	Name of the user to create, modify or delete.
splunkd_uri aliases: uri string	The Splunkd endpoint of the Splunk server to configure. Defaults to the local server and default splunkd port. Default: "https://localhost:8089"
state string	Ensure the user is either present or absent; or list the contents of the user’s configuration. With present, existing users are updated in place. See notes regarding specific handling of the roles, splunk_pass, and force_change_pass. Choices: "present" ← (default) "absent" "list"
token string	Token to use when authentication has already taken place. The token can be specified instead of username and password. This module returns an output named token that can be used for subsequent splunkd calls to the same splunkd endpoint.
tz aliases: timezone string	Timezone associated with the Splunk user.
update_force_change_pass boolean	Use in combination with force_change_pass to force an update to an existing user. Whenever this is set to true the module will always report as changed. The Splunk REST api does not allow the force-change-pass to be read. Choices: false ← (default) true
update_password boolean	Replace the existing password with the one specified in password. When true this module will always report changed since there is no way to determine if the new password is different than the currently assigned password. Choices: false ← (default) true
username string	Splunk username for username/password authentication to Splunkd. When provided, password must also be specified.

Notes

Note

• The default behavior of this module will only set password and force_change_pass when the user is first created. This enables mostly idempotent behavior for other parameters without unwanted side effects. Set update_password=true to explicitly update the password of an existing account, or update_force_change_pass=true to force a user to change their current password. Similarly, updates to the roles field can be set to overwrite roles by default or append new roles when append_roles=true.

Examples

- name: Create a new user named 'bob'
  cdillc.splunk.splunk_user::
    state: present
    username: admin
    password: "{{ splunk_admin_password }}"
    splunk_user: bob
    splunk_pass: aReallyGoodPassword
    roles: user,admin
    tz: America/New_York

# Run splunk_user on the controller if missing splunksdk on targets
- name: Create a new user remotely
  cdillc.splunk.splunk_user:
    state: present
    splunkd_uri: "https://{{ ansible_fqdn }}:{{ splunkd_port}}"
    username: "{{ splunk_admin_username }}"
    password: "{{ splunk_admin_password }}"
    splunk_user: bob
    splunk_pass: aReallyGoodPassword
    roles:
     - user
     - admin
  delegate_to: localhost

- name: Add bob to the 'delete_stuff' role.  (existing roles are preserved)
  cdillc.splunk.splunk_user::
    username: admin
    password: "{{ splunk_admin_password }}"
    splunk_user: bob
    roles: delete_stuff
    append_roles: true

- name: Terminate bob after data deletion incident
  cdillc.splunk.splunk_user::
    state: absent
    username: admin
    password: "{{ splunk_admin_password }}"
    splunk_user: bob

- name: Change the password of existing user 'joe'
  cdillc.splunk.splunk_user::
    username: admin
    password: "{{ splunk_admin_password }}"
    splunk_user: joe
    splunk_pass: NewPassWord
    update_password: true

- name: Force existing user 'joe' to change their password at next login
  splunk_user:
    splunkd_uri: https://splunk-sh01.megacorp.example:8089
    username: admin
    password: "{{ splunk_admin_password }}"
    splunk_user: joe
    force_change_pass: true
    update_force_change_pass: true

- name: Retrieve information about top users
  splunk_user:
    state: list
    username: admin
    password: "{{ splunk_admin_password }}"
    splunk_user: "{{ item }}
   register: user_info
   loop:
     - bob
     - joe
     - henry

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
content dictionary	User attributes as returned by Splunk. A few highlights have provided below for quick reference. Returned: when user is listed, created, or updated. Upon deletion this is shown too, but subsequent invocations of state=absent will return an empty dictionary.
capabilities list / elements=string	A list of effectively Splunk capabilities for the user Returned: success Sample: ["search", "install_apps", "..."]
defaultApp string	Returned: success
email string	Returned: success
locked-out string	Returned: success Sample: "0"
relname string	Real user name Returned: success
restart_background_jobs string	Returned: success
roles string	Splunk roles assigned to user. Returned: success Sample: ["user", "power"]
search_assistant string	Returned: success Sample: "compact"
search_auto_format string	Returned: success Sample: "0"
search_line_numbers string	Returned: success Sample: "0"
search_syntax_highlighting string	Returned: success Sample: "light"
search_use_advanced_editor string	Returned: success Sample: "1"
theme string	Returned: success Sample: "enterprise"
tz string	Time zone Returned: success
endpoint string	URL used to edit the user object Returned: always
result string	The overall result of the module run. Options include created, updated, deleted, or unchanged. Returned: always Sample: "updated"
token string	The Splunk auth token created used for the REST API calls. This value can be passed into token of a subsequent REST-based operation. Returned: always
updated_attrs list / elements=string	A list of attributes that were set. Returned: success

Authors

• Lowell C. Alleman

Collection links

• Issue Tracker
• Homepage
• Repository (Sources)