AWS AWSEC2 documentation change
Summary
Restructured documentation to clarify update processes for different Mac instance types. Added detailed prerequisites and procedures for ENA driver updates, volume ownership delegation, and secure token configuration for Apple silicon instances.
Security assessment
The changes introduce security-related documentation for administrative user authentication (password setup, secure token activation) and credential management for volume ownership delegation. While the ENA driver update addresses compatibility issues, there is no explicit mention of a security vulnerability being patched. The security documentation additions focus on hardening authentication processes rather than addressing a disclosed vulnerability.
Diff
diff --git a/AWSEC2/latest/UserGuide/mac-instance-updates.md b/AWSEC2/latest/UserGuide/mac-instance-updates.md index ca2167fda..5241b72f3 100644 --- a//AWSEC2/latest/UserGuide/mac-instance-updates.md +++ b//AWSEC2/latest/UserGuide/mac-instance-updates.md @@ -5 +5 @@ -Update software on x86 Mac instancesUpdate software on Apple silicon Mac instances +# Update the operating system and software on Amazon EC2 Mac instances @@ -7 +7 @@ Update software on x86 Mac instancesUpdate software on Apple silicon Mac instanc -# Update the operating system and software on Mac instances +The following topic explains how to update the operating system and software on Apple silicon Mac instances (Mac2, Mac2-m1ultra, Mac2-m2, Mac2-m2pro) and x86 Mac instances (Mac1). @@ -15 +15 @@ Attempting to install beta or preview macOS versions on Amazon EC2 x86 Mac insta -###### Steps to update software on x86 Mac instances and Apple silicon Mac instances: +###### Follow the correct steps below, depending on your Amazon EC2 Mac instance type. @@ -17 +16,0 @@ Attempting to install beta or preview macOS versions on Amazon EC2 x86 Mac insta - * Update software on x86 Mac instances @@ -19 +17,0 @@ Attempting to install beta or preview macOS versions on Amazon EC2 x86 Mac insta - * Update software on Apple silicon Mac instances @@ -21,0 +20 @@ Attempting to install beta or preview macOS versions on Amazon EC2 x86 Mac insta +### Prerequisites @@ -22,0 +22 @@ Attempting to install beta or preview macOS versions on Amazon EC2 x86 Mac insta +Due to an update in the network driver configuration, ENA driver version 1.0.2 isn't compatible with macOS 13.3 and later. If you want to install any beta, preview, or production macOS version 13.3 or later and have not installed the latest ENA driver, use the following procedure to install a new version of the driver. @@ -24 +24 @@ Attempting to install beta or preview macOS versions on Amazon EC2 x86 Mac insta -## Update software on x86 Mac instances +###### To install a new version of the ENA driver @@ -26 +26 @@ Attempting to install beta or preview macOS versions on Amazon EC2 x86 Mac insta -On x86 Mac instances, you can install operating system updates from Apple using the `softwareupdate` command. + 1. In a Terminal window, connect to your Apple silicon Mac instance using [SSH](./connect-to-mac-instance.html#mac-instance-ssh). @@ -28 +28 @@ On x86 Mac instances, you can install operating system updates from Apple using -Supported instance types: `mac1.metal` + 2. Update Homebrew and download the ENA application into the `Applications` file using the following command. @@ -30 +30 @@ Supported instance types: `mac1.metal` -###### **To install operating system updates from Apple on x86 Mac instances** + [ec2-user ~]$ brew update @@ -32 +32 @@ Supported instance types: `mac1.metal` - 1. List the packages with available updates using the following command. + [ec2-user ~]$ brew install amazon-ena-ethernet-dext @@ -34 +34 @@ Supported instance types: `mac1.metal` - [ec2-user ~]$ softwareupdate --list + 3. Disconnect from your instance by typing **exit** and pressing return. @@ -36 +36 @@ Supported instance types: `mac1.metal` - 2. Install all updates or only specific updates. To install specific updates, use the following command. + 4. Use the VNC client to activate the ENA application. @@ -38 +38 @@ Supported instance types: `mac1.metal` - [ec2-user ~]$ sudo softwareupdate --install label + 1. Setup the VNC client using [Connect to your instance's graphical user interface (GUI)](./connect-to-mac-instance.html#mac-instance-vnc). @@ -40 +40 @@ Supported instance types: `mac1.metal` -To install all updates instead, use the following command. + 2. Once you have connected to your instance using the Screen Sharing application, go to the **Applications** folder and open the ENA application. @@ -42 +42 @@ To install all updates instead, use the following command. - [ec2-user ~]$ sudo softwareupdate --install --all --restart + 3. Choose **Activate** @@ -43,0 +44 @@ To install all updates instead, use the following command. + 4. To confirm the driver was activated correctly, run the following command in the Terminal window. The output of the command shows that the old driver is in the terminating state and the new driver is in the activated state. @@ -44,0 +46 @@ To install all updates instead, use the following command. + systemextensionsctl list; @@ -45,0 +48 @@ To install all updates instead, use the following command. + 5. After you restart the instance, only the new driver will be present. @@ -47 +49,0 @@ To install all updates instead, use the following command. -System administrators can use AWS Systems Manager to roll out pre-approved operating system updates on x86 Mac instances. For more information, see the [AWS Systems Manager User Guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/). @@ -49 +50,0 @@ System administrators can use AWS Systems Manager to roll out pre-approved opera -You can use Homebrew to install updates to packages in the EC2 macOS AMIs, so that you have the latest version of these packages on your instances. You can also use Homebrew to install and run common macOS applications on Amazon EC2 macOS. For more information, see the [Homebrew Documentation](https://docs.brew.sh/). @@ -51 +51,0 @@ You can use Homebrew to install updates to packages in the EC2 macOS AMIs, so th -###### To install updates using Homebrew @@ -53 +53 @@ You can use Homebrew to install updates to packages in the EC2 macOS AMIs, so th - 1. Update Homebrew using the following command. +### Perform the software update @@ -55 +55 @@ You can use Homebrew to install updates to packages in the EC2 macOS AMIs, so th - [ec2-user ~]$ brew update +On Apple silicon Mac instances, you must complete several steps to perform an in-place operating system update. This includes delegating ownership of the Amazon EBS root volume to the EBS root volume administrative user. You can choose to do this either automatically using an Amazon EC2 API, or you can do it manually by running the commands on your instance. @@ -57 +57 @@ You can use Homebrew to install updates to packages in the EC2 macOS AMIs, so th - 2. List the packages with available updates using the following command. +Automated volume ownership delegation (Recommended) @@ -59 +58,0 @@ You can use Homebrew to install updates to packages in the EC2 macOS AMIs, so th - [ec2-user ~]$ brew outdated @@ -61 +60 @@ You can use Homebrew to install updates to packages in the EC2 macOS AMIs, so th - 3. Install all updates or only specific updates. To install specific updates, use the following command. +###### Considerations @@ -63 +62 @@ You can use Homebrew to install updates to packages in the EC2 macOS AMIs, so th - [ec2-user ~]$ brew upgrade package name + * It can take between 30 and 90 minutes for the volume ownership delegation task to complete. During this time, the instance is unreachable. @@ -65 +64 @@ You can use Homebrew to install updates to packages in the EC2 macOS AMIs, so th -To install all updates instead, use the following command. + * The following macOS versions are supported: @@ -67 +66 @@ To install all updates instead, use the following command. - [ec2-user ~]$ brew upgrade + * **Mac2 | Mac2-m1ultra** — macOS Ventura (version 13.0 or later) @@ -68,0 +68 @@ To install all updates instead, use the following command. + * **Mac2-m2 | Mac2-m2pro** — macOS Ventura (version 13.2 or later) @@ -69,0 +70 @@ To install all updates instead, use the following command. + * Instances must have only one bootable volume, and each attached volume can have only one additional admin user. @@ -72 +72,0 @@ To install all updates instead, use the following command. -## Update software on Apple silicon Mac instances @@ -74 +73,0 @@ To install all updates instead, use the following command. -Supported instance types: `mac2.metal`, `mac2-m1ultra.metal`, `mac2-m2.metal`, `mac2-m2pro.metal` @@ -76 +75 @@ Supported instance types: `mac2.metal`, `mac2-m1ultra.metal`, `mac2-m2.metal`, ` -### Considerations +###### Step 1: Set a password and enable the secure token for the EBS root volume administrative user @@ -78 +77 @@ Supported instance types: `mac2.metal`, `mac2-m1ultra.metal`, `mac2-m2.metal`, ` -###### Elastic Network Adapter (ENA) driver +You must set a password and enable the secure token for the Amazon EBS root volume administrative user (`ec2-user`). @@ -80 +79 @@ Supported instance types: `mac2.metal`, `mac2-m1ultra.metal`, `mac2-m2.metal`, ` -Due to an update in the network driver configuration, ENA driver version 1.0.2 isn't compatible with macOS 13.3 or greater. If you want to install any beta, preview, or production macOS version 13.3 or later and have not installed the latest ENA driver, use the following procedure to install a new version of the driver. +###### Note @@ -82 +81 @@ Due to an update in the network driver configuration, ENA driver version 1.0.2 i -###### To install a new version of the ENA driver +The password and secure token are set the first time you connect to an Apple silicon Mac instance using the GUI. If you previously [ connected to the instance using the GUI](./connect-to-mac-instance.html#mac-instance-vnc), you **do not** need to perform these steps. @@ -84 +83 @@ Due to an update in the network driver configuration, ENA driver version 1.0.2 i - 1. In a Terminal window, connect to your Apple silicon Mac instance using [SSH](./connect-to-mac-instance.html#mac-instance-ssh). + 1. [Connect to the instance using SSH](./connect-to-mac-instance.html#mac-instance-ssh). @@ -86 +85 @@ Due to an update in the network driver configuration, ENA driver version 1.0.2 i - 2. Download the ENA application into the `Applications` file using the following command. + 2. Set the password for the `ec2-user` user. @@ -88 +87 @@ Due to an update in the network driver configuration, ENA driver version 1.0.2 i - [ec2-user ~]$ brew install amazon-ena-ethernet-dext + $ sudo /usr/bin/dscl . -passwd /Users/ec2-user @@ -90 +89 @@ Due to an update in the network driver configuration, ENA driver version 1.0.2 i -###### Troubleshooting tip + 3. Enable the secure token for the `ec2-user` user. For `-oldPassword`, specify the same password from the previous step. For `-newPassword`, specify a different password. The following command assumes that you have your old and new passowords saved in `.txt` files. @@ -92 +91 @@ Due to an update in the network driver configuration, ENA driver version 1.0.2 i -If you receive the warning `No available formula with the name amazon-ena-ethernet-dext`, run the following command. + $ sysadminctl -oldPassword `cat old_password.txt` -newPassword `cat new_password.txt` @@ -94 +93 @@ If you receive the warning `No available formula with the name amazon-ena-ethern - [ec2-user ~]$ brew update + 4. Verify that the secure token is enabled. @@ -96 +95 @@ If you receive the warning `No available formula with the name amazon-ena-ethern - 3. Disconnect from your instance by typing **exit** and pressing return. + $ sysadminctl -secureTokenStatus ec2-user @@ -98 +96,0 @@ If you receive the warning `No available formula with the name amazon-ena-ethern - 4. Use the VNC client to activate the ENA application. @@ -100 +97,0 @@ If you receive the warning `No available formula with the name amazon-ena-ethern - 1. Setup the VNC client using [Connect to your instance's graphical user interface (GUI)](./connect-to-mac-instance.html#mac-instance-vnc). @@ -102 +98,0 @@ If you receive the warning `No available formula with the name amazon-ena-ethern - 2. Once you have connected to your instance using the Screen Sharing application, go to the **Applications** folder and open the ENA application. @@ -104 +100 @@ If you receive the warning `No available formula with the name amazon-ena-ethern - 3. Choose **Activate** +###### Step 2: Delegate ownership of the Amazon EBS root volume to the EBS root volume administrative user @@ -106 +102 @@ If you receive the warning `No available formula with the name amazon-ena-ethern - 4. To confirm the driver was activated correctly, run the following command in the Terminal window. The output of the command shows that the old driver is in the terminating state and the new driver is in the activated state. +To delegate ownership, you must create a volume ownership delegation task. @@ -108 +104 @@ If you receive the warning `No available formula with the name amazon-ena-ethern - systemextensionsctl list; + 1. Use the [ create-delegate-mac-volume-ownership-task](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) command to create the task. For `--instance-id`, specify the ID of the instance. For `--mac-credentials`, specify the following credentials: @@ -110 +106,15 @@ If you receive the warning `No available formula with the name amazon-ena-ethern - 5. After you restart the instance, only the new driver will be present. + * **Internal disk administrative user** + + * **Username** — Only the default administrative user (`aws-managed-user`) is supported and it is used by default. You can't specify a different administrative user. + + * **Password** — If you did not change the default password for `aws-managed-user`, specify the default password, which is _blank_. Otherwise, specify your password. + + * **Amazon EBS root volume administrative user** + + * **Username** — If you did not change the default administrative user, specify `ec2-user`. Otherwise, specify the username for your administrative user. + + * **Password** — Specify the password that you set for root volume admin user in Step 1 above. + + aws ec2 create-delegate-mac-volume-ownership-task \ + --instance-id i-1234567890abcdef0 \ + --mac-credentials file://mac-credentials.json @@ -111,0 +122 @@ If you receive the warning `No available formula with the name amazon-ena-ethern +The following is the contents of the `mac-credentials.json` file referenced in the preceding examples. @@ -112,0 +124,5 @@ If you receive the warning `No available formula with the name amazon-ena-ethern + { + "internalDiskPassword":"_internal-disk-admin_password_ ", + "rootVolumeUsername":"_root-volume-admin_username_ ", + "rootVolumepassword":"_root-volume-admin_password_ " + } @@ -113,0 +130 @@ If you receive the warning `No available formula with the name amazon-ena-ethern + 2. Wait for the volume ownership delegation task to complete and for the instance to return to a healthy state. Use the [ describe-mac-modification-tasks](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-mac-modification-tasks.html) command. For `--mac-modification-task-id`, specify the ID of the volume ownership delegation task from the previous step. @@ -115 +132,2 @@ If you receive the warning `No available formula with the name amazon-ena-ethern -### Software update on Apple silicon Mac instances + aws ec2 describe-mac-modification-tasks \ + --mac-modification-task-id task-id @@ -117 +135 @@ If you receive the warning `No available formula with the name amazon-ena-ethern -On Apple silicon Mac instances, you must complete several steps to perform an in-place operating system update. First, access the internal disk of the instance using the GUI with a VNC (Virtual Network Computing) client. This procedure uses macOS Screen Sharing, the built in VNC client. Then, delegate ownership to the administrative user (`ec2-user`) by signing in as `aws-managed-user` on the Amazon EBS volume. + 3. After the volume ownership delegation task completes, continue to Step 3. @@ -119 +137,11 @@ On Apple silicon Mac instances, you must complete several steps to perform an in -As you work through this procedure, you create two passwords. One password is for the administrative user (`ec2-user`) and the other password is for a special administrative user (`aws-managed-user`). Remember these passwords since you will use them as you work through the procedure. + + + +###### Step 3: Update the software + +After you have delegated ownership of the Amazon EBS root volume, follow the steps described in Update software on x86 Mac instances (below) to update the software. + +Manual volume ownership delegation + + +As you work through this procedure, you create two passwords. One password is for the Amazon EBS root volume administrative user (`ec2-user`), and the other password is for the internal disk administrative user (`aws-managed-user`). Remember these passwords since you will use them as you work through the procedure. @@ -125 +153 @@ With this procedure on macOS Big Sur, you can only perform minor updates such as -###### **To access the internal disk** +###### To access the internal disk @@ -272,0 +301,44 @@ If you get the warning `WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!`, run t +On x86 Mac instances, you can install operating system updates from Apple using the `softwareupdate` command. + +###### To install operating system updates from Apple on x86 Mac instances + + 1. List the packages with available updates using the following command. + + [ec2-user ~]$ softwareupdate --list