# 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 required | Access data of all users accounts
Power | Power User privileges are required (Power Users no longer exist in Windows Vista. For Vista this is equivalent to Admin) | Installation for all users (writing to "Program Files" or HKLM registry keys), driver installation
Highest | Request the highest possible execution level for the current user | Mixed-mode installer that can both be installed per-machine or per-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
MULTIUSER_INIT_TEXT_ADMINREQUIRED | Error message to be displayed when administrator rights are required but not available.
MULTIUSER_INIT_TEXT_POWERREQUIRED | Error message to be displayed when Power User rights are required but not available.
MULTIUSER_INIT_TEXT_ALLUSERSNOTPOSSIBLE | Error message to be displayed when administrator or Power User rights are required because of an installation mode setting on the command line (see below) but are not available.
MULTIUSER_USE_PROGRAMFILES64 | Use $PROGRAMFILES64 instead of $PROGRAMFILES as the default all users directory.
MULTIUSER_INIT_FUNCTIONQUIT MULTIUSER_INIT_UNFUNCTIONQUIT | A custom function to be called when the 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_CURRENTUSER | Set default to a per-user installation, even if the rights for a per-machine installation are available.
MULTIUSER_INSTALLMODE_DEFAULT_REGISTRY_KEY MULTIUSER_INSTALLMODE_DEFAULT_REGISTRY_VALUENAME | Non-empty registry key that is created during the installation in either HKCU or HKLM. The default installation mode 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_CURRENTUSER | Text to display on the radio button for 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
MULTIUSER_INSTALLMODE_INSTDIR | Name of the folder in which to install the application, without a path. This 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 MULTIUSER_INSTALLMODE_INSTDIR_REGISTRY_VALUENAME | Registry key from which to obtain a previously stored installation folder. It will be retrieved from HKCU for per-user and HKLM for per-machine.
MULTIUSER_INSTALLMODE_FUNCTION MULTIUSER_INSTALLMODE_UNFUNCTION | A custom function to be called during the initialization of the installation mode 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