ansible-later/testenv/lib/python2.7/site-packages/ansible/modules/windows/win_chocolatey.py

331 lines
10 KiB
Python
Raw Normal View History

2019-04-23 11:04:27 +00:00
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: (c) 2014, Trond Hindenes <trond@hindenes.com>
# Copyright: (c) 2018, Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
# this is a windows documentation stub. actual code lives in the .ps1
# file of the same name
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'}
DOCUMENTATION = r'''
---
module: win_chocolatey
version_added: "1.9"
short_description: Manage packages using chocolatey
description:
- Manage packages using Chocolatey (U(http://chocolatey.org/)).
- If Chocolatey is missing from the system, the module will install it.
- List of packages can be found at U(http://chocolatey.org/packages).
requirements:
- chocolatey >= 0.10.5 (will be upgraded if older)
options:
allow_empty_checksums:
description:
- Allow empty checksums to be used for downloaded resource from non-secure
locations.
- Use M(win_chocolatey_feature) with the name C(allowEmptyChecksums) to
control this option globally.
type: bool
default: 'no'
version_added: '2.2'
allow_prerelease:
description:
- Allow the installation of pre-release packages.
- If I(state) is C(latest), the latest pre-release package will be
installed.
type: bool
default: 'no'
version_added: '2.6'
architecture:
description:
- Force Chocolatey to install the package of a specific process
architecture.
- When setting C(x86), will ensure Chocolatey installs the x86 package
even when on an x64 bit OS.
choices:
- default
- x86
default: default
version_added: '2.7'
force:
description:
- Forces the install of a package, even if it already is installed.
- Using I(force) will cause Ansible to always report that a change was
made.
type: bool
default: 'no'
install_args:
description:
- Arguments to pass to the native installer.
- These are arguments that are passed directly to the installer the
Chocolatey package runs, this is generally an advanced option.
type: str
version_added: '2.1'
ignore_checksums:
description:
- Ignore the checksums provided by the package.
- Use M(win_chocolatey_feature) with the name C(checksumFiles) to control
this option globally.
type: bool
default: 'no'
version_added: '2.2'
ignore_dependencies:
description:
- Ignore dependencies, only install/upgrade the package itself.
type: bool
default: 'no'
version_added: '2.1'
name:
description:
- Name of the package(s) to be installed.
- Set to C(all) to run the action on all the installed packages.
required: yes
type: list
package_params:
description:
- Parameters to pass to the package.
- These are parameters specific to the Chocolatey package and are generally
documented by the package itself.
- Before Ansible 2.7, this option was just I(params).
type: str
version_added: '2.1'
aliases:
- params
proxy_url:
description:
- Proxy URL used to install chocolatey and the package.
- Use M(win_chocolatey_config) with the name C(proxy) to control this
option globally.
type: str
version_added: '2.4'
proxy_username:
description:
- Proxy username used to install Chocolatey and the package.
- Before Ansible 2.7, users with double quote characters C(") would need to
be escaped with C(\) beforehand. This is no longer necessary.
- Use M(win_chocolatey_config) with the name C(proxyUser) to control this
option globally.
type: str
version_added: '2.4'
proxy_password:
description:
- Proxy password used to install Chocolatey and the package.
- This value is exposed as a command argument and any privileged account
can see this value when the module is running Chocolatey, define the
password on the global config level with M(win_chocolatey_config) with
name C(proxyPassword) to avoid this.
type: str
version_added: '2.4'
skip_scripts:
description:
- Do not run I(chocolateyInstall.ps1) or I(chocolateyUninstall.ps1) scripts
when installing a package.
type: bool
default: 'no'
version_added: '2.4'
source:
description:
- Specify the source to retrieve the package from.
- Use M(win_chocolatey_source) to manage global sources.
- This value can either be the URL to a Chocolatey feed, a path to a folder
containing C(.nupkg) packages or the name of a source defined by
M(win_chocolatey_source).
- This value is also used when Chocolatey is not installed as the location
of the install.ps1 script and only supports URLs for this case.
type: str
source_username:
description:
- A username to use with I(source) when accessing a feed that requires
authentication.
- It is recommended you define the credentials on a source with
M(win_chocolatey_source) instead of passing it per task.
type: str
version_added: '2.7'
source_password:
description:
- The password for I(source_username).
- This value is exposed as a command argument and any privileged account
can see this value when the module is running Chocolatey, define the
credentials with a source with M(win_chocolatey_source) to avoid this.
type: str
version_added: '2.7'
state:
description:
- State of the package on the system.
- When C(absent), will ensure the package is not installed.
- When C(present), will ensure the package is installed.
- When C(downgrade), will allow Chocolatey to downgrade a package if
I(version) is older than the installed version.
- When C(latest), will ensure the package is installed to the latest
available version.
- When C(reinstalled), will uninstall and reinstall the package.
choices:
- absent
- downgrade
- latest
- present
- reinstalled
default: present
type: str
timeout:
description:
- The time to allow chocolatey to finish before timing out.
type: int
default: 2700
version_added: '2.3'
aliases:
- execution_timeout
validate_certs:
description:
- Used when downloading the Chocolatey install script if Chocolatey is not
already installed, this does not affect the Chocolatey package install
process.
- When C(no), no SSL certificates will be validated.
- This should only be used on personally controlled sites using self-signed
certificate.
type: bool
default: 'yes'
version_added: '2.7'
version:
description:
- Specific version of the package to be installed.
- Ignored when I(state) is set to C(absent).
type: str
notes:
- Provide the C(version) parameter value as a string (e.g. C('6.1')), otherwise it
is considered to be a floating-point number and depending on the locale could
become C(6,1), which will cause a failure.
- When using verbosity 2 or less (C(-vv)) the C(stdout) output will be restricted.
- When using verbosity 4 (C(-vvvv)) the C(stdout) output will be more verbose.
- When using verbosity 5 (C(-vvvvv)) the C(stdout) output will include debug output.
- This module will install or upgrade Chocolatey when needed.
- Some packages, like hotfixes or updates need an interactive user logon in
order to install. You can use (C(become)) to achieve this, see
:doc:`/user_guide/become`.
- Even if you are connecting as local Administrator, using (C(become)) to
become Administrator will give you an interactive user logon, see examples
below.
- If (C(become)) is unavailable, use (M(win_hotfix) to install hotfixes instead
of (M(win_chocolatey)) as (M(win_hotfix)) avoids using wusa.exe which cannot
be run without (C(become)).
author:
- Trond Hindenes (@trondhindenes)
- Peter Mounce (@petemounce)
- Pepe Barbe (@elventear)
- Adam Keech (@smadam813)
- Pierre Templier (@ptemplier)
- Jordan Borean (@jborean93)
'''
# TODO:
# * Better parsing when a package has dependencies - currently fails
# * Time each item that is run
# * Support 'changed' with gems - would require shelling out to `gem list` first and parsing, kinda defeating the point of using chocolatey.
# * Version provided not as string might be translated to 6,6 depending on Locale (results in errors)
EXAMPLES = r'''
- name: Install git
win_chocolatey:
name: git
state: present
- name: Upgrade installed packages
win_chocolatey:
name: all
state: latest
- name: Install notepadplusplus version 6.6
win_chocolatey:
name: notepadplusplus
version: '6.6'
- name: Install notepadplusplus 32 bit version
win_chocolatey:
name: notepadplusplus
architecture: x86
- name: Install git from specified repository
win_chocolatey:
name: git
source: https://someserver/api/v2/
- name: Install git from a pre configured source (win_chocolatey_source)
win_chocolatey:
name: git
source: internal_repo
- name: ensure Chocolatey itself is installed and use internal repo as source
win_chocolatey:
name: chocolatey
source: http://someserver/chocolatey
- name: Uninstall git
win_chocolatey:
name: git
state: absent
- name: Install multiple packages
win_chocolatey:
name:
- procexp
- putty
- windirstat
state: present
- name: Install multiple packages sequentially
win_chocolatey:
name: '{{ item }}'
state: present
with_items:
- procexp
- putty
- windirstat
- name: uninstall multiple packages
win_chocolatey:
name:
- procexp
- putty
- windirstat
state: absent
- name: Install curl using proxy
win_chocolatey:
name: curl
proxy_url: http://proxy-server:8080/
proxy_username: joe
proxy_password: p@ssw0rd
- name: Install a package that requires 'become'
win_chocolatey:
name: officepro2013
become: yes
become_user: Administrator
become_method: runas
'''
RETURN = r'''
command:
description: The full command used in the chocolatey task.
returned: changed
type: str
sample: choco.exe install -r --no-progress -y sysinternals --timeout 2700 --failonunfound
rc:
description: The return code from the chocolatey task.
returned: always
type: int
sample: 0
stdout:
description: The stdout from the chocolatey task. The verbosity level of the
messages are affected by Ansible verbosity setting, see notes for more
details.
returned: changed
type: str
sample: Chocolatey upgraded 1/1 packages.
'''