Imported Upstream version 1.8.7

[debian/sudo] / doc / UPGRADE

Notes on upgrading from an older release
========================================

o Upgrading from a version prior to 1.8.7:

    Sudo now stores its libexec files in a "sudo" sub-directory
    instead of in libexec itself.  For backwards compatibility, if
    the plugin is not found in the default plugin directory, sudo
    will check the parent directory default directory ends in "/sudo".

    The default sudo plugins now all use the .so extension, regardless
    of the extension used by native shared libraries.  For backwards
    compatibility, sudo on HP-UX will also search for a plugin with
    an .sl extension if the .so version is not found.

    Handling of users belonging to a large number of groups has
    changed.  Previously, sudo would only use the group list from
    the kernel unless the system_group plugin was enabled in sudoers.
    Now, sudo will query the groups database if the user belongs
    to the maximum number of groups supported by the kernel.  See
    the group_source and max_groups settings in the sudo.conf manual
    for details.

o Upgrading from a version prior to 1.8.2:

    When matching Unix groups in the sudoers file, sudo will now
    match based on the name of the group as it appears in sudoers
    instead of the group ID.  This can substantially reduce the
    number of group lookups for sudoers files that contain a large
    number of groups.  There are a few side effects of this change.

    1) Unix groups with different names but the same group ID are
       can no longer be used interchangeably.  Sudo will look up all
       of a user's groups by group ID and use the resulting group
       names when matching sudoers entries.  If there are multiple
       groups with the same ID, the group name returned by the
       system getgrgid() library function is the name that will be
       used when matching sudoers entries.

    2) Unix group names specified in the sudoers file that are
       longer than the system maximum will no longer match.  For
       instance, if there is a Unix group "fireflie" on a system
       where group names are limited to eight characters, "%fireflies"
       in sudoers will no longer match "fireflie".  Previously, a
       lookup by name of the group "fireflies" would have matched
       the "fireflie" group on most systems.

o Upgrading from a version prior to 1.8.1:

    Changes in the sudoers parser could result in parse errors for
    existing sudoers file.  These changes cause certain erroneous
    entries to be flagged as errors where before they allowed.
    Changes include:

    Combining multiple Defaults entries with a backslash.  E.g.

        Defaults set_path \
        Defaults syslog

    which should be:

        Defaults set_path
        Defaults syslog

    Also, double-quoted strings with a missing end-quote are now
    detected and result in an error.  Previously, text starting a
    double quote and ending with a newline was ignored.  E.g.

        Defaults set_path"foo

    In previous versions of sudo, the `"foo' portion would have
    been ignored.

    To avoid problems, sudo 1.8.1's "make install" will not install
    a new sudo binary if the existing sudoers file has errors.

    In Sudo 1.8.1 the "noexec" functionality has moved out of the
    sudoers policy plugin and into the sudo front-end.  As a result,
    the path to the noexec file is now specified in the sudo.conf
    file instead of the sudoers file.  If you have a sudoers file
    that uses the "noexec_file" option, you will need to move the
    definition to the sudo.conf file instead.

    Old style in /etc/sudoers:
        Defaults noexec_file=/usr/local/libexec/sudo_noexec.so

    New style in /etc/sudo.conf:
        Path noexec /usr/local/libexec/sudo_noexec.so

o Upgrading from a version prior to 1.8.0:

    Starting with version 1.8.0, sudo uses a modular framework to
    support policy and I/O logging plugins.  The default policy
    plugin is "sudoers" which provides the traditional sudoers
    evaluation and I/O logging.  Plugins are typically located in
    /usr/libexec or /usr/local/libexec, though this is system-dependent.
    The sudoers plugin is named "sudoers.so" on most systems.

    The sudo.conf file, usually stored in /etc, is used to configure
    plugins.  This file is optional--if no plugins are specified
    in sudo.conf, the "sudoers" plugin is used.  See the sample.sudo.conf
    file in the doc directory or refer to the updated sudo manual
    to see how to configure sudo.conf.

    The "askpass" setting has moved from the sudoers file to the
    sudo.conf file.  If you have a sudoers file that uses the
    "askpass" option, you will need to move the definition to the
    sudo.conf file.

    Old style in /etc/sudoers:
        Defaults askpass=/usr/X11R6/bin/ssh-askpass

    New style in /etc/sudo.conf:
        Path askpass /usr/X11R6/bin/ssh-askpass

o Upgrading from a version prior to 1.7.5:

    Sudo 1.7.5 includes an updated LDAP schema with support for
    the sudoNotBefore, sudoNotAfter and sudoOrder attributes.

    The sudoNotBefore and sudoNotAfter attribute support is only
    used when the SUDOERS_TIMED setting is enabled in ldap.conf.
    If enabled, those attributes are used directly when constructing
    an LDAP filter.  As a result, your LDAP server must have the
    updated schema if you want to use sudoNotBefore and sudoNotAfter.

    The sudoOrder support does not affect the LDAP filter sudo
    constructs and so there is no need to explicitly enable it in
    ldap.conf.  If the sudoOrder attribute is not present in an
    entry, a value of 0 is used.  If no entries contain sudoOrder
    attributes, the results are in whatever order the LDAP server
    returns them, as in past versions of sudo.

    Older versions of sudo will simply ignore the new attributes
    if they are present in an entry.  There are no compatibility
    problems using the updated schema with older versions of sudo.

o Upgrading from a version prior to 1.7.4:

    Starting with sudo 1.7.4, the time stamp files have moved from
    /var/run/sudo to either /var/db/sudo, /var/lib/sudo or /var/adm/sudo.
    The directories are checked for existence in that order.  This
    prevents users from receiving the sudo lecture every time the
    system reboots.  Time stamp files older than the boot time are
    ignored on systems where it is possible to determine this.

    Additionally, the tty_tickets sudoers option is now enabled by
    default.  To restore the old behavior (single time stamp per user),
    add a line like:
        Defaults !tty_tickets
    to sudoers or use the --without-tty-tickets configure option.

    The HOME and MAIL environment variables are now reset based on the
    target user's password database entry when the env_reset sudoers option
    is enabled (which is the case in the default configuration).  Users
    wishing to preserve the original values should use a sudoers entry like:
        Defaults env_keep += HOME
    to preserve the old value of HOME and
        Defaults env_keep += MAIL
    to preserve the old value of MAIL.

    NOTE: preserving HOME has security implications since many programs
    use it when searching for configuration files.  Adding HOME to env_keep
    may enable a user to run unrestricted commands via sudo.

    The default syslog facility has changed from "local2" to "authpriv"
    (or "auth" if the operating system doesn't have "authpriv").
    The --with-logfac configure option can be used to change this
    or it can be changed in the sudoers file.

o Upgrading from a version prior to 1.7.0:

    Starting with sudo 1.7.0, comments in the sudoers file must not
    have a digit or minus sign immediately after the comment character
    ('#').  Otherwise, the comment may be interpreted as a user or
    group ID.

    When sudo is build with LDAP support the /etc/nsswitch.conf file is
    now used to determine the sudoers sea ch order.  sudo will default to
    only using /etc/sudoers unless /etc/nsswitch.conf says otherwise.
    This can be changed with an nsswitch.conf line, e.g.:
        sudoers:        ldap files
    Would case LDAP to be searched first, then the sudoers file.
    To restore the pre-1.7.0 behavior, run configure with the
    --with-nsswitch=no flag.

    Sudo now ignores user .ldaprc files as well as system LDAP defaults.
    All LDAP configuration is now in /etc/ldap.conf (or whichever file
    was specified by configure's --with-ldap-conf-file option).
    If you are using TLS, you may now need to specify:
        tls_checkpeer no
    in sudo's ldap.conf unless ldap.conf references a valid certificate
    authority file(s).

    Please also see the NEWS file for a list of new features in
    sudo 1.7.0.

o Upgrading from a version prior to 1.6.9:

    Starting with sudo 1.6.9, if an OS supports a modular authentication
    method such as PAM, it will be used by default by configure.

    Environment variable handling has changed significantly in sudo
    1.6.9.  Prior to version 1.6.9, sudo would preserve the user's
    environment, pruning out potentially dangerous variables.
    Beginning with sudo 1.6.9, the environment is reset to a default
    set of values with only a small number of "safe" variables
    preserved.  To preserve specific environment variables, add
    them to the "env_keep" list in sudoers.  E.g.

        Defaults env_keep += "EDITOR"

    The old behavior can be restored by negating the "env_reset"
    option in sudoers.  E.g.

        Defaults !env_reset

    There have  also been changes to how the "env_keep" and
    "env_check" options behave.

    Prior to sudo 1.6.9, the TERM and PATH environment variables
    would always be preserved even if the env_keep option was
    redefined.  That is no longer the case.  Consequently, if
    env_keep is set with "=" and not simply appended to (i.e. using
    "+="), PATH and TERM must be explicitly included in the list
    of environment variables to keep.  The LOGNAME, SHELL, USER,
    and USERNAME environment variables are still always set.

    Additionally, the env_check setting previously had no effect
    when env_reset was set (which is now on by default).  Starting
    with sudo 1.6.9, environment variables listed in env_check are
    also preserved in the env_reset case, provided that they do not
    contain a '/' or '%' character.  Note that it is not necessary
    to also list a variable in env_keep--having it in env_check is
    sufficient.

    The default lists of variables to be preserved and/or checked
    are displayed when sudo is run by root with the -V flag.

o Upgrading from a version prior to 1.6.8:

    Prior to sudo 1.6.8, if /var/run did not exist, sudo would put
    the time stamp files in /tmp/.odus.  As of sudo 1.6.8, the
    time stamp files will be placed in /var/adm/sudo or /usr/adm/sudo
    if there is no /var/run directory.  This directory will be
    created if it does not already exist.

    Previously, a sudoers entry that explicitly prohibited running
    a command as a certain user did not override a previous entry
    allowing the same command.  This has been fixed in sudo 1.6.8
    such that the last match is now used (as it is documented).
    Hopefully no one was depending on the previous (buggy) behavior.

o Upgrading from a version prior to 1.6:

    As of sudo 1.6, parsing of runas entries and the NOPASSWD tag
    has changed.  Prior to 1.6, a runas specifier applied only to
    a single command directly following it.  Likewise, the NOPASSWD
    tag only allowed the command directly following it to be run
    without a password.  Starting with sudo 1.6, both the runas
    specifier and the NOPASSWD tag are "sticky" for an entire
    command list.  So, given the following line in sudo < 1.6

        millert ALL=(daemon) NOPASSWD:/usr/bin/whoami,/bin/ls

    millert would be able to run /usr/bin/whoami as user daemon
    without a password and /bin/ls as root with a password.

    As of sudo 1.6, the same line now means that millert is able
    to run run both /usr/bin/whoami and /bin/ls as user daemon
    without a password.  To expand on this, take the following
    example:

        millert ALL=(daemon) NOPASSWD:/usr/bin/whoami, (root) /bin/ls, \
            /sbin/dump

    millert can run /usr/bin/whoami as daemon and /bin/ls and
    /sbin/dump as root.  No password need be given for either
    command.  In other words, the "(root)" sets the default runas
    user to root for the rest of the list.  If we wanted to require
    a password for /bin/ls and /sbin/dump the line could be written
    as:

        millert ALL=(daemon) NOPASSWD:/usr/bin/whoami, \
            (root) PASSWD:/bin/ls, /sbin/dump

    Additionally, sudo now uses a per-user time stamp directory
    instead of a time stamp file.  This allows tty time stamps to
    simply be files within the user's time stamp dir.  For the
    default, non-tty case, the time stamp on the directory itself
    is used.

    Also, the temporary file used by visudo is now /etc/sudoers.tmp
    since some versions of vipw on systems with shadow passwords use
    /etc/stmp for the temporary shadow file.

o Upgrading from a version prior to 1.5:

    By default, sudo expects the sudoers file to be mode 0440 and
    to be owned by user and group 0.  This differs from version 1.4
    and below which expected the sudoers file to be mode 0400 and
    to be owned by root.  Doing a `make install' will set the sudoers
    file to the new mode and group.  If sudo encounters a sudoers
    file with the old permissions it will attempt to update it to
    the new scheme.  You cannot, however, use a sudoers file with
    the new permissions with an old sudo binary.  It is suggested
    that if have a means of distributing sudo you distribute the
    new binaries first, then the new sudoers file (or you can leave
    sudoers as is and sudo will fix the permissions itself as long
    as sudoers is on a local file system).