# salt.modules.freebsdpkg

Remote package support using `pkg_add(1)`

Important

If you feel that Salt should be using this module to manage packages on a minion, and it is using a different module (or gives an error similar to 'pkg.install' is not available), see here.

Warning

This module has been completely rewritten. Up to and including version 0.17.0, it supported `pkg_add(1)`, but checked for the existence of a pkgng local database and, if found, would provide some of pkgng's functionality. The rewrite of this module has removed all pkgng support, and moved it to the `pkgng` execution module. For versions <= 0.17.0, the documentation here should not be considered accurate. If your Minion is running one of these versions, then the documentation for this module can be viewed using the `sys.doc` function:

    salt bsdminion sys.doc pkg

This module acts as the default package provider for FreeBSD 9 and older. If you need to use pkgng on a FreeBSD 9 system, you will need to override the `pkg` provider by setting the `providers` parameter in your Minion config file, in order to use pkgng.

    providers:
      pkg: pkgng

More information on pkgng support can be found in the documentation for the `pkgng` module.

This module will respect the `PACKAGEROOT` and `PACKAGESITE` environment variables, if set, but these values can also be overridden in several ways:

1. Salt configuration parameters. The configuration parameters `freebsdpkg.PACKAGEROOT` and `freebsdpkg.PACKAGESITE` are recognized. These config parameters are looked up using `config.get` and can thus be specified in the Master config file, Grains, Pillar, or in the Minion config file. Example:

       freebsdpkg.PACKAGEROOT: ftp://ftp.freebsd.org/
       freebsdpkg.PACKAGESITE: ftp://ftp.freebsd.org/pub/FreeBSD/ports/ia64/packages-9-stable/Latest/

2. CLI arguments. Both the `packageroot` (used interchangeably with `fromrepo` for API compatibility) and `packagesite` CLI arguments are recognized, and override their config counterparts from section 1 above.

           salt -G 'os:FreeBSD' pkg.install zsh fromrepo=ftp://ftp2.freebsd.org/
           salt -G 'os:FreeBSD' pkg.install zsh packageroot=ftp://ftp2.freebsd.org/
           salt -G 'os:FreeBSD' pkg.install zsh packagesite=ftp://ftp2.freebsd.org/pub/FreeBSD/ports/ia64/packages-9-stable/Latest/

       .. note::

           These arguments can also be passed through in states:

           .. code-block:: yaml

               zsh:
                 pkg.installed:
                   - fromrepo: ftp://ftp2.freebsd.org/

salt.modules.freebsdpkg.available_version(*names, **kwargs)

  This function is an alias of `latest_version`.

  > `pkg_add(1)` is not capable of querying for remote packages, so this function will always return results as if there is no package available for install or upgrade.

  > CLI Example:

  >     salt '*' pkg.latest_version <package name>
  >     salt '*' pkg.latest_version <package1> <package2> <package3> ...

salt.modules.freebsdpkg.delete(name=None, pkgs=None, **kwargs)

  This function is an alias of `remove`.

  > Remove packages using `pkg_delete(1)`

  > name

  >   The name of the package to be deleted.

  > Multiple Package Options:

  > pkgs

  >   A list of packages to delete. Must be passed as a python list. The `name` parameter will be ignored if this option is passed.

  > New in version 0.16.0.

  > Returns a dict containing the changes.

  > CLI Example:

  >     salt '*' pkg.remove <package name>
  >     salt '*' pkg.remove <package1>,<package2>,<package3>
  >     salt '*' pkg.remove pkgs='["foo", "bar"]'

salt.modules.freebsdpkg.file_dict(*packages, **kwargs)

  List the files that belong to a package, grouped by package. Not specifying any packages will return a list of _every_ file on the system's package database (not generally recommended).

  CLI Examples:

      salt '*' pkg.file_list httpd
      salt '*' pkg.file_list httpd postfix
      salt '*' pkg.file_list

salt.modules.freebsdpkg.file_list(*packages, **kwargs)

  List the files that belong to a package. Not specifying any packages will return a list of _every_ file on the system's package database (not generally recommended).

  CLI Examples:

      salt '*' pkg.file_list httpd
      salt '*' pkg.file_list httpd postfix
      salt '*' pkg.file_list

salt.modules.freebsdpkg.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs)

  Install package(s) using `pkg_add(1)`

  name

    The name of the package to be installed.

  refresh

    Whether or not to refresh the package database before installing.

  fromrepo or packageroot

    Specify a package repository from which to install. Overrides the system default, as well as the PACKAGEROOT environment variable.

  packagesite

    Specify the exact directory from which to install the remote package. Overrides the PACKAGESITE environment variable, if present.

  Multiple Package Installation Options:

  pkgs

    A list of packages to install from a software repository. Must be passed as a python list.

    CLI Example:

        salt '*' pkg.install pkgs='["foo", "bar"]'

  sources

    A list of packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package.

    CLI Example:

        salt '*' pkg.install sources='[{"foo": "salt://foo.deb"}, {"bar": "salt://bar.deb"}]'

  Return a dict containing the new package names and versions:

      {'<package>': {'old': '<old-version>',
                     'new': '<new-version>'}}

  CLI Example:

      salt '*' pkg.install <package name>

salt.modules.freebsdpkg.latest_version(*names, **kwargs)

  `pkg_add(1)` is not capable of querying for remote packages, so this function will always return results as if there is no package available for install or upgrade.

  CLI Example:

      salt '*' pkg.latest_version <package name>
      salt '*' pkg.latest_version <package1> <package2> <package3> ...

salt.modules.freebsdpkg.list_pkgs(versions_as_list=False, with_origin=False, **kwargs)

  List the packages currently installed as a dict:

      {'<package_name>': '<version>'}

  with_originFalse

    Return a nested dictionary containing both the origin name and version for each installed package.

    New in version 2014.1.0.

  CLI Example:

      salt '*' pkg.list_pkgs

salt.modules.freebsdpkg.purge(name=None, pkgs=None, **kwargs)

  This function is an alias of `remove`.

  > Remove packages using `pkg_delete(1)`

  > name

  >   The name of the package to be deleted.

  > Multiple Package Options:

  > pkgs

  >   A list of packages to delete. Must be passed as a python list. The `name` parameter will be ignored if this option is passed.

  > New in version 0.16.0.

  > Returns a dict containing the changes.

  > CLI Example:

  >     salt '*' pkg.remove <package name>
  >     salt '*' pkg.remove <package1>,<package2>,<package3>
  >     salt '*' pkg.remove pkgs='["foo", "bar"]'

salt.modules.freebsdpkg.refresh_db(**kwargs)

  `pkg_add(1)` does not use a local database of available packages, so this function simply returns `True`. it exists merely for API compatibility.

  CLI Example:

      salt '*' pkg.refresh_db

salt.modules.freebsdpkg.remove(name=None, pkgs=None, **kwargs)

  Remove packages using `pkg_delete(1)`

  name

    The name of the package to be deleted.

  Multiple Package Options:

  pkgs

    A list of packages to delete. Must be passed as a python list. The `name` parameter will be ignored if this option is passed.

  New in version 0.16.0.

  Returns a dict containing the changes.

  CLI Example:

      salt '*' pkg.remove <package name>
      salt '*' pkg.remove <package1>,<package2>,<package3>
      salt '*' pkg.remove pkgs='["foo", "bar"]'

salt.modules.freebsdpkg.version(*names, **kwargs)

  Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.

  with_originFalse

    Return a nested dictionary containing both the origin name and version for each specified package.

    New in version 2014.1.0.

  CLI Example:

      salt '*' pkg.version <package name>
      salt '*' pkg.version <package1> <package2> <package3> ...