# salt.modules.chocolatey

A module that wraps calls to the Chocolatey package manager (http://chocolatey.org)

Added in version 2014.1.0.

salt.modules.chocolatey.add_source(name, source_location, username=None, password=None, priority=None)

  Instructs Chocolatey to add a source.

  Parameters:

    - name (str) -- The name of the source to be added as a chocolatey repository.

    - source (str) -- Location of the source you want to work with.

    - username (str) -- Provide username for chocolatey sources that need authentication credentials.

    - password (str) -- Provide password for chocolatey sources that need authentication credentials.

    - priority (int) -- The priority order of this source as compared to other sources, lower is better. Defaults to 0 (no priority). All priorities above 0 will be evaluated first, then zero-based values will be evaluated in config file order.

  CLI Example:

      salt '*' chocolatey.add_source <source name> <source_location>
      salt '*' chocolatey.add_source <source name> <source_location> priority=100
      salt '*' chocolatey.add_source <source name> <source_location> user=<user> password=<password>

salt.modules.chocolatey.bootstrap(force=False, source=None, version=None)

  Download and install the latest version of the Chocolatey package manager via the official bootstrap.

  Chocolatey requires Windows PowerShell and the .NET v4.0 runtime. Depending on the host's version of Windows, chocolatey.bootstrap will attempt to ensure these prerequisites are met by downloading and executing the appropriate installers from Microsoft.

  Note

  If PowerShell is installed, you may have to restart the host machine for Chocolatey to work.

  Note

  If you're installing offline using the source parameter, the PowerShell and .NET requirements must already be met on the target. This shouldn't be a problem on Windows versions 2012/8 and later

  Note

  If you're installing chocolatey version 2.0+ the system requires .NET 4.8. Installing this requires a reboot, therefore this module will not automatically install .NET 4.8.

  Parameters:

    - force (bool) -- Run the bootstrap process even if Chocolatey is found in the path.

    - source (str) --

      The location of the `.nupkg` file or `.ps1` file to run from an alternate location. This can be one of the following types of URLs:

      - salt://

      - http(s)://

      - ftp://

      - file:// - A local file on the system

      Added in version 3001.

    - version (str) --

      The version of chocolatey to install. The latest version is installed if this value is `None`. Default is `None`

      Added in version 3007.1.

  Returns:

    The stdout of the Chocolatey installation script

  Return type:

    str

  CLI Example:

      # To bootstrap Chocolatey
      salt '*' chocolatey.bootstrap
      salt '*' chocolatey.bootstrap force=True

      # To bootstrap Chocolatey offline from a file on the salt master
      salt '*' chocolatey.bootstrap source=salt://files/chocolatey.nupkg

      # To bootstrap Chocolatey from a file on C:\Temp
      salt '*' chocolatey.bootstrap source=C:\Temp\chocolatey.nupkg

      # To bootstrap Chocolatey version 1.4.0
      salt '*' chocolatey.bootstrap version=1.4.0

salt.modules.chocolatey.chocolatey_version(refresh=False)

  Returns the version of Chocolatey installed on the minion.

  Parameters:

    refresh (bool) --

    Refresh the cached version of chocolatey

    Added in version 3007.1.

  CLI Example:

      salt '*' chocolatey.chocolatey_version

salt.modules.chocolatey.disable_source(name)

  Instructs Chocolatey to disable a source.

  Parameters:

    name (str) -- Name of the source repository to disable.

  CLI Example:

      salt '*' chocolatey.disable_source <name>

salt.modules.chocolatey.enable_source(name)

  Instructs Chocolatey to enable a source.

  Parameters:

    name (str) -- Name of the source repository to enable.

  CLI Example:

      salt '*' chocolatey.enable_source <name>

salt.modules.chocolatey.install(name, version=None, source=None, force=False, pre_versions=False, install_args=None, override_args=False, force_x86=False, package_args=None, allow_multiple=False, execution_timeout=None)

  Instructs Chocolatey to install a package.

  Parameters:

    - name (str) -- The name of the package to be installed. Only accepts a single argument. Required.

    - version (str) -- Install a specific version of the package. Defaults to latest version. Default is `None`.

    - source (str) --

      Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed. Default is `None`.

      Alternate Sources:

      - cygwin

      - python

      - ruby

      - webpi

      - windowsfeatures

    - force (bool) -- Reinstall the current version of an existing package. Do not use with `allow_multiple`. Default is `False`.

    - pre_versions (bool) -- Include pre-release packages. Default is `False`.

    - install_args (str) -- A list of install arguments you want to pass to the installation process, i.e. product key or feature list. Default is `None`.

    - override_args (bool) -- Set to true if you want to override the original install arguments (for the native installer) in the package and use your own. When this is set to `False` install_args will be appended to the end of the default arguments. Default is `None`.

    - force_x86 (bool) -- Force x86 (32bit) installation on 64bit systems. Default is `False`.

    - package_args (str) -- Arguments you want to pass to the package. Default is `None`.

    - allow_multiple (bool) --

      Allow multiple versions of the package to be installed. Do not use with `force`. Does not work with all packages. Default is `False`.

      Added in version 2017.7.0.

    - execution_timeout (str) --

      Chocolatey execution timeout value you want to pass to the installation process. Default is `None`.

      Added in version 2018.3.0.

  Returns:

    The output of the `chocolatey` command

  Return type:

    str

  CLI Example:

      salt '*' chocolatey.install <package name>
      salt '*' chocolatey.install <package name> version=<package version>
      salt '*' chocolatey.install <package name> install_args=<args> override_args=True

salt.modules.chocolatey.install_cygwin(name, install_args=None, override_args=False)

  Instructs Chocolatey to install a package via Cygwin.

  Parameters:

    - name (str) -- The name of the package to be installed. Only accepts a single argument.

    - install_args (str) -- A list of install arguments you want to pass to the installation process, i.e. product key or feature list

    - override_args (bool) -- Set to `True` if you want to override the original install arguments (for the native installer) in the package and use your own. When this is set to `False` install_args will be appended to the end of the default arguments

  CLI Example:

      salt '*' chocolatey.install_cygwin <package name>
      salt '*' chocolatey.install_cygwin <package name> install_args=<args> override_args=True

salt.modules.chocolatey.install_gem(name, version=None, install_args=None, override_args=False)

  Instructs Chocolatey to install a package via Ruby's Gems.

  Parameters:

    - name (str) -- The name of the package to be installed. Only accepts a single argument.

    - version (str) -- Install a specific version of the package. Defaults to the latest version available.

    - install_args (str) -- A list of install arguments you want to pass to the installation process, i.e. product key or feature list

    - override_args (bool) -- Set to `True` if you want to override the original install arguments (for the native installer) in the package and use your own. When this is set to `False` install_args will be appended to the end of the default arguments

  CLI Example:

      salt '*' chocolatey.install_gem <package name>
      salt '*' chocolatey.install_gem <package name> version=<package version>
      salt '*' chocolatey.install_gem <package name> install_args=<args> override_args=True

salt.modules.chocolatey.install_missing(name, version=None, source=None)

  Instructs Chocolatey to install a package if it doesn't already exist.

  Changed in version 2014.7.0: If the minion has Chocolatey >= 0.9.8.24 installed, this function calls `chocolatey.install` instead, as `installmissing` is deprecated as of that version and will be removed in Chocolatey 1.0.

  Parameters:

    - name (str) -- The name of the package to be installed. Only accepts a single argument.

    - version (str) -- Install a specific version of the package. Defaults to the latest version available.

    - source (str) -- Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed.

  CLI Example:

      salt '*' chocolatey.install_missing <package name>
      salt '*' chocolatey.install_missing <package name> version=<package version>

salt.modules.chocolatey.install_python(name, version=None, install_args=None, override_args=False)

  Instructs Chocolatey to install a package via Python's easy_install.

  Parameters:

    - name (str) -- The name of the package to be installed. Only accepts a single argument.

    - version (str) -- Install a specific version of the package. Defaults to the latest version available.

    - install_args (str) -- A list of install arguments you want to pass to the installation process, i.e. product key or feature list.

    - override_args (bool) -- Set to `True` if you want to override the original install arguments (for the native installer) in the package and use your own. When this is set to `False` install_args will be appended to the end of the default arguments.

  CLI Example:

      salt '*' chocolatey.install_python <package name>
      salt '*' chocolatey.install_python <package name> version=<package version>
      salt '*' chocolatey.install_python <package name> install_args=<args> override_args=True

salt.modules.chocolatey.install_webpi(name, install_args=None, override_args=False)

  Instructs Chocolatey to install a package via the Microsoft Web PI service.

  Parameters:

    - name (str) -- The name of the package to be installed. Only accepts a single argument.

    - install_args (str) -- A list of install arguments you want to pass to the installation process, i.e. product key or feature list.

    - override_args (bool) -- Set to `True` if you want to override the original install arguments (for the native installer) in the package and use your own. When this is set to `False` install_args will be appended to the end of the default arguments.

  CLI Example:

      salt '*' chocolatey.install_webpi <package name>
      salt '*' chocolatey.install_webpi <package name> install_args=<args> override_args=True

salt.modules.chocolatey.install_windowsfeatures(name)

  Instructs Chocolatey to install a Windows Feature via the Deployment Image Servicing and Management tool.

  Parameters:

    name (str) -- The name of the feature to be installed. Only accepts a single argument.

  CLI Example:

      salt '*' chocolatey.install_windowsfeatures <package name>

salt.modules.chocolatey.list_(narrow=None, all_versions=False, pre_versions=False, source=None, local_only=False, exact=False)

  Instructs Chocolatey to pull a vague package list from the repository.

  Parameters:

    - narrow (str) -- Term used to narrow down results. Searches against name/description/tag. Default is None.

    - all_versions (bool) -- Display all available package versions in results. Default is False.

    - pre_versions (bool) -- Display pre-release packages in results. Default is False.

    - source (str) -- Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed if None is passed. Default is None.

    - local_only (bool) -- Only display packages that are installed locally. Default is False.

    - exact (bool) --

      Only display packages that match `narrow` exactly. Default is False.

      Added in version 2017.7.0.

  Returns:

    A dictionary of results.

  Return type:

    dict

  CLI Example:

      salt '*' chocolatey.list <narrow>
      salt '*' chocolatey.list <narrow> all_versions=True

salt.modules.chocolatey.list_sources()

  Returns the list of installed sources.

  CLI Example:

      salt '*' chocolatey.list_sources

salt.modules.chocolatey.list_webpi()

  Instructs Chocolatey to pull a full package list from the Microsoft Web PI repository.

  Returns:

    List of webpi packages

  Return type:

    str

  CLI Example:

      salt '*' chocolatey.list_webpi

salt.modules.chocolatey.list_windowsfeatures()

  Instructs Chocolatey to pull a full package list from the Windows Features list, via the Deployment Image Servicing and Management tool.

  Returns:

    List of Windows Features

  Return type:

    str

  CLI Example:

      salt '*' chocolatey.list_windowsfeatures

salt.modules.chocolatey.unbootstrap()

  Uninstall chocolatey from the system by doing the following:

  - Delete the Chocolatey Directory

  - Remove Chocolatey from the path

  - Remove Chocolatey environment variables

  Added in version 3001.

  Returns:

    A list of items that were removed, otherwise an empty list

  Return type:

    list

  CLI Example:

      salt * chocolatey.unbootstrap

salt.modules.chocolatey.uninstall(name, version=None, uninstall_args=None, override_args=False, force=False)

  Instructs Chocolatey to uninstall a package.

  Parameters:

    - name (str) -- The name of the package to be uninstalled. Only accepts a single argument.

    - version (str) -- Uninstalls a specific version of the package. Defaults to the latest version installed.

    - uninstall_args (str) -- A list of uninstall arguments you want to pass to the uninstallation process, i.e. product key or feature list.

    - override_args -- Set to `True` if you want to override the original uninstall arguments (for the native uninstaller) in the package and use your own. When this is set to `False` uninstall_args will be appended to the end of the default arguments.

  CLI Example:

      salt '*' chocolatey.uninstall <package name>
      salt '*' chocolatey.uninstall <package name> version=<package version>
      salt '*' chocolatey.uninstall <package name> version=<package version> uninstall_args=<args> override_args=True

salt.modules.chocolatey.update(name, source=None, pre_versions=False)

  Instructs Chocolatey to update packages on the system.

  Parameters:

    - name (str) -- The name of the package to update, or "all" to update everything installed on the system.

    - source (str) -- Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed.

    - pre_versions (bool) -- Include pre-release packages in comparison. Defaults to `False`.

  CLI Example:

      salt "*" chocolatey.update all
      salt "*" chocolatey.update <package name> pre_versions=True

salt.modules.chocolatey.upgrade(name, version=None, source=None, force=False, pre_versions=False, install_args=None, override_args=False, force_x86=False, package_args=None)

  Added in version 2016.3.4.

  Instructs Chocolatey to upgrade packages on the system. (update is being deprecated). This command will install the package if not installed.

  Parameters:

    - name (str) -- The name of the package to update, or "all" to update everything installed on the system.

    - version (str) -- Install a specific version of the package. Defaults to latest version.

    - source (str) -- Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed.

    - force (bool) -- Reinstall the same version already installed.

    - pre_versions (bool) -- Include pre-release packages in comparison. Defaults to `False`.

    - install_args (str) -- A list of install arguments you want to pass to the installation process, i.e. product key or feature list.

    - override_args (bool) -- Set to `True` if you want to override the original install arguments (for the native installer) in the package and use your own. When this is set to `False` install_args will be appended to the end of the default arguments.

    - force_x86 (bool) -- Force x86 (32bit) installation on 64bit systems. Defaults to `False`.

    - package_args (str) -- A list of arguments you want to pass to the package.

  Returns:

    Results of the `chocolatey` command

  Return type:

    str

  CLI Example:

      salt "*" chocolatey.upgrade all
      salt "*" chocolatey.upgrade <package name> pre_versions=True

salt.modules.chocolatey.version(name, check_remote=False, source=None, pre_versions=False)

  Instructs Chocolatey to check an installed package version, and optionally compare it to one available from a remote feed.

  Parameters:

    - name (str) -- The name of the package to check. Required.

    - check_remote (bool) -- Get the version number of the latest package from the remote feed. Default is `False`.

    - source (str) -- Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed. Default is `None`.

    - pre_versions (bool) -- Include pre-release packages in comparison. Default is `False`.

  Returns:

    A dictionary of currently installed software and versions

  Return type:

    dict

  CLI Example:

      salt "*" chocolatey.version <package name>
      salt "*" chocolatey.version <package name> check_remote=True