

Multi-User Header File (MultiUser.nsh)

Installer configuration for multi-user Windows environments

Table of Contents


* Introduction
* Initialization_and_Execution_Level
* Installation_Mode
* Example


Introduction

Modern Windows versions support multiple users accounts on a single computer,
each with different privileges. For security reasons, the privileges of
applications can also be limited. For an installer, the execution level and
installation mode are important. The execution level determines the privileges
of the installer application. For example, to install hardware drivers,
administrator privileges are required. Applications can also be installed for a
single user or for all users on a computer, which is determined by the
installation mode. Installation for all users requires a higher execution level
as compared with a single user setup. The MultiUser.nsh header files provides
the features to automatically handle all these aspects related to user accounts
and installer privileges.
Note that all settings need to be set before including the MultiUser.nsh header
file.

Initialization and Execution Level 

Before the MultiUser.nsh file is included, the MULTIUSER_EXECUTIONLEVEL define
should be set to one of the following values depending on the execution level
that is required:

Value    Description                        Typical application
Admin    Administrator privileges are       Access data of all users accounts
         required
         Power User privileges are required Installation for all users (writing
Power    (Power Users no longer exist in    to "Program Files" or HKLM registry
         Windows Vista. For Vista this is   keys), driver installation
         equivalent to Admin)
         Request the highest possible       Mixed-mode installer that can both
Highest  execution level for the current    be installed per-machine or per-
         user                               user
Standard No special rights required         Installation for current user only

Insert the MULTIUSER_INIT and MULTIUSER_UNINT macros in the .onInit and
un.onInit function to verify these privileges. If no uninstaller is created in
the script, define MULTIUSER_NOUNINSTALL.

  !define MULTIUSER_EXECUTIONLEVEL Highest
  ;!define MULTIUSER_NOUNINSTALL ;Uncomment if no uninstaller is created
  !include MultiUser.nsh

  ...

  Function .onInit
    !insertmacro MULTIUSER_INIT
  FunctionEnd

  Function un.onInit
    !insertmacro MULTIUSER_UNINIT
  FunctionEnd

Whether the required privileges can be obtained depends on the user that starts
the installer:

* Windows NT 4/2000/XP/2003 give the installer the same privileges as the user
  itself. If the privileges of the user are not sufficient (e.g. Admin level is
  required is set but the user has no administrator rights), the macros will
  display an error message and quit the installer. If is however possible to
  manually run the installer with an administrator account.
* Windows Vista restricts the privileges of all applications by default.
  Depending on requested execution level, MultiUser.nsh will set the
  RequestExecutionLevel flag to request privileges. The user will be asked for
  confirmation and (if necessary) for an administrator password.
* Windows 95/98/98 do not set any restrictions on users or applications.
  Administrator rights are always available.

It is recommended to insert these initialization macros before macros that
require user intervention. For example, it does not make sense to ask a user
for an installer language if the installer will quit afterwards because the
user account does not have the required privileges. After the macros are
inserted, the variable $MultiUser.Privileges will contain the current execution
level (Admin, Power, User or Guest).
The following additional settings are available to customize the
initialization:

Setting                                 Description
                                        Error message to be displayed when
MULTIUSER_INIT_TEXT_ADMINREQUIRED       administrator rights are required but
                                        not available.
                                        Error message to be displayed when
MULTIUSER_INIT_TEXT_POWERREQUIRED       Power User rights are required but not
                                        available.
                                        Error message to be displayed when
                                        administrator or Power User rights are
MULTIUSER_INIT_TEXT_ALLUSERSNOTPOSSIBLE required because of an installation
                                        mode setting on the command line (see
                                        below) but are not available.
                                        Use $PROGRAMFILES64 instead of
MULTIUSER_USE_PROGRAMFILES64            $PROGRAMFILES as the default all users
                                        directory.
MULTIUSER_INIT_FUNCTIONQUIT             A custom function to be called when the
MULTIUSER_INIT_UNFUNCTIONQUIT           installer is closed due to insufficient
                                        privileges.


Installation Mode

As mentioned before, applications can both be installed for a single users or
for all users on a computer. Applications for all users are typically installed
in the Program Files folder and appear in the Start Menu of every user. On the
contrary, applications for a single user are usually installed in the local
Application Data folder and only a appear in the Start Menu of the user who
installed the application.
By default, MultiUser.nsh will set the installation mode for a per-machine
installation if Administrator or Power User rights are available (this is
always the case if the execution level is set to Admin or Power, if Highest is
set it depends on the user account). For the Standard execution level the
installation will always be for a single user. On Windows 95/98/Me installation
for a single user is not possible, a per-machine installation will be
performed.
The following settings are available to change the default installation mode:

Setting                                 Description
MULTIUSER_INSTALLMODE_DEFAULT_          Set default to a per-user installation,
CURRENTUSER                             even if the rights for a per-machine
                                        installation are available.
                                        Non-empty registry key that is created
MULTIUSER_INSTALLMODE_DEFAULT_REGISTRY_ during the installation in either HKCU
KEY MULTIUSER_INSTALLMODE_DEFAULT_      or HKLM. The default installation mode
REGISTRY_VALUENAME                      will automatically be set to the
                                        previously selected mode depending on
                                        the location of the key.

After initialization, the variable $MultiUser.InstallMode will contain the
current installation mode (AllUsers or CurrentUser).

Mixed-Mode Installation

For the Admin and Power levels, both a per-machine as well as a per-user
installation is possible. If the Highest level is set and the user is an
Administrator or Power User, both options are also available.
Usually it's a good thing to give the user to choice between these options. For
users of the Modern UI version 2, a page is provided that asks the user for the
installation mode. To use this page, define MULTIUSER_MUI before including
MultiUser.nsh. Then, the MULTIUSER_PAGE_INSTALLMODE macro can be used just like
a normal Modern UI page (this page will automatically be skipped when running
Windows 95/98/Me):

  !define MULTIUSER_EXECUTIONLEVEL Highest
  !define MULTIUSER_MUI
  !define MULTIUSER_INSTALLMODE_COMMANDLINE
  !include MultiUser.nsh
  !include MUI2.nsh

  !insertmacro MULTIUSER_PAGE_INSTALLMODE
  !insertmacro MUI_PAGE_DIRECTORY
  !insertmacro MUI_PAGE_INSTFILES

  !insertmacro MUI_LANGUAGE English

  ...

  Function .onInit
    !insertmacro MULTIUSER_INIT
  FunctionEnd

  Function un.onInit
    !insertmacro MULTIUSER_UNINIT
  FunctionEnd

The MULTIUSER_INSTALLMODE_COMMANDLINE setting that also appears in this example
enables the installation mode to be set using the /AllUsers or /CurrentUser
command line parameters. This is especially useful for silent setup.
The following settings can be used to customize the texts on the page (in
addition to the general Modern UI page settings):

Setting                                 Description
MULTIUSER_INSTALLMODEPAGE_TEXT_TOP      Text to display on the top of the page.
MULTIUSER_INSTALLMODEPAGE_TEXT_ALLUSERS Text to display on the radio button for
                                        a per-machine installation.
MULTIUSER_INSTALLMODEPAGE_TEXT_         Text to display on the radio button for
CURRENTUSER                             a per-user installation.
MULTIUSER_INSTALLMODEPAGE_SHOWUSERNAME  Append the username to the per-user
                                        radio button.


Installation Mode Initialization

The SetShellVarContext flag (which determines the folders for e.g. shortcuts,
like $DESKTOP) is automatically set depending on the installation mode. In
addition, the following settings can be used to perform additional actions when
the installation mode is initialized:

Setting                               Description
                                      Name of the folder in which to install
                                      the application, without a path. This
MULTIUSER_INSTALLMODE_INSTDIR         folder will be located in Program Files
                                      for a per-machine installation and in the
                                      local Application Data folder for a per-
                                      user installation (if supported).
MULTIUSER_INSTALLMODE_INSTDIR_        Registry key from which to obtain a
REGISTRY_KEY MULTIUSER_INSTALLMODE_   previously stored installation folder. It
INSTDIR_REGISTRY_VALUENAME            will be retrieved from HKCU for per-user
                                      and HKLM for per-machine.
                                      A custom function to be called during the
MULTIUSER_INSTALLMODE_FUNCTION        initialization of the installation mode
MULTIUSER_INSTALLMODE_UNFUNCTION      to set additional installer settings that
                                      depend on the mode

To set the installation mode manually, call one of these four functions:

Function name                        Installation mode
MultiUser.InstallMode.AllUsers       Installer: Per-machine installation
MultiUser.InstallMode.CurrentUser    Installer: Per-user installation
un.MultiUser.InstallMode.AllUsers    Uninstaller: Per-machine installation
un.MultiUser.InstallMode.CurrentUser Uninstaller: Per-user installation


Example

Basic: MultiUser.nsi
