How to start a RDP session from the command line to a Windows server running on AWS

25 Oct, 2022
Xebia Background Header Wave

To start a RDP session to a Windows server on AWS is a very labour-intensive task. You have
to select the instance on the console, copy the private key to get the password, copy the password,
download the RDP file. Then double-click on the RDP file, paste the password in a dialog box, and
you are done. But it does not have to be this way. In this blog we will show you it can be as easy as using ssh!


To allow quick and easy access you need to do prepare the following three things.

  1. install freeRDP on your machine
  2. install XQuartz on MacOS
  3. store the private key material of the EC2 keypair in the SSM parameter store

The first two steps are simple, and will not be explained here. To store the private key material
of the EC2 keypair in the SSM parameter store we use the following CloudFormation resource:

    Type: AWS::EC2::KeyPair
      KeyName: WindowsServer
      KeyType: rsa

Once you deploy this resource, the private key of the keypair named WindowsServer is stored in the parameter store
under the name /ec2/keypair/<key-id>. This is nice, because it standardizes the name of the
SSM parameter with the private key material.

start the rdp session

Now we have everything to automate the start of a RDP session, using the following steps.

  1. determine the ec2 instance to connect to
  2. retrieve the private key of the keypair
  3. retrieve the admin password of the Windows server
  4. start the RDP session o/

determine ec2 instance to connect to

First we determine the EC2 instance id of the machine we want to connect to. In the following
snippet, we assume that you have a single machine with tagged with the name.

instance_id=$(aws ec2 describe-instances 
              --query 'join(<code>n, Reservations[].Instances[].InstanceId)' 
              --output text 
              --filter "Name=tag:Name,Values=$instance_name" 

retrieve the private key of the keypair

To retrieve the private key of the keypair, we first retrieve the name of the keypair associated
with the instance and retrieve the key id.

key_name=$(aws ec2 describe-instances 
          --instance-id $instance_id 
          --query Reservations[0].Instances[0].KeyName 
          --output text)

key_id=$(aws ec2 describe-key-pairs 
         --key-names $key_name 
         --query KeyPairs[0].KeyPairId 
         --output text)

Now we can pull the private key material in:

chmod 0600 $private_key
aws ssm get-parameter --name /ec2/keypair/$key_id 
      --with-decryption --query Parameter.Value  
      --output text >  $private_key

retrieve the admin password of the Windows server

To retrieve the admin password of the Windows server, we call get-password-data with the private key.

password=$(aws ec2 get-password-data 
          --priv-launch-key $private_key --instance-id $instance_id 
          --query PasswordData 
          --output text)
rm -f $private_key

start the rdp session

Finally, we have everything to automatically login using RDP. we just have to pick an IP address
and run FreeRDP!

ip_address=$(aws ec2 describe-instances 
                --instance-ids $instance_id 
                --query 'join(<code>n, Reservations[].Instances[].PublicIpAddress)' 
                --output text)

xfreerdp /u:administrator /p:$password  /v:$ip_address /cert:ignore

That is all there is to it! It is just as easy as running ssh :-p You can find
the complete script on github.
You can tailor it anyway you like.

Why freeRDP and not Microsoft’s Remote Desktop Client

So you may ask: Why not use Microsoft’s Remote Desktop Client?
That is quite easy: it does not support command line options. The alternative would be to
generate the RDP file, but on non-Windows platforms you cannot store the password as the
required encryption function only works on Windows.


With the freeRDP client, you can fully automate starting an RDP session to a Windows Server running
on AWS!

Image by ArtificialOG from Pixabay

Mark van Holsteijn
Mark van Holsteijn is a senior software systems architect at Xebia Cloud-native solutions. He is passionate about removing waste in the software delivery process and keeping things clear and simple.

Get in touch with us to learn more about the subject and related solutions

Explore related posts