Merge branch 'master' into PD-1706-document-new-cloud-backup-option

content/Contributing/Applications/_index.md

@@ -37,7 +37,7 @@ Users can submit changes to an existing application catalogs through:
   To request a feature change, go to the [TrueNAS Community Forum](https://forums.truenas.com/), and click **Feature Request**.
   Read the **About the Feature Requests category - README First** topic, then click **Open Draft** on the top right of the screen.
   Populate the new request form with the relevant information for each section, **Problem/Justification**, **Impact**, and **User Story**.
-  The form provides guidance on how to populate these sections.
+  The form guides you on populating these sections.
   Click **Create Topic** to add your suggestion to the list of topics.
 
   Users vote and comment on these suggestions.
@@ -49,23 +49,130 @@ Users can submit changes to an existing application catalogs through:
 To see a current list of apps, visit the [TrueNAS Apps repository](https://github.com/truenas/apps) on GitHub.
 
 ## Contributing to TrueNAS Application Documentation
-Community members can submit change requests or add new tutorials to the Community Apps tutorials section of the Documentation Hub.
+Community members can submit change requests or add new tutorials to the **Truenas Apps > Community Apps** tutorials section of the Documentation Hub.
+
 For more information on submitting change requests, forking repos, and submitting PRs, see [Updating Content]({{< relref "/Contributing/Documentation/ContentUpdate.md" >}}).
 
+### Submitting New Tutorial Articles
 When submitting new tutorials or requesting changes to existing TrueNAS Documentation Hub application tutorials:
 
-* Create the PR against a forked copy of the [TrueNAS Documentation Hub public repository](https://github.com/truenas/documentation/tree/master).
-
-  In your local forked repository, open the existing article file in either the **CommunityApps** or the **StableApps** folder of the **/content/TrueNASApps/** directory.
+1. Create the PR against a forked copy of the [TrueNAS Documentation Hub public repository](https://github.com/truenas/documentation/tree/master).
+  
+2. Open the existing article file in the <file>/content/TrueNASApps/CommunityApps</file> directory of your local forked repository.
 
-  If submitting a new tutorial, add the new tutorial to the **CommunityApps** folder in your local copy of the repository.
+3. Add the new tutorial to the <file>CommunityApps</file> folder in your local copy of the repository if submitting a new tutorial.
 
-  Use the text editor of your choice to make changes to the [application tutorial template]({{< relref "/Contributing/Applications/AppArticleTemplate.md" >}}) as the basis for your new article.
+4. Use the text editor of your choice to make changes to the [application tutorial template]({{< relref "/Contributing/Applications/AppArticleTemplate.md" >}}) as the basis for your new article.
   Article content is written in Commonmark Markdown.
 
-  (Optional) Save images in the **/documentation/static/images/scale/apps** folder of your local branch.
+5. (Optional) Save images in the **/documentation/static/images/scale/apps** folder of your local branch.
+
+6. Submit the PR against the **Master** branch.
+
+### Using the App Tutorial Template
+Feel free to change standard article content by adding or removing sections to fit the app installation process.
+Change the front matter <file>description:</file> parameter at the top of the article to suit the subject and content of the new tutorial.
+Description text must not exceed 160 alphanumeric or special characters, including spaces between characters.
+After updating content, delete commented-out sections providing instructions for using this template when they are no longer needed.
+When documenting a **Community** train app, not delete any of the commented-out instructions in the COMMUNITY APP INTRO SNIPPETS section.
 
-  Submit the PR against the **Master** branch.
+#### Formatting Tips for Content Development
+Standard text emphasis:
+* Apply **Bold** to UI elements seen on the screen, including field, button, and navigation option names, other descriptions, etc.
+  Use double asterisks preceding and following the name or text string to make it bold.
+  Do not use bold in code strings.
 
-* Click **Edit Article** at the top of the Documentation Hub article to request changes to an existing article.
-  Refer to the [Content Updates]({{< relref "/Contributing/Documentation/ContentUpdate.md" >}}) article for more details.
+* Apply *Italics* to any variable.
+  Use single asterisks preceding and following the name or text string to make it italics.
+  If using a variable in a code example, use the HTML tags (\<i>\</i>) and not the Markdown tags.
+
+* Apply HTML file tags (<code>\<file>\</file></code>) when entering a path to a file or file name, for example <code>\<file>iso\</file></code>, which renders as <file>iso</file>.
+
+* Apply HTML keyboard tags (<code>\<kbd>\</kbd></code>) to keys on a keyboard, for example <code>\<kbd>Enter\</kbd></code>, which renders as <kbd>Enter</kbd>.
+
+When entering commands, command strings, or code blocks:
+
+* Apply backticks(<code>\`\`</code>) or HTML <code>\<code>\</code></code> tags to format command strings or output, for example <code>\`string\`</code> or <code>\<code>string\</code></code>, which render as <code>string</code>.
+
+* Apply HTML <code>\<code>\</code></code> tags to strings with variables.
+
+  * Do not enclose variables in angle or square brackets as these can also be part of command syntax.
+
+  * Do not enter variables in all caps unless the command requires entering the value in all caps.
+
+To create a code block, either use three backticks (<code>```</code>) on the line before and after the content block, or use the HTML code tags.
+
+#### Using the Apps Snippet Library
+When creating your articles you can use the library of snippets that contain explanations of settings and configuration instructions for the various app Install Wizard settings in your submitted content.
+These snippets are maintained by the Technical Documentation team, but you can submit change requests for these files just as with full articles if you find content that needs updating or changing.
+
+The tutorial template includes the shortcode that calls these files into the app wizard sections of the Stable Apps and Enterprise Apps tutorials in the Documentation Hub.
+To use snippets where the template does not have one, enter the include file shortcode where you want to call another snippet.
+The shortcode to call snippet files is <code>{{\<include&nbsp;file="/static/includes/apps/snippetFileName.md">}}</code>, where *snippetFileName.md* is the name of the snippet file.
+
+The following table shows the current list of snippet files.
+{{< expand "App Tutorial Snippet Files" "v" >}}
+Snippet files are located in the <file>/documentation/static/includes/apps</file> folder.
+Not all snippet files in this folder apply to tutorial content.
+Refer to the tables below for a list of snippet files with content about tutorial sections.
+Open and read snippet files to determine where to use them in your tutorial.
+
+**Community Apps General Snippets**
+{{< truetable >}}
+| File Name | Snippet Use and Content |
+|-----------|-------------------------|
+| CommunityApp.md | Introduces Community Apps section tutorials, and contributing content. |
+| CommunityPleaseExpand.md | States the tutorial is incomplete or a placeholder needing further development. Use if you are proposing a partial expansion of the content, but further work is needed. | 
+| CommunityPleaseImprove.md | States the tutorial content is suspected to be out of date or inaccurate. Use if you suspect the Community app documentation is out of date, inaccurate, or needs further improvement. |
+{{< /truetable >}}
+
+**Before You Begin Snippets**
+{{< truetable >}}
+| File Name | Snippet Use and Content |
+|-----------|-------------------------|
+| BeforeYouBeginStableApps.md | Bullet point for adding the apps pool. Includes warning about choosing an encrypted pool for apps. |
+| BeforeYouBeginRunAsUser.md | Bullet point describing where to find the run as user information, and includes a screenshot of the app information screen for the app being documented. |
+| BeforeYouBegigAddAppDatasets.md | Bullet point for adding datasets for the app. Does does not include details on adding datasets as these vary by app. |
+| BeforeYouBeginAddAppDatasetsProcedure.md | Procedure for correctly creating datasets for apps in an expand/collapse area. |
+| BeforeYouBeginAddAppCertificate.md | Bullet point for adding a certificate if required for the app. Also include the AddingAppCertificate.md snippet with detailed instructions on adding a self-signed certificate. |
+| AddingAppCertificate.md | Detailed set procedure on adding a self-signed certificate authority (CA) and certificate. |
+| BeforeYouBeginAddNewUser.md | Single bullet point and procedure for adding a new user as a TrueNAS app administrator. |
+{{< /truetable >}}
+
+**Installing the App**
+{{< truetable >}}
+| File Name | Snippet Use and Content |
+|-----------|---------------------|
+| LocateAndOpenInstallWizard.md | Describes locating the app widget, and opening the install wizard for the app. |
+| MultipleAppInstancesAndNaming.md | Describes adding more than one instance of the same app and naming it. For example, adding two stable or community app instances, or an enterprise and stable train version of the same app. |
+| Configuring the app | InstallWizardEnvironVariablesSettings.md | Details the Environment Variable settings. Can use this if the procedure requires adding environment variables, or leave the snippet in the Understanding App Install Wizard section and refer to it for more information. |
+| InstallWizardAdvancedDNSSettings.md | Details the Advanced DNS setting options that might be included as part of the app configuration or network configuration settings. |
+{{< /truetable >}}
+
+**Understanding App Install Wizard Settings**
+{{< truetable >}}
+| Wizard Settings | File Name | Snippet Use and Content |
+|---------|-----------|---------------------|
+| App Name and Version | InstallWizardAppNameAndVersion.md | Details the **Application Name** and **Version** settings. |
+| Advanced DNS | InstallWizardAdvancedDNSSettings.md | Details DNS option settings. Might be included as a Network Configuration or App Configuration setting option. |
+| Environment Variables | InstallWizardEnvironVariablesSettings.md | Use in the Install Wizard Setting section, or if adding environment variables is required for configuring the app, use in the configuring the app procedure section. |
+| Timezone | InstallWizardTimezoneSetting.md |  |
+| Network (default ports) | InstallWizardDefaultPorts.md | Details changing the default port assignment. Can use this snippet in the Before You Begin and/or Installing the App sections, but is more suited to the section explaining the Network settings. |
+| Host Network  | InstallWizardHostNetworkSettings.md | Details the **Host Network** setting in the Network Configuration section of the wizard. Use when the wizard includes this setting. |
+| Certificate ID | InstallWizardCertificateSettings.md | Details **Certificate ID** settings, that might be optional and recommended, or required to deploy the app. Include this snippet if you used the two certificate snippets in the Before You Begin section. |
+| Storage Configuration | InstallAppsStorageConfig.md | Adds the **Setting the Storage Volume Type** expand section detailing storage volume types, configuring host path storage volume ACL permissions using the **Enable ACL** and **ACL Entries** options. Does not cover specific datasets required by the app. |
+| Storage Configuration | InstallAppsStorageConfig2.md | Adds the **Configuring Additional Storage Volumes** expand section detailing adding additional storage volumes, with a list of the **Additional Storage** types. |
+| Storage ACL permissions | InstallWizardStorageACLConfig.md | Details on the Edit ACL and ACE Entries settings. Includes the **Configuring ACE Entries** expand detailing how to add ACE entries, default user IDs for apps, or postgres storage volumes. |
+| Additional Storage SMB Option | InstallWizardStorageSMBOption.md | Details on the Additional Storage volume SMB share option. |
+| Storage Temporary and tmpfs directories | InstallWizardStorageTemporaryAndTmpfs.md | Details on the **Temporary** and **Tmpfs** directory storage options that are available as primary and/or additional storage volume types, and when to use each. |
+| Users and Groups | InstallWizardUserAndGroupConfig.md | Details user and group setting options. |
+| Labels Configuration | InstallWizardLabelsConfiguration.md | Details on using Docker label-based configuration. |
+| Resource Configuration | InstallWizardResourceConfig.md | Details CPU and memory setting options for all apps. If the app includes GPU passthrough, use with the InstallWizardGPUPassthrough.md snippet. |
+| GPU Passthrough | InstallWizardGPUPassthrough.md | Details information on GPU settings if the app includes the GPU passthrough settings. Not present if the app does not detect a GPU device. |
+{{< /truetable >}}
+{{< /expand >}}
+
+### Suggesting Edits to Existing Articles
+Click **Edit Article** at the top of the Documentation Hub article to suggest changes to an existing article.
+
+Refer to the [Content Updates]({{< relref "/Contributing/Documentation/ContentUpdate.md" >}}) article for more details.

content/SCALE/SCALETutorials/Credentials/ManageLocalUsersSCALE.md

@@ -37,7 +37,7 @@ TrueNAS hides all built-in users (except root) by default. Click the toggle **Sh
 
 TrueNAS 24.04 or newer supports administrator privileges for role-based administrator accounts.
 Users can create new administrator accounts with limited privileges based on their needs.
-Predefined administrator roles are read only, share admin, and the default full access local administrator account.
+Predefined administrator roles are read-only, share admin, and the default full access local administrator account.
 See [Using Administrator Logins]({{< relref "adminroles.md" >}}) for more information.
 
 {{< include file="/static/includes/AddAdminGroup.md" >}}
@@ -115,7 +115,7 @@ Do *not* paste the private key.
 
 Always keep a backup of an SSH public key if you are using one.
 
-As of TrueNAS 24.04, the **Shell** setting defaults to **nologin** for read only and sharing administrators, which means they cannot access the **Shell** screen.
+As of TrueNAS 24.04, the **Shell** setting defaults to **nologin** for read-only and sharing administrators, which means they cannot access the **Shell** screen.
 
 Select the [shell]({{< relref "LocalUsersScreensSCALE.md" >}}) option for the admin user from the **Shell** dropdown list.
 Options are **nologin**, **TrueNAS CLI**, **TrueNAS Console**, **sh**, **bash**, **rbash**, **dash**, **tmux**, and **zsh**.
@@ -136,12 +136,35 @@ While on the user configuration screen:
 
 Enter the path to the new dataset for home directories in **Home Directory**. For example, change **/var/empty/** to the path to the new dataset */tank/homedirs*.
 
-Next select **Create Home Directory**, and select the level of permissions you want to apply. We recommend leaving the default selections, **Read/Write/Execute** selected for the user home directory.
+Next, select **Create Home Directory**, and select the level of permissions you want to apply. We recommend leaving the default selections, **Read/Write/Execute** selected for the user home directory.
 
-Click **Save**. TrueNAS creates the new home directory for the user.
+Click **Save**. TrueNAS creates a new home directory for the user.
 
 ## Editing User Accounts
 
 To edit an existing user account, go to **Credentials > Users**.
 Click anywhere on the user row to expand the user entry, then click **Edit** to open the **Edit User** configuration screen.
 See [Local User Screens]({{< relref "LocalUsersScreensScale.md" >}}) for details on all settings.
+
+## Utilizing API Keys Feature
+
+{{< trueimage src="/images/SCALE/Credentials/UsersAPIKeysButton.png" alt="Users API Keys Option" id="Users API Keys Option" >}}
+
+To view API keys that are linked to different user accounts, you can visit **Credentials > Users** and click the **API Keys** button on the right side of the screen.
+
+{{< trueimage src="/images/SCALE/Credentials/UsersAPIKeysMenu.png" alt="Users API Keys Menu" id="Users API Keys Menu" >}}
+
+The **API Keys** selection takes users to the **Users API Keys** page, which provides a table of all API keys linked to user accounts on your TrueNAS. Information in this table includes the **Name**, **Username**, **Local** status, **Revoked** status, **Created Date**, and **Expires** status.
+
+{{< truetable >}}
+| Value | Description |
+|------------------|-----------------|
+| Name  | The name given to the API key when it was created.  |
+| Username  | The username of the TrueNAS user associated with the API key.  |
+| Local  | Indication of whether the API key is for a local TrueNAS user account.  |
+| Revoked  | Indication of whether the API key has been revoked and is no longer valid.  |
+| Created Date  | The date and time when the API key was created.  |
+| Expires  | The expiration date of the API key.  |
+{{< /truetable >}}
+
+You can edit or delete your API keys in the **User API Keys** screen. Click <i class="material-icons" aria-hidden="true" title="Edit">edit</i> **Edit** to open the **Edit API Key** screen. Click <i class="material-icons" aria-hidden="true" title="Delete">delete</i> **Delete** to delete an API key.

content/SCALE/SCALETutorials/DataProtection/TrueCloudTasks.md

@@ -24,7 +24,7 @@ This article provides instructions on configuring a TrueCloud backup task using
 {{< hint type=important >}}
 To take advantage of the lower-cost benefits of the TrueCloud backup service, you must create your Storj iX account using the link provided on the **Add Cloud Credentials** screen.
 
-You must also create and authorize the storage buckets on Storj for TrueNAS to useS.
+You must also create and authorize the storage buckets on Storj for TrueNAS to use.
 
 iXsystems is not responsible for charges incurred using a third-party vendor with the TrueCloud backup feature.
 {{< /hint >}}
@@ -151,4 +151,4 @@ A **Delete Snapshot** dialog opens.
 
 {{< trueimage src="/images/SCALE/DataProtection/TrueCloudDeleteSnapshot.png" alt="Delete Snapshot" id="Delete Snapshot" >}}
 
-Click **Confirm** and then **Delete** to start the job.
+Click **Confirm** and then **Delete** to start the job.

content/SCALE/SCALETutorials/Network/ConfigureIPv6.md

@@ -12,7 +12,7 @@ tags:
 
 TrueNAS provides the option to configure network interfaces using either IPv4 or IPv6 addresses.
 IPv4 networks cannot see or communicate with an IPv6 website or network unless a gateway or some other implementation is configured to allow it.
-See [Implementing IPv6](https://www.truenas.com/docs/references/IPv6/) for more information.
+See [Understanding IPv6](https://www.truenas.com/docs/references/ipv6/) for more information.
 
 ## Configuring IPv6 Addresses
 After configuring your network infrastructure for IPv6, assign the IP addresses for your TrueNAS system.

content/SCALE/SCALETutorials/Storage/Disks/ReplacingDisks.md

@@ -103,6 +103,13 @@ Select the new drive from the **Member Disk** dropdown list on the **Replacing d
 
    {{< trueimage src="/images/SCALE/Storage/ReplacingDiskDialog.png" alt="Replacing Disk Dialog" id="Replacing Disk Dialog" >}}
 
+
+**Force** overrides the safety check and adds the disk to the pool. Selecting this option erases any data stored on the disk!
+
+**Preserve Power Management and S.M.A.R.T. settings** transfers all power management and S.M.A.R.T. test configurations from the original disk to your replacement disk. This option is enabled by default. Select to clear the checkmark so you can reset your configurations.
+
+**Preserve disk description** maintains any descriptions associated with the original disk, which prevents you from needing to copy descriptors to the new disk manually. This option is enable by default. Select to clear the checkmark  if you want the replacement disk to use descriptors that differ from those attached to the original disk.
+
 Click **Replace Disk** to add the new disk to the VDEV and bring it online.
 
 Disk replacement fails when the selected disk has partitions or data present.