AWS res documentation change
Summary
Added troubleshooting sections for Active Directory issues and VDI performance/display problems. Removed custom domain setup documentation. Added new runbooks: launching large numbers of VDIs, blank VDI screens, and Active Directory troubleshooting scenarios.
Security assessment
Changes consist of troubleshooting documentation updates without evidence of security vulnerability fixes. Added AD sections describe configuration issues, not vulnerabilities. Removed custom domain setup doesn't indicate security remediation. No CVEs, vulnerabilities, or security incidents referenced.
Diff
diff --git a/res/archive/release-minus-4/ug/res-troubleshooting-issue-runbooks.md b/res/archive/release-minus-4/ug/res-troubleshooting-issue-runbooks.md index d6826011d..ce334c45e 100644 --- a//res/archive/release-minus-4/ug/res-troubleshooting-issue-runbooks.md +++ b//res/archive/release-minus-4/ug/res-troubleshooting-issue-runbooks.md @@ -7 +7 @@ -Installation issuesIdentity management issuesStorageSnapshotsInfrastructureLaunching Virtual DesktopsVirtual Desktop ComponentEnv deletionDemo environment +Installation issuesIdentity management issuesStorageSnapshotsInfrastructureLaunching Virtual DesktopsVirtual Desktop ComponentEnv deletionDemo environmentActive Directory issues @@ -15,2 +14,0 @@ The following section contains issues that may occur, how to detect them, and su - * I want to set up custom domains after I install RES - @@ -70,0 +69,2 @@ The following section contains issues that may occur, how to detect them, and su + * I need to launch / resume a large number of VDIs in the RES web portal + @@ -84,0 +85,2 @@ The following section contains issues that may occur, how to detect them, and su + * VDI session goes to a blank screen after logging in + @@ -120,0 +123,12 @@ The following section contains issues that may occur, how to detect them, and su + * Active Directory issues + + * My VDI is stuck in the provisioning state for a long time, or I cannot login my VDI as an AD user after the VDI is ready + + * I cannot login the RES web portal after configuring SSO + + * AD user cannot access the home directory using File Browser even after launching Linux VDIs successfully + + * AD admin user cannot access the Bastion Host after SSH access is enabled + + * View and manage my Active Directory deployed by RES external resource stack + @@ -128,2 +141,0 @@ The following section contains issues that may occur, how to detect them, and su - * I want to set up custom domains after I install RES - @@ -147,88 +158,0 @@ The following section contains issues that may occur, how to detect them, and su -........................ - -### I want to set up custom domains after I install RES - -###### Note - - _Prerequisites_ : You must store Certificate and PrivateKey contents in a Secrets Manager secret before performing these steps. - -###### Add certs to the web client - - 1. Update the cert attached to the listener of the external-alb load balancer: - - 1. Navigate to the RES external load balancer in the AWS console under **EC2** > **Load Balancing** > **Load Balancers**. - - 2. Search for the load balancer that follows the naming convention ``<env-name>`-external-alb`. - - 3. Check the listeners attached to the load balancer. - - 4. Update the listener that has a Default SSL/TLS certificate attached with the new certificate details. - - 5. Save your changes. - - 2. In the cluster-settings table: - - 1. Find the cluster-settings table in DynamoDB -> Tables -> ``<env-name>`.cluster-settings`. - - 2. Go to **Explore Items** and **Filter by Attribute** – name "key", Type "string", condition "contains", and value "external_alb". - - 3. Set `cluster.load_balancers.external_alb.certificates.provided` to True. - - 4. Update the value of `cluster.load_balancers.external_alb.certificates.custom_dns_name`. This is the custom domain name for web user interface. - - 5. Update the value of `cluster.load_balancers.external_alb.certificates.acm_certificate_arn`. This is the Amazon Resource Name (ARN) for the corresponding certificate stored in Amazon Certificate Manager (ACM). - - 3. Update the corresponding Route53 subdomain record you created for your web client to point to the DNS name of the external alb load balancer `<env-name>-external-alb`. - - 4. If SSO is already configured in the environment, re-configure SSO with the same inputs as you used initially from the **Environment Management** > **Identity management** > **Single Sign-On** > **Status** > **Edit** button in the RES web portal. - - - - -###### Add certs to the VDIs - - 1. Grant the RES application permission to perform a GetSecret operation on the secret by adding the following tags to the secrets: - - * `res:EnvironmentName` : ``<env-name>`` - - * `res:ModuleName` : `virtual-desktop-controller` - - 2. In the cluster-settings table: - - 1. Find the cluster-settings table in DynamoDB -> Tables -> ``<env-name>`.cluster-settings`. - - 2. Go to **Explore Items** and **Filter by Attribute** – name "key", Type "string", condition "contains", and value "dcv_connection_gateway". - - 3. Set `vdc.dcv_connection_gateway.certificate.provided` to True. - - 4. Update the value of `vdc.dcv_connection_gateway.certificate.custom_dns_name`. This is the custom domain name for VDI access. - - 5. Update the value of `vdc.dcv_connection_gateway.certificate.certificate_secret_arn`. This is the ARN for the secret that holds the Certificate contents. - - 6. Update the value of `vdc.dcv_connection_gateway.certificate.private_key_secret_arn`. This is the ARN for the secret that holds the Private Key contents. - - 3. Update the launch template used for the gateway instance: - - 1. Open the Auto Scaling group in the AWS Console under **EC2** > **Auto Scaling** > **Auto Scaling Groups**. - - 2. Select the gateway auto scaling group that corresponds to the RES environment. The name follows the naming convention ``<env-name>`-vdc-gateway-asg`. - - 3. Find and open the Launch Template in the details section. - - 4. Under **Details** > **Actions** > choose **Modify template** (Create new version). - - 5. Scroll down to **Advanced details**. - - 6. Scroll to the very bottom, to **User data**. - - 7. Look for the words `CERTIFICATE_SECRET_ARN` and `PRIVATE_KEY_SECRET_ARN`. Update these values with the ARNs given to the secrets that hold the Certificate (see step 2.c) and Private Key (see step 2.d) contents. - - 8. Ensure the Auto Scaling group is configured to use the recently created version of the launch template (from the Auto Scaling group page). - - 4. Update the corresponding Route53 subdomain record you created for your virtual desktops to point to the DNS name of the external nlb load balancer: ``<env-name>`-external-nlb`. - - 5. Terminate the existing dcv-gateway instance: ``<env-name>`-vdc-gateway` and wait for a new one to spin up. - - - - @@ -814,0 +739,2 @@ If both Healthy and Unhealthy entries are 0, that indicates a potential network + * I need to launch / resume a large number of VDIs in the RES web portal + @@ -828,0 +755,2 @@ If both Healthy and Unhealthy entries are 0, that indicates a potential network + * VDI session goes to a blank screen after logging in + @@ -831,0 +760,12 @@ If both Healthy and Unhealthy entries are 0, that indicates a potential network +........................ + +### I need to launch / resume a large number of VDIs in the RES web portal + +When you launch or resume a large number of VDIs in batch, they may end up in the Error state due to the configured provisioned throughput (5 - 20) for the ``environment-name`.vdc.dcv-broker.dcvServer` DynamoDB tables. + +To get around this issue, you can change the maximum read / write capacity units of the ``environment-name`.vdc.dcv-broker.dcvServer` table in the AWS DynamoDB console based on the historical capacity usage data as shown here: + + + +Note that launching 5 VDIs requires about 1 WCU of write operations and changing the read / write capacity units may impact your cost on RES. Please check [Pricing for Provisioned Capacity](https://aws.amazon.com/dynamodb/pricing/provisioned/) on the _Amazon DynamoDB pricing page_ for more details. + @@ -838 +778 @@ If you're able to launch a Windows Virtual Desktop in the RES web portal but its -To verify, connect to the Windows instance from the Amazon EC2 console and check the bootstrap logs under `C:\Users\Administrator\RES\Bootstrap\virtual-desktop-host-windows\`. An error message starting with `[Join AD] authorization failed:` indicates that the instance failed to join the AD. Check the Cluster Manager logs in CloudWatch under the log group name ``<res-environment-name>`/cluster-manager` for more details about the failure: +To verify, connect to the Windows instance from the Amazon EC2 console and check the bootstrap logs under `C:\Users\Administrator\RES\Bootstrap\virtual-desktop-host-windows\`. An error message starting with `[Join AD] authorization failed:` indicates that the instance failed to join the AD. Check the Cluster Manager logs in CloudWatch under the log group name `/`<res-environment-name>`/cluster-manager` for more details about the failure: @@ -1047,0 +988,18 @@ This could be the issue you are facing if the following scenarios are true: +........................ + +### VDI session goes to a blank screen after logging in + +When a VDI session with Console Session type is blank and unresponsive after you log in, this means that the X server is broken. This likely is due to a OS issue where DCV is attempting to stream the desktop, but there isn't one to stream. The most probable cause of this is an issue with the Xorg configuration. The following command can be run to rely less on the default Xorg configuration. + +**Debian based Linux:** + + + dpkg-divert --package nice-xdcv --divert /usr/bin/Xorg.orig --rename /usr/bin/Xorg ln -sf /usr/bin/Xdcv-console /usr/bin/Xorg + +**Red Hat based Linux:** + + + rpm -q --whatprovides /usr/bin/Xorg && \ + cp /usr/bin/Xorg /usr/bin/Xorg.orig && \ + ln -sf /usr/bin/Xdcv-console /usr/bin/Xorg + @@ -1470,0 +1429,100 @@ Make sure the stack has been deleted completely. +........................ + +## Active Directory issues + +###### Topics + + * My VDI is stuck in the provisioning state for a long time, or I cannot login my VDI as an AD user after the VDI is ready + + * I cannot login the RES web portal after configuring SSO + + * AD user cannot access the home directory using File Browser even after launching Linux VDIs successfully + + * AD admin user cannot access the Bastion Host after SSH access is enabled + + * View and manage my Active Directory deployed by RES external resource stack + + + + +### My VDI is stuck in the provisioning state for a long time, or I cannot login my VDI as an AD user after the VDI is ready + +Check the VDI installation and configuration logs (`/root/bootstrap/logs/` and `/opt/idea/app/logs/` directories for Linux, or `C:\Users\Administrator\RES\Bootstrap\Log\` and `C:\Program Files\RES\app\logs\` directories for Windows) first for any installation or configuration errors. + +If you find an error message saying that the instance failed to join Active Directory, this is usually because the Cluster Manager cannot preset the computer account for the instance in your AD. Check the Cluster Manager logs under the `/`environment-name`/cluster-manager` CloudWatch log group and filter for error messages that contains `[preset-computer]`. Common issues include: + + * Credentials for the AD Service Account are invalid. + + * Check the Service Account secret you provided to RES. Make sure that the username and password are provided as a key value pair `{`username`: `password`}` and credentials are valid. You will need to cycle the Cluster Manager instance by terminating the existing instance and allowing the auto scaling group to launch a new one automatically after you change the Service Account secret. Then launch new VDIs to apply the change. + + * Service Account doesn't have the permission to create computer accounts in AD. + + * Make sure that your Service Account has all the required permissions listed at [Set up a Service Account for Microsoft Active Directory](./prerequisites.html#service-account-ms-ad). You will need to launch new VDIs after fixing the Service Account permissions in AD. + + * Cannot connect to the LDAP server. + + * Make sure that your AD configuration allows LDAP/LDAPS connection within the VPC and the DHCP option of your VPC is set properly following [ Creating or changing a DHCP options set for AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/dhcp_options_set.html) if you're using AWS managed AD. +