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.file_dict(*packages)

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)

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.refresh_db()

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> ...