Known Issues

1. Run the following commands to download patch.py and cognito_sign_up_email_fix.patch for version 2024.12 or cognito_sign_up_email_fix.patch for version 2024.12.01, replacing <output-directory> with the directory where you want to download the patch script and patch file, and <environment-name> with the name of your RES environment:

   1. The patch applies to RES 2024.12 and 2024.12.01.

   2. The patch script requires AWS CLI v2, Python 3.9.16 or above, and Boto3.

   3. Configure the AWS CLI for the account and region where RES is deployed, and make sure that you have S3 permissions to write to the bucket created by RES.

   OUTPUT_DIRECTORY=<output-directory>
   ENVIRONMENT_NAME=<environment-name>
   RES_VERSION=<res-version> # either 2024.12 or 2024.12.01
   
   mkdir -p ${OUTPUT_DIRECTORY}
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/${RES_VERSION}/patch_scripts/patch.py --output ${OUTPUT_DIRECTORY}/patch.py
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/${RES_VERSION}/patch_scripts/patches/cognito_sign_up_email_fix.patch --output ${OUTPUT_DIRECTORY}/cognito_sign_up_email_fix.patch 

2. Navigate to the directory where the patch script and patch file were downloaded. Run the following patch command:

   python3 ${OUTPUT_DIRECTORY}/patch.py --environment-name ${ENVIRONMENT_NAME} --res-version ${RES_VERSION} --module cluster-manager --patch ${OUTPUT_DIRECTORY}/cognito_sign_up_email_fix.patch
   

3. Restart the Cluster Manager instance for your environment. You may also terminate the instance from the Amazon EC2 Management Console.

   INSTANCE_ID=$(aws ec2 describe-instances \
       --filters \
       Name=tag:Name,Values=${ENVIRONMENT_NAME}-cluster-manager \
       Name=tag:res:EnvironmentName,Values=${ENVIRONMENT_NAME}\
       --query "Reservations[0].Instances[0].InstanceId" \
       --output text)
    
   aws ec2 terminate-instances --instance-ids ${INSTANCE_ID} 

4. Verify the Cluster Manager instance status by checking the activity of the auto scaling group starting with the name <RES-EnvironmentName>-cluster-manager-asg. Wait until the new instance is launched successfully.

1. Navigate to the EC2 console. If there is an instance named CertificateRenewalNode-, terminate the instance.

2. Navigate to the Lambda console. Open the source code of the Lambda function named -CertificateRenewalLambda-. Identify the line staring with ./acme.sh --issue --dns dns_aws --ocsp-must-staple --keylength 4096 and remove the --ocsp-must-staple argument.

3. Select Deploy and wait for the code change to take effect.

4. To manually trigger the Lambda function: go to the Test tab and then select Test. No additional input is required. This should create a certificate EC2 instance that updates the Certificate and PrivateKey secrets in Secret Manager. The instance will be terminated automatically once the secrets are updated.

5. Terminate the existing dcv-gateway instance: <env-name>-vdc-gateway and wait for the auto scaling group to automatically deploy a new one.

1. Connect to the Bastion Host instance from the EC2 console.

2. Edit /etc/environment and add environment_name=<res-environment-name> as a new line under IDEA_CLUSTER_NAME.

3. Run the following commands on the instance:

   source /etc/environment
   sudo service supervisord restart
   sudo systemctl restart supervisord 

4. Try to connect to the Bastion Host again following the instructions from the RES web portal.

1. Download patch.py and graphic_enhanced_instance_types_fix.patch by replacing <output-directory> with the directory where you want to download the patch script and patch file and <environment-name> with the name of your RES environment in the command below:

   1. The patch only applies to RES 2024.10.

   2. The patch script requires AWS CLI v2, Python 3.9.16 or above, and Boto3.

   3. Configure the AWS CLI for the account and region where RES is deployed, and make sure that you have S3 permissions to write to the bucket created by RES.

   OUTPUT_DIRECTORY=<output-directory>
   ENVIRONMENT_NAME=<environment-name>
   
   mkdir -p ${OUTPUT_DIRECTORY}
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.10/patch_scripts/patch.py --output ${OUTPUT_DIRECTORY}/patch.py
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.10/patch_scripts/patches/graphic_enhanced_instance_types_fix.patch --output ${OUTPUT_DIRECTORY}/graphic_enhanced_instance_types_fix.patch 

2. Navigate to the directory where the patch script and patch file were downloaded. Run the following patch command:

   python3 ${OUTPUT_DIRECTORY}/patch.py --environment-name ${ENVIRONMENT_NAME} --res-version 2024.10 --module virtual-desktop-controller --patch ${OUTPUT_DIRECTORY}/graphic_enhanced_instance_types_fix.patch

3. To terminate the Virtual Desktop Controller (vdc-controller) instance for your environment, run the following commands, replacing the name of your RES environment where shown.

   INSTANCE_ID=$(aws ec2 describe-instances \
       --filters \
       Name=tag:Name,Values=${ENVIRONMENT_NAME}-vdc-controller \
       Name=tag:res:EnvironmentName,Values=${ENVIRONMENT_NAME}\
       --query "Reservations[0].Instances[0].InstanceId" \
       --output text)
    
   aws ec2 terminate-instances --instance-ids ${INSTANCE_ID}

4. Launch a new instance after the target group starting with the name <RES-EnvironmentName>-vdc-ext becomes healthy. We recommend any new software stacks you register for graphics instances have at least 50GB storage.

1. Download the updated res-installation-scripts.tar.gz file.

2. Follow the steps listed under Prepare Amazon Machine Images (AMIs) on the Prerequisites page.

1. Download the updated res-installation-scripts.tar.gz file.

2. Navigate to EC2 Image Builder → Components → Click on the Component created for preparing RES AMIs.

3. Note the S3 location listed under Content → DownloadRESInstallScripts step → inputs → source.

4. The S3 location found above contains the dependencies file that was previously used, replace this file with the file downloaded in the first step.

1. To download the patch script and patch file (patch.py and s3_mount_custom_prefix_fix.patch), run the following command, replacing <output-directory> with the directory where you want to download the patch script and patch file and <environment-name> with the name of your RES environment:

   1. The patch only applies to RES 2024.08.

   2. The patch script requires AWS CLI v2, Python 3.9.16 or above, and Boto3.

   3. Configure the AWS CLI for the account and region where RES is deployed, and make sure that you have Amazon S3 permissions to write to the bucket created by RES.

   OUTPUT_DIRECTORY=<output-directory>
   ENVIRONMENT_NAME=<environment-name>
   
   mkdir -p ${OUTPUT_DIRECTORY}
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.08/patch_scripts/patch.py --output ${OUTPUT_DIRECTORY}/patch.py
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.08/patch_scripts/patches/s3_mount_custom_prefix_fix.patch --output ${OUTPUT_DIRECTORY}/s3_mount_custom_prefix_fix.patch 

2. Navigate to the directory where the patch script and patch file are downloaded. Run the following patch command:

   python3 ${OUTPUT_DIRECTORY}/patch.py --environment-name ${ENVIRONMENT_NAME} --res-version 2024.08 --module virtual-desktop-controller --patch ${OUTPUT_DIRECTORY}/s3_mount_custom_prefix_fix.patch
   

3. To terminate the Virtual Desktop Controller (vdc-controller) instance for your environment, run the following commands. (You already set the ENVIRONMENT_NAME variable to the name of your RES environment in the first step.)

   INSTANCE_ID=$(aws ec2 describe-instances \
       --filters \
       Name=tag:Name,Values=${ENVIRONMENT_NAME}-vdc-controller \
       Name=tag:res:EnvironmentName,Values=${ENVIRONMENT_NAME}\
       --query "Reservations[0].Instances[0].InstanceId" \
       --output text)
    
   aws ec2 terminate-instances --instance-ids ${INSTANCE_ID} 

   Note

   For private VPC setups, if you haven't already done so, for the <RES-EnvironmentName>-vdc-custom-credential-broker-lambda function make sure to add the Environment variable with name AWS_STS_REGIONAL_ENDPOINTS and value of regional. See Amazon S3 bucket prerequisites for isolated VPC deployments for more information.

4. After the target group starting with the name <RES-EnvironmentName>-vdc-ext becomes healthy, new VDIs will need to be launched that will have the read/write S3 buckets with root bucket ARN and custom prefixing mounted correctly.

1. To download the patch script and patch file ( patch.py and groupname_regex.patch), run the following command, replacing <output-directory> with the directory where you want to put the files, and <environment-name> with the name of your RES environment:

   1. The patch only applies to RES 2024.06

   2. The patch script requires AWS CLI v2, Python 3.9.16 or above, and Boto3.

   3. Configure the AWS CLI for the account and region where RES is deployed, and make sure that you have S3 permissions to write to the bucket created by RES:

      OUTPUT_DIRECTORY=<output-directory>
      ENVIRONMENT_NAME=<environment-name>
      
      mkdir -p ${OUTPUT_DIRECTORY}
      curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.06/patch_scripts/patch.py --output ${OUTPUT_DIRECTORY}/patch.py
      curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.06/patch_scripts/patches/groupname_regex.patch --output ${OUTPUT_DIRECTORY}/groupname_regex.patch 

2. Navigate to the directory where the patch script and patch file are downloaded. Run the following patch command:

   python3 patch.py --environment-name ${ENVIRONMENT_NAME} --res-version 2024.06 --module cluster-manager --patch ${OUTPUT_DIRECTORY}/groupname_regex.patch 

3. To restart the Cluster Manager instance for your environment, run the following commands: You may also terminate the instance from the Amazon EC2 Management Console.

   INSTANCE_ID=$(aws ec2 describe-instances \
       --filters \
       Name=tag:Name,Values=${ENVIRONMENT_NAME}-cluster-manager \
       Name=tag:res:EnvironmentName,Values=${ENVIRONMENT_NAME}\
       --query "Reservations[0].Instances[0].InstanceId" \
       --output text)
    
   aws ec2 terminate-instances --instance-ids ${INSTANCE_ID} 

1. To download the patch.py script and group_member_sync_bug_fix.patch file, run the following commands, replacing <output-directory> with the local directory where you'd like to download the files, and <res_version> with the version of RES you want to patch:

   Note

   • The patch script requires AWS CLI v2, Python 3.9.16 or above, and Boto3.

   • Configure the AWS CLI for the account and region where RES is deployed, and make sure that you have S3 permissions to write to the bucket created by RES.

   • The patch only supports RES versions 2024.04.02 and 2024.06. If you are using 2024.04 or 2024.04.01, you can follow the steps listed in Minor version updates to first update your environment to 2024.04.02 prior to applying the patch.

     • RES Version: RES 2024.04.02

       Patch download link: 2024.04.02_group_member_sync_bug_fix.patch

     • RES Version: RES 2024.06

       Patch download link: 2024.06_group_member_sync_bug_fix.patch

   OUTPUT_DIRECTORY=<output-directory>
   RES_VERSION=<res_version>
   mkdir -p ${OUTPUT_DIRECTORY}
   
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/${RES_VERSION}/patch_scripts/patch.py --output ${OUTPUT_DIRECTORY}/patch.py
   
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/${RES_VERSION}/patch_scripts/patches/${RES_VERSION}_group_member_sync_bug_fix.patch --output ${OUTPUT_DIRECTORY}/${RES_VERSION}_group_member_sync_bug_fix.patch 

2. Navigate to the directory where the patch script and patch file are downloaded. Run the following patch command, replacing <environment-name> with the name of your RES environment:

   cd ${OUTPUT_DIRECTORY}
   ENVIRONMENT_NAME=<environment-name>
   
   python3 patch.py --environment-name ${ENVIRONMENT_NAME} --res-version ${RES_VERSION} --module cluster-manager --patch $PWD/${RES_VERSION}_group_member_sync_bug_fix.patch 

3. To restart the cluster-manager instance for your environment, run the following commands:

   INSTANCE_ID=$(aws ec2 describe-instances \
       --filters \
       Name=tag:Name,Values=${ENVIRONMENT_NAME}-cluster-manager \
       Name=tag:res:EnvironmentName,Values=${ENVIRONMENT_NAME}\
       --query "Reservations[0].Instances[0].InstanceId" \
       --output text)
    
   aws ec2 terminate-instances --instance-ids ${INSTANCE_ID} 

PATCH EXISTING VDIs

1. Run the following command which will patch all existing Ubuntu and RHEL9 VDIs:

   1. The patch script requires AWS CLI v2.

   2. Configure the AWS CLI for the account and region where RES is deployed, and make sure that you have AWS Systems Manager permissions to send a Systems Manager Run Command.

      aws ssm send-command \
          --document-name "AWS-RunRemoteScript" \
          --targets "Key=tag:res:NodeType,Values=virtual-desktop-dcv-host" \
          --parameters '{"sourceType":["S3"],"sourceInfo":["{\"path\":\"https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.06/patch_scripts/scripts/patch_openssh.sh\"}"],"commandLine":["bash patch_openssh.sh"]}' 

2. You can verify the script ran successfully on the Run Command page. Click on the Command History tab, select the most recent Command ID, and verify that all instance IDs have a SUCCESS message.

PATCH FUTURE VDIs

1. To download the patch script and patch file ( patch.py and update_openssh.patch) run the following commands, replacing <output-directory> with the directory where you want to download the files, and <environment-name> with the name of your RES environment:

   Note

   • The patch only applies to RES 2024.06.

   • The patch script requires AWS CLI v2), Python 3.9.16 or above, and Boto3.

   • Configure your copy of the AWS CLI for the account and region where RES is deployed, and make sure that you have S3 permissions to write to the bucket created by RES.

   OUTPUT_DIRECTORY=<output-directory>
   ENVIRONMENT_NAME=<environment-name>
   
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.06/patch_scripts/patch.py --output ${OUTPUT_DIRECTORY}/patch.py
   
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.06/patch_scripts/patches/update_openssh.patch --output ${OUTPUT_DIRECTORY}/update_openssh.patch 

2. Run the following patch command:

   python3 ${OUTPUT_DIRECTORY}/patch.py --environment-name ${ENVIRONMENT_NAME} --res-version 2024.06 --module virtual-desktop-controller --patch ${OUTPUT_DIRECTORY}/update_openssh.patch 

3. Restart the VDC Controller instance for your environment with the following commands:

   INSTANCE_ID=$(aws ec2 describe-instances \
       --filters \
       Name=tag:Name,Values=${ENVIRONMENT_NAME}-vdc-controller \
       Name=tag:res:EnvironmentName,Values=${ENVIRONMENT_NAME}\
       --query "Reservations[0].Instances[0].InstanceId" \
       --output text)
    
   aws ec2 terminate-instances --instance-ids ${INSTANCE_ID} 

1. To download the patch script and patch file ( patch.py and vdi_host_role_permission_boundary.patch), run the following command, replacing <output-directory> with the local directory where you'd like to put the files:

   1. The patch only applies to RES 2024.04.02. If you are on version 2024.04 or 2024.04.01, you can follow the steps listed in the public document for minor version updates to update your environment to 2024.04.02.

   2. The patch script requires AWS CLI v2), Python 3.9.16 or above, and Boto3.

   3. Configure the AWS CLI for the account and region where RES is deployed, and make sure that you have S3 permissions to write to the bucket created by RES.

   OUTPUT_DIRECTORY=<output-directory>
   
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.04.02/patch_scripts/patch.py --output ${OUTPUT_DIRECTORY}/patch.py
   
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.04.02/patch_scripts/patches/vdi_host_role_permission_boundary.patch --output ${OUTPUT_DIRECTORY}/vdi_host_role_permission_boundary.patch 

2. Navigate to the directory where the patch script and patch file are downloaded. Run the following patch command, replacing <environment-name> with the name of your RES environment:

   python3 patch.py --environment-name <environment-name> --res-version 2024.04.02 --module cluster-manager --patch vdi_host_role_permission_boundary.patch 

3. Restart the cluster-manager instance in your environment by running this command, replacing <environment-name> with the name of your RES environment. You may also terminate the instance from the Amazon EC2 Management Console.

   ENVIRONMENT_NAME=<environment-name>
   
   INSTANCE_ID=$(aws ec2 describe-instances \
       --filters \
       Name=tag:Name,Values=${ENVIRONMENT_NAME}-cluster-manager \
       Name=tag:res:EnvironmentName,Values=${ENVIRONMENT_NAME}\
       --query "Reservations[0].Instances[0].InstanceId" \
       --output text)
    
   aws ec2 terminate-instances --instance-ids ${INSTANCE_ID} 

1. SSH into the problem instance from the EC2 console.

2. Run the following commands on the instance:

   sudo su -
   /bin/bash /root/bootstrap/latest/virtual-desktop-host-linux/configure_post_reboot.sh
   sudo reboot 

3. Wait for the instance to reboot.

1. To download the patch script and patch file ( patch.py and vdi_stuck_in_resuming_status.patch), run the following command, replacing <output-directory> with the directory where you want to put the files:

   Note

   • The patch only applies to RES 2024.04.02.

   • The patch script requires AWS CLI v2, Python 3.9.16 or above, and Boto3.

   • Configure the AWS CLI for the account and region where RES is deployed, and make sure that you have S3 permissions to write to the bucket created by RES.

   OUTPUT_DIRECTORY=<output-directory>
   
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.04.02/patch_scripts/patch.py --output ${OUTPUT_DIRECTORY}/patch.py
   
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.04.02/patch_scripts/patches/vdi_stuck_in_resuming_status.patch --output ${OUTPUT_DIRECTORY}/vdi_stuck_in_resuming_status.patch 

2. Navigate to the directory where the patch script and patch file are downloaded. Run the following patch command, replacing <environment-name> with the name of your RES environment and <aws-region> with the region where RES is deployed:

   python3 patch.py --environment-name <environment-name> --res-version 2024.04.02 --module virtual-desktop-controller --patch vdi_stuck_in_resuming_status.patch --region <aws-region> 

3. To restart the VDC Controller instance for your environment, run the following commands, replacing <environment-name> with the name of your RES environment:

   ENVIRONMENT_NAME=<environment-name>
   
   INSTANCE_ID=$(aws ec2 describe-instances \
       --filters \
       Name=tag:Name,Values=${ENVIRONMENT_NAME}-vdc-controller \
       Name=tag:res:EnvironmentName,Values=${ENVIRONMENT_NAME}\
       --query "Reservations[0].Instances[0].InstanceId" \
       --output text)
    
   aws ec2 terminate-instances --instance-ids ${INSTANCE_ID} 

1. To download the patch script and patch file ( patch.py and samaccountname_regex.patch), run the following command, replacing <output-directory> with the directory where you want to put the files:

   Note

   • The patch only applies to RES 2024.04.02.

   • The patch script requires AWS CLI v2, Python 3.9.16 or above, and Boto3.

   • Configure the AWS CLI for the account and region where RES is deployed, and make sure that you have S3 permissions to write to the bucket created by RES.

   OUTPUT_DIRECTORY=<output-directory>
   
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.04.02/patch_scripts/patch.py --output ${OUTPUT_DIRECTORY}/patch.py
   
   curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/2024.04.02/patch_scripts/patches/samaccountname_regex.patch --output ${OUTPUT_DIRECTORY}/samaccountname_regex.patch 

2. Navigate to the directory where the patch script and patch file are downloaded. Run the following patch command, replacing <environment-name> with the name of your RES environment:

   python3 patch.py --environment-name <environment-name> --res-version 2024.04.02 --module cluster-manager --patch samaccountname_regex.patch 

3. To restart the Cluster Manager instance for your environment, run the following commands, replacing <environment-name> with the name of your RES environment. You may also terminate the instance from the Amazon EC2 Management Console.

   ENVIRONMENT_NAME=<environment-name>
   
   INSTANCE_ID=$(aws ec2 describe-instances \
       --filters \
       Name=tag:Name,Values=${ENVIRONMENT_NAME}-cluster-manager \
       Name=tag:res:EnvironmentName,Values=${ENVIRONMENT_NAME}\
       --query "Reservations[0].Instances[0].InstanceId" \
       --output text)
    
   aws ec2 terminate-instances --instance-ids ${INSTANCE_ID}