= Windows installer logic for version 6 =

[[T(VersionSix)]]

Major differences from version 5 are:
 * Account-based sandboxing using unprivileged accounts.
 * Moves the BOINC data directory if needed.
 * BOINC executables are in a separate directory.
 * Simplified installer user experience.

[[PageOutline]]

== Protection policy ==

The installer has a "Allow all users on this computer to control BOINC" checkbox.
If checked, then all users on the host will be able control BOINC (i.e. attach/detach projects) using the BOINC Manager.
Otherwise only the user who installed BOINC or an administrator can control BOINC.

When BOINC Manager cannot access the gui_rpc_auth.cfg file, it'll display a dialog stating that the user does not currently 
have access to BOINC and to contact the administrator to add them to the 'boinc_users' group.

== Sandboxing ==

The installer offers two modes: 'Graphics compatible' and 'Secure'.

Graphics compatible installation is the same as the single-user installation of v5.
The manager will be responsible for launching the core client, and all applications will be launched in the same security context as the user who logged into the system.
This allows users to see graphics from older as well as newer science applications,
or projects with long running tasks which won't complete for a while.

If the user selects Secure,
the core client will run as a service.
Two user accounts and two groups will be created:

=== Users: ===

 boinc_master:: The core client runs under this account.
 boinc_project:: Apps and graphics app run under this account.

If the computer being installed upon is a domain controller,
then the account names will have the computer name appended on to them.

=== Groups: ===

 boinc_admins:: Members of this group can change the configuration and protection settings for the BOINC client (for example the GUI RPC password and host list) and can also run the BOINC Manager and screensaver.
 boinc_users:: Members of this group can run the BOINC Manager and screensaver.

Initially, each group contains the following members:

|| boinc_admins  || Administrator [[BR]] <Installing User> [[BR]] 'boinc_master' ||
|| boinc_users || Everyone (if 'Allow everyone to use BOINC' is checked), else empty ||
|| boinc_projects || 'boinc_project' ||

Account passwords are managed as follows:
 * The installer creates a file 'client_auth.xml' in the BOINC data directory containing the name and base64 encoded password of the boinc_project account.
 * The password properties are added to !SecureCustomProperties to prevent them being logged.
 * The password for boinc_master is managed by Windows.

On each installation, both of the account passwords are randomly regenerated.

=== User Rights Assignment ===

||boinc_master||Deny logon locally [[BR]] Deny access to this computer from the network [[BR]] Debug programs [[BR]] Log on as a service [[BR]] Bypass traverse checking||
||boinc_project||Deny logon locally [[BR]] Deny access to this computer from the network||

== Data directory ==

All data, configuration files, and logs will be moved to the following default location:
{{{
Vista:
C:\Users\All Users\BOINC

2000/XP:
C:\Documents and Settings\All Users\Application Data\BOINC
}}}

Under the data directory there will be 'projects' and 'slots' directories.

Directories will have the following permissions:

|| BOINC          || SYSTEM (Full Control) [[BR]] Administrators (Full Control) [[BR]] boinc_admins (Modify, Read & Execute, List Folder Contents, Read, Write) [[BR]] boinc_users (Read & Execute, List Folder Contents, Read) [[BR]] boinc_projects (Deny All) ||
|| BOINC\projects || SYSTEM (Full Control) [[BR]] Administrators (Full Control) [[BR]] boinc_admins (Modify, Read & Execute, List Folder Contents, Read, Write) [[BR]] boinc_users (Read & Execute, List Folder Contents, Read) [[BR]] boinc_projects (Modify, Read & Execute, List Folder Contents, Read, Write) ||
|| BOINC\slots    || SYSTEM (Full Control) [[BR]] Administrators (Full Control) [[BR]] boinc_admins (Modify, Read & Execute, List Folder Contents, Read, Write) [[BR]] boinc_users (Read & Execute, List Folder Contents, Read) [[BR]] boinc_projects (Modify, Read & Execute, List Folder Contents, Read, Write) ||

== Executables directory ==

Same default location as previous versions, C:\Program Files\BOINC

Directory will have the following permissions:

|| BOINC          || SYSTEM (Full Control) [[BR]] Administrators (Full Control) [[BR]] boinc_admins (Modify, Read & Execute, List Folder Contents, Read, Write) [[BR]] boinc_users (Read & Execute, List Folder Contents, Read) [[BR]] boinc_projects (Deny All) ||

== User Interface ==

=== Welcome Screen ===

Same as before.

=== License Screen ===

Same as before.

=== Configuration Screen ===

{{{
title: Installation options
subtitle: These are the current installation options

Program directory:  C:\\Program Files\BOINC\
Data directory: C:\\Documents and Settings\All Users\Application Data\ BOINC\

Use BOINC screensaver
Protected application execution
Allow all users on this computer to control BOINC


Click Next to use these options.
Click Advanced to customize options.
[Advanced] [Next]
}}}

Advanced goes to the advanced configuration page.
Next goes to the Confirmation screen.

=== Advanced Configuration ===

{{{
title: Customize installation options
subtitle: Customize how BOINC is installed on your computer

Program directory: [...] [Browse]
Data directory: [...] [Browse]

[ ] Use BOINC Screensaver
[X] Protected application execution.
    This provides increased protection against faulty project applications.
    However, it may cause screensaver graphics to not work with older applications.
[X] Allow all users on this computer to control BOINC
[Next]
}}}

Checkboxes labeled as [X] are enabled by default, otherwse they are disabled.
If any values are present from previous install, use them.
The "Allow users" checkbox is disabled unless the "Protected" checkbox is set.

'Next' goes to 'Confimation' screen.

=== Confirmation Screen ===

Same as before.

== Custom Actions ==

Custom actions are executed in the following sequence:
{{{
    ... MSI: Validates installation package
    ...
    CAValidateSetup
    CAShutdownBOINC
    CAShutdownBOINCManager
    CAShutdownBOINCManager95
    CAShutdownBOINCScreensaver
    ...
    ... MSI: Remove older version if it exists
    ...
    CACleanupOldBinaries
    CAMigratex86x64
    CAMigrateCPDNBBC
    CACreateBOINCAccounts (New in Version 6.0)
    CACreateBOINCGroups (New in Version 6.0)
    CAMigrateBOINCData (New in Version 6.0)
    ...
    ... MSI: Begin installation process
}}}

=== CAValidateSetup ===

Checks that the parameters passed into the installation program are valid for the installation type. Otherwise it reports an error to the user. This is a backup check for validating the parameters passed in via the command line, if the user is installing via the GUI this shouldn't ever be a problem.

{{{
IF SetupType == 'Single-User' THEN
    IF ALLUSERS == 1 THEN
        ABORT
    END IF
    IF SERVICE* IS NOT NULL THEN
        ABORT
    END IF
ELSE
    IF SERVICE* IS NULL THEN
        ABORT
    END IF
END IF
}}}

=== CAShutdownBOINC ===

Kills boinc.exe if it is currently executing on the system.

{{{
TerminateProcessByName("boinc.exe")
}}}

=== CAShutdownBOINCManager ===

Kills boincmgr.exe if it is currently executing on the system.

{{{
TerminateProcessByName("boincmgr.exe")
}}}

=== CAShutdownBOINCManager95 ===

Kills boincmgr.exe if it is currently executing on the system using Win9x compatible means.

{{{
TerminateProcessByName95("boincmgr.exe")
}}}

=== CAShutdownBOINCScreensaver ===

Kills boinc.scr if it is currently executing on the system.

{{{
TerminateProcessByName95("boinc.scr")
}}}

=== CACleanupOldBinaries ===

Deletes any lingering files left over from a previous BOINC installation.
This can sometimes happen if a user replaces a stock client with a optimized one.

{{{
DeleteFile(strInstallDirectory + _T("\\boinc.exe"));
DeleteFile(strInstallDirectory + _T("\\boincmgr.exe"));
DeleteFile(strInstallDirectory + _T("\\boinccmd.exe"));
DeleteFile(strInstallDirectory + _T("\\boinc.dll"));
DeleteFile(strInstallDirectory + _T("\\libcurl.dll"));
DeleteFile(strInstallDirectory + _T("\\libeay32.dll"));
DeleteFile(strInstallDirectory + _T("\\ssleay32.dll"));
DeleteFile(strInstallDirectory + _T("\\zlib1.dll"));
DeleteFile(strInstallDirectory + _T("\\dbghelp.dll"));
DeleteFile(strInstallDirectory + _T("\\dbghelp95.dll"));
DeleteFile(strInstallDirectory + _T("\\srcsrv.dll"));
DeleteFile(strInstallDirectory + _T("\\symsrv.dll"));
}}}

=== CAMigratex86x64 ===

Migrate any data files from "C:\Program Files (x86)\BOINC" to "C:\Program Files\BOINC" if "C:\Program Files\BOINC" doesn't already exist.
This handles the case where the user is upgrading from a 32-bit BOINC
to a 64-bit BOINC on Win64.

{{{
MoveFileEx("C:\\Program Files (x86)\\BOINC", strInstallDirectory, MOVEFILE_COPY_ALLOWED|MOVEFILE_WRITE_THROUGH);
}}}

=== CAMigrateCPDNBBC ===

Migrate any data files from "C:\Program Files\Climate Change Experiment" to "C:\Program Files\BOINC" if "C:\Program Files\BOINC" doesn't already exist.
Handles case where user is upgrading from BBC to V6.

{{{
MoveFileEx("C:\\Program Files\\Climate Change Experiment", strInstallDirectory, MOVEFILE_COPY_ALLOWED|MOVEFILE_WRITE_THROUGH);
}}}

=== CACreateBOINCAccounts ===

Creates the two user accounts used for a protected installation.  Passwords are base64 encoded before being stored to disk.

{{{

strComputerName = GetComputerName()
bIsDomainController = IsDomainController()

GetProperty("BOINC_USERNAME", strBOINCUsername)
GetProperty("BOINC_PROJECT_USERNAME", strBOINCProjectUsername)

IF bIsDomainController THEN
    IF strBOINCUsername IS NULL THEN
        strBOINCUsername = "boinc_" + strComputerName
    END IF
    IF strBOINCProjectUsername IS NULL THEN
        strBOINCProjectUsername = "boinc_project_" + strComputerName
    END IF
ELSE
    IF strBOINCUsername IS NULL THEN
        strBOINCUsername = "boinc"
    END IF
    IF strBOINCProjectUsername IS NULL THEN
        strBOINCProjectUsername = "boinc_project"
    END IF
END IF

strBOINCAccountPassword = GenerateNewPassword()
strBOINCProjectAccountPassword = GenerateNewPassword()

IF GetUserAccount(strBOINCUsername) EXISTS THEN
    ResetUserAccountPassword(strBOINCUsername, strBOINCAccountPassword);
ELSE
    CreateUserAccount(strBOINCUsername, strBOINCAccountPassword)
    SetUserAccountProperty(strBOINCUsername, "PasswordNeverExpires")
END IF
    
IF GetUserAccount(strBOINCProjectUsername) EXISTS THEN
    ResetUserAccountPasswordstrBOINCProjectUsername, strBOINCProjectAccountPassword);
ELSE
    CreateUserAccount(strBOINCProjectUsername, strBOINCProjectAccountPassword)
    SetUserAccountProperty(strBOINCProjectUsername, "PasswordNeverExpires")
END IF

WriteAccountsToDisk(strBOINCUsername, strBOINCAccountPassword, strBOINCProjectUsername, strBOINCProjectAccountPassword)
}}}

=== CACreateBOINCGroups ===

Creates the two security groups that BOINC will need to complete a secure installation.

{{{

strComputerName = GetComputerName()
bIsDomainController = IsDomainController()

GetProperty("BOINC_USERNAME", strBOINCUsername)
GetProperty("BOINC_PROJECT_USERNAME", strBOINCProjectUsername)

IF bIsDomainController THEN
    IF strBOINCUsername IS NULL THEN
        strBOINCUsername = "boinc_" + strComputerName
    END IF
    IF strBOINCProjectUsername IS NULL THEN
        strBOINCProjectUsername = "boinc_project_" + strComputerName
    END IF
ELSE
    IF strBOINCUsername IS NULL THEN
        strBOINCUsername = "boinc"
    END IF
    IF strBOINCProjectUsername IS NULL THEN
        strBOINCProjectUsername = "boinc_project"
    END IF
END IF

IF GetGroup("boinc_admins") NOT EXISTS THEN
    CreateGroup("boinc_administrators")
    AddUserToGroup("Administrator")
    AddUserToGroup(GetCurrentUsername())
    AddUserToGroup(strBOINCUsername)
END IF
    
IF GetGroup("boinc_project") NOT EXISTS THEN
    CreateGroup("boinc_project")
    AddUserToGroup(strBOINCProjectUsername)
END IF

}}}

=== CAMigrateBOINCData ===

Look in the registry for the old data directory, else "C:\Program Files\BOINC".
Move data files from old data dir to all users application data location if the all users application data location doesn't already exist.

{{{
old_data_dir = registry_lookup
MoveFileEx(old_data_dir, strDataDirectory, MOVEFILE_COPY_ALLOWED|MOVEFILE_WRITE_THROUGH);
}}}

== Reverting to a pre-V6 version of BOINC ==

Manually move data dir contents to executables dir, then install old version.

Manually remove BOINC-related accounts and groups.
Note: we can't remove them automatically on uninstall,
otherwise they'd get removed and recreated on each upgrade,
and any group membership changes would be lost.

== Design Decisions ==

 * Why install as a service instead of a single user install?

Service installs allow for the boinc core client to be isolated from any users files. Since the core client has the only available incoming TCP/IP connection it is at risk of being hacked, to mitigate information disclosure of sensitive user files such as MS Money or Quicken files the core client is executed with its own user account.

By default non-administrative accounts cannot create globally named shared memory segments, therefore keyboard and mouse activity could not be monitored without setting up an account with that additional user right. 

 * Launching worker and graphics applications as boinc_project.

Isolate BOINC-based applications from BOINC and the rest of the system.

 * Why was the 'Launch BOINC on startup' option removed from the installer?

The 'Launch BOINC on startup' option actually started the BOINC Manager, so on systems where BOINC was being installed as a service it was being ignored. Most people do not understand the difference between BOINC and the BOINC Manager. Most people who install BOINC want it to run whenever they are not around.

To keep things simple we decided to remove the option and setup the system so that both BOINC and the BOINC Manager are started at system startup or logon, if the users want to change this behaviour they can delete the BOINC Manager shortcut and/or change the service properties via the service control manager administrative tool.