• 6 min read

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.

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

Updates in December 2015:
1. Azure VM OSPatching extension for Linux is now supporting Azure Resource Manager model, for sample Powershell and CLI scripts on running OS Pathching Extension for Linux under ARM model, please see the GitHub release document here: https://github.com/Azure/azure-linux-extensions/tree/master/OSPatching
2.  Azure VM OSPatching extension for Linux 2.0 is released, adding two options: 1. Checking idle state before patching. 2.Validating the system status after patching

A. Checking idle state:
Before patching, the extension will check the status of the VM, by calling a user provided script. IF this script returns 1 it will move foward for the patching, otherwise it will stop. The script can be located at Azure storge or Github,  you need to provide the URL of the location as the parameter.
B. Validating the system status after patching
After patching, the extension will check the system health by calling a user provided script, and report the result to the extension log file. The script can be  located at Azure storge or Github,  you just need to provide the URL of the location as the parameter.

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.

Parameter Description Value Type Default Value
intervalOfWeeks The update frequency (in weeks) Integer. Starting from 1.e.g. “intervalOfWeeks” : “1” “1”
dayOfWeek The patching date (of the week)You can specify multiple days in a week. String. Enumeration of “Sunday”, “Monday”, “Tuesday”, “Wednesday”, “Thursday”, “Friday”, “Saturday”, Everyday (Use “|” to separate multiple values).e.g. “dayOfWeek” : “Sunday|Wednesday” “Everyday”
startTime Start time of patching String. In the format of “hr:min”e.g. “startTime” : “03:00” , with hour ranging from 0 to 23. More notes below. .1 Empty string(One-off mode)
installDuration The allowed total time for installation String. In the format of “hr:mins”e.g. “installDuration” : “00:30”. More notes below.2 “01:00”
category Type of patches to install String. Enumeration of “Important” and “ImportantAndRecommended”.e.g. “category” : “ImportantAndRecommended” “ImportantAndRecommended”
rebootAfterPatch The reboot behavior after patching String. Enumeration of “Required” (always reboot), “NotRequired” (never reboot) and “ Auto”(use the VM’s current reboot mechanism).e.g. “rebootAfterPatch” : “Auto “Auto”
disabled Flag to disable this extension, String. “True” or “False”e.g. “disabled” : “False” “False”
stop Flag to cancel the OS update process String. “True” or “False”e.g. “stop” : “False” “False

1 If the startTime is set to an empty string, it will set the installation to “One-off” mode, see scenario 3 below for details. 2For 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

Sometimes 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 -ServiceName "Your Service Name"
  • 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.

No. Command Linux OS
1 apt-get Ubuntu
2 yum CentOS, Oracle
3 zypper SUSE