Client setup logic for Windows

There are three install types supported by the 5.x generation of BOINC clients.

Single-User Install

Single user installs are the most basic and least prone to failure form of BOINC client installation.

It has the following properties:

File Layout:	Standard File Layout
File Permissions:	SYSTEM (Full Control) Administrators (Full Control) %USERNAME% (Full Control)
Launch Mechinism:	Shortcut to boincmgr.exe in the user's 'Startup' folder

Shared Install

Shared installs are geared towards computers who have multiple user accounts and fast user switching is enabled. The first person to login launches BOINC and all the science applications. If the first person logs out BOINC is shutdown.

It has the following properties:

File Layout:	Standard File Layout
File Permissions:	SYSTEM (Full Control) Administrators (Full Control) Users (Full Control)
Launch Mechinism:	Shortcut to boincmgr.exe in the all-users 'Startup' folder

Service-Mode Install

Service-Mode installs allows BOINC to run even when nobody is logged into the system. When Windows boots up, it'll launch BOINC. An existing user account must be specified to execute BOINC with at startup. This user account will be granted the 'Execute as a Service' user right during the installation process if it doesn't already have it.

It has the following properties:

File Layout:	Standard File Layout
File Permissions:	SYSTEM (Full Control) Administrators (Full Control) %SERVICE_USERNAME% (Full Control) %USERNAME% (Modify, Read & Execute, List Folder Contents, Read, Write)
Launch Mechinism:	Shortcut to boincmgr.exe in the user's 'Startup' folder BOINC will be launched at boot by the Service Control Manager

Install Details

Installer packages based on the Microsoft Installer technology are divided into two phases. Phase one is the 'User Interface' phase where the installer presents all the questions that need to be answered before a successful installation can occur. Phase two is the 'Execution' phase where the actual installation occurs.

Both phases are broken up into a sequence which executes custom actions in a specific order. Each custom action, whether defined by the MSI system or the setup programmer, preforms a specific action.

The following custom actions were designed specifically for BOINC:

CARestoreSetupState

Restore the previous setup parameters from the registry.

Registry location: HKLM\Software\Space Sciences Laboratory, U.C. Berkeley\BOINC Setup

Execution After:	ISSetupFilesExtract
Execution Condition:

Pseudocode:

GetRegistryValue( "INSTALLDIR", strInstallDirectory );
GetRegistryValue( "SETUPTYPE", strSetupType );
GetRegistryValue( "LAUNCHPROGRAM", strLaunchProgram );
GetRegistryValue( "ENABLELAUNCHATLOGON", strEnableLaunchAtLogon );
GetRegistryValue( "ENABLESCREENSAVER", strEnableScreensaver );
GetRegistryValue( "SERVICE_DOMAIN", strServiceDomain );
GetRegistryValue( "SERVICE_USERNAME", strServiceUsername );

SET INSTALLDIR TO strInstallDirectory
SET SETUPTYPE TO strSetupType
SET LAUNCHPROGRAM TO strLaunchProgram
SET ENABLELAUNCHATLOGON TO strEnableLaunchAtLogon
SET ENABLESCREENSAVER TO strEnableScreensaver
SET SERVICE_DOMAIN TO strServiceDomain
SET SERVICE_USERNAME TO strServiceUsername

RETURN SUCCESS

CASaveSetupState

Save the current setup parameters to the registry.

Registry location: HKLM\Software\Space Sciences Laboratory, U.C. Berkeley\BOINC Setup

Execution After:	ExecuteAction
Execution Condition:

Pseudocode:

GET INSTALLDIR STORE strInstallDirectory
GET SETUPTYPE STORE strSetupType
GET LAUNCHPROGRAM STORE strLaunchProgram
GET ENABLELAUNCHATLOGON STORE strEnableLaunchAtLogon
GET ENABLESCREENSAVER STORE strEnableScreensaver
GET SERVICE_DOMAIN STORE strServiceDomain
GET SERVICE_USERNAME STORE strServiceUsername

SetRegistryValue( "INSTALLDIR", strInstallDirectory );
SetRegistryValue( "SETUPTYPE", strSetupType );
SetRegistryValue( "LAUNCHPROGRAM", strLaunchProgram );
SetRegistryValue( "ENABLELAUNCHATLOGON", strEnableLaunchAtLogon );
SetRegistryValue( "ENABLESCREENSAVER", strEnableScreensaver );
SetRegistryValue( "SERVICE_DOMAIN", strServiceDomain );
SetRegistryValue( "SERVICE_USERNAME", strServiceUsername );
SetRegistryValue( "SETUPSTATESTORED", strSetupStateStored );

RETURN SUCCESS

CAValidateSetupType

The Microsoft Installer technology allows you to install a package without using the 'User Interface', so this custom action validates the input passed to the execution phase.

Execution After:	ValidateProductID
Execution Condition:

Pseudocode:

IF SetupType IS NOT NULL
    IF (SetupType IS 'Single') OR (SetupType IS 'Service')
        IF (AllUsers IS NOT NULL) OR (IsAdminPagage IS '1')
            RETURN ERROR
        END IF
    ELSE
        IF (AllUsers IS '1')
            RETURN ERROR
        END IF
    END IF
END IF

RETURN SUCCESS

CAValidateServiceAccount

Validates the service parameters passed to the execution phase.

Execution After:	CAValidateSetupType
Execution Condition:	VersionNT AND (SETUPTYPE = "Service OR SETUPTYPE = "ServiceGUI")

Pseudocode:

IF ServicePassword IS NULL
    IF (ServiceDomainUsername IS NOT 'LOCALSYSTEM') AND (ServiceDomainUsername IS NOT 'NetworkService')
        RETURN ERROR
    END IF
END IF

IF ServiceDomainUsername IS NULL
    IF (ServiceDomain IS NULL) OR (ServiceUsername IS NULL)
        RETURN ERROR
    END IF
ELSE
    SET ServiceDomain TO "Domain portion of ServiceDomainUsername"
    SET ServiceUsername TO "Username portion of ServiceDomainUsername"
END IF

RETURN SUCCESS

CAShutdownBOINC

Gracefully shutdown BOINC if it is running, if that fails terminate it.

Execution After:	CAValidateServiceAccount
Execution Condition:	VersionNT AND NOT INSTALLED

Pseudocode:

IF BOINCIsRunning() = TRUE
    ShutdownBOINC()
END IF
TerminateBOINC()

RETURN SUCCESS

CAShutdownBOINCManager

Gracefully shutdown BOINC Manager if it is running, if that fails terminate it.

Execution After:	CAShutdownBOINC
Execution Condition:	VersionNT AND NOT INSTALLED

Pseudocode:

IF BOINCManagerIsRunning() = TRUE
    ShutdownBOINCManager()
END IF
TerminateBOINCManager()

RETURN SUCCESS

CAShutdownBOINCManager95

Gracefully shutdown BOINC Manager if it is running, if that fails terminate it.

Execution After:	CAShutdownBOINCManager
Execution Condition:	Version95 AND NOT INSTALLED

Pseudocode:

IF BOINCManagerIsRunning() = TRUE
    ShutdownBOINCManager()
END IF
TerminateBOINCManager()

RETURN SUCCESS

CAShutdownBOINCScreensaver

Gracefully shutdown BOINC Screensaver if it is running, if that fails terminate it.

Execution After:	CAShutdownBOINCManager95
Execution Condition:	VersionNT AND NOT INSTALLED

Pseudocode:

IF BOINCScreensaverIsRunning() = TRUE
    ShutdownBOINCScreensaver()
END IF
TerminateBOINCScreensaver()

RETURN SUCCESS

CAMigratex86x64

Migrate BOINC Data from the 32-bit application storage location to the 64-bit application storage location.

Execution After:	CAShutdownBOINCScreensaver
Execution Condition:

Pseudocode:

MoveFileEx(
    "C:\Program Files (x86)\BOINC",
    InstallDir,
    MOVEFILE_COPY_ALLOWED|MOVEFILE_WRITE_THROUGH
)

RETURN SUCCESS

CAMigrateCPDNBBC

Migrate the CPDNBBC data from the specialized CPDNBBC directory to the standard BOINC installation directory.

Execution After:	CAMigratex86x64
Execution Condition:

Pseudocode:

MoveFileEx(
    "C:\Program Files\Climate Change Experiment",
    InstallDir,
    MOVEFILE_COPY_ALLOWED|MOVEFILE_WRITE_THROUGH
)

RETURN SUCCESS

CACleanupOldBinaries

After uninstalling any older versions of BOINC, make sure all BOINC related binaries have been deleted from the system.

Execution After:	CAMigrateCPDNBBC
Execution Condition:

Pseudocode:

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

RETURN SUCCESS

CAGrantServiceExecutionRight

Make sure the service user account is allowed to execute services.

Execution After:	InstallInitialize
Execution Condition:	VersionNT And (SETUPTYPE = "Service" Or SETUPTYPE = "ServiceGUI") And SERVICE_GRANTEXECUTIONRIGHT = "1"

Pseudocode:

pSID = GetAccountSid(ServiceDomainUsername)
SetPrivilegeOnAccount(
    pSID,
    "SeServiceLogonRight",
    TRUE
)

RETURN SUCCESS

CAGetAdministratorsGroupName

Convert the well known group SID into the human readable localized version of the name.

Execution After:	CAGrantServiceExecutionRight
Execution Condition:	VersionNT

Pseudocode:

GroupName = LookupAliasFromRid(NULL, DOMAIN_ALIAS_RID_ADMINS)
SET GROUPALIAS_ADMINISTRATORS TO GroupName


RETURN SUCCESS

CAGetUsersGroupName

Convert the well known group SID into the human readable localized version of the name.

Execution After:	CAGetAdministratorsGroupName
Execution Condition:	VersionNT

Pseudocode:

GroupName = LookupAliasFromRid(NULL, DOMAIN_ALIAS_RID_USERS)
SET GROUPALIAS_USERS TO GroupName


RETURN SUCCESS