salt/doc/topics/releases/nitrogen.rst

:orphan:

======================================
Salt Release Notes - Codename Nitrogen
======================================

States Added for Management of systemd Unit Masking
===================================================

The :py:func:`service.masked <salt.states.service.masked>` and
:py:func:`service.umasked <salt.states.service.unmasked>` states have been
added to allow Salt to manage masking of systemd units.

Additionally, the following functions in the :mod:`systemd
<salt.modules.systemd>` execution module have changed to accomodate the fact
that indefinite and runtime masks can co-exist for the same unit:

- :py:func:`service.masked <salt.modules.systemd.masked>` - The return from
  this function has changed from previous releases. Before, ``False`` would be
  returned if the unit was not masked, and the output of ``systemctl is-enabled
  <unit name>`` would be returned if the unit was masked. However, since
  indefinite and runtime masks can exist for the same unit at the same time,
  this function has been altered to accept a ``runtime`` argument. If ``True``,
  the minion will be checked for a runtime mask assigned to the named unit. If
  ``False``, then the minion will be checked for an indefinite mask. If one is
  found, ``True`` will be returned. If not, then ``False`` will be returned.
- :py:func:`service.masked <salt.modules.systemd.masked>` - This function used
  to just run ``systemctl is-enabled <unit name>`` and based on the return
  from this function the corresponding mask type would be removed. However, if
  both runtime and indefinite masks are set for the same unit, then ``systemctl
  is-enabled <unit name>`` would show just the indefinite mask. The indefinite
  mask would be removed, but the runtime mask would remain. The function has
  been modified to accept a ``runtime`` argument, and will attempt to remove a
  runtime mask if that argument is set to ``True``. If set to ``False``, it
  will attempt to remove an indefinite mask.

These new ``runtime`` arguments default to ``False``.

Pillar Encryption
=================

Beginning in 2016.3.0 the CLI pillar data passed to several functions could
conditionally be passed through a renderer to be decrypted. This functionality
has now been extended to pillar SLS files as well. See :ref:`here
<pillar-encryption>` for detailed documentation on this feature.

Grains Changes
==============

- The ``os_release`` grain has been changed from a string to an integer.
  State files, especially those using a templating language like Jinja
  may need to be adjusted to account for this change.
- Add ability to specify disk backing mode in the VMWare salt cloud profile.

State Module Changes
====================

- The :py:func:`service.running <salt.states.service.running>` and
  :py:func:`service.dead <salt.states.service.dead>` states now support a
  ``no_block`` argument which, when set to ``True`` on systemd minions, will
  start/stop the service using the ``--no-block`` flag in the ``systemctl``
  command. On non-systemd minions, a warning will be issued.

Execution Module Changes
========================

- Several functions in the :mod:`systemd <salt.modules.systemd>` execution
  module have gained a ``no_block`` argument, which when set to ``True`` will
  use ``--no-block`` in the ``systemctl`` command.
- In the :mod:`solarisips <salt.modules.solarisips>` ``pkg`` module, the
  default value for the ``refresh`` argument to the ``list_upgrades`` function
  has been changed from ``False`` to ``True``. This makes the function more
  consistent with all of the other ``pkg`` modules (The other
  ``pkg.list_upgrades`` functions all defaulted to ``True``).
- The functions which handle masking in the :mod:`systemd
  <salt.modules.systemd>` module have changed. These changes are described
  above alongside the information on the new states which have been added to
  manage masking of systemd units.
- The :py:func:`pkg.list_repo_pkgs <salt.modules.yumpkg.list_repo_pkgs>`
  function for yum/dnf-based distros has had its default output format changed.
  In prior releases, results would be organized by repository. Now, the default
  for each package will be a simple list of versions. To get the old behavior,
  pass ``byrepo=True`` to the function.
- A ``pkg.list_repo_pkgs`` function has been added for both
  :py:func:`Debian/Ubuntu <salt.modules.aptpkg.list_repo_pkgs>` and
  :py:func:`Arch Linux <salt.modules.pacman.list_repo_pkgs>`-based distros.

Wildcard Versions in :py:func:`pkg.installed <salt.states.pkg.installed>` States
================================================================================

The :py:func:`pkg.installed <salt.states.pkg.installed>` state now supports
wildcards in package versions, for the following platforms:

- Debian/Ubuntu
- RHEL/CentOS
- Arch Linux

This support also extends to any derivatives of these distros, which use the
:mod:`aptpkg <salt.modules.aptpkg>`, :mod:`yumpkg <salt.modules.yumpkg>`, or
:mod:`pacman <salt.modules.pacman>` providers for the ``pkg`` virtual module.

Using wildcards can be useful for packages where the release name is built into
the version in some way, such as for RHEL/CentOS which typically has version
numbers like ``1.2.34-5.el7``. An example of the usage for this would be:

.. code-block:: yaml

    mypkg:
      pkg.installed:
        - version: '1.2.34*'

- The :mod:`system <salt.modules.system>` module changed the returned format
  from "HH:MM AM/PM" to "HH:MM:SS AM/PM" for `get_system_time`.

Master Configuration Additions
==============================

- :conf_master:`syndic_forward_all_events` - Option on multi-syndic or single
  when connected to multiple masters to be able to send events to all connected
  masters.

Minion Configuration Additions
==============================

- :conf_minion:`pillarenv_from_saltenv` - When set to ``True`` (default is
  ``False``), the :conf_minion:`pillarenv` option will take the same value as
  the effective saltenv when running states. This would allow a user to run
  ``salt '*' state.apply mysls saltenv=dev``, and the SLS for both the state
  and pillar data would be sourced from the ``dev`` environment, essentially
  the equivalent of running ``salt '*' state.apply mysls saltenv=dev
  pillarenv=dev``. Note that if :conf_minion:`pillarenv` is set in the minion
  config file, or if ``pillarenv`` is provided on the CLI, it will override
  this option.

Python API Changes
==================

The :ref:`LocalClient <local-client>`'s ``expr_form`` argument has been
deprecated and renamed to ``tgt_type``. This change was made due to numerous
reports of confusion among community members, since the targeting method is
published to minions as ``tgt_type``, and appears as ``tgt_type`` in the job
cache as well.

While ``expr_form`` will continue to be supported until the **Fluorine**
release cycle (two major releases after this one), those who are using the
:ref:`LocalClient <local-client>` (either directly, or implictly via a
:ref:`netapi module <all-netapi-modules>`) are encouraged to update their code
to use ``tgt_type``.

Custom Refspecs in GitFS / git_pillar / winrepo
===============================================

It is now possible to specify the refspecs to use when fetching from remote
repositories for GitFS, git_pillar, and winrepo. More information on how this
feature works can be found :ref:`here <gitfs-custom-refspecs>` in the GitFS
Walkthrough. The git_pillar and winrepo versions of this feature work the same
as their GitFS counterpart.

git_pillar "mountpoints" Feature Added
======================================

See :ref:`here <git-pillar-mountpoints>` for detailed documentation.

``dockerng`` State/Execution Module Renamed to ``docker``
=========================================================

The old ``docker`` state and execution modules have been moved to
salt-contrib_. The ``dockerng`` state and execution module have been renamed to
``docker`` and now serve as the official Docker state and execution modules.

These state and execution modules can be used interchangeably both with
``docker`` and ``dockerng`` to preserve backward-compatibility, but it is
recommended to update your SLS files to use ``docker`` instead of ``dockerng``
in event that the ``dockerng`` alias is dropped in a future release.

.. _salt-contrib: https://github.com/saltstack/salt-contrib

Deprecations
============

General Deprecations
--------------------

- Removed support for aliasing ``cmd.run`` to ``cmd.shell``.
- Removed support for Dulwich from :ref:`GitFS <tutorial-gitfs>`.
- Beacon configurations should be lists instead of dictionaries.
- The ``PidfileMixin`` has been removed. Please use ``DaemonMixIn`` instead.
- The ``use_pending`` argument was removed from the ``salt.utils.event.get_event``
  function.
- The ``pending_tags`` argument was removed from the ``salt.utils.event.get_event``
  function.

Configuration Option Deprecations
---------------------------------

- The ``client_acl`` configuration option has been removed. Please use
  ``publisher_acl`` instead.
- The ``client_acl_blacklist`` configuration option has been removed.
  Please use ``publisher_acl_blacklist`` instead.
- The ``win_gitrepos`` configuration option has been removed. Please use
  the ``winrepo_remotes`` option instead.
- The ``win_repo`` configuration option has been removed. Please use
  ``winrepo_dir`` instead.
- The ``win_repo_mastercachefile`` configuration option has been removed.
  Please use the ``winrepo_cachefile`` option instead.

Module Deprecations
-------------------

The ``git`` execution module had the following changes:

- The ``fmt`` argument was removed from the ``archive`` function. Please
  use ``format`` instead.
- The ``repository`` argument was removed from the ``clone`` function.
  Please use ``url`` instead.
- The ``is_global`` argument was removed from the ``config_set`` function.
  Please use ``global`` instead.
- The ``branch`` argument was removed from the ``merge`` function. Please
  use ``rev`` instead.
- The ``branch`` argument was removed from the ``push`` function. Please
  use ``rev`` instead.

The ``glusterfs`` execution module had the following functions removed:

- ``create``: Please use ``create_volume`` instead.
- ``delete``: Please use ``delete_volume`` instead.
-  ``list_peers``: Please use ``peer_status`` instead.

The ``htpasswd`` execution module had the following function removed:

- ``useradd_all``: Please use ``useradd`` instead.

The ``img`` execution module has been removed. All of its associated functions
were marked for removal in the Nitrogen release. The functions removed in this
module are mapped as follows:

- ``mount_image``/``mnt_image``: Please use ``mount.mount`` instead.
- ``umount_image``: Please use ``mount.umount`` instead.
- ``bootstrap``: Please use ``genesis.bootstrap`` instead.

The ``smartos_virt`` execution module had the following functions removed:

- ``create``: Please use ``start`` instead.
- ``destroy`` Please use ``stop`` instead.
- ``list_vms``: Please use ``list_domains`` instead.

The ``virt`` execution module had the following functions removed:

- ``create``: Please use ``start`` instead.
- ``destroy`` Please use ``stop`` instead.
- ``list_vms``: Please use ``list_domains`` instead.

The ``virtualenv_mod`` execution module had the following changes:

- The ``package_or_requirement`` argument was removed from both the
  ``get_resource_path`` and the ``get_resource_content`` functions.
  Please use ``package`` instead.
- The ``resource_name`` argument was removed from both the
  ``get_resource_path`` and ``get_resource_content`` functions.
  Please use ``resource`` instead.

The ``win_repo`` execution module had the following changes:

- The ``win_repo_source_dir`` option was removed from the ``win_repo``
  module. Please use ``winrepo_source_dir`` instead.

The ``xapi`` execution module had the following functions removed:

- ``create``: Please use ``start`` instead.
- ``destroy``: Please use ``stop`` instead.
- ``list_vms``: Please use ``list_domains`` instead.

The ``zypper`` execution module had the following function removed:

- ``info``: Please use ``info_available`` instead.

Pillar Deprecations
-------------------

- Support for the ``raw_data`` argument for the file_tree ext_pillar has been
  removed. Please use ``keep_newline`` instead.
- SQLite3 database connection configuration previously had keys under
  pillar. This legacy compatibility has been removed.

Proxy Minion Deprecations
-------------------------

- The ``proxy_merge_grains_in_module`` default has been switched from
  ``False`` to ``True``.

Salt-API Deprecations
---------------------

- The ``SaltAPI.run()`` function has been removed. Please use the
  ``SaltAPI.start()`` function instead.

Salt-Cloud Deprecations
-----------------------

- Support for using the keyword ``provider`` in salt-cloud provider config
  files has been removed. Please use ``driver`` instead. The ``provider``
  keyword should now only be used in cloud profile config files.

Salt-SSH Deprecations
---------------------

- The ``wipe_ssh`` option for ``salt-ssh`` has been removed. Please use the
  ``ssh_wipe`` option instead.

State Deprecations
------------------

The ``apache_conf`` state had the following functions removed:

  - ``disable``: Please use ``disabled`` instead.
  - ``enable``: Please use ``enabled`` instead.

The ``apache_module`` state had the following functions removed:

  - ``disable``: Please use ``disabled`` instead.
  - ``enable``: Please use ``enabled`` instead.

The ``apache_site`` state had the following functions removed:

  - ``disable``: Please use ``disabled`` instead.
  - ``enable``: Please use ``enabled`` instead.

The ``chocolatey`` state had the following functions removed:

  - ``install``: Please use ``installed`` instead.
  - ``uninstall``: Please use ``uninstalled`` instead.

The ``git`` state had the following changes:

  - The ``config`` function was removed. Please use ``config_set`` instead.
  - The ``is_global`` option was removed from the ``config_set`` function.
    Please use ``global`` instead.
  - The ``always_fetch`` option was removed from the ``latest`` function, as
    it no longer has any effect. Please see the :ref:`2015.8.0<release-2015-8-0>`
    release notes for more information.
  - The ``force`` option was removed from the ``latest`` function. Please
    use ``force_clone`` instead.
  - The ``remote_name`` option was removed from the ``latest`` function.
    Please use ``remote`` instead.

The ``glusterfs`` state had the following function removed:

  - ``created``: Please use ``volume_present`` instead.

The ``openvswitch_port`` state had the following change:

  - The ``type`` option was removed from the ``present`` function. Please use ``tunnel_type`` instead.