Adding AutoUpdate.UpdateToLatestVersion new flag support

README.md

@@ -273,19 +273,38 @@ _Note_: setting up this parameter to more than a few minutes can make the state
 the VM be reported as unresponsive/unavailable on the Azure portal. Also, this 
 setting affects how fast the agent starts executing extensions. 
 
-#### __AutoUpdate.Enabled__
+#### __AutoUpdate.UpdateToLatestVersion__
 
-_Type: Boolean_  
+_Type: Boolean_
 _Default: y_
 
 Enables auto-update of the Extension Handler. The Extension Handler is responsible 
 for managing extensions and reporting VM status. The core functionality of the agent
 is contained in the Extension Handler, and we encourage users to enable this option 
 in order to maintain an up to date version.
 
-On most distros the default value is 'y'.
+_Note_:
+1. This option becomes effective from version 2.10.0.8 onwards.
+2. If AutoUpdate.UpdateToLatestVersion is present, it overrides any value set for AutoUpdate.Enabled (if present).
+3. If AutoUpdate.UpdateToLatestVersion is not present but AutoUpdate.Enabled is present and set to 'n', we adhere to AutoUpdate.Enabled flag's behavior. Refer to the definition of _AutoUpdate.Enabled_ for additional details.
+4. If AutoUpdate.UpdateToLatestVersion is set to 'n', it will use the most recent version that has already been installed on the VM.
+5. If AutoUpdate.Enabled is set to 'y', new VMs created from marketplace images(if they ship with lower version than 2.10.0.8) will promptly update to the latest Extension Handler version, irrespective of this option.
+6. Waagent has a built-in mechanism; if the current version running is unstable, it will roll back to previous versions. If those rollback versions are lower than 2.10.0.8, then they _may_ not support this option, and they will not honor this setting
+7. Changing config option requires a service restart to pick up the updated setting.
+
+For more information on the agent version, see our [FAQ](https://github.com/Azure/WALinuxAgent/wiki/FAQ#what-does-goal-state-agent-mean-in-waagent---version-output). <br/>
+For more information on the agent update, see our [FAQ](https://github.com/Azure/WALinuxAgent/wiki/FAQ#how-auto-update-works-for-extension-handler). <br/>
+For more information on the AutoUpdate.UpdateToLatestVersion vs AutoUpdate.Enabled, see our [FAQ](https://github.com/Azure/WALinuxAgent/wiki/FAQ#autoupdateenabled-vs-autoupdateupdatetolatestversion). <br/>
+
+#### __AutoUpdate.Enabled__
 
-For more information on the agent version, see our [FAQ](https://github.com/Azure/WALinuxAgent/wiki/FAQ#what-does-goal-state-agent-mean-in-waagent---version-output).
+_Type: Boolean_  
+_Default: y_
+
+Enables auto-update of the Extension Handler. This flag is supported for legacy reasons and we strongly recommend using AutoUpdate.UpdateToLatestVersion instead. 
+The difference between these 2 flags is that, when set to 'n', AutoUpdate.Enabled will use the version of the Extension Handler that is pre-installed on the image, while AutoUpdate.UpdateToLatestVersion will use the most recent version that has already been installed on the VM (via auto-update).
+
+On most distros the default value is 'y'.
 
 #### __Provisioning.Agent__