Automate Linux VM OS Updates Using OSPatching Extension

Azure VM OSPatching extension for Linux enables the Azure VM administrators to automate the VM OS updates with the customized configurations.

If this is your first time using VM extensions, you might want to check here for background.

Pre-requisites

• The latest Microsoft Azure Linux Agent (minimal Version 2.0.6)
•  Azure PowerShell

Note you can also use Azure Cross-Platform Command-Line (referred to as “xPlat” below) as an alternative to Azure PowerShell.

Please check here for the xPlat release announcement. For the details on how to install and use Xplat package, please refer to Install and Configure the Azure Cross-Platform Command-Line Interface and Azure command-line tool for Mac and Linux.

Supported Functions

You can use the OSPatching extension to configure OS updates for your virtual machines, including:

• Specify how often and when to install OS patches
• Specify what patches to install
• Configure the reboot behavior after updates

Extension Parameters

Administrator can configure the OS updates with following parameters, please note the parameters are case sensitive.

¹ If the startTime is set to an empty string, it will set the installation to “One-off” mode, see scenario 3 below for details.

²For installDuration, if the actual installation exceeds the allowed time user had specified, the update process will try to stop the installation, and  resume it at next scheduled installation. However depending on the installation stage, the installation may not always be stopped, in that case, it may exceed the allowed time.

Please also note, there is a fixed download time limit of 1 hour. If the downloading time exceeds 1 hour, the downloading process will be stopped, it can be resumed next time. The extension will log the error in the log file, see the “Checking the Status” section for details.

Sample Scripts and User Scenarios

Following are major scenarios with the sample PowerShell scripts and xPlat commands. Please note the parameters are case sensitive.

Scenario 1: Setting up Recurring OS Updates

For regular recurring patching, you can configure the schedule using “intervalOfWeeks”, “dayOfWeek” and “startTime”. Below is the sample script:

PowerShell Script:

# Sample PowerShell script to configure an OS update schedule
# Get the VM
$vm = Get-AzureVM -ServiceName "Your Service Name" -Name "Your VM Name"
# Set the extension information
$ExtensionName="OSPatchingForLinux"
$version="1.0"
$Publisher="Microsoft.OSTCExtensions"

# Set the parameter value
# The OS updates for “ImportantAndRecommended” patches will start at “03:00” on “Sunday” and “Wednesday” every week. 
$PrivateConfig = '{
    "disabled" : "False",
    "stop" : "False",
    "rebootAfterPatch" : "Auto",
    "intervalOfWeeks" : "1",
    "dayOfWeek" : "Sunday|Wednesday",
    "startTime" : "03:00",
    "category" : "ImportantAndRecommended",
    "installDuration" : "00:30" }'
$PublicConfig = '{}'

# Apply the configuration to the extension
Set-AzureVMExtension -ExtensionName $ExtensionName -VM $vm -Publisher $Publisher -Version $version -PrivateConfiguration $PrivateConfig -PublicConfiguration $PublicConfig | Update-AzureVM

Xplat Command:

node bin/azure vm extension set "Your VM Name" OSPatchingForLinux Microsoft.OSTCExtensions 1.0 -i '{}' -t '{"disabled:" False","stop":"False","rebootAfterPatch":"Auto","intervalOfWeeks":"1","dayOfWeek":"Sunday|Wednesday","startTime":"03:00","category":"ImportantAndRecommended","installDuration":"00:30"}'

Scenario 2: Modify Existing Patching Configuration

You can modify the update schedule settings (“intervalOfWeeks”, “dayOfWeek” and “startTime”) as following example.

PowerShell Script:

# Get the VM
$vm = Get-AzureVM -ServiceName "Your Service Name" -Name "Your VM Name"
# Set the extension information
$ExtensionName="OSPatchingForLinux"
$version="1.0"
$Publisher="Microsoft.OSTCExtensions"

# Set the parameter value
# Here we modify the “intervalOfWeeks” to “2” and “dayOfWeek” to “Monday”. The rest are unchanged
$PrivateConfig = '{
    "disabled" : "False",
    "stop" : "False",
    "rebootAfterPatch" : "Auto",
    "intervalOfWeeks" : "2",
    "dayOfWeek" : "Monday",
    "startTime" : "03:00",
    "category" : "ImportantAndRecommended",
    "installDuration" : "00:30" }'
$PublicConfig = '{}'

# Apply the configuration to the extension
Set-AzureVMExtension -ExtensionName $ExtensionName -VM $vm -Publisher $Publisher -Version $version -PrivateConfiguration $PrivateConfig -PublicConfiguration $PublicConfig | Update-AzureVM

xPlat Command:

node bin/azure vm extension set "Your VM Name" OSPatchingForLinux Microsoft.OSTCExtensions 1.0 -i '{}' -t '{"disabled:" False","stop":"False","rebootAfterPatch":"Auto","intervalOfWeeks":"2","dayOfWeek":"Monday","startTime":"03:00","category":"ImportantAndRecommended","installDuration":"00:30"}'

Please note, the extension will not “remember” the state of the settings; when you modify existing settings, you have to specify the value for each parameter again, even though you don’t intend to change it, otherwise the value will be reset to default. You can check your current OS update setting from the status file, see the “Checking Status” section below for details.

Scenario 3: One-off Patching

Sometime you may want to install updates immediately, for example, installing critical patches. You can configure your OS update as one-off mode, by setting “startTime” to empty string without change other settings. OS updates will start immediately after the configuration.

The One-Off patching will only be executed once, after that, it will automatically go back to the last recurring update settings.

Note if you need to modify any settings in addition to “startTime” when setting the One-off mode, you will need to run the script again, specifying value for each parameter after the One-off patching, in order to resume the original settings, see scenario 2 on how to modify settings.

PowerShell Script:

# Get the VM
$vm = Get-AzureVM -ServiceName "Your Service Name" -Name "Your VM Name"
# Set the extension information
$ExtensionName="OSPatchingForLinux"
$version="1.0"
$Publisher="Microsoft.OSTCExtensions"

# Set the parameter value
# Here we set the “startTime” to empty string for one-off mode
$PrivateConfig = '{
    "disabled" : "False",
    "stop" : "False",
    "rebootAfterPatch" : "Auto",
    "startTime" : "",
    "category" : "ImportantAndRecommended",
    "installDuration" : "00:30" }'

$TimeStamp = (Get-Date).Ticks
$PublicConfig = '{"timestamp" : "' + $TimeStamp + '"}'

# Apply the configuration to the extension
Set-AzureVMExtension -ExtensionName $ExtensionName -VM $vm -Publisher $Publisher -Version $version -PrivateConfiguration $PrivateConfig -PublicConfiguration $PublicConfig | Update-AzureVM

xPlat Command:

node bin/azure vm extension set "Your VM Name" OSPatchingForLinux Microsoft.OSTCExtensions  1.0 -i '{"timestamp":"'`(date +%s)`'"}' -t '{"disabled:" False","stop":"False","rebootAfterPatch":"Auto","startTime":"","category":"ImportantAndRecommended","installDuration":"00:30"}'

Additional Scenarios:

You can stop the OS updates for debugging. Once the “stop” parameter is set to “true”, the OS update will stop after the current update is finished.

PowerShell Script:

# Get the VM
$vm = Get-AzureVM -ServiceName "Your Service Name" -Name "Your VM Name"
# Set the extension information
$ExtensionName="OSPatchingForLinux"
$version="1.0"
$Publisher="Microsoft.OSTCExtensions"

# Set the parameter value
# When you set the “stop” parameter to true, the OS update will stop after the current update is finished.
$PrivateConfig = '{
    "disabled" : "False",
    "stop" : "True"    
 }'
$PublicConfig = '{}'

# Apply the configuration to the extension
Set-AzureVMExtension -ExtensionName $ExtensionName -VM $vm -Publisher $Publisher -Version $version -PrivateConfiguration $PrivateConfig -PublicConfiguration $PublicConfig | Update-AzureVM

xPlat Command:

node bin/azure vm extension set "Your VM Name" OSPatchingForLinux Microsoft.OSTCExtensions  1.0 -i '{}' -t '{"disabled:" False","stop":"True"}'

If you want to switch to manual OS update, you can set the “disable” parameter to “true”.

PowerShell Script:

# Get the VM
$vm = Get-AzureVM -ServiceName "Your Service Name" -Name "Your VM Name"
# Set the extension information
$ExtensionName="OSPatchingForLinux"
$version="1.0"
$Publisher="Microsoft.OSTCExtensions"

# Set the parameter value
# When you set the “disabled” parameter to true, the OSPatching extension is disabled.
$PrivateConfig = '{
    "disabled" : "True"
 }'
$PublicConfig = '{}'

# Apply the configuration to the extension
Set-AzureVMExtension -ExtensionName $ExtensionName -VM $vm -Publisher $Publisher -Version $version -PrivateConfiguration $PrivateConfig -PublicConfiguration $PublicConfig | Update-AzureVM

xPlat Command:

node bin/azure vm extension set "Your VM Name" OSPatchingForLinux Microsoft.OSTCExtensions  1.0 -i '{}' -t '{"disabled:" True"}'

Checking Status

Checking the OS Update Configuring Status and Settings

• To check the deployment status of the extension, run following PowerShell command :

Get-AzureDeployment

• Azure Portal will display the extension status and final OS update settings, this feature will be available in a few weeks.
• To check the detailed extension status and final OS update settings,  you can reference files in following location inside the VM: “/var/lib/waagent/Microsoft.OSTCExtensions.OSPatchingForLinux-version/status/”

Checking the OS Update Status

• The OS patching process will log status and errors in following files inside the VM: “/var/log/azure/Microsoft.OSTCExtensions.OSPatchingForLinux//extension.log” and “/var/log/waagent.log”.
• The OS patching process will also record the downloaded and installed package list in following files inside the VM: Downloaded packages in file “/var/lib/waagent/package.downloaded”. Installed packages in file “/var/lib/waagent/package.patched”.

Additional Notes

The OSPatching leverages following Linux commands for OS patching. When using OSPatching extension, we recommend you stop applications that utilizing the same commands listed below to avoid conflicts. In most cases they cannot be executed in multiple processes at the same time.