Install-BoxstarterPackage

SYNOPSIS

Installs a Boxstarter package

DESCRIPTION

This function must be run as administrator.

This function wraps a Chocolatey Install and provides these additional features:
  • Installs chocolatey if it is not already installed
  • Installs the .net 4.5 framework if it is not installed which is a chocolatey requirement
  • Disables windows update service during installation to prevent installation conflicts and minimize the need for reboots
  • Imports the Boxstarter.WinConfig module that provides functions for customizing windows
  • Detects pending reboots and restarts the machine when necessary to avoid installation failures
  • Provides Reboot Resiliency by ensuring the package installation is immediately restarted up on reboot if there is a reboot during the installation.
  • Ensures everything runs under admin
  • Supports remote installations allowing packages to be installed on a remote machine

The .nupkg file for the provided package name is searched in the following locations and order:
  • .\BuildPackages relative to the parent directory of the module file
  • The chocolatey feed
  • The boxstarter feed on myget
This can be configured by editing $($Boxstarter.BaseDir)\Boxstarter.Config

If the package name provided is a URL or resolves to a file, then
it is assumed that this contains the chocolatey install script and
a .nupkg file will be created using the script.

Boxstarter can install packages onto a remote machine. To accomplish this,
use either the ComputerName, Session or ConnectionURI parameters. Boxstarter uses
powershell remoting to establish an iteractive session on the remote computer.
Boxstarter configures all the necessary client side remoting settings necessary if
they are not already configured. Boxstarter will prompt the user to verify that
this is ok. Using the -Force switch will suppress the prompt. Boxstarter also ensures
that CredSSP authentication is enabled so that any network calls made by a package will
forward the users credentials.

Powershell Remoting must be enabled on the target machine in order to establish a connection.
If that machine's WMI ports are accesible, Boxstarter can enable powershell remoting
on the remote machine on its own. Otherwise, it can be manually enabled by entering

Enable-PSRemoting -Force

In an administrative powershell console on the remote machine.

PARAMETER ComputerName

If provided, Boxstarter will install the specified package name on all computers.
Boxstarter will create a Remote Session on each computer using the Credentials
given in the Credential parameter.

PARAMETER ConnectionURI

Specifies one or more Uniform Resource Identifiers (URI) that Boxstarter will use
to establish a connection with the remote computers upon which the pakage should
be installed. Use this parameter if you need to use a non default PORT or SSL.

PARAMETER Session

If provided, Boxstarter will install the specified package in all given Windows
PowerShell sessions. Note that these sessions may be closed by the time
Install-BoxstarterPackage finishes. If Boxstarter needs to restart the remote
computer, the session will be discarded and a new session will be created using
the ConnectionURI of the original sesion.

PARAMETER PackageName

The name of a NugetPackage to be installed or a URI or
file path pointing to a chocolatey script. If using a package name,
the .nupkg file for the provided package name is searched in the
following locations and order:
- .\BuildPackages relative to the parent directory of the module file
- The chocolatey feed
- The boxstarter feed on myget

PARAMETER DisableReboots

If set, reboots are suppressed.

PARAMETER Credential

The credentials to use for auto logins after reboots. If installing on
a remote machine, ths credential will also be used to establish the
connecion to the remote machine and also for any scheduled task that
boxstarter needs to create and run under a local context.

PARAMETER KeepWindowOpen

Enabling this switch will prevent the command window from closing and
prompt the user to pres the Enter key before the window closes. This
is ideal when not invoking boxstarter from a console.

Parameter Localrepo

This is the path to the local boxstarter repository where boxstarter
should look for .nupkg files to install. By default this is located
in the BuildPackages directory just under the root Boxstarter
directory but can be changed with Set-BoxstarterConfig.

NOTES

When establishing a remote connection, Boxstarter uses CredSSP
authentication so that the session can access any network resources
normally accessible to the Credential. If necessary, Boxstarter
configures CredSSP authentication on both the local and remote
machines as well as the necessary Group Policy and WSMan settings
for credential delegation. When the installation completes,
Boxstarter rolls back all settings that it changed to their original
state.

When using a Windows PowerShell session instead of ComputerName or
ConnectionURI, Boxstarter will use the authentication mechanism of the
existing session and will not configure CredSSP if the session provided
is not using CredSSP. If the session is not using CredSSP, it may be
denied access to network resources normally accessible to the Credential
being used. If you do need to access network resources external to the
session, you should use CredSSP when establishing the connection.

INPUTS

ComputerName, ConnrectionURI and Session may all be specified on the
pipeline.

OUTPUTS

Returns a PSObject for each session, ComputerName or ConnectionURI or a
single PSObject for local installations. The PSObject has the following
properties:

ComputerName: The name of the computer where the package was installed

StartTime: The time that the installation began

FinishTime: The time that Boxstarter finished the installation

Completed: True or False indicating if Boxstarter was able to complete
the installation without a terminating exception interrupting the install.
Even if this value is True, it does not mean that all components installed
in the package succeeded. Boxstarter will not terminate an installation if
individual Chocolatey packages fail. Use the Errors property to discover
errors that were raised throughout the installation.

Errors: An array of all errors encountered during the duration of the
installaion.

EXAMPLE

Invoke-ChocolateyBoxstarter example

This installs the example .nupkg. If pending
reboots are detected, boxstarter will restart the machine. Boxstarter
will not perform automatic logins after restart since no Credential
was given.

EXAMPLE

$cred=Get-Credential mwrock
Install-BoxstarterPackage -Package https://gist.github.com/mwrock/6771863/raw/b579aa269c791a53ee1481ad01711b60090db1e2/gistfile1.txt `
-Credential $cred

This installs the script uploaded to the github gist. The credentials
of the user mwrock are used to automatically login the user if
boxstarter needs to reboot the machine.

EXAMPLE

$cred=Get-Credential mwrock
Install-BoxstarterPackage -ComputerName MyOtherComputer.mydomain.com -Package MyPackage -Credential $cred

This installs the MyPackage package on MyOtherComputer.mydomain.com.

EXAMPLE

$cred=Get-Credential mwrock
$session=New-PSSession SomeComputer -Credential $cred
Install-BoxstarterPackage -Session $session -Package MyPackage -Credential $cred

This installs the MyPackage package on an existing session established with
SomeComputer. A Credential is still passed to Boxstarter even though it is
also used to establish the session because Boxstarter will need it for logons
and creating Scheduled Tasks on SomeComputer. If Boxstarter does need to
reboot SomeComputer, it will need to create a new session after SomeComputer
has rebooted and then $session will no longer be in an Available state when
Install-BoxstarterPackage completes.

EXAMPLE

$cred=Get-Credential mwrock
Install-BoxstarterPackage -ConnectionURI http://RemoteComputer:59876/wsman -Package MyPackage -Credential $cred

This installs the MyPackage package on RemoteComputer which does not
listen on the default wsman port but has been configured to listen
on port 59876.

EXAMPLE

$cred=Get-Credential mwrock
"computer1","computer2" | Install-BoxstarterPackage -Package MyPackage -Credential $cred -Force

This installs the MyPackage package on computer1 and computer2
Because the -Force parameter is used, Boxstarter will not prompt the
user to confirm that it is ok to enable Powershell remoting if it is
not already enabled. It will attempt to enable it without prompts.

Using -Force is especially advisable when installing packages on multiple
computers because otherwise, if one computer is not accesible, the command
will prompt the user if it is ok to try and confiure the computer before
proceeding to the other computers.

EXAMPLE

$cred=Get-Credential mwrock
Install-BoxstarterPackage -ComputerName MyOtherComputer.mydomain.com -Package MyPackage -Credential $cred -Force

This installs the MyPackage package on MyOtherComputer.mydomain.com.
Becauce the -Force parameter is used, Boxstarter will not prompt the
user to confirm that it is ok to enable Powershell remoting if it is
not already enabled. It will attempt to enable it without prompts.

EXAMPLE

$cred=Get-Credential mwrock
Install-BoxstarterPackage script.ps1 -Credential $cred

This installs the script located at script.ps1
in the command line's current directory.

EXAMPLE

$cred=Get-Credential mwrock
Install-BoxstarterPackage \\server\share\script.ps1 -Credential $cred

This invokes boxstarter and installs the script located at the
specified share.

EXAMPLE

$cred=Get-Credential mwrock
Install-BoxstarterPackage win8Install -LocalRepo \\server\share\boxstarter -Credential $cred

This installs the Win8Install .nupkg. Boxstarter will look
for the Win8Install .nupkg file in the \\serer\share\boxstarter
directory.

LINK

About Boxstarter.Chocolatey

Last edited Dec 1, 2013 at 6:28 AM by mwrock, version 3