Writing to the EC2 Console

I have been building a bunch of Windows AMIs for EC2 recently. If the instance fails to build it can be a real bear to diagnose issues. You don't have access to the console to watch what's happening. It would be great if I could log to the EC2 Console (also called the System Log on the web site) so I knew what was happening. So I hacked the EC2Config Service to see how it was writing to the console.

The EC2 Console, it turns out, is listening to Serial Port COM1. So if want to write a message to the log, all you have to do is write to COM1. Of course the EC2 Config Service already has COM1 open, so we have to close it first. Here is a quick sample.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Stop-Service Ec2Config
$Port = New-Object System.IO.Ports.SerialPort
$Port.PortName = "COM1"
$Port.BaudRate = 0x1c200
$Port.Parity = [System.IO.Ports.Parity]::None
$Port.DataBits = 8
$Port.StopBits = [System.IO.Ports.StopBits]::One
$Port.Open()
$Port.WriteLine("This was written directly to the serial port");
$Port.Close()

You can also use a helper class that ships with EC2 Config Service called ConsoleLibrary. This implementation is thread-safe, adds the date and time, and takes care of all the serial port configuration details. Of course you still need to close the EC2 Config Service before running this code.

1
2
3
4
5
6
7
8


#Stop the EC2 Config Service
Stop-Service Ec2Config
#Ensure the log file exists or you will get an error
New-Item -ItemType File -Force -Path 'C:\Windows\system32\WindowsPowerShell\v1.0\Logs\Ec2ConfigLog.txt'
#Load the Ec2Config Library
[System.Reflection.Assembly]::LoadFrom("C:\Program Files\Amazon\Ec2ConfigService\Ec2ConfigLibrary.dll")
#Write to the Console
[ConsoleLibrary.ConsoleLibrary]::Instance().WriteToConsole("This was written using the Ec2ConfigLibrary", $true)

As you can see below, me messages appear mixed in with the standard console messages, but note that the Console is only updated during boot. If you write to the log after boot the messages will not appear until the next reboot.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


2014/07/19 18:18:50Z: AMI Origin Version: 2014.07.10
2014/07/19 18:18:50Z: AMI Origin Name: Windows_Server-2012-R2_RTM-English-64Bit-Base
2014/07/19 18:18:50Z: OS: Microsoft Windows NT 6.2.9200.0
2014/07/19 18:18:50Z: Language: en-US
2014/07/19 18:18:50Z: EC2 Agent: Ec2Config service v2.2.5.0
2014/07/19 18:18:50Z: Driver: AWS PV Network Device v7.2.0.0
2014/07/19 18:18:50Z: Driver: AWS PV Storage Host Adapter v7.2.0.0
2014/07/19 18:18:51Z: Message: Waiting for meta-data accessibility...
2014/07/19 18:18:51Z: Message: Meta-data is now available.
2014/07/19 18:18:51Z: AMI-ID: ami-9ade1df2
2014/07/19 18:18:51Z: Instance-ID: i-05132d2e
2014/07/19 18:18:51Z: Ec2SetPassword: Disabled
2014/07/19 18:18:51Z: RDPCERTIFICATE-SUBJECTNAME: WIN-JCK73T6NRFU
2014/07/19 18:18:51Z: RDPCERTIFICATE-THUMBPRINT: 68D80A1B0567E60D0BD2C6A8068D7E1D55ED3DDC
2014/07/19 18:18:53Z: Message: Windows is Ready to use
<span style="background-color: yellow;">This was written directly to the serial port
2014/07/19 19:30:54Z: This was written using the Ec2ConfigLibrary</span>
2014/07/19 19:32:57Z: AMI Origin Version: 2014.07.10
2014/07/19 19:32:57Z: AMI Origin Name: Windows_Server-2012-R2_RTM-English-64Bit-Base
2014/07/19 19:32:57Z: OS: Microsoft Windows NT 6.2.9200.0
2014/07/19 19:32:57Z: Language: en-US
2014/07/19 19:32:57Z: EC2 Agent: Ec2Config service v2.2.5.0
2014/07/19 19:32:58Z: Driver: AWS PV Network Device v7.2.0.0
2014/07/19 19:32:58Z: Driver: AWS PV Storage Host Adapter v7.2.0.0
2014/07/19 19:32:58Z: Message: Waiting for meta-data accessibility...
2014/07/19 19:32:59Z: Message: Meta-data is now available.
2014/07/19 19:32:59Z: AMI-ID: ami-9ade1df2
2014/07/19 19:32:59Z: Instance-ID: i-05132d2e
2014/07/19 19:32:59Z: Ec2SetPassword: Disabled
2014/07/19 19:32:59Z: RDPCERTIFICATE-SUBJECTNAME: WIN-JCK73T6NRFU
2014/07/19 19:32:59Z: RDPCERTIFICATE-THUMBPRINT: 68D80A1B0567E60D0BD2C6A8068D7E1D55ED3DDC
2014/07/19 19:33:00Z: Message: Windows is Ready to use

Posts

Setting the Hostname in a SysPreped AMI

When you create an Windows AMI (Amazon Machine Image) it is configured to generate a random server name. Often this name does not meet your needs. Maybe your company has a specific naming convention (e.g US-NYC-1234) or you just want to use a descriptive name (e.g. WEB01). Whatever the reason, let's look at how to set the name when you launch the machine.

In this post we will use PowerShell to read the name from a Tag on the instance. When done, you set the hostname in launch wizard by simply filling in the Name tag. See the image below. Our script will read this tag and rename the server when it boots for the first time.

It is important to automate the name change. As your cloud adoption matures, you quickly realize that you cannot have an admin log in and rename the server when it's launched. First, it takes too long. Second, you want servers to launch automatically, for example, in response to an auto-scaling event.

So how can you set the name? You will find a ComputerName element in the SysPrep2008.xml file that ships with the EC2 Config Service (or in the unattended.xml file if you're not using the EC2 Config Service.) The computer name is in the specialize section. In the snippet below, you can see the default value of "*". The star means that windows should generate a random name.

1
2
3
4
5
6


 <component language="neutral" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State" versionScope="nonSxS" publicKeyToken="31bf3856ad364e35" processorArchitecture="amd64" name="Microsoft-Windows-Shell-Setup" >
     <ComputerName >* </ComputerName >
     <CopyProfile >true </CopyProfile >
     <RegisteredOrganization >Amazon </RegisteredOrganization >
     <TimeZone >Eastern Standard Time </TimeZone >
 </component >

If you want to change the name you can simply hard-code whatever you want here. Of course, if you hard-code if before you run SysPrep, every machine you create from the AMI will have the same name. That's not what we want. So the trick is to set the name when the machine first boots and before specialize runs.

Let's quickly review how SysPrep works. When you run SysPrep, it wipes any identifying information form the machine (e.g. Name, SIDs, etc.) This is known as the generalize phase. After the generalize phase you shutdown the machine and take the image.

When a SysPreped image first boots, it runs windows setup (WinDeploy.exe). This is known as the specialize phase. If you have ever bought a new home computer, you have experienced the setup wizard that allows you to configure your timezone, etc. In the cloud you cannot answer questions so you have to supply an unattended.xml file with the answers to all the questions.

We need to inject our script into the specialize phase before setup runs. Our script will get the machine name from the EC2 API and modify the unattended.xml file. Here is a sample script to do just that. The script has three parts.

The first part uses the meta-data service to discover the identity of the instance and the region the machine is running in.
The second part of the script uses the EC2 API to get the name tag from for the instance. Note that I have not included any credentials. I assume that the instance is in a role that allows access to the Get-EC2Tag API call.
The third part of the script modifies the unattended.xml file. This is the same file shown earlier. The script simply finds the ComputerName node and replaces the * with the correct name.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


Write-Host "Discovering instance identity from meta-data web service"
$InstanceId = (Invoke-RestMethod 'http://169.254.169.254/latest/meta-data/instance-id').ToString()
$AvailabilityZone = (Invoke-RestMethod 'http://169.254.169.254/latest/meta-data/placement/availability-zone').ToString()
$Region = $AvailabilityZone.Substring(0,$AvailabilityZone.Length-1)

Write-Host "Getting Tags for the instance"
$Tags = Get-EC2Tag -Filters @{Name='resource-id';Value=$InstanceId} -Region $Region
$InstanceName = ($Tags | Where-Object {$_.Key -eq 'Name'}).Value
Write-Host "`tFound Instance Name: $InstanceName"
Write-Host "`tFound Instance Owner: $InstanceOwner"

If($InstanceName -ne $null) {
 Write-Host "Setting the machine name to $InstanceName"

$AnswerFilePath = "C:\Windows\Panther\unattend.xml"

$AnswerFile = [xml](Get-Content -Path $AnswerFilePath) 
 $ns = New-Object System.Xml.XmlNamespaceManager($AnswerFile.NameTable)
 $ns.AddNamespace("ns", $AnswerFile.DocumentElement.NamespaceURI)
 $ComputerName = $AnswerFile.SelectSingleNode('/ns:unattend/ns:settings[@pass="specialize"]/ns:component[@name="Microsoft-Windows-Shell-Setup"]/ns:ComputerName', $ns)
 $ComputerName.InnerText = $InstanceName
 $AnswerFile.Save($AnswerFilePath)
}

So how do we get this script to run before setup? That's the tricky part. Let's dig a bit deeper. I said earlier that when a SysPreped image first boots it will run WinDeploy.exe. To be more specific, it will run whatever it finds in the HKLM:\System\Setup registry key. SysPrep will put c:\Windows\System32\oobe\windeploy.exe in the registry key before shutdown.

So we need to change that registry key after SysPrep runs, but before the system shuts down. To do that we need to pass the /quit flag rather than /shutdown. I'm writing about AWS, so I assume you are calling SysPrep from the EC2Config service. If you are, you need to edit the switches element of the BundleConfig.xml file in the EC2Config folder. The switches element is about midway down the file. See the example below. Just remove /shutdown and replace it with /quit.

1
2
3
4
5
6


 <Sysprep version="6.0" >
       <PreSysprepRunCmd >C:\Program Files\Amazon\Ec2ConfigService\Scripts\BeforeSysprep.cmd </PreSysprepRunCmd >
       <ExePath >C:\windows\system32\sysprep\sysprep.exe </ExePath >
       <AnswerFilePath >sysprep2008.xml </AnswerFilePath >
       <Switches >/oobe /shutdown /generalize <syspr/Switches >
 </Sysprep >

Alright, we are almost there. Now you can run SysPrep and it will give you a chance to make changes before shutting down. You want to replace the HKLM:\System\Setup registry key with the script we created above. Don't forget to add a line to call WinDeploy.exe at the end of the script.

With all that done (it's not as bad it sounds) you can shutdown and take an image. It will take a few tries to get all this working correctly. I recommend that you log the output of the script using Start-Transcript. If the server fails to boot you can attach the volume to another instance and read the log.