Amazon Elastic Compute Cloud
User Guide for Microsoft Windows (API Version 2014-10-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Configuring a Windows Instance Using the EC2Config Service

AWS Windows AMIs contain an additional service installed by Amazon Web Services, the EC2Config service. Although optional, this service provides access to advanced features that aren't otherwise available. This service runs in the LocalSystem account and performs tasks on the instance. For example, it can send Windows event logs and IIS request logs to Amazon CloudWatch Logs. For more information about how to configure EC2Config for use with CloudWatch Logs, see Sending Performance Counters to CloudWatch and Logs to CloudWatch Logs. The service binaries and additional files are contained in the %ProgramFiles%\Amazon\EC2ConfigService directory.

The EC2Config service is started when the instance is booted. It performs tasks during initial instance startup and each time you stop and start the instance. It can also perform tasks on demand. Some of these tasks are automatically enabled, while others must be enabled manually. EC2Config uses settings files to control its operation. You can update these settings files using either a graphical tool or by directly editing XML files.

The EC2Config service runs Sysprep, a Microsoft tool that enables you to create a customized Windows AMI that can be reused. For more information about Sysprep, see Sysprep Technical Reference.

When EC2Config calls Sysprep, it uses the settings files in EC2ConfigService\Settings to determine which operations to perform. You can edit these files indirectly using the Ec2 Service Properties dialog box, or directly using an XML editor or a text editor. However, there are some advanced settings that aren't available in the Ec2 Service Properties dialog box, so you must edit those entries directly.

If you create an AMI from an instance after updating its settings, the new settings are applied to any instance that's launched from the new AMI. For information about creating an AMI, see Creating an Amazon EBS-Backed Windows AMI.

Overview of EC2Config Tasks

EC2Config runs initial startup tasks when the instance is first started and then disables them. To run these tasks again, you must explicitly enable them prior to shutting down the instance, or by running Sysprep manually. These tasks are as follows:

  • Set a random, encrypted password for the administrator account.

  • Generate and install the host certificate used for Remote Desktop Connection.

  • Dynamically extend the operating system partition to include any unpartitioned space.

  • Execute the specified user data (and Cloud-Init, if it's installed).

EC2Config performs the following tasks every time the instance starts:

  • Set the computer host name to match the private DNS name (this task is disabled by default and must be enabled in order to run at instance start).

  • Configure the key management server (KMS), check for Windows activation status, and activate Windows as necessary.

  • Format and mount any Amazon EBS volumes and instance store volumes, and map volume names to drive letters.

  • Write event log entries to the console to help with troubleshooting (this task is disabled by default and must be enabled in order to run at instance start).

  • Write to the console that Windows is ready.

  • Add a custom route to the primary network adapter to enable the following IP addresses when multiple NICs are attached: 169.254.169.250, 169.254.169.251, and 169.254.169.254. These addresses are used by Windows Activation and when you access instance metadata.

EC2Config performs the following task every time a user logs in:

  • Display wallpaper information to the desktop background.

While the instance is running, you can request that EC2Config perform the following task on demand:

EC2Config creates a WMI object that you can use to detect when Windows is ready. You can get the value of ConfigurationComplete as follows, and test whether it is true.

(Get-WmiObject -Namespace root\Amazon -Class EC2_ConfigService).ConfigurationComplete

Ec2 Service Properties

The following procedure describes how to use the Ec2 Service Properties dialog box to enable or disable settings.

To change settings using the Ec2 Service Properties dialog box

  1. Launch and connect to your Windows instance.

  2. From the Start menu, click All Programs, and then click EC2ConfigService Settings.

  3. On the General tab of the Ec2 Service Properties dialog box, you can enable or disable the following settings.

    Set Computer Name

    If this setting is enabled (it is disabled by default), the host name is compared to the current internal IP address at each boot; if the host name and internal IP address do not match, the host name is reset to contain the internal IP address and then the system reboots to pick up the new host name. To set your own host name, or to prevent your existing host name from being modified, do not enable this setting.

    User Data

    User data execution enables you to inject scripts into the instance metadata during the first launch. From an instance, you can read user data at http://169.254.169.254/latest/user-data/. This information remains static for the life of the instance, persisting when the instance is stopped and started, until it is terminated.

    If you use a large script, we recommend that you use user data to download the script, and then execute it.

    For EC2Config to execute user data, you must enclose the lines of the script within one of the following special tags:

    <script></script>

    Run any command that you can run at the cmd.exe prompt.

    Example: <script>dir > c:\test.log</script>

    <powershell></powershell>

    Run any command that you can run at the Windows PowerShell prompt.

    If you use an AMI that includes the AWS Tools for Windows PowerShell, you can also use those cmdlets. If you specify an IAM role when you launch your instance, then you don't need to specify credentials to the cmdlets, as applications that run on the instance can use the role's credentials to access AWS resources such as Amazon S3 buckets.

    Example: <powershell>Read-S3Object -BucketName myS3Bucket -Key myFolder/myFile.zip -File c:\destinationFile.zip</powershell>

    You can separate the commands in a script using line breaks.

    If EC2Config finds script or powershell tags, it saves the script to a batch or PowerShell file in its /Scripts folder. It runs these files when the instance starts. If both script and powershell tags are present, it runs the batch script first and the PowerShell script next, regardless of the order in which they appear.

    The /Logs folder contains output from the standard output and standard error streams.

    EC2Config expects the user data to be available in base64 encoding. If the user data is not available in base64 encoding, EC2Config logs an error about being unable to find script or powershell tags to execute. If your encoding is not correct, the following is an example that sets the encoding using PowerShell.

    $UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))

    Initial Boot

    By default, all Amazon AMIs have user data execution enabled for the initial boot. If you click Shutdown with Sysprep in EC2Config, user data execution is enabled, regardless of the setting of the User Data check box.

    User data execution happens under the local administrator user only when a random password is generated. This is because EC2Config generates the password and is aware of the credentials briefly (prior to sending to the console). EC2Config doesn't store or track password changes, so when you don't generate a random password, user data execution is performed by the EC2Config service account.

    Subsequent Boots

    Because Amazon AMIs automatically disable user data execution after the initial boot, you must do one of the following to make user data persist across reboots:

    • Programmatically create a scheduled task to run at system start using schtasks.exe /Create, and point the scheduled task to the user data script (or another script) at C:\Program Files\Amazon\Ec2ConfigServer\Scripts\UserScript.ps1.

    • Programmatically enable the user data plug-in in Config.xml using a script similar to the following:

      <powershell>
      $EC2SettingsFile="C:\Program Files\Amazon\Ec2ConfigService\Settings\Config.xml"
      $xml = [xml](get-content $EC2SettingsFile)
      $xmlElement = $xml.get_DocumentElement()
      $xmlElementToModify = $xmlElement.Plugins
      
      foreach ($element in $xmlElementToModify.Plugin)
      {
          if ($element.name -eq "Ec2SetPassword")
          {
              $element.State="Enabled"
          }
          elseif ($element.name -eq "Ec2HandleUserData")
          {
              $element.State="Enabled"
          }
      }
      $xml.Save($EC2SettingsFile)
      </powershell>
    • Starting with EC2Config version 2.1.10, you can use <persist>true</persist> to enable the plug-in after user data execution.

      <powershell>
          insert script here
      </powershell>
      <persist>true</persist>
    Event Log

    Use this setting to display event log entries on the console during boot for easy monitoring and debugging.

    Click Settings to specify filters for the log entries sent to the console. By default, the three most recent error entries from the system event log are sent to the console.

    CloudWatch Logs

    Starting with EC2Config version 2.2.5 (version 2.2.6 or later is recommended), you can export all Windows Server messages in the System log, Security log, Application log, and IIS log to CloudWatch Logs and monitor them using CloudWatch metrics. EC2Config version 2.2.10 or later adds the ability to export any event log data, Event Tracing (Windows) data, or text-based log files to CloudWatch Logs. In addition, you can also export performance counter data to CloudWatch For more information, see Monitoring System, Application, and Custom Log Files in the Amazon CloudWatch Developer Guide.

    1. Select Enable CloudWatch integration, and then click OK.

    2. Edit the \Amazon\Ec2ConfigService\Settings\AWS.EC2.Windows.CloudWatch.json file and configure the types of logs you want to send to CloudWatch Logs. For more information, see Sending Performance Counters to CloudWatch and Logs to CloudWatch Logs.

    Wallpaper Information

    Use this setting to display system information on the desktop background. The following is an example of the information displayed on the desktop background.

    The information displayed on the desktop background is controlled by the settings file EC2ConfigService\Settings\WallpaperSettings.xml.

  4. Click the Storage tab. You can enable or disable the following settings.

    Root Volume

    This setting dynamically extends Disk 0/Volume 0 to include any unpartitioned space. This can be useful when the instance is booted from a root device volume that has a custom size.

    Initialize Drives

    This setting formats and mounts all instance store volumes attached to the instance during start.

    Drive Letter Mapping

    The system maps the volumes attached to an instance to drive letters. For Amazon EBS volumes, the default is to assign drive letters going from D: to Z:. For instance store volumes, the default depends on the driver. Citrix PV drivers assign instance store volumes drive letters going from Z: to A:. Red Hat drivers assign instance store volumes drive letters going from D: to Z:.

    To choose the drive letters for your volumes, click Mappings. In the DriveLetterSetting dialog box, specify the Volume Name and Drive Letter values for each volume, and then click OK. We recommend that you select drive letters that avoid conflicts with drive letters that are likely to be in use, such as drive letters in the middle of the alphabet.

    After you specify a drive letter mapping and attach a volume with same label as one of the volume names that you specified, EC2Config automatically assigns your specified drive letter to that volume. However, the drive letter mapping fails if the drive letter is already in use. Note that EC2Config doesn't change the drive letters of volumes that were already mounted when you specified the drive letter mapping.

  5. To save your settings and continue working on them later, click OK to close the Ec2 Service Properties dialog box.

    Otherwise, if you have finished customizing your instance and are ready to create your AMI from this instance, click the Image tab.

    Select an option for the Administrator password, and then click Shutdown with Sysprep or Shutdown without Sysprep. EC2Config edits the settings files based on the password option that you selected.

    • Random—EC2Config generates a password, encrypts it with user's key, and displays the encrypted password to the console. We disable this setting after the first launch so that this password persists if the instance is rebooted or stopped and started.

    • Specify—The password is stored in the Sysprep answer file in unencrypted form (clear text). When Sysprep runs next, it sets the Administrator password. If you shut down now, the password is set immediately. When the service starts again, the Administrator password is removed. It's important to remember this password, as you can't retrieve it later.

    • Keep Existing—The existing password for the Administrator account doesn't change when Sysprep is run or EC2Config is restarted. It's important to remember this password, as you can't retrieve it later.

    When you are asked to confirm that you want to run Sysprep and shut down the instance, click Yes. You'll notice that EC2Config runs Sysprep. Next, you are logged off the instance, and the instance is shut down. If you check the Instances page in the Amazon EC2 console, the instance state changes from running to stopping, and then finally to stopped. At this point, it's safe to create an AMI from this instance.

    You can manually invoke the Sysprep tool from the command line using the following command:

    C:\> %ProgramFiles%\Amazon\Ec2ConfigService\ec2config.exe -sysprep

    However, you must be very careful that the XML file options specified in the Ec2ConfigService\Settings folder are correct; otherwise, you might not be able to connect to the instance. For more information about the settings files, see EC2Config Settings Files. For an example of configuring and then running Sysprep from the command line, see Ec2ConfigService\Scripts\InstallUpdates.ps1.

EC2Config Settings Files

The settings files control the operation of the EC2Config service. These files are located in the Ec2ConfigService\Settings directory:

  • ActivationSettings.xml—Controls product activation using a key management server (KMS).

  • AWS.EC2.Windows.CloudWatch.json—Controls which performance counters to send to CloudWatch and which logs to send to CloudWatch Logs. For more information about how to change the settings in this file, see Sending Performance Counters to CloudWatch and Logs to CloudWatch Logs.

  • BundleConfig.xml—Controls how EC2Config prepares an instance for AMI creation.

  • Config.xml—Controls the primary settings.

  • DriveLetterConfig.xml—Controls drive letter mappings.

  • EventLogConfig.xml—Controls the event log information that's displayed on the console while the instance is booting.

  • WallpaperSettings.xml—Controls the information that's displayed on the desktop background.

ActivationSettings.xml

This file contains settings that control product activation. When Windows boots, the EC2Config service checks whether Windows is already activated. If Windows is not already activated, it attempts to activate Windows by searching for the specified KMS server.

  • SetAutodiscover—Indicates whether to detect a KMS automatically.

  • TargetKMSServer—Stores the private IP address of a KMS. The KMS must be in the same region as your instance.

  • DiscoverFromZone—Discovers the KMS server from the specified DNS zone.

  • ReadFromUserData—Gets the KMS server from UserData.

  • LegacySearchZones—Discovers the KMS server from the specified DNS zone.

  • DoActivate—Attempts activation using the specified settings in the section. This value can be true or false.

  • LogResultToConsole—Displays the result to the console.

BundleConfig.xml

This file contains settings that control how EC2Config prepares an instance for AMI creation.

  • AutoSysprep—Indicates whether to use Sysprep automatically. Change the value to Yes to use Sysprep.

  • SetRDPCertificate—Sets a self-signed certificate to the Remote Desktop server running on a Windows 2003 instance. This enables you to securely RDP into the instances. Change the value to Yes if the new instances should have the certificate.

    This setting is not used with Windows Server 2008 or Windows Server 2012 instances because they can generate their own certificates.

  • SetPasswordAfterSysprep—Sets a random password on a newly launched instance, encrypts it with the user launch key, and outputs the encrypted password to the console. Change the value of this setting to No if the new instances should not be set to a random encrypted password.

Config.xml

Plug-ins

  • Ec2SetPassword—Generates a random encrypted password each time you launch an instance. This feature is disabled by default after the first launch so that reboots of this instance don't change a password set by the user. Change this setting to Enabled to continue to generate passwords each time you launch an instance.

    This setting is important if you are planning to create an AMI from your instance.

  • Ec2SetComputerName—Sets the host name of the instance to a unique name based on the IP address of the instance and reboots the instance. To set your own host name, or prevent your existing host name from being modified, you must disable this setting.

  • Ec2InitializeDrives—Initializes and formats all instance store volumes during startup. This feature is enabled by default and initializes and mounts the instance store volumes as drives D:, E:, and so on. For more information about instance store volumes, see Amazon EC2 Instance Store.

  • Ec2EventLog—Displays event log entries in the console. By default, the three most recent error entries from the system event log are displayed. To specify the event log entries to display, edit the EventLogConfig.xml file located in the EC2ConfigService\Settings directory. For information about the settings in this file, see Eventlog Key in the MSDN Library.

  • Ec2ConfigureRDP—Sets up a self-signed certificate on the instance, so users can securely access the instance using Remote Desktop. This feature is disabled on Windows Server 2008 and Windows Server 2012 instances because they can generate their own certificates.

  • Ec2OutputRDPCert—Displays the Remote Desktop certificate information to the console so that the user can verify it against the thumbprint.

  • Ec2SetDriveLetter—Sets the drive letters of the mounted volumes based on user-defined settings. By default, when an Amazon EBS volume is attached to an instance, it can be mounted using the drive letter on the instance. To specify your drive letter mappings, edit the DriveLetterConfig.xml file located in the EC2ConfigService\Settings directory.

  • Ec2WindowsActivate—Indicates whether to search through the DNS Suffix List for appropriate KMS entries. When the appropriate KMS entries are found, the plug-in sets your activation server to the first server to respond to the request successfully. Starting with Windows Server 2008 R2, Windows Server is able to search the suffix list automatically. Otherwise, the plug-in performs this search manually.

    To modify the KMS settings, edit the ActivationSettings.xml file located in the EC2ConfigService\Settings directory.

  • Ec2DynamicBootVolumeSize—Extends Disk 0/Volume 0 to include any unpartitioned space.

  • Ec2HandleUserData—Creates and executes scripts created by the user on the first launch of an instance after Sysprep is run. Commands wrapped in script tags are saved to a batch file, and commands wrapped in PowerShell tags are saved to a .ps1 file.

Global Settings

  • ManageShutdown—Ensures that instances launched from instance store-backed AMIs do not terminate while running Sysprep.

  • SetDnsSuffixList—Sets the DNS suffix of the network adapter for Amazon EC2. This allows DNS resolution of servers running in Amazon EC2 without providing the fully qualified domain name.

  • WaitForMetaDataAvailable—Ensures that the EC2Config service will wait for metadata to be accessible and the network available before continuing with the boot. This check ensures that EC2Config can obtain information from metadata for activation and other plug-ins.

  • ShouldAddRoutes—Adds a custom route to the primary network adapter to enable the following IP addresses when multiple NICs are attached: 169.254.169.250, 169.254.169.251, and 169.254.169.254. These addresses are used by Windows Activation and when you access instance metadata.

  • RemoveCredentialsfromSyspreponStartup—Removes the administrator password from Sysprep.xml the next time the service starts. To ensure that this password persists, edit this setting.

DriveLetterConfig.xml

This file contains settings that control drive letter mappings. By default, a volume can be mapped to any available drive letter. You can mount a volume to a particular drive letter as follows.

<?xml version="1.0" standalone="yes"?>
<DriveLetterMapping>
  <Mapping>
    <VolumeName></VolumeName>
    <DriveLetter></DriveLetter>
  </Mapping>
  . . .
  <Mapping>
    <VolumeName></VolumeName>
    <DriveLetter></DriveLetter>
  </Mapping>
</DriveLetterMapping>
  • VolumeName—The volume label. For example, My Volume. To specify a mapping for an instance storage volume, use the label Temporary Storage X, where X is a number from 0 to 25.

  • DriveLetter—The drive letter. For example, M:. The mapping fails if the drive letter is already in use.

EventLogConfig.xml

This file contains settings that control the event log information that's displayed on the console while the instance is booting. By default, we display the three most recent error entries from the System event log.

  • Category—The event log key to monitor.

  • ErrorType—The event type (for example, Error, Warning, Information.)

  • NumEntries—The number of events stored for this category.

  • LastMessageTime—To prevent the same message from being pushed repeatedly, the service updates this value every time it pushes a message.

  • AppName—The event source or application that logged the event.

WallpaperSettings.xml

This file contains settings that control the information that's displayed on the desktop background. The following information is displayed by default.

  • Hostname—Displays the computer name.

  • Instance ID—Displays the ID of the instance.

  • Public IP Address—Displays the public IP address of the instance.

  • Private IP Address—Displays the private IP address of the instance.

  • Availability Zone—Displays the Availability Zone in which the instance is running.

  • Instance Size—Displays the type of instance.

  • Architecture—Displays the setting of the PROCESSOR_ARCHITECTURE environment variable.

  • AddMemory—Displays the system memory, in GB.

  • AddECU—Displays the processing power, in ECU.

  • AddIO—Displays the I/O performance.

You can remove any of the information that's displayed by default by deleting its entry. You can add additional instance metadata to display as follows.

<WallpaperInformation>
  <name>display_name</name>
  <source>metadata</source>
  <identifier>meta-data/path</identifier>
</WallpaperInformation>

You can add additional System environment variables to display as follows.

<WallpaperInformation>
  <name>display_name</name>
  <source>EnvironmentVariable</source>
  <identifier>variable-name</identifier>
</WallpaperInformation>

Sending Performance Counters to CloudWatch and Logs to CloudWatch Logs

Starting with EC2Config version 2.2.5 (version 2.2.6 or later is recommended), you can export all Windows Server messages in the system, security, application, and IIS logs to CloudWatch Logs and monitor them using CloudWatch metrics. EC2Config version 2.2.10 or later adds the ability to export any event log data, Event Tracing (Windows), or text-based log files to CloudWatch Logs. In addition, you can also export performance counter data to CloudWatch.

To set up EC2Config to send data to CloudWatch Logs, complete the following steps:

Step 1: Enable CloudWatch Logs Integration

  1. Launch and connect to your Windows instance.

  2. From the Start menu, click All Programs, and then click EC2ConfigService Settings.

  3. On the General tab of the Ec2 Service Properties dialog box, under CloudWatch Logs, select Enable CloudWatch Logs integration, and then click OK.

Note

You can also enable CloudWatch Logs by adding the following script to the user data field when you launch an instance. EC2Config will run this script every time your instance is restarted to make sure that CloudWatch Logs integration is enabled. To run this script only when an instance is first launched, remove <persist>true</persist> from the script.

<powershell>
$EC2SettingsFile="C:\Program Files\Amazon\Ec2ConfigService\Settings\Config.xml"
$xml = [xml](get-content $EC2SettingsFile)
$xmlElement = $xml.get_DocumentElement()
$xmlElementToModify = $xmlElement.Plugins

foreach ($element in $xmlElementToModify.Plugin)
{
    if ($element.name -eq "AWS.EC2.Windows.CloudWatch.PlugIn")
    {
        $element.State="Enabled"
    }
}
$xml.Save($EC2SettingsFile)
</powershell>
<persist>true</persist>

Step 2: Configure the Credentials for CloudWatch and CloudWatch Logs

To set the credentials, region, and metric namespace for CloudWatch

This section of the AWS.EC2.Windows.CloudWatch.json file defines the credentials, region, and metric namespace that comprise the destination where your data is sent. You can add additional sections with unique IDs (for example, "CloudWatch2", CloudWatch3", etc.) and specify a different region for each new ID to send the same data to different locations.

Note

You only need to set CloudWatch credentials if you plan to send performance counters to CloudWatch.

  1. Open the C:\Program Files\Amazon\Ec2ConfigService\Settings\AWS.EC2.Windows.CloudWatch.json file, and locate the CloudWatch section.

    To download a sample of the file, see AWS.EC2.Windows.CloudWatch.json.

    {
        "Id": "CloudWatch",
        "FullName": "AWS.EC2.Windows.CloudWatch.CloudWatch.CloudWatchOutputComponent,AWS.EC2.Windows.CloudWatch",
        "Parameters": {
            "AccessKey": "",
            "SecretKey": "",
            "Region": "us-west-1",
            "NameSpace": "Windows/Default"
        }
    },
  2. In the AccessKey parameter, enter your access key ID. This is not necessary if you launched your instance using an IAM role. For more information, see IAM Roles for Amazon EC2.

  3. In the SecretKey parameter, enter your secret access key. This is not necessary if you launched your instance using an IAM role. For more information, see IAM Roles for Amazon EC2.

  4. In the Region parameter, enter the region where you want EC2Config to send log data. You can specify us-east-1, us-west-2, eu-west-1, eu-central-1, ap-southeast-1, ap-southeast-2, or ap-northeast-1. Although you can send performance counters to a different region from where you send your log data, we recommend that you set this parameter to the same region where your instance is running.

  5. In the NameSpace parameter, enter the metric namespace where you want performance counter data to be written in CloudWatch.

To set the credentials, region, log group, and log stream for CloudWatch Logs

This section of the AWS.EC2.Windows.CloudWatch.json file defines the credentials, region, log group name and log stream namespace that comprise the destination where your data is sent. You can add additional sections with unique IDs (for example, "CloudWatchLogs2", CloudWatchLogs3", etc.) and specify a different region for each new ID to send the same data to different locations.

  1. Open the C:\Program Files\Amazon\Ec2ConfigService\Settings\AWS.EC2.Windows.CloudWatch.json file, and locate the CloudWatchLogs section.

    {
        "Id": "CloudWatchLogs",
        "FullName": "AWS.EC2.Windows.CloudWatch.CloudWatchLogsOutput,AWS.EC2.Windows.CloudWatch",
        "Parameters": {
            "AccessKey": "",
            "SecretKey": "",
            "Region": "us-east-1",
            "LogGroup": "Default-Log-Group",
            "LogStream": "{instance_id}"
        }
    },
  2. In the AccessKey parameter, enter your access key ID. This is not necessary if you launched your instance using an IAM role. For more information, see IAM Roles for Amazon EC2.

  3. In the SecretKey parameter, enter your secret access key. This is not necessary if you launched your instance using an IAM role. For more information, see IAM Roles for Amazon EC2.

  4. In the Region parameter, enter the region where you want EC2Config to send log data. You can specify us-east-1, us-west-2, eu-west-1, eu-central-1, ap-southeast-1, ap-southeast-2, or ap-northeast-1.

  5. In the LogGroup parameter, enter the name for your log group. This is the same name that will be displayed on the Log Groups screen in the CloudWatch console.

  6. In the LogStream parameter, enter the destination log stream. If you use {instance_id}, the default, EC2Config uses the instance ID of this instance as the log stream name.

    If you enter a log stream name that doesn't already exist, CloudWatch Logs automatically creates it for you. You can use a literal string or predefined variables ({instance_id} or {hostname}, or a combination of both to define a log stream name.

    The log stream name specified in this parameter appears on the Log Groups > Streams for <YourLogStream> screen in the CloudWatch console.

Step 3: Configure the Performance Counters and Logs to Send to CloudWatch and CloudWatch Logs

To configure the performance counters to send to CloudWatch

You can select any performance counters that are available in perfmon.exe. You can select different categories to upload to CloudWatch as metrics, such as .NET CLR Data, ASP.NET Applications, HTTP Service, Memory, or Process and Processors.

For each performance counter that you want to upload to CloudWatch, copy the PerformanceCounter section and change the Id parameter to make it unique (e.g., "PerformanceCounter2") and update the other parameters as necessary.

Note

You must configure the credentials for CloudWatch in Step 2: Configure the Credentials for CloudWatch and CloudWatch Logs.

  1. Locate the PerformanceCounter section.

    {
        "Id": "PerformanceCounter",
        "FullName": "AWS.EC2.Windows.CloudWatch.PerformanceCounterComponent.PerformanceCounterInputComponent,AWS.EC2.Windows.CloudWatch",
        "Parameters": {
            "CategoryName": "Memory",
            "CounterName": "Available MBytes",
            "InstanceName": "",
            "MetricName": "AvailableMemory",
            "Unit": "Megabytes",
            "DimensionName": "",
            "DimensionValue": ""
        }
    },
  2. In the CategoryName parameter, enter the performance counter category.

    1. To find the available categories and counters, open perfmon.exe.

    2. Click Monitoring Tools, and then click Performance Monitor.

    3. In the results pane, click the green + (plus) button.

      The categories and counters are listed in the Add Counters dialog box.

  3. In the CounterName parameter, enter the name of the performance counter.

  4. In the InstanceName parameter, enter the name of instance. Do not use an asterisk (*) to indicate all instances because each performance counter component only supports one metric. You can, however use _Total.

  5. In the MetricName parameter, enter the CloudWatch metric that you want performance data to appear under.

  6. In the Unit parameter, enter the appropriate unit of measure for the metric:

    Seconds | Microseconds | Milliseconds | Bytes | Kilobytes | Megabytes | Gigabytes | Terabytes | Bits | Kilobits | Megabits | Gigabits | Terabits | Percent | Count | Bytes/Second | Kilobytes/Second | Megabytes/Second | Gigabytes/Second | Terabytes/Second | Bits/Second | Kilobits/Second | Megabits/Second | Gigabits/Second | Terabits/Second | Count/Second | None.

  7. (optional) You can enter a dimension name and value in the DimensionName and DimensionValue parameters to specify a dimension for your metric. These parameters provide another view when listing metrics. You can also use the same dimension for multiple metrics so that you can view all metrics belonging to a specific dimension.

To send Windows application event log data to CloudWatch Logs

  1. Locate the ApplicationEventLog section.

    {
        "Id": "ApplicationEventLog",
        "FullName": "AWS.EC2.Windows.CloudWatch.EventLog.EventLogInputComponent,AWS.EC2.Windows.CloudWatch",
        "Parameters": {
            "LogName": "Application",
            "Levels": "1"
        }
    },
  2. In the Levels parameter, enter one of the following values:

    1 - Only error messages uploaded.

    2 - Only warning messages uploaded.

    4 - Only information messages uploaded.

    You can add values together to include more than one type of message. For example, 3 means that error messages (1) and warning messages (2) get uploaded. A value of 7 means that error messages (1), warning messages (2), and information messages (4) get uploaded.

To send security log data to CloudWatch Logs

  1. Locate the SecurityEventLog section.

    {
        "Id": "SecurityEventLog",
        "FullName": "AWS.EC2.Windows.CloudWatch.EventLog.EventLogInputComponent,AWS.EC2.Windows.CloudWatch",
        "Parameters": {
            "LogName": "Security",
            "Levels": "7"
        }
    },
  2. In the Levels parameter, enter one of the following values:

    1 - Only error messages uploaded.

    2 - Only warning messages uploaded.

    4 - Only information messages uploaded.

    You can add values together to include more than one type of message. For example, 3 means that error messages (1) and warning messages (2) get uploaded. A value of 7 means that error messages (1), warning messages (2), and information messages (4) get uploaded.

To send system event log data to CloudWatch Logs

  1. Locate the SystemEventLog section.

    {
        "Id": "SystemEventLog",
        "FullName": "AWS.EC2.Windows.CloudWatch.EventLog.EventLogInputComponent,AWS.EC2.Windows.CloudWatch",
        "Parameters": {
            "LogName": "System",
            "Levels": "7"
        }
    },
  2. In the Levels parameter, enter one of the following values:

    1 - Only error messages uploaded.

    2 - Only warning messages uploaded.

    4 - Only information messages uploaded.

    You can add values together to include more than one type of message. For example, 3 means that error messages (1) and warning messages (2) get uploaded. A value of 7 means that error messages (1), warning messages (2), and information messages (4) get uploaded.

To send other types of event log data to CloudWatch Logs

In addition to the application, system, and security logs, you can upload other types of event logs.

  1. In the AWS.EC2.Windows.CloudWatch.json file, add a new section.

    {
        "Id": "",
        "FullName": "AWS.EC2.Windows.CloudWatch.EventLog.EventLogInputComponent,AWS.EC2.Windows.CloudWatch",
        "Parameters": {
            "LogName": "",
            "Levels": "7"
        }
    },
  2. In the Id parameter, enter a name for the log you want to upload (e.g., WindowsBackup).

  3. In the LogName parameter, enter the name of the log you want to upload.

    1. To find the name of the log, in Event Viewer, in the navigation pane, click Applications and Services Logs.

    2. In the list of logs, right-click the log you want to upload (e.g., Microsoft>Windows>Backup>Operational), and then click Create Custom View.

    3. In the Create Custom View dialog box, click the XML tab. The LogName is in the <Select Path=> tag (e.g., Microsoft-Windows-Backup). Copy this text into the LogName parameter in the AWS.EC2.Windows.CloudWatch.json file.

  4. In the Levels parameter, enter one of the following values:

    1 - Only error messages uploaded.

    2 - Only warning messages uploaded.

    4 - Only information messages uploaded.

    You can add values together to include more than one type of message. For example, 3 means that error messages (1) and warning messages (2) get uploaded. A value of 7 means that error messages (1), warning messages (2), and information messages (4) get uploaded.

To send Event Tracing (Windows) data to CloudWatch Logs

ETW (Event Tracing for Windows) provides an efficient and detailed logging mechanism that applications can write logs to. Each ETW is controlled by a session manager that can start and stop the logging session. Each session has a provider and one or more consumers.

  1. Locate the ETW section.

    {
        "Id": "ETW",
        "FullName": "AWS.EC2.Windows.CloudWatch.EventLog.EventLogInputComponent,AWS.EC2.Windows.CloudWatch",
        "Parameters": {
            "LogName": "Microsoft-Windows-WinINet/Analytic",
            "Levels": "7"
        }
    },
  2. In the LogName parameter, enter the name of the log you want to upload.

    1. To find the name of the log, in Event Viewer, on the View menu, click Show Analytic and Debug Logs.

    2. In the navigation pane, click Applications and Services Logs.

    3. In the list of ETW logs, right-click the log you want to upload, and then click Enable Log.

    4. Right-click the log again, and click Create Custom View.

    5. In the Create Custom View dialog box, click the XML tab. The LogName is in the <Select Path=> tag (e.g., Microsoft-Windows-WinINet/Analytic). Copy this text into the LogName parameter in the AWS.EC2.Windows.CloudWatch.json file.

  3. In the Levels parameter, enter one of the following values:

    1 - Only error messages uploaded.

    2 - Only warning messages uploaded.

    4 - Only information messages uploaded.

    You can add values together to include more than one type of message. For example, 3 means that error messages (1) and warning messages (2) get uploaded. A value of 7 means that error messages (1), warning messages (2), and information messages (4) get uploaded.

To send custom logs (any text-based log file) to CloudWatch Logs

  1. Locate the CustomLogs section.

    {
        "Id": "CustomLogs",
        "FullName": "AWS.EC2.Windows.CloudWatch.CustomLog.CustomLogInputComponent,AWS.EC2.Windows.CloudWatch",
        "Parameters": {
            "LogDirectoryPath": "C:\\CustomLogs\\",
            "TimestampFormat": "MM/dd/yyyy HH:mm:ss",
            "Encoding": "UTF-8",
            "Filter": "",
            "CultureName": "en-US",
            "TimeZoneKind": "Local",
            "LineCount": "1"
        }
    },
  2. In the LogDirectoryPath parameter, enter the path where logs are stored on your instance.

  3. In the TimestampFormat parameter, enter the timestamp format you want to use. For a list of supported values, see the Custom Date and Time Format Strings topic on MSDN.

    Note

    Your source log file must have the timestamp at the beginning of each log line.

  4. In the Encoding parameter, enter the file encoding to use (e.g., UTF-8). For a list of supported values, see the Encoding Class topic on MSDN.

    Note

    Use the encoding name, not the display name, as the value for this parameter.

  5. (optional) In the Filter parameter, enter the prefix of log names. Leave this parameter blank to monitor all files. For a list of supported values, see the FileSystemWatcherFilter Property topic on MSDN.

  6. (optional) In the CultureName parameter, enter the locale where the timestamp is logged. If CultureName is blank, it defaults to the same locale currently used by your Windows instance. For a list of supported values, see the National Language Support (NLS) API Reference topic on MSDN.

    Note

    The div, div-MV, hu, and hu-HU values are not supported.

  7. (optional) In the TimeZoneKind parameter, enter Local or UTC. You can set this to provide time zone information when no time zone information is included in your log’s timestamp. If this parameter is left blank and if your timestamp doesn’t include time zone information, CloudWatch Logs defaults to the local time zone. This parameter is ignored if your timestamp already contains time zone information.

  8. (optional) In the LineCount parameter, enter the number of lines in the header to identify the log file. For example, IIS log files have virtually identical headers. You could enter 3, which would read the first three lines of the log file's header to identify it. In IIS log files, the third line is the date and time stamp, which is different between log files.

To send IIS log data to CloudWatch Logs

  1. Locate the IISLog section.

    {
        "Id": "IISLogs",
        "FullName": "AWS.EC2.Windows.CloudWatch.CustomLog.CustomLogInputComponent,AWS.EC2.Windows.CloudWatch",
        "Parameters": {
            "LogDirectoryPath": "C:\\inetpub\\logs\\LogFiles\\W3SVC1",
            "TimestampFormat": "yyyy-MM-dd HH:mm:ss",
            "Encoding": "UTF-8",
            "Filter": "",
            "CultureName": "en-US",
            "TimeZoneKind": "UTC",
            "LineCount": "3"
        }
    },
  2. In the LogDirectoryPath parameter, enter the folder where IIS logs are stored for an individual site (e.g., C:\\inetpub\\logs\\LogFiles\\W3SVCn).

    Note

    Only W3C log format is supported. IIS, NCSA, and Custom formats are not supported.

  3. In the TimestampFormat parameter, enter the timestamp format you want to use. For a list of supported values, see the Custom Date and Time Format Strings topic on MSDN.

  4. In the Encoding parameter, enter the file encoding to use (e.g., UTF-8). For a list of supported values, see the Encoding Class topic on MSDN.

    Note

    Use the encoding name, not the display name, as the value for this parameter.

  5. (optional) In the Filter parameter, enter the prefix of log names. Leave this parameter blank to monitor all files. For a list of supported values, see the FileSystemWatcherFilter Property topic on MSDN.

  6. (optional) In the CultureName parameter, enter the locale where the timestamp is logged. If CultureName is blank, it defaults to the same locale currently used by your Windows instance. For a list of supported values, see the National Language Support (NLS) API Reference topic on MSDN.

    Note

    The div, div-MV, hu, and hu-HU values are not supported.

  7. (optional) In the TimeZoneKind parameter, enter Local or UTC. You can set this to provide time zone information when no time zone information is included in your log’s timestamp. If this parameter is left blank and if your timestamp doesn’t include time zone information, CloudWatch Logs defaults to the local time zone. This parameter is ignored if your timestamp already contains time zone information.

  8. (optional) In the LineCount parameter, enter the number of lines in the header to identify the log file. For example, IIS log files have virtually identical headers. You could enter 3, which would read the first three lines of the log file's header to identify it. In IIS log files, the third line is the date and time stamp, which is different between log files.

Step 4: Configure the Flow Control

In order to send performance counter data to CloudWatch or to send log data to CloudWatch Logs, each data type must have a corresponding destination listed in the Flows section. For example, to send a performance counter defined in Step 3: Configure the Performance Counters and Logs to Send to CloudWatch and CloudWatch Logs to the CloudWatch destination defined in Step 2: Configure the Credentials for CloudWatch and CloudWatch Logs, you would enter "PerformanceCounter,CloudWatch" in the Flows section. Similarly, to send the custom log, ETW log, and system log to CloudWatch Logs, you would enter "(CustomLogs, ETW,SystemEventLog),CloudWatchLogs". In addition, you can send the same performance counter or log file to more than one destination. For example, to send the application log to two different destinations that you defined in Step 2: Configure the Credentials for CloudWatch and CloudWatch Logs, you would enter "ApplicationEventLog,(CloudWatchLogs, CloudWatchLogs2)" in the Flows section.

  1. Locate the Flows section.

    "Flows": {
        "Flows": [
          "PerformanceCounter,CloudWatch",
          "(PerformanceCounter,PerformanceCounter2), CloudWatch2",
          "(CustomLogs, ETW, SystemEventLog),CloudWatchLogs",
          "CustomLogs, CloudWatchLogs2",
          "ApplicationEventLog,(CloudWatchLogs, CloudWatchLogs2)"
        ]
    }
  2. In the Flows parameter, enter each data type that you want to upload (e.g., ApplicationEventLog) and destination where you want to send it (e.g., CloudWatchLogs).

Step 5: Restart EC2Config

After you're finished updating the C:\Program Files\Amazon\Ec2ConfigService\Settings\AWS.EC2.Windows.CloudWatch.json file, you should restart EC2Config. For more information, see Stopping, Restarting, Deleting, or Uninstalling EC2Config.

Troubleshooting CloudWatch Logs in EC2Config

If you're experiencing trouble with uploading performance counters or logs, the first place you should check is the C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2ConfigLog.txt file. Some of the most commonly encountered problems are listed below.

I cannot see logs in the CloudWatch console.

Please verify that you are using EC2Config version 2.2.6 or later. If you are still using EC2Config version 2.2.5, use the following steps to solve the issue:

  1. In the Services Microsoft Management Console (MMC) snap-in, restart the EC2Config service. To open the Services snap-in, click the Start menu and then in the Run box, type services.msc.

  2. Sign in to the AWS Management Console and open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

  3. On the navigation bar, select the appropriate region.

  4. In the navigation pane, click Logs.

  5. In the contents pane, in the Expire Events After column, click the retention setting for the log group that you just created.

  6. In the Edit Retention dialog box, in the New Retention list, select 10 years (3653 days), and then click OK.

    Note

    You can also set log retention (in days) using the following Windows PowerShell command:

    Write-CWLRetentionPolicy-LogGroupName Default-Log-Group -RetentionInDays 3653
The Enable CloudWatch Logs integration check box won't stay selected after I click OK and then reopen EC2Config.

This issue might occur if you've performed an upgrade from an earlier version of EC2Config to version 2.2.5. To resolve this issue, install version 2.2.6 or later.

I see errors like Log events cannot be more than 2 hours in the future or InvalidParameterException.

This error might occur if you are using EC2Config version 2.2.5 and your instance's time zone falls between UTC-12:00 and UTC-02:00. To resolve this issue, install EC2Config version 2.2.6 or later.

I cannot see SQL Server logs in the CloudWatch console and see this error in Ec2ConfigLog.txt [Error] Exception occurred: Index and length must refer to a location within the string. Parameter name: length.

To resolve this issue, install EC2Config version 2.2.11 or later.

I'm running ten or fewer workflows and EC2Config is using over 500MB of memory.

To resolve this issue, install version 2.3.313 or later.

Only the first one or two IIS logs are uploaded and then no other IIS logs get uploaded.

Update the IISlog section of the C:\Program Files\Amazon\Ec2ConfigService\Settings\AWS.EC2.Windows.CloudWatch.json file and set the LineCount parameter to 3, which would read the first three lines of the log file's header to identify it. In IIS log files, the third line is the date and time stamp, which is different between log files.

Installing the Latest Version of EC2Config

By default, the EC2Config service is included in each AWS Windows AMI. When we release an updated version, we update all AWS Windows AMIs with the latest version. However, you need to update your own Windows AMIs and instances with the latest version.

To find notifications of updates to EC2Config, go to the Amazon EC2 forum. For more information about the changes in each version, see the What's New section on the download page.

To verify the version of EC2Config included with your Windows AMI

  1. Launch an instance from your AMI and connect to it.

  2. In Control Panel, select Programs and Features.

  3. In the list of installed programs, look for Ec2ConfigService. Its version number appears in the Version column.

To install the latest version of EC2Config on your instance

  1. (Optional) If you have changed any settings, note these changes, as you'll need to restore them after installing the latest version of EC2Config.

  2. (Optional) If you have a version of EC2Config that is earlier than version 2.1.19, you must first update to version 2.1.19, and then update to the current version. To update to version 2.1.19, download EC2Install_2.1.19.zip, unzip the file, and then run EC2Install.exe.

  3. Go to Amazon Windows EC2Config Service.

  4. Click Download.

  5. Download and unzip the file.

  6. Run EC2Install.exe. For a complete list of options, run EC2Install with the /? option. Note the following:

    • By default, the setup replaces your settings files with default settings files during installation and restarts the EC2Config service when the installation is completed. To keep the custom settings that you saved in step 1, run EC2Install with the /norestart option, restore your settings, and then restart the EC2Config service manually.

    • By default, the setup displays prompts. To run the command with no prompts, use the /quiet option.

  7. Connect to your instance, run the Services administrative tool, and verify that the status of EC2Config service is Started.

If you can't connect to your instance, it's possible that updating its version of EC2Config will solve the issue. If your instance is an Amazon EBS-backed instance, you can use the following procedure to update EC2Config even though you can't connect to your instance.

To update EC2Config on an Amazon EBS-backed Windows instance that you can't connect to

  1. Stop the affected instance and detach its root volume.

  2. Launch a temporary t2.micro instance in the same Availability Zone as the affected instance using an AMI for Windows Server 2003. (If you use a later version of Windows Server, you won't be able to boot the original instance when you restore its root volume.) To find an AMI for Windows Server 2003, search for public Windows AMIs with the name Windows_Server-2003-R2_SP2.

  3. Attach the root volume from the affected instance to this temporary instance. Connect to the temporary instance, open the Disk Management utility, and bring the drive online.

  4. Download the latest EC2Config from Amazon Windows EC2Config Service. Extract the files from the .zip file to the Temp directory on the drive you attached.

  5. Open Regedit and select HKEY_LOCAL_MACHINE. From the File menu, click Load Hive. Select the drive, open the file Windows\System32\config\SOFTWARE, and specify a key name when prompted (you can use any name).

  6. Select the key you just loaded and navigate to Microsoft\Windows\CurrentVersion. Select the RunOnce key. (If this key doesn't exist, right-click CurrentVersion, point to New, select Key, and name the key RunOnce.) Right-click, point to New, and select String Value. Enter Ec2Install as the name and C:\Temp\Ec2Install.exe /quiet as the data.

  7. Select the key again, and from the File menu, click Unload Hive.

  8. Open the Disk Management utility and bring the drive offline. Detach the volume from the temporary instance. You can terminate the temporary instance if you have no further use for it.

  9. Restore the root volume of the affected instance by attaching it as /dev/sda1.

  10. Start the instance.

  11. After the instance starts, check the system log and verify that you see the message Windows is ready to use.

Stopping, Restarting, Deleting, or Uninstalling EC2Config

You can manage the EC2Config service just as you would any other service.

To apply updated settings to your instance, you can stop and restart the service. If you're manually installing EC2Config, you must stop the service first.

To stop the EC2Config service

  1. Launch and connect to your Windows instance.

  2. On the Start menu, point to Administrative Tools, and then click Services.

  3. In the list of services, right-click EC2Config, and select Stop.

If you don't need to update the configuration settings or create your own AMI, you can delete the service. Deleting a service removes its registry subkey.

To restart the EC2Config service

  1. Launch and connect to your Windows instance.

  2. On the Start menu, point to Administrative Tools, and then click Services.

  3. In the list of services, right-click EC2Config, and select Restart.

To delete the EC2Config service

  1. Start a command prompt window.

  2. Run the following command:

    C:\> sc delete ec2config

If you don't need to update the configuration settings or create your own AMI, you can uninstall EC2Config. Uninstalling a service removes the files, the registry subkey, and any shortcuts to the service.

To uninstall EC2Config

  1. Launch and connect to your Windows instance.

  2. On the Start menu, click Control Panel.

  3. Double-click Programs and Features.

  4. On the list of programs, select EC2ConfigService, and click Uninstall .