Skip to content

Commit

Permalink
PD-1404 / 25.04 / Pd 1404 bulk reworks of scale terminology (#3233)
Browse files Browse the repository at this point in the history
* Update CONTRIBUTING.md

* Update Archive.md

* more removals

* more changes

* More scale removals

* manual resolutions

* Update VMandAppConfigSCALE.md

* Update scale-releases.yaml

* Update page-header.html

* "CORE and SCALE" replace

* Scale > Truenas

* scale replacements

* more scale replacements

* core replacements

* Replace Scale Logo

* Update related-content.html

* Outstanding Changes

* Update words-to-ignore.txt

* Apply suggestions from code review

Co-authored-by: MicJ <[email protected]>

* Update content/Solutions/Integrations/Containers.md

Co-authored-by: MicJ <[email protected]>

* Update content/Solutions/Integrations/Veeam.md

Co-authored-by: MicJ <[email protected]>

* Update content/Solutions/Integrations/Veeam.md

Co-authored-by: MicJ <[email protected]>

* Update Veeam.md

* Update content/Solutions/MigratingToTrueNAS.md

Co-authored-by: MicJ <[email protected]>

* Update SCALEEULA.md

---------

Co-authored-by: MicJ <[email protected]>
  • Loading branch information
DjP-iX and micjohnson777 authored Nov 15, 2024
1 parent b3e740a commit f1a1e4b
Show file tree
Hide file tree
Showing 282 changed files with 1,044 additions and 1,075 deletions.
1 change: 0 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ See the repository README to learn more about content specifications and technol

## Content Needs

The content in this repository attempts to document the latest version of TrueNAS CORE, TrueNAS SCALE, and TrueCommand.
It is very easy for content to become out of date or syntax and typographical errors to creep in.
Contributions that resolve a discovered content issue are extremely helpful!

Expand Down
6 changes: 2 additions & 4 deletions content/Archive.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,21 +61,19 @@ All documentation provided here is end-of-life (EoL), intended for reference onl
Software releases after TrueNAS 22.12 (Bluefin) are available as navigable website branches.
Earlier releases are available only in PDF.

## TrueNAS SCALE
## TrueNAS

{{< expand "TrueNAS 22.12 (Bluefin)" "v" >}}
[TrueNAS 22.12 (Bluefin)](https://www.truenas.com/docs/scale/22.12/)

Release notes for each minor release of 22.12 are available in the [SCALE 22.12 Bluefin Release Notes](https://www.truenas.com/docs/scale/22.12/gettingstarted/scalereleasenotes/).
Release notes for each minor release of 22.12 are available in the [22.12 Bluefin Release Notes](https://www.truenas.com/docs/scale/22.12/gettingstarted/scalereleasenotes/).
{{< /expand >}}

{{< expand "TrueNAS 22.02 (Angelfish)" "v" >}}
Release notes for each minor release of 22.02 Angelfish are included in the archived docs.
<a href="https://www.truenas.com/docs/files/SCALE22.02Docs.pdf">TrueNAS 22.02 (Angelfish)</a>
{{< /expand >}}

## TrueNAS CORE

{{< hint type=important >}}
**12.0 NVDIMM Alert**

Expand Down
8 changes: 4 additions & 4 deletions content/Contributing/Applications/AppArticleTemplate.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,13 +40,13 @@ If the app requires setting up a crypto wallet, include this information.
Example of possible points to include in this section: (do not include the three backticks in the article)
```
```
Prepare TrueNAS SCALE before installing the app by:
Prepare TrueNAS before installing the app by:

* [Creating datasets](#creating-the-storj-datasets-on-truenas-scale) for application storage.
Create a parent dataset, such as *appName*, and then the storage datasets (***config*** and ***data***) under it.
Select **apps** as the **Dataset Preset** for these datasets. You can modify the dataset ACLs at the time of creation, or modify them later when adding them in the app.

* Add a new SCALE user account if not using the default apps user and group (568).
* Add a new TrueNAS user account if not using the default apps user and group (568).
Go to **Credentials > Local User**, click **Add** and create the new user.
Make sure the user has read/write/execute privileges. If you have an existing admin user on your system with the right permissions, you make that user the app user.

Expand Down Expand Up @@ -79,7 +79,7 @@ Accept the default name or enter a new name for your application if you prefer.
Enter a name that consists of, and begins or ends with lowercase alphanumeric characters.
Do not use a hyphen as the first or last character. For example, *appName*, or *app-name*, but not *-appName* or *appName-*.

Do not change the **Version**. SCALE alerts you when a new version is available for deployed apps, and allows you to update through the click of a button on the **Installed** application screen.
Do not change the **Version**. TrueNAS alerts you when a new version is available for deployed apps, and allows you to update through the click of a button on the **Installed** application screen.

1. Enter the ***AppName* Configuration** settings:

Expand All @@ -101,7 +101,7 @@ Do not change the **Version**. SCALE alerts you when a new version is available
Leave **Host Network** unselected.

5. Configure the **Storage Configuration** settings.
You can use the default **ixVolume** option to allow SCALE to create a data storage volume or select **Host Path** to select the path to the new datasets created earlier in this document.
You can use the default **ixVolume** option to allow TrueNAS to create a data storage volume or select **Host Path** to select the path to the new datasets created earlier in this document.

{{\< trueimage src="/images/SCALE/Apps/InstallAppNameStorage.png" alt="Add Datasets" id="Add Datasets" >}}

Expand Down
2 changes: 1 addition & 1 deletion content/Contributing/Applications/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ aliases:
We welcome community user contributions, issue reporting, and suggestions for new features and apps to create the best possible TrueNAS app user experience!

## App Updates and Releases
Application maintenance is independent of TrueNAS SCALE version release cycles.
Application maintenance is independent of TrueNAS version release cycles.
App version information, features, configuration options, and installation behavior during access might vary from those in documented tutorials.

TrueNAS apps show the **Update** badge and button on any deployed application instance on the **Installed** application screen when a new version is available.
Expand Down
6 changes: 3 additions & 3 deletions content/Contributing/Documentation/ContentUpdate.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Images are located in the <file>/static/images/</file> directory and in the same
[![ImageLocation](/images/Contribute/GitHubImagesLocation.png)](/images/Contribute/GitHubImagesLocation.png)

Click **Upload files** and either drag and drop the new or replacement image into the file upload area or open the file browser to select your image.
Naming the new image name the same as the old image automatically replaces the old image with the new one in every article that includes it.
Naming the new image name the same as the old image automatically replaces the old image with the new one in every article that includes it.

If adding a new image to the article, give the PNG image a descriptive name, such as *Adding an SMB Share* or *Add SMB Share Advanced Settings* and save it in the appropriate <file>/static/images/</file> folder.
Enter the path to the image and the image name to the image link in the article.
Expand Down Expand Up @@ -70,9 +70,9 @@ Make changes directly in the article that are specific to the article but not ap
For example, make only content changes that apply to the advanced scheduler in the snippet, but do not include mentions about tasks that use the scheduler.

## Master and Version Branch Differences
TrueNAS documentation uses branches to organize content related to specific software releases and updates, for example, the ***24.04*** and ***23.10*** SCALE branches of the Documentation Hub.
TrueNAS documentation uses branches to organize content related to specific software releases and updates, for example, the ***24.04*** and ***23.10*** branches of the Documentation Hub.

+ Content changes in the ***master*** branch result in changes to the TrueNAS SCALE Nightly Development Documentation content.
+ Content changes in the ***master*** branch result in changes to the TrueNAS Nightly Development Documentation content.
To make changes in the ***master*** branch, *fork* this branch to create a simple copy of the main repository.
Make changes in your forked *master* as the *base* for your changes.
Do not make changes directly to the TrueNAS **master** branch of the Documentation Hub repository.
Expand Down
2 changes: 1 addition & 1 deletion content/Contributing/Documentation/Style.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ You can also link directly just by typing the URL with no additional markup: `ww
HTML linking syntax is also allowed: `<a href="www.example.com">Example Site</a>`

You can also use the `relref` shortcode to link to documents on the TrueNAS Documentation Hub website.
For example, linking to an existing article such as a SCALE tutorial [Dashboard]({{ relref "/SCALE/SCALETutorials/Dashboard.md" }}).
For example, linking to an existing article such as a TrueNAS tutorial [Dashboard]({{ relref "/SCALE/SCALETutorials/Dashboard.md" }}).

To link to another section of the **same** article, use an anchor (`#`) to refer to that section header.
The header title needs to be in lower case and spaces replaced with dashes (-): `[Escape Characters](#escape-characters)`
Expand Down
2 changes: 1 addition & 1 deletion content/Contributing/UITranslations.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ tags:
- contributing
---

## How to Contribute CORE and SCALE Text String Translations
## How to Contribute TrueNAS Text String Translations

By default, TrueNAS is available in English.
However, users can contribute text string translations for the TrueNAS web interface to help make TrueNAS available in many other languages!
Expand Down
2 changes: 1 addition & 1 deletion content/Hardware/MSeries.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ descr="Comprehensive User Manual for TrueNAS M-Series systems." >}}
descr="Additional cabling examples for High Availability M-Series systems." >}}

{{< imagecard image="/images/Hardware/NetworkPortID.png" title="Network Port IDs" link="https://www.truenas.com/docs/files/MSeriesNetworkPortID.pdf"
descr="TrueNAS SCALE identifications list of TrueNAS M-Series systems network ports." >}}
descr="Identifications list of TrueNAS M-Series systems network ports." >}}

{{< imagecard image="/images/Hardware/MSeries/MSeriesOOBM.png" title="Out-of-Band Management" link="https://www.truenas.com/docs/files/MSeriesOOBM.pdf"
descr="BIOS configuration instructions for TrueNAS M-Series systems." >}}
Expand Down
2 changes: 1 addition & 1 deletion content/Hardware/RSeries.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ descr="Deployment Guide for TrueNAS R30 systems." >}}
descr="Deployment Guide for 3rd Generation TrueNAS R50 systems." >}}

{{< imagecard image="/images/Hardware/NetworkPortID.png" title="Network Port IDs" link="https://www.truenas.com/docs/files/RSeriesNetworkPortIDs.pdf"
descr="TrueNAS SCALE identifications list of TrueNAS R-Series systems network ports." >}}
descr="Identifications list of TrueNAS R-Series systems network ports." >}}

{{< imagecard image="/images/Hardware/RSeries/RSeriesOOBM.png" title="Out-of-Band Management" link="https://www.truenas.com/docs/files/RSeriesOOBM1.1.pdf"
descr="BIOS configuration instructions for TrueNAS R-Series systems." >}}
Expand Down
14 changes: 7 additions & 7 deletions content/References/ACLPrimer.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ tags:
- permissions
---

[TrueNAS SCALE brings full Access Control List (ACL) compatibility]({{< relref "PermissionsSCALE.md" >}}) between Windows and Linux with NFSv4 ACLs on ZFS and eases the challenges of integrating Unix servers in Windows environments.
[TrueNAS provides for full Access Control List (ACL) compatibility]({{< relref "PermissionsSCALE.md" >}}) between Windows and Linux with NFSv4 ACLs on ZFS and eases the challenges of integrating Unix servers in Windows environments.

## ACL Overview

Expand Down Expand Up @@ -40,9 +40,9 @@ Advanced flags give further control of how an ACE applies to a dataset's files a

For example, advanced flags allow an administrator to apply the ACL to new directories within a dataset, but not new files.

### NFSV4.1 Support in TrueNAS SCALE
### NFSV4.1 Support in TrueNAS

SCALE 24.04 NFSv4.1 adds support to the NFS Linux client and brings support for higher ACL types to the filesystem NFS and SMB clients.
TrueNAS 24.04 and later includes NFSv4.1 support to the NFS Linux client and brings support for higher ACL types to the filesystem NFS and SMB clients.

It also enhances the SMB client to present the Windows NT security descriptor as xattr in our system.
This security descriptor is a list containing the discretionary access control lists (DACLs) entries that grant or deny access to users or groups.
Expand Down Expand Up @@ -79,16 +79,16 @@ In general, NFSv4.1 adds these new features:

To properly configure ACLs on SMB shares, users should consider how they intend to access the dataset/share with other devices and services on the network.

Even though TrueNAS SCALE NFSv4 ACL support provides the best possible compatibility with a Windows file system security model, it is not the best choice for every situation.
Even though TrueNAS NFSv4 ACL support provides the best possible compatibility with a Windows file system security model, it is not the best choice for every situation.

### When to use NFSv4 ACLs

TrueNAS administrators should use NFSv4 ACLs to cleanly migrate Windows-style ACLs across Active Directory domains (or stand-alone servers) that use ACL models richer than POSIX.

Since POSIX ACLs are a Linux-specific ZFS feature, administrators should use NFSv4 to maintain compatibility with TrueNAS CORE, FreeBSD, or other non-Linux ZFS implementations.
Since POSIX ACLs are a Linux-specific ZFS feature, administrators should use NFSv4 to maintain compatibility with FreeBSD-based TrueNAS versions, FreeBSD, or other non-Linux ZFS implementations.

{{< hint type=warning >}}
Administrators *must* use NFSv4 if they intend to replicate data from TrueNAS SCALE to a TrueNAS CORE disaster recovery target.
Administrators *must* use NFSv4 if they intend to replicate data from Linux-based TrueNAS to a FreeBSD-based TrueNAS disaster recovery target.
{{< /hint >}}

TrueNAS administrators should also use NFSv4 ACLs if their organization requires advanced NFSv4 ACL features.
Expand Down Expand Up @@ -116,4 +116,4 @@ Using POSIX ACLs preserves POSIX.1e ACLs from client systems.

TrueNAS administrators should also use POSIX ACLs if they wish to replicate SMB datasets to other non-TrueNAS Linux servers with ZFS, especially when the Linux server should seamlessly take over serving files during disaster recovery.

TrueNAS SCALE creates a POSIX.1e ACL for datasets created when the **Dataset Preset** (ACL Type) is set to **Generic**.
TrueNAS creates a POSIX.1e ACL for datasets created when the **Dataset Preset** (ACL Type) is set to **Generic**.
2 changes: 1 addition & 1 deletion content/References/IPv6.md
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,7 @@ Your DNS server needs to be capable of providing name resolution for these more
Specific network topology and configuration instructions and recommendations are outside the scope of this article.
Consult with your IT network administrator or service provider for how to equip your network to allow communication between both IP protocols.

You can dual-stack IPv4 and IPv6 in SCALE.
You can dual-stack IPv4 and IPv6.
{{< /expand >}}

{{< expand "What type of IPv6 address do you want to assign?" "v" >}}
Expand Down
36 changes: 18 additions & 18 deletions content/References/L2ARC.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,27 @@
---
title: "L2ARC"
description: "Provides information on L2ARC, caches drives, and persistent L2ARC implementations in TrueNAS CORE and SCALE."
description: "Provides information on L2ARC, caches drives, and persistent L2ARC implementations in TrueNAS."
weight: 30
aliases:
- /core/notices/persistentl2arcin12.0/
---

ZFS has several features to help improve performance for frequent access data read operations.
One is Adaptive Replacement Cache (ARC), which uses the server memory (RAM).
The other is second level adaptive replacement cache (L2ARC), which uses cache drives added to ZFS storage pools.
These cache drives are multi-level cell (MLC) SSD drives and, while slower than system memory, are still much faster than standard hard drives.
ZFS (including TrueNAS) uses all of the RAM installed in a system to make the ARC as large as possible, but this can be very expensive.
ZFS has several features to help improve performance for frequent access data read operations.
One is Adaptive Replacement Cache (ARC), which uses the server memory (RAM).
The other is second level adaptive replacement cache (L2ARC), which uses cache drives added to ZFS storage pools.
These cache drives are multi-level cell (MLC) SSD drives and, while slower than system memory, are still much faster than standard hard drives.
ZFS (including TrueNAS) uses all of the RAM installed in a system to make the ARC as large as possible, but this can be very expensive.
Cache drives provide a cheaper alternative to RAM for frequently accessed data.

## How Does L2ARC Work?

When a system gets read requests, ZFS uses ARC (RAM) to serve those requests.
When the ARC is full and there are L2ARC drives allocated to a ZFS pool, ZFS uses the L2ARC to serve the read requests that overflowed from the ARC.
When a system gets read requests, ZFS uses ARC (RAM) to serve those requests.
When the ARC is full and there are L2ARC drives allocated to a ZFS pool, ZFS uses the L2ARC to serve the read requests that overflowed from the ARC.
This reduces the use of slower hard drives and therefore increases system performance.

## Implementation in TrueNAS

TrueNAS integrates L2ARC management in the web interface **Storage** section.
TrueNAS integrates L2ARC management in the web interface **Storage** section.
Specifically, adding a **Cache** vdev to a new or existing pool and allocating drives to that pool enables L2ARC for that specific storage pool.

Cached drives are always striped, not mirrored.
Expand All @@ -30,19 +30,19 @@ You cannot share dedicated L2ARC devices between ZFS pools.

A cache device failure does not affect the integrity of the pool, but it might impact read performance depending on the workload and the dataset size to cache size ratio.

### Persistent L2ARC in CORE and SCALE
### Persistent L2ARC in TrueNAS

By default, the L2ARC cache empties when the system reboots.
When Persistent L2ARC is enabled, a sysctl repopulates the cache device mapping during the reboot process.
Persistent L2ARC preserves L2ARC performance even after a system reboot.

However, persistent L2ARC for large data pools can drastically slow the reboot process, degrading middleware and web interface performance.
Because of this, we have disabled persistent L2ARC by default in TrueNAS CORE, but you can manually activate it.
Because of this, we have disabled persistent L2ARC by default in TrueNAS, but you can manually activate it.

### Activating Persistent L2ARC

{{< tabs "L2ARC" >}}
{{< tab "CORE" >}}
{{< tab "TrueNAS 13.0" >}}
Go to **System > Tunables** and click **ADD**.
For the **Variable**, enter **vfs.zfs.l2arc.rebuild_enabled**. Set the **Value** to **1** and the **Type** to **sysctl**.
We recommend noting in the **Description** that this is the persistent L2ARC activation.
Expand All @@ -52,14 +52,14 @@ Make sure **Enabled** is selected and click **SUBMIT**.

{{< expand "CLI Instructions" "v" >}}
{{< hint type=important >}}
TrueNAS CORE does not write settings changed through the CLI to the configuration database. TrueNAS resets them on reboot.
TrueNAS does not write settings changed through the CLI to the configuration database. TrueNAS resets them on reboot.
{{< /hint >}}
In a command line, enter `sysctl vfs.zfs.l2arc.rebuild_enabled=1`.
When successful, the output reads: `vfs.zfs.l2arc.rebuild_enabled: 0 -> 1`
{{< /expand >}}
{{< /tab >}}
{{< tab "SCALE" >}}
TrueNAS SCALE enables persistent L2ARC by default. We do not recommend users disable it.
{{< tab "TrueNAS 24.04 or later" >}}
TrueNAS enables persistent L2ARC by default. We do not recommend users disable it.
{{< /tab >}}
{{< /tabs >}}

Expand All @@ -73,9 +73,9 @@ However, we have a few recommendations for L2ARC devices:

* Using large capacity L2ARC SSDs can benefit random Read Heavy workloads. L2ARC SSDs are faster than the existing data storage drives.

* Using an L2ARC device that is much faster than the data storage devices makes better use of its larger capacity.
Sequential or streaming workloads need very fast, low-latency L2ARC devices.
[We recommend Enterprise-grade NVMe devices](https://www.snia.org/sites/default/files/SDC/2019/presentations/File_Systems/McKenzie_Ryan_Best_Practices_for_OpenZFS_L2ARC_in_the_Era_of_NVMe.pdf). L2ARC device capacity depends on how much faster it is than the data storage devices.
* Using an L2ARC device that is much faster than the data storage devices makes better use of its larger capacity.
Sequential or streaming workloads need very fast, low-latency L2ARC devices.
[We recommend Enterprise-grade NVMe devices](https://www.snia.org/sites/default/files/SDC/2019/presentations/File_Systems/McKenzie_Ryan_Best_Practices_for_OpenZFS_L2ARC_in_the_Era_of_NVMe.pdf). L2ARC device capacity depends on how much faster it is than the data storage devices.


## Resources
Expand Down
Loading

0 comments on commit f1a1e4b

Please sign in to comment.