Dell Appassure 5 User Guide

							Dell AppAssure User Guide
Version 5.4.3 Revision B
C
359
Extending AppAssure jobs using 
scripting
AppAssure enables administrators to automate the administration and management of resources at certain 
occurrences through the execution of commands and scripts. The AppAssure software supports the use of 
PowerShell scripting for Windows and Bourne Shell scripting for Linux.
Core jobs are automatically created whenever you initiate operations on the AppAssure Core such as 
replication, virtual export, or a backup snapshot. You can extend these jobs by running a script before it or 
after it. These are known as pre and post scripts.
This section describes the scripts that can be used by administrators at designated occurrences in AppAssure for 
Windows and Linux.
This section includes the following topics:
•Using PowerShell scripts in AppAssure
•Input Parameters for PowerShell Scripting
•Sample PowerShell scripts
•Using Bourne Shell scripting in AppAssure
•Input parameters for Bourne Shell scripting
•Sample Bourne Shell scripts
•Sample PowerShell scripts
Using PowerShell scripts in AppAssure
Windows PowerShell is a Microsoft .NET Framework-connected environment designed for administrative 
automation. AppAssure includes comprehensive client software development kits (SDKs) for PowerShell scripting 
that lets administrative users run user-provided PowerShell scripts at designated occurrences; for example, 
before or after a snapshot, attachability and mountability checks, and so on. Administrators can run scripts 
from both the AppAssure Core and the protected machine. Scripts can accept parameters, and the output of a 
script is written to Core and protected machine log files.
Script files are located in the %ALLUSERSPROFILE%\AppRecovery\Scripts folder.
•In Windows 7, the path to locate the %ALLUSERSPROFILE% folder is: C:\ProgramData.
•In Windows 2003, the path to locate the folder is: Documents and Settings\All Users\Application Data\.
CAUTION: The sample PowerShell and Bourne scripts provided in this document will function when 
run as designed by qualified administrators. Take precautions when modifying functioning scripts to 
retain working versions. Any modifications to the script samples included here, or any scripts you 
create, are considered customization, which is not typically covered by Customer Support.
NOTE: For nightly jobs, preserve one script file and the JobType input parameter to distinguish between 
nightly jobs.
NOTE: Windows PowerShell is required and must be installed and configured before running AppAssure 
scripts. 
						

							Dell AppAssure User Guide
Version 5.4.3 Revision B360 For more information on how using PowerShell scripts see Sample PowerShell scripts, Input Parameters for 
PowerShell Scripting, Input parameters for Bourne Shell scripting, and Sample Bourne Shell scripts.
Prerequisites for PowerShell scripting
Before running PowerShell scripts for AppAssure, you must have Windows PowerShell 2.0 or later installed. Due 
to new features introduced in PowerShell 3.0, including easier access to object properties, PowerShell Web 
access, and support for REST calls, Dell recommends using PowerShell 3.0 or later.
powershell.exe.config







Testing PowerShell Scripts
If you want to test the scripts you plan to run, you can do so by using the PowerShell graphical editor, 
powershell_is. You also need to add the configuration file, powershell_ise.exe.config to the same folder the 
configuration file, powershell.exe.config.
Localization
When running on the same machine on which AppAssure Core is installed, the AppAssure PowerShell module 
bases its display language on the language set for the AppAssure Core. In this release, supported languages 
include English, Chinese (Simplified), French, Korean, German, Japanese, Portuguese (Brazil), and Spanish.
If the AppAssure PowerShell module is installed on a separate machine, English is the only language supported.
NOTE: Place the powershell.exe.config file in the PowerShell home directory. For example, 
C:\WindowsPowerShell\powershell.exe.config.
NOTE: The configuration file, powershell_ise.exe.config must have the same content as the 
powershell.exe.config file.
CAUTION: If the pre-PowerShell or post-PowerShell script fails, the job also fails. 
						

							Dell AppAssure User Guide
Version 5.4.3 Revision B361
Qualifiers
The following table describes the qualifiers available for AppAssure PowerShell module.
Input Parameters for PowerShell Scripting
All available input parameters are used in sample scripts. The parameters are described in the following tables.
AgentProtectionStorageConfiguration (namespace 
Replay.Common.Contracts.Agents)
The following table presents the available objects for the AgentProtectionStorageConfiguration parameter. Table 206. Qualifiers for the AppAssure PowerShell module
Qualifier Usage
-core Host name of the Core.
Default: Localhost
-ProtectedServer 
Host name/IP address of the AppAssure Agent.
Default: Localhost if multiple servers protected, otherwise the 
single server protected.
-Mode 
Recovery Point Mount mode.
Default: Read.
-Volumes 
Snapshot volume letter from AppAssure Agent.
Default: All.
-User 
User name used to connect to the AppAssure Core, which is 
typically the service user.
-Domain 
Domain to which the user defined in /User belongs.
-Password 
Password of the user defined in /User.
-Path 
For example: C:\AppAssureMount.
NOTE: Script files must possess the same name as the sample script files.
Table 207. Objects for the AgentProtectionStorageConfiguration parameter
 Method Description
public Guid RepositoryId { get; set; } Gets or sets the ID of the repository where the agent 
recovery points are stored.
public string EncryptionKeyId { get; set; } Gets or sets the ID of the encryption key for this 
agents recovery points. An empty string means no 
encryption. 
						

							Dell AppAssure User Guide
Version 5.4.3 Revision B362
AgentTransferConfiguration (namespace 
Replay.Common.Contracts.Transfer)
The following table presents the available objects for the AgentTransferConfiguration parameter.
Table 208. Objects for the AgentTransferConfiguration parameter
 Method Description
public uint MaxConcurrentStreams { get; set; } Gets or sets the maximum number of concurrent TCP 
connections the Core establishes to the agent for 
transferring data.
public uint MaxTransferQueueDepth { get; set; } When a range of blocks are read from a transfer 
stream, that range is placed on a producer or 
consumer queue, where a consumer thread reads it 
and writes it to the epoch object. If the repository 
writes slower than the network reads, this queue 
fills up. The point at which the queue is full and 
reads stop is the maximum transfer queue depth.
public uint MaxConcurrentWrites { get; set; } Gets or sets the maximum number of block write 
operations to have outstanding on an epoch at any 
given time. If additional blocks are received when 
this many block writes are outstanding, those 
additional blocks are ignored until one of the 
outstanding writes finishes.
public ulong MaxSegmentSize { get; set; } Gets or sets the maximum number of contiguous 
blocks to transfer in a single request. Depending on 
testing, higher or lower values may be optimal.
public Priority Priority { get; set; } Gets or sets the priority for transfer request.
public int MaxRetries { get; set; } Gets or sets the maximum number of times a failed 
transfer should be retried before it is presumed 
failed.
public Guid ProviderId{ get; set; } Gets or sets the GUID of the VSS provider to use for 
snapshots on this host. Administrators typically 
accept the default.
public Collection ExcludedWriterIds { 
get; set; }Gets or sets the collection of VSS writer IDs, which 
should be excluded from this snapshot. The writer ID 
is determined by the name of the writer. This name 
is for documentation purposes only and does not 
have to exactly match the name of the writer.
public ushort TransferDataServerPort { get; set; } Gets or sets a value containing the TCP port upon 
which to accept connections from the Core for the 
actual transfer of data from the Agent to the Core. 
The Agent attempts to listen on this port, but if the 
port is in use, the Agent can use a different port 
instead. The Core should use the port number 
specified in the BlockHashesUri and BlockDataUri 
properties of the VolumeSnapshotInfo object for 
each snapped volume.
public TimeSpan SnapshotTimeout { get; set; } Gets or sets the amount of time to wait for a VSS 
snapshot operation to complete before giving up and 
timing out.
public TimeSpan TransferTimeout { get; set; } Gets or sets the amount of time to wait for further 
contact from the Core before abandoning the 
snapshot. 
						

							Dell AppAssure User Guide
Version 5.4.3 Revision B363
BackgroundJobRequest (namespace 
Replay.Core.Contracts.BackgroundJobs)
The following table presents the available objects for the BackgroundJobRequest parameter.
ChecksumCheckJobRequest (namespace 
Replay.Core.Contracts.Exchange.ChecksumChecks)
Inherits its values from the parameter, DatabaseCheckJobRequestBase.
DatabaseCheckJobRequestBase (namespace 
Replay.Core.Contracts.Exchange)
Inherits its values from the parameter, BackgroundJobRequest.
ExportJobRequest (namespace 
Replay.Core.Contracts.Export)
Inherits its values from the parameter, BackgroundJobRequest.
The following table presents the available objects for the ExportJobRequest parameter.public TimeSpan NetworkReadTimeout { get; set; } Gets or sets the timeout for network read operations 
related to this transfer.
public TimeSpan NetworkWriteTimeout { get; set; } Gets or sets the timeout for network write 
operations related to this transfer.
Table 209. Objects for the BackgroundJobRequest parameter
 Method Description
public Guid AgentId { get; set; } Gets or sets the ID of the Agent.
public bool IsNightlyJob { get; set; } Gets or sets the value indicating whether the 
background job is a nightly job.
public virtual bool InvolvesAgentId(Guid agentId) Determines the value indicating whether the 
concrete agent is involved in job.
Table 210. Objects for the ExportJobRequest parameter
 Method Description
public uint RamInMegabytes { get; set; } Gets or sets the memory size for the exported VM. 
Set to zero (0) to use the memory size of the source 
machine.
public VirtualMachineLocation Location { get; set; } Gets or sets the target location for this export. This is 
an abstract base class.
public VolumeImageIdsCollection VolumeImageIds { 
get; private set; }Gets or sets the volume images to include in the VM 
export.
public ExportJobPriority Priority { get; set; } Gets or sets the priority for export request. Table 208. Objects for the AgentTransferConfiguration parameter
 Method Description 
						

							Dell AppAssure User Guide
Version 5.4.3 Revision B364
NightlyAttachabilityJobRequest (namespace 
Replay.Core.Contracts.Sql)
Inherits its values from the parameter, BackgroundJobRequest.
RollupJobRequest (namespace 
Replay.Core.Contracts.Rollup)
Inherits its values from the parameter, BackgroundJobRequest.
TakeSnapshotResponse (namespace 
Replay.Agent.Contracts.Transfer)
The following table presents the available objects for the TakeSnapshotResponse parameter.
TransferJobRequest (namespace 
Replay.Core.Contracts.Transfer)
Inherits its values from the parameter, BackgroundJobRequest.
The following table presents the available objects for the TransferJobRequest parameter. Table 211. Objects for the TakeSnapshotResponse parameter
 Method Description
public Guid SnapshotSetId { get; set; } Gets or sets the GUID assigned by VSS to this 
snapshot.
public VolumeSnapshotInfoDictionary VolumeSnapshots 
{ get; set; }Gets or sets the collection of snapshot info for each 
volume included in the snap.
Table 212. Objects for the TransferJobRequest parameter
 Method Description
public VolumeNameCollection VolumeNames { get; set; 
} Gets or sets the collection of names for transfer.
VolumeNames is a data structure that contains the 
following data:
•GuidName. The Guid associated with the 
volume, used as the name if a DisplayName is 
not set.
•DisplayName. The displayed name of the 
volume.
public ShadowCopyType ShadowCopyType { get; set; }  Gets or sets the type of copying for transfer. The 
available values are:
•Unknown
•Copy
•Full
public AgentTransferConfiguration 
TransferConfiguration { get; set; } Gets or sets the transfer configuration.
public AgentProtectionStorageConfiguration 
StorageConfiguration { get; set; } Gets or sets the storage configuration. 
						

							Dell AppAssure User Guide
Version 5.4.3 Revision B365
TransferPrescriptParameter (namespace 
Replay.Common.Contracts.PowerShellExecution)
The following table presents the available objects for the TransferPrescript parameter.public string Key { get; set; }  Generates a pseudorandom (but not 
cryptographically secure) key, which can be used as a 
one-time password to authenticate transfer requests.
public bool ForceBaseImage { get; set; }  Gets or sets the value indicating whether the base 
image was forced or not.
public bool IsLogTruncation { get; set; }  Gets or sets the value indicating whether the job is 
log truncation or not.
Table 213. Objects for the TransferPrescript parameter
 Method Description
public VolumeNameCollection VolumeNames (get; set; ) Gets or sets the collection of volume names for 
transfer.
VolumeNames is a data structure that contains the 
following data:
•GuidName. The Guid associated with the 
volume, used as the name if a DisplayName is 
not set.
• DisplayName. The displayed name of the 
volume.
public ShadowCopyType ShadowCopyType { get; set; } Gets or sets the type of copying for 
transfer.ShadowCopyType is an enumeration with 
values. The available values are:
•Unknown
•Copy
•Full Table 212. Objects for the TransferJobRequest parameter
 Method Description 
						

							Dell AppAssure User Guide
Version 5.4.3 Revision B366 public AgentTransferConfiguration TransferConfiguration 
{ get; set; } Gets or sets the transfer configuration.
AgentTransferConfiguration is an object which will 
have the following data:
• MaxConcurrentStreams. The maximum 
number of concurrent TCP connections the 
core will establish to the agent for 
transferring data
• MaxTransferQueueDepth. The maximum 
number of block extents which can be 
queued up for writing
• MaxConcurrentWrites. The maximum 
number of block write operations to have 
outstanding on an epoch at any given time. If 
additional blocks are received when this 
many block writes are outstanding, those 
additional blocks will be ignored until one of 
the outstanding blocks gets written.
•MaxSegmentSize. The maximum number of 
contiguous blocks to transfer in a single 
request
•Priority. An object which will have the 
following data:
•Undefined
•One
•Tw o
•Three
•Four
•Five
•Six
•Seven
•Eight
•Nine
•Te n
•Highest (which is equal to One)
•Lowest (which is equal to Ten)
•Default (which is equal to Five)
•MaxRetries. The maximum number of times a 
failed transfer should be retried before it is 
presumed failed
• UseDefaultMaxRetries. A value indicating 
that the maximum number of retries is the 
default value
• ProviderId. The GUID of the VSS provider to 
use for snapshots on this host. Users typically 
use the default setting. Table 213. Objects for the TransferPrescript parameter
 Method Description 
						

							Dell AppAssure User Guide
Version 5.4.3 Revision B367 public AgentTransferConfiguration TransferConfiguration 
{ get; set; } (cont.)• ExcludedWriterIds. Collection of VSS writer 
IDs which should be excluded from this 
snapshot. The writer ID is keyed by the name 
of the writer. This name is for documentation 
purposes only and does not have to exactly 
match the actual name of the writer.
• TransferDataServerPort. A value containing 
the TCP port upon which to accept 
connections from the core for the actual 
transfer of data from the agent to the core.
•SnapshotTimeout. The amount of time to 
wait for a VSS snapshot operation to 
complete before giving up and timing out.
•TransferTimeout. The amount of time to 
wait for further contact from the core before 
abandoning the snapshot.
•NetworkReadTimeout. The timeout for 
network read operations related to this 
transfer.
• NetworkWriteTimeout. The timeout for 
network write operations related to this 
transfer.
•InitialQueueSize. A size of initial queue of 
requests.
• MinVolumeFreeSpacePercents. A minimal 
amount of free space on a volume in percent.
• MaxChangeLogsSizePercents. A maximum 
size of driver change logs as part of volume 
capacity measured in percent.
• EnableVerification. A value indicating 
whether diagnostic verification of each block 
sent to Core should be performed.
public string Key { get; set; } The Key method generates a pseudorandom (but not 
cryptographically secure) key, which can be used as 
a one-time password to authenticate transfer 
requests.
public bool ForceBaseImage { get; set; } Gets or sets the value indicating whether the 
transfer was a forced base image capture.
public bool IsLogTruncation { get; set; } Gets or sets the value indicating whether logging is 
being truncated.
public uint LatestEpochSeenByCore { get; set; } Gets or sets latest epoch value.
The LatestEpochSeenByCore method is the ordinal 
number of the most recent snapshot taken by the 
Core. This is the epoch number assigned by the 
filter driver to this particular snapshot at the 
moment it was taken with VSS. Table 213. Objects for the TransferPrescript parameter
 Method Description 
						

							Dell AppAssure User Guide
Version 5.4.3 Revision B368
TransferPostscriptParameter (namespace 
Replay.Common.Contracts.PowerShellExecution)
The following table presents the available objects for the TransferPostscript parameter.
Table 214. Objects for the TransferPostscript parameter
 Method Description
public VolumeNameCollection VolumeNames (get; set; ) Gets or sets the collection of volume names for 
transfer.
VolumeNames is a data structure that contains the 
following data:
• GuidName. The Guid associated with the 
volume, used as the name if a DisplayName is 
not set.
• DisplayName. The displayed name of the 
volume.
public ShadowCopyType ShadowCopyType { get; set; } Gets or sets the type of copying for 
transfer.ShadowCopyType is an enumeration with 
values. The available values are:
•Unknown
•Copy
•Full