Instructor-led XUP tutorial: Connecting to AWS

The following instructions are for live, instructor-led XUP tutorials where AWS F1 instances have been set by Xilinx and login details have been provided to attendees. You can check the XUP workshop schedule for upcoming training. Ask your instructor if you do not have your login details. If you are not attending a live XUP tutorial, go back to the Quick Start page and follow one of the other options to work through these labs.

Introduction

This lab will show you how to start, stop, and connect to a preconfigured AWS EC2 F1 instance.

Objectives

After completing this lab, you will be able to:

Steps

Each registered participant to Xilinx tutorial has been allocated a pre-configured EC2 F1 instance. You should have received an email with the following details:

Login into the AWS and starting an F1 instance

  1. Follow the link provided by your instructor, or go to https://console.aws.amazon.com/ec2.

    If you see the login page for Root user, click the link to sign in to a different account.

  2. Select IAM user and use the account ID provided by your instructor (E.g. xilinx-aws-f1-developer-labs) in Account ID (12 digits) or account alias.

  3. Use the username and password provided by your instructor

  4. In the top right corner make sure to select the AWS region specified by your instructor (E.g. N. Virginia).

    If the wrong region is selected you will not be able to see your instance.

  5. Click on the Services in the menu bar at the top of the screen and click on EC2 to see the available instances.

    You can also click on the Instances link on the left panel

    You may see several instances.

  6. Find the instance that matches your username. If you need to check your username, the account you are logged in as is visible in the menu bar at the top of the screen.

    You can enter your username in the Filter instances box to filter the list

  7. Select your instance (tick the checkbox) and click on Instance state > Start

  8. Click on the refresh button to check the status of the instance. It will take about a few seconds before the instance is ready.

    Keep refreshing the status until you see the Instance state update to Running. This means the instance is now ready for you to connect to it.

  9. With your instance selected, view the instance Details in the bottom part of the page. You can resize the page to make this section easier to view. Find the Public IPv4 address and copy it. Notice the copy button that will automatically copy the IP address to your clipboard.

    This address will be used by to access the remote instance.

Connect to your remote instance

Your instance has been preconfigured to allow you to connect to a remote desktop for your instance using NICE DCV or RDP.

You can also ssh to AWS instances (E.g. using PuTTY) if you only need a terminal. See Appendix: ssh using PuTTY for details.

Connect using NICE DCV

NICE DCV is recommended by Amazon for use with AWS instances. This is also the recommended way to connect to your instance for this tutorial.

The NICE DCV session has already been started on the pre-configured instance. See the Appendix for details on how to setup a NICE DCV session - for example if you wanted to set up your own AWS instance after this tutorial.

  1. Open the NICE DCV application on your computer, enter the IPv4 Public IP from the Amazon console and click Open

  2. The first time a certificate warning will be displayed. Click Trust to continue

  3. When prompted, enter the Instance ssh\RDP credentials: username and password provided by your instructor (E.g. username: centos). Note that this is different to the username that you used to log in to AWS.

  4. Continue to Lab setup

Connect using RDP

The following instructions are for Windows Remote Desktop Connection (pre-installed on Windows 10 and recent versions). For Mac VNC is recommended (see the next section). For Linux you can use Remmina or Vinagre (search for instructions on how to install this for your OS). Detailed instructions are not provided for Linux. You can follow the steps below and carry out the corresponding actions in your Linux RDP client.

  1. Search for Remote Desktop Connection in the windows start menu, and open it to start a session

  2. Enter the IPv4 Public IP address for your instance

  3. Click on the Show Options

  4. Select the Display tab and select True Color (24 bit) and click Connect

  5. A certificate warning will be displayed. Click Yes to open the RDP session

  6. Enter the RDP credentials you were provided with and click OK

  1. Continue to Lab setup

Known issues:

Connect using VNC (Suggested for Mac users)

  1. Install RealVNC client for Mac

    Other alternatives for Linux-based OS are Remmina or Vinagre

  2. Open the RealVNC client

  3. Enter IPv4 Public IP:01 and then hit the enter key

  4. You will be informed that the connection is Unencrypted, click Continue

  5. Enter the provided RDP credentials password and click OK

  6. Continue to Lab setup

Lab setup

  1. In your remote desktop session, right click on the desktop and select Open Terminal

  2. Copy and paste the following commands to your terminal (make sure to hit enter to run the last command):

    cd ~
    git clone https://github.com/aws/aws-fpga -b v1.4.21
    echo "export PLATFORM_REPO_PATHS=~/aws-fpga/Vitis/aws_platform/xilinx_aws-vu9p-f1_shell-v04261818_201920_2/" >> ~/.bashrc
    echo "source /opt/xilinx/xrt/setup.sh" >> ~/.bashrc
    echo "source $XILINX_VITIS/settings64.sh" >> ~/.bashrc
    git clone https://github.com/Xilinx/xup_compute_acceleration.git
    source ~/.bashrc
    source ~/aws-fpga/vitis_setup.sh
    source ~/aws-fpga/vitis_runtime_setup.sh
    

    This will

    • Clone the aws-fpga repository to your home area. aws-fpga includes the AWS F1 tools, Hardware Development Kit (HDK) and documentation.

    • Setup the AWS platform path, and add XRT and Vitis setup scripts to your .bashrc file. This means they will be available in every new terminal session you open.

    • Clone this repository to get source code for the labs
    • Source ~/bashrc to refresh this terminal session
    • Source AWS Vitis setup scripts. This are setup scripts that need to be run once to configure the aws-fpga and Vitis tools.

You will see a lot of messages in the terminal. The last line should read:

INFO: Vitis runtime check PASSED

You can now proceed to Lab 1: Introduction to Vitis Part 1.

If you are using the AWSEducate instances then execute the following to clone the xup_compute_acceleration repository. No additional variables need to be set as the provided AMI has all necessary files including aws-fpga repository cloning, the AWS F1 tools, Hardware Development Kit (HDK) and documentation

git clone https://github.com/Xilinx/xup_compute_acceleration.git

The previous command will:


Appendix

SSH using PuTTY

  1. Start PuTTY or your preferred SSH client

  2. Enter centos@<IPv4_Public_IP> in the Host Name field and 22 in the Port field
    Make sure that SSH is selected as the Connection type

  3. Click Open and then Yes when PuTTY Security Alert is shown

    The PuTTY window will open. It will ask for the password (in case of the workshop). Enter the provided password

  4. Enter exit to close the session

Set up the NICE DCV session

  1. Open PuTTY, and ssh to your instance as described on SSH using PuTTY

  2. On the terminal, enter the following command to start the DCV server:

    dcv create-session --user centos centos
    

    By default NICE DCV runs in the TCP port 8443

  3. Verify dcv session

    If the output of dcv list-sessions should look like:

    Session: 'centos' (owner: centos)
    
  4. Stop the firewall

    sudo systemctl disable firewalld
    sudo systemctl stop firewalld
    

Copyright© 2021 Xilinx