Extended Attributes: Re-write of xattrs information

This section is about how to include xattrs when you create
bootable media using 'tar'.  For now, it remains in the
"Troubleshooting" section.

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>

1 files changed, 49 insertions, 28 deletions

diff --git a/docs/getting-started/troubleshooting.md b/docs/getting-started/troubleshooting.md
index 4e2b495..ea3aba1 100644
--- a/docs/getting-started/troubleshooting.md
+++ b/docs/getting-started/troubleshooting.md
@@ -8,34 +8,55 @@
   into their respective build topics in the section describing how to
   build an AGL image.
 
-## Extended attributes MUST be copied
-
-**IMPORTANT, The extended attribute set during image construction MUST be copied to the SD card.**
-
-When using tar to create the SDcard, it is a common error to not copy the extended attributes. Find below instruction for using tar.
-
-Verify that **tar** version is 1.28 or newer:
-
-```bash
-tar --version
-tar (GNU tar) 1.28
-[snip]
-```
-
-If it is not the case, a native up-to-date version of tar is also generated while building AGL distribution:
-
-```bash
-tmp/sysroots/x86_64-linux/usr/bin/tar-native/tar --version
-tar (GNU tar) 1.28
-[snip]
-```
-
-To copy Automotive Grade Linux (AGL) files AND EXTENDED ATRIBUTES onto the SDcard using tar the command is:
-
-```bash
-tar --extract --xz --numeric-owner --preserve-permissions --preserve-order --totals \
-           --xattrs-include='*' --directory=DESTINATION_DIRECTORY --file=agl-demo-platform.....tar.xz
-```
+## Including Extended Attributes
+
+The
+[Extended Attributes Set (`xattrs`)](https://linux-audit.com/using-xattrs-extended-attributes-on-linux/)
+associated with the image during its construction must be copied to
+the bootable media.
+The `xattrs` supports
+[Smack](https://en.wikipedia.org/wiki/Smack_(software)), which is a
+Simplified Mandatory Access Control kernel.
+
+**NOTE:** See
+  [https://www.kernel.org/doc/Documentation/security/Smack.txt](https://www.kernel.org/doc/Documentation/security/Smack.txt).
+  for detailed information on Smack.
+
+Many methods exist that allow you to create bootable media (e.g. `dd`, `bmaptools`,
+`tar`, and AGL-provided scripts such as `mkabl-agl.sh` and `mkefi-agl.sh`).
+It is recommended that you do not use `tar` to create bootable media.
+However, if you do, you must take these steps to copy `xattrs` to the media:
+
+1. Verify your `tar` version is 1.28 or newer:
+
+   ```bash
+   $ tar --version
+   tar (GNU tar) 1.28
+   [snip]
+   ```
+
+2. Optionally update `tar` if required.
+   Most systems come with `tar` installed.
+   If you need to install it, see the
+   "[Installing tar](https://www.howtoforge.com/tutorial/linux-tar-command/#installing-tar)"
+   section for instructions.
+
+   When you build an AGL distribution, a native up-to-date version of
+   `tar` is created.
+   Use the following command to see that version:
+
+   ```bash
+   $ tmp/sysroots/x86_64-linux/usr/bin/tar-native/tar --version
+   tar (GNU tar) 1.28
+   [snip]
+   ```
+
+3. Copy the AGL files and Extended Attributes Set to your bootable media:
+
+   ```bash
+   $ tar --extract --xz --numeric-owner --preserve-permissions --preserve-order --totals \
+              --xattrs-include='*' --directory=DESTINATION_DIRECTORY --file=agl-demo-platform.....tar.xz
+   ```
 
 <!--
 ## meta-rust