.scriptrun (Run Script)

The .scriptrun command will load and run a JavaScript.

Parameters

ScriptFile
Specifies the name of the script file to load and execute. ScriptFile should include the .js file name extension. Absolute or relative paths can be used. Relative paths are relative to the directory that you started the debugger in. File paths containing spaces are not supported.

Environment

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

Additional Information

The .scriptrun command will load a script and, execute the following code.

A confirmation message is displayed when the code is loaded and executed.

Any object model manipulations made by the script will stay in place until the script is subsequently unloaded or is run again with different content.

This table summarizes which functions are executed by .scriptload and .scriptrun.

.scriptload	.scriptrun
root	yes	yes
initializeScript	yes	yes
invokeScript	yes
uninitializeScript

You can use this code to see which functions are called with the .script run command.

For more information about working with JavaScript, see JavaScript Debugger Scripting. For more information about the debugger objects, see Native Objects in JavaScript Extensions.

Requirements

Before using any of the .script commands, a scripting provider needs to be loaded. Use the .load (Load Extension DLL) command to load the JavaScript provider dll.

Windows Run a Script on Startup

Introduction

You can specify what programs you want to run on Windows boot. All you have to do is add the script, executable, or shortcut in to the startup folder. Alternatively you can use scheduled tasks to manage startup scripts. This will show you how to use both methods.

Using startup folder to launch scripts

The easiest way to trigger scripts to run at startup is to drop then inside the startup folder.

To easily navigate to the startup folder, Windows has an alias available: shell:startup . Use shell:common startup

You can get to the startup folder a couple ways:

1. Open the Run dialog with WindowsKey+R and enter shell:startup .
2. In the command prompt, enter explorer shell:startup .

Simply copy your files that you want run on startup in to the folder.

For example, in Windows 10, these paths work for me for user and global:

Enable and disable startup apps

Many apps run on startup that do not have any files in the startup folder. You can manage the startup apps from the Task Manager | Startup tab or by running taskmgr.exe .

In addition you can disable scripts from your startup folder so you don’t have to remove them to disable them. Right click on an item to enable or disable it.

Using scheduled tasks

An alternative to the startup folder is scheduled tasks. You can schedule a task to run on startup.

For a GUI, run taskschd.msc to create, delete, enable, disable, and otherwise manage all scheduled tasks.

To manage scheduled tasks from the command prompt, use schtasks.exe . This program will allow you to create, delete, and run scheduled tasks. You can get help about the commands by running one of the following:

Remember to run an administrator command prompt for these commands. Example for creating a script to launch on startup as local user on login:

You can tell a script to run as system on start like this:

Conclusion

After this, you should understand how easy it is to launch your own programs on startup.

Use the Azure Custom Script Extension Version 2 with Linux virtual machines

The Custom Script Extension Version 2 downloads and runs scripts on Azure virtual machines. This extension is useful for post-deployment configuration, software installation, or any other configuration/management task. You can download scripts from Azure Storage or another accessible internet location, or you can provide them to the extension runtime.

The Custom Script Extension integrates with Azure Resource Manager templates. You can also run it by using Azure CLI, PowerShell, or the Azure Virtual Machines REST API.

This article details how to use the Custom Script Extension from Azure CLI, and how to run the extension by using an Azure Resource Manager template. This article also provides troubleshooting steps for Linux systems.

There are two Linux Custom Script Extensions:

• Version 1 — Microsoft.OSTCExtensions.CustomScriptForLinux
• Version 2 — Microsoft.Azure.Extensions.CustomScript

Please switch new and existing deployments to use the new version 2 instead. The new version is intended to be a drop-in replacement. Therefore, the migration is as easy as changing the name and version, you do not need to change your extension configuration.

Operating System

The Custom Script Extension for Linux will run on the extension supported extension OS’s, for more information, see this article.

Script Location

You can use the extension to use your Azure Blob storage credentials, to access Azure Blob storage. Alternatively, the script location can be any where, as long as the VM can route to that end point, such as GitHub, internal file server etc.

Internet Connectivity

If you need to download a script externally such as GitHub or Azure Storage, then additional firewall/Network Security Group ports need to be opened. For example if your script is located in Azure Storage, you can allow access using Azure NSG Service Tags for Storage.

If your script is on a local server, then you may still need additional firewall/Network Security Group ports need to be opened.

Tips and Tricks

• The highest failure rate for this extension is due to syntax errors in the script, test the script runs without error, and also put in additional logging into the script to make it easier to find where it failed.
• Write scripts that are idempotent, so if they get run again more than once accidentally, it will not cause system changes.
• Ensure the scripts do not require user input when they run.
• There is 90 mins allowed for the script to run, anything longer will result in a failed provision of the extension.
• Do not put reboots inside the script, this will cause issues with other extensions that are being installed, and post reboot, the extension will not continue after the restart.
• It is not recommended to run a script that will cause a stop or update of the VM Agent. This might leave the extension in a Transitioning state and lead to a timeout.
• If you have a script that will cause a reboot, then install applications and run scripts etc. You should schedule the reboot using a Cron job, or using tools such as DSC, or Chef, Puppet extensions.
• The extension will only run a script once, if you want to run a script on every boot, then you can use cloud-init image and use a Scripts Per Boot module. Alternatively, you can use the script to create a SystemD service unit.
• You can only have one version of an extension applied to the VM. In order to run a second custom script, you can update the existing extension with new configuration. Alternatively, you can remove the custom script extension and reapply it again with the updated script.
• If you want to schedule when a script will run, you should use the extension to create a Cron job.
• When the script is running, you will only see a ‘transitioning’ extension status from the Azure portal or CLI. If you want more frequent status updates of a running script, you will need to create your own solution.
• Custom Script extension does not natively support proxy servers, however you can use a file transfer tool that supports proxy servers within your script, such as Curl.
• Be aware of non default directory locations that your scripts or commands may rely on, have logic to handle this.
• When deploying custom script to production VMSS instances it is suggested to deploy via json template and store your script storage account where you have control over the SAS token.

Extension schema

The Custom Script Extension configuration specifies things like script location and the command to be run. You can store this configuration in configuration files, specify it on the command line, or specify it in an Azure Resource Manager template.

You can store sensitive data in a protected configuration, which is encrypted and only decrypted inside the virtual machine. The protected configuration is useful when the execution command includes secrets such as a password.

These items should be treated as sensitive data and specified in the extensions protected setting configuration. Azure VM extension protected setting data is encrypted, and only decrypted on the target virtual machine.

managedIdentity property must not be used in conjunction with storageAccountName or storageAccountKey properties

Property values

Name	Value / Example	Data Type
apiVersion	2019-03-01	date
publisher	Microsoft.Compute.Extensions	string
type	CustomScript	string
typeHandlerVersion	2.1	int
fileUris (e.g)	https://github.com/MyProject/Archive/MyPythonScript.py	array
commandToExecute (e.g)	python MyPythonScript.py	string
script	IyEvYmluL3NoCmVjaG8gIlVwZGF0aW5nIHBhY2thZ2VzIC4uLiIKYXB0IHVwZGF0ZQphcHQgdXBncmFkZSAteQo=	string
skipDos2Unix (e.g)	false	boolean
timestamp (e.g)	123456789	32-bit integer
storageAccountName (e.g)	examplestorageacct	string
storageAccountKey (e.g)	TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg==	string
managedIdentity (e.g)	< >or < "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" >or	json object

Property value details

• apiVersion : The most up to date apiVersion can be found using Resource Explorer or from Azure CLI using the following command az provider list -o json
• skipDos2Unix : (optional, boolean) skip dos2unix conversion of script-based file URLs or script.
• timestamp (optional, 32-bit integer) use this field only to trigger a re-run of the script by changing value of this field. Any integer value is acceptable; it must only be different than the previous value.
• commandToExecute : (required if script not set, string) the entry point script to execute. Use this field instead if your command contains secrets such as passwords.
• script : (required if commandToExecute not set, string)a base64 encoded (and optionally gzip’ed) script executed by /bin/sh.
• fileUris : (optional, string array) the URLs for file(s) to be downloaded.
• storageAccountName : (optional, string) the name of storage account. If you specify storage credentials, all fileUris must be URLs for Azure Blobs.
• storageAccountKey : (optional, string) the access key of storage account
• managedIdentity : (optional, json object) the managed identity for downloading file(s)
  • clientId : (optional, string) the client ID of the managed identity
  • objectId : (optional, string) the object ID of the managed identity

The following values can be set in either public or protected settings, the extension will reject any configuration where the values below are set in both public and protected settings.

Using public settings maybe useful for debugging, but it is strongly recommended that you use protected settings.

Public settings are sent in clear text to the VM where the script will be executed. Protected settings are encrypted using a key known only to the Azure and the VM. The settings are saved to the VM as they were sent, i.e. if the settings were encrypted they are saved encrypted on the VM. The certificate used to decrypt the encrypted values is stored on the VM, and used to decrypt settings (if necessary) at runtime.

Property: skipDos2Unix

The default value is false, which means dos2unix conversion is executed.

The previous version of CustomScript, Microsoft.OSTCExtensions.CustomScriptForLinux, would automatically convert DOS files to UNIX files by translating \r\n to \n . This translation still exists, and is on by default. This conversion is applied to all files downloaded from fileUris or the script setting based on any of the following criteria.

• If the extension is one of .sh , .txt , .py , or .pl it will be converted. The script setting will always match this criteria because it is assumed to be a script executed with /bin/sh, and is saved as script.sh on the VM.
• If the file starts with #! .

The dos2unix conversion can be skipped by setting the skipDos2Unix to true.

Property: script

CustomScript supports execution of a user-defined script. The script settings to combine commandToExecute and fileUris into a single setting. Instead of the having to setup a file for download from Azure storage or GitHub gist, you can simply encode the script as a setting. Script can be used to replaced commandToExecute and fileUris.

The script must be base64 encoded. The script can optionally be gzip’ed. The script setting can be used in public or protected settings. The maximum size of the script parameter’s data is 256 KB. If the script exceeds this size it will not be executed.

For example, given the following script saved to the file /script.sh/.

The correct CustomScript script setting would be constructed by taking the output of the following command.

The script can optionally be gzip’ed to further reduce size (in most cases). (CustomScript auto-detects the use of gzip compression.)

CustomScript uses the following algorithm to execute a script.

1. assert the length of the script’s value does not exceed 256 KB.
2. base64 decode the script’s value
3. attempt to gunzip the base64 decoded value
4. write the decoded (and optionally decompressed) value to disk (/var/lib/waagent/custom-script/#/script.sh)
5. execute the script using _/bin/sh -c /var/lib/waagent/custom-script/#/script.sh.

Property: managedIdentity

This property must be specified in protected settings only.

CustomScript (version 2.1 onwards) supports managed identity for downloading file(s) from URLs provided in the «fileUris» setting. It allows CustomScript to access Azure Storage private blobs or containers without the user having to pass secrets like SAS tokens or storage account keys.

To use this feature, the user must add a system-assigned or user-assigned identity to the VM or VMSS where CustomScript is expected to run, and grant the managed identity access to the Azure Storage container or blob.

To use the system-assigned identity on the target VM/VMSS, set «managedidentity» field to an empty json object.

To use the user-assigned identity on the target VM/VMSS, configure «managedidentity» field with the client ID or the object ID of the managed identity.

managedIdentity property must not be used in conjunction with storageAccountName or storageAccountKey properties

Template deployment

Azure VM extensions can be deployed with Azure Resource Manager templates. The JSON schema detailed in the previous section can be used in an Azure Resource Manager template to run the Custom Script Extension during an Azure Resource Manager template deployment. A sample template that includes the Custom Script Extension can be found here, GitHub.

These property names are case-sensitive. To avoid deployment problems, use the names as shown here.

Azure CLI

When you’re using Azure CLI to run the Custom Script Extension, create a configuration file or files. At a minimum, you must have ‘commandToExecute’.

Optionally, you can specify the settings in the command as a JSON formatted string. This allows the configuration to be specified during execution and without a separate configuration file.

Azure CLI examples

Public configuration with script file

Azure CLI command:

Public configuration with no script file

Azure CLI command:

Public and protected configuration files

You use a public configuration file to specify the script file URI. You use a protected configuration file to specify the command to be run.

Public configuration file:

Protected configuration file:

Azure CLI command:

Troubleshooting

When the Custom Script Extension runs, the script is created or downloaded into a directory that’s similar to the following example. The command output is also saved into this directory in stdout and stderr files.

To troubleshoot, first check the Linux Agent Log, ensure the extension ran, check:

You should look for the extension execution, it will look something like:

Some points to note:

1. Enable is when the command starts running.
2. Download relates to the downloading of the CustomScript extension package from Azure, not the script files specified in fileUris.

The Azure Script Extension produces a log, which you can find here:

You should look for the individual execution, it will look something like:

Here you can see:

• The Enable command starting is this log
• The settings passed to the extension
• The extension downloading file and the result of that.
• The command being run and the result.

You can also retrieve the execution state of the Custom Script Extension including the actual arguments passed as the commandToExecute by using Azure CLI:

The output looks like the following text:

Next steps

To see the code, current issues and versions, see custom-script-extension-linux repo.