Register for the iXsystems Community to get an ad-free experience and exclusive discounts in our eBay Store.

TrueNAS 12 docs in awful condition compared to 11.3 - can't IX do something?

morganL

Captain Morgan
Administrator
Moderator
iXsystems
Joined
Mar 10, 2018
Messages
268
Thanks Stilez, Ornias

The major changes I see are that you want more topics at the top level...which is more like a traditional manual. This can be done progressively.

As a start, we could add "ZFS Storage" as a top level topic...its a peer of "Sharing". This makes it easier to add advanced topics.

I'm also open to adding a "Basic Concepts" section... after we have sufficient content. In the meantime we could start a "Concepts" page in "Overview".

The "Common recipes" i'd prefer to keep as part of "Initial setup"...... we have too many users that want to do multiple things and hence need a generalized setup advice. However, adding a how to on "Setting up a Media server" would be useful.

Morgan
 

Stilez

Senior Member
Joined
Apr 8, 2016
Messages
465
Thanks Stilez, Ornias

The major changes I see are that you want more topics at the top level...which is more like a traditional manual. This can be done progressively.

As a start, we could add "ZFS Storage" as a top level topic...its a peer of "Sharing". This makes it easier to add advanced topics.

I'm also open to adding a "Basic Concepts" section... after we have sufficient content. In the meantime we could start a "Concepts" page in "Overview".

The "Common recipes" i'd prefer to keep as part of "Initial setup"...... we have too many users that want to do multiple things and hence need a generalized setup advice. However, adding a how to on "Setting up a Media server" would be useful.
The reason for a flatter wider top level is that if you don't, you aren't helping anyone. You're just forcing then to open 2 menu levels instead of one, to get to whatever they want.

As a bonus, they are also forced to guess where the material they want is located because you've had to crush disparate or logically separable things into the same top level sections to do so ("round pegs in square holes").

The rationale for the menu structure I suggested was this. See if you agree.

  1. Everyone needs basic concepts - to not screw up pool design, to comprehend core information needed.to.run the platform. That's applicable to everyone. Basic concepts is wider than just ZFS, as you can see from the subtopics, but also splits logically into chunks.
  2. Once you have basic concepts, the next easy tranche to deal with is the kind of user who says "I just wanna X, how do I do it?" That kind of user doesn't want detail first, they want to go direct to solutions. So let them. They can always read specific other stuff when needed. So next, all your "one stop shop" solutions.
  3. All solutions need a basic setup, so I make basic setup the first recipe, and for all the others make step one "set up the basic server (see recipe 1)". This positions basic setup as simply being the first recipe.
  4. Extending via jails/plugins/VM is a neat chunk - all of these have in common "This is how to set it up, after that its up to you". Keep that as a top.level chunk on its own, as a peer to basic recipes and full details.
  5. Last, your users who want to set it up "as they want it", or are technical, or want to set up something more individual/specific. These users are more likely to be willing to read the detail, and want that detail. They are the ones who need the deeper coverage by area. But if you bury all that within "Advanced use" all you are doing is annoyingly forcing them to open 2 levels instead of 1 every single time....... and trust me, that gets *really* annoying *really* fast.
  6. Its also pretty condescending to users, to label non-advanced stuff as "advanced", it can come over as if all but elite users dont need to worry their heads about the arcane controls in "dataset options", whereas many will be interested in compression, dedup, encryption and so on. Its also incredibly vague and therefore unhelpful as a title. So I label them as what they are - "Technical and in depth", or "Managing your pool and its data". *Not* just "advanced".
 
Last edited:

morganL

Captain Morgan
Administrator
Moderator
iXsystems
Joined
Mar 10, 2018
Messages
268
There is a tradeoff in the visual layout when you have too many top levels and use the modern style.... we have 7 top levels right now. Adding a couple is reasonable, but more would require a major change in graphical layout....... won't be done in this cycle. We'd prefer to focus on completeness of content. Names can be adjusted once we have the top level optics settled. Lets discuss on slack..
 

ornias

Senior Member
Joined
Mar 6, 2020
Messages
473
I'm very busy right now, But I want to add a bit:
Thanks @morganL for thinking with us and agreeing the ZFS content is a good one to put on top level. This change should already clean things up significantly and I expect the storage/zfs related content to grow expodentially and even surpass the initial setup menu eventually :)

I agree that there should be a balance between the amount of top-level items and levels.
I don't think everything should be on top level either, some very-seldome used things could just as well be another layer.
It's also VERY understandable that you aren't going to fully re-itterate on the layout.

That being said:
I was viewing the side on my wifes 1080p screen yesterday... and you might want to give the left-side menu another 10-20% width. It doesn't "fit" very well with the 2-3 layers depths, because every layer adds another indentation.
*edit*
I took a quick other look: The issue is really just with with lower resolutions, maybe just don't show the right hand menu below a certain resolution and give some more room for both text and left-side menu? I think that would solve all readability issues on lower-res.
 

tim64

Neophyte
Joined
Oct 30, 2020
Messages
5
Hello,

I am a new user and as a new user I just want to give some feedback about the TrueNAS 12 documentation from a new user perspective. I do not want to highjack this discussion (for personal technical questions) and because of this I do not want technical solutions (in this discussion thread) for my problems.

Some background: I configured Samba-servers decades ago and used several QNAP-NAS boxes (but I do not like their closed system). I selected TrueNAS 12 for my next NAS because I heard a lot of good things about FreeNAS in the past and TrueNAS seems a better/modern version of FreeNAS with better ZFS and other things. So I decided to got with TrueNAS-software (from ixsystems) and TrueNAS-hardware (from ixsystems) so everything should work out of the box. Well, that was my intention.

But setting up a TrueNAS 12 NAS seems much more complicated that setting up a QNAP NAS. It even seems more complicated than setting up a samba server on a unix/linux server.

I started with a simple requirement/task as an example: Setting up a SMB-share named "office" where the local users "jim" and "john" have full read+write access, where user "jack" only has read access and all others have no access at all. And all permission-security-related settings (like ACLs etc.) are only allowed to be changed from user "admin".

I managed to add the users in TrueNAS.

But the page https://www.truenas.com/docs/hub/tasks/administrative/users/ does not help at all. It does not have information how to set up users restrictions/permissons (i.e. how to allow/disallow a specific service, how to setup a password-policy etc...) but writes about user-IDs and primary-groups without explaining, why this is important to set up manually. It seems the GUI/doc reflects more the underlying OS-view (/etc/password and /etc/group files) and makes it more complicated than it has to be.

I still do not know how to set up the users, so that they are only allowed for SMB. Is this even possible?

Because I already understood some ZFS-basics I was able to create a pool and a dataset.

But then I wanted to add a SMB-share and set up access permissions and the informations for this
https://www.truenas.com/docs/hub/sharing/smb/smb-share/
https://www.truenas.com/docs/hub/tasks/advanced/editingacls/
are sparse and nearly non-existent.

The doc-page mentions ACLs (access control lists) and ACEs (access control entries) and writes, that ACLs can be assigned to datasets, directories and files.

However, in the GUI there are permissions in path "Storage / Pools / Edit Permissions" and there is "Storage Pools / Edit ACLs" that kind of is doing the same thing. And then there is "Sharing / SMB / Share ACL".

It seems, ACLs can be setup for a filesystem (bad wording, probably "dataset" should be used as wording) and for a share.

Why are this different ways existing? Whats the best way of setting up permissions if there are only SMB-shares used on the NAS? Does it matter in this case if an ACL is setup as "filesystem" or "share" and can both setups do the exact same thing? Where are all the fields and their possible data values and the consequences of values explained in detail? Is there an easy way to see all ACLs and ACE (ACL entries) in one place at a glance? And it seems there is no clear distinction between adding an ACL and adding an ACE for an ACL.

Sorry, if this is not only about documentation. But at this moment I can not differentiate between a missing description/explanation in the TrueNAS 12 docs and a missing functionality in TrueNAS 12.

To make sure that users only see the data they are allowed to see it is important to fully understand how user permissions are set-up. This is very important for a NAS that stores sensitive data and that serves several users with different permissions.

But at the moment I do not trust TrueNAS 12 (and my knowledge of TrueNAS 12) for a NAS to store sensitive, protected data.

To look at old docs for FreeNAS 11.x does not help (I do not use FreeNAS and I do not know whats the same/different between FreeNAS 11 and TrueNAS 12).

TrueNAS 12 does use standard building blocks (like ZFS, BSD, Samba, etc.) and glues and "value adds" a middleware and a nice web based GUI.

But as long as the TrueNAS 12 documention is so sparse and superficial like it is now, this middleware looks more like the part of a problem than part of a (good) solution for a NAS. Maybe its easier to install FreeBSD and ZFS and a Samba-server manually? At least I could better understand from the docs of the building-blocks, how to set up a secure system.

If I understand it correctly, the "TrueNAS Documentation Hub" is for the community-version and also the commercial-version of TrueNAS 12. Documentation is part of a product. With the actual quality of the TrueNAS 12 documentation, I would not recommend the commercial product to anyone.

Sorry, if my text maybe sounds harsh. I do appreciate the hard work everyone puts into it (during work time and free time).
 

ornias

Senior Member
Joined
Mar 6, 2020
Messages
473
Sorry, if this is not only about documentation. But at this moment I can not differentiate between a missing description/explanation in the TrueNAS 12 docs and a missing functionality in TrueNAS 12.
It is only about documentations, because there are no mission features, just badly documented procedures ;-)
Because what you want to do is certainly very easily possible (as i've done so myself)

To make sure that users only see the data they are allowed to see it is important to fully understand how user permissions are set-up.
Yes, imho (and thats a bit off topic) ACL's have overcomplicated things needlessly from a GUI perspective.

To look at old docs for FreeNAS 11.x does not help (I do not use FreeNAS and I do not know whats the same/different between FreeNAS 11 and TrueNAS 12).
95% (except new features like metadata vdevs) are the same, don't worry too much about use the old docks ;)

Documentation is part of a product. With the actual quality of the TrueNAS 12 documentation, I would not recommend the commercial product to anyone.
I warned for this response and I fully agree. I would not call the included documentation "Enterprise" "SMB" or "Ready" in any way, shape or form.
 

Gcon

Junior Member
Joined
Aug 1, 2015
Messages
20
I am extremely happy wiith the FreeNAS 11.3 and earlier documentation. My immediate response to perusing the TrueNAS 12 "documentation" was "what the.... is this some sort of a joke?! *checks date* nope not April fools... "

Surely the 11.3 technical guides can be adapted and updated for 12? Just work on the task-based "baby steps" hand-holding guide as an additional resource for noobs. It seems like the baby has been thrown out with the bathwater and is now floating down the river and out to sea! You'd think that with TrueNAS being the commerical offering (whereas FreeNAS wasn't), that TrueNAS docs would be top notch and even better than 11.3 but there's now a huge regression. Something is definitely not right here.

So what's changed? Are the BSD variants about to be dead (insert "netcraft confirms" meme) due to SCALE developments? TrueNAS 12 docs in their current state do not inspire any sort of confidence in the product.

iXsystems have made missteps in the past and corrected them (Corral). Hopefully the documenation gets sorted out in time as well.
 
Last edited:

Stilez

Senior Member
Joined
Apr 8, 2016
Messages
465
Hello,

I am a new user and as a new user I just want to give some feedback about the TrueNAS 12 documentation from a new user perspective. I do not want to highjack this discussion (for personal technical questions) and because of this I do not want technical solutions (in this discussion thread) for my problems.

Some background: I configured Samba-servers decades ago and used several QNAP-NAS boxes (but I do not like their closed system). I selected TrueNAS 12 for my next NAS because I heard a lot of good things about FreeNAS in the past and TrueNAS seems a better/modern version of FreeNAS with better ZFS and other things. So I decided to got with TrueNAS-software (from ixsystems) and TrueNAS-hardware (from ixsystems) so everything should work out of the box. Well, that was my intention.

But setting up a TrueNAS 12 NAS seems much more complicated that setting up a QNAP NAS. It even seems more complicated than setting up a samba server on a unix/linux server.

I started with a simple requirement/task as an example: Setting up a SMB-share named "office" where the local users "jim" and "john" have full read+write access, where user "jack" only has read access and all others have no access at all. And all permission-security-related settings (like ACLs etc.) are only allowed to be changed from user "admin".

I managed to add the users in TrueNAS.

But the page https://www.truenas.com/docs/hub/tasks/administrative/users/ does not help at all. It does not have information how to set up users restrictions/permissons (i.e. how to allow/disallow a specific service, how to setup a password-policy etc...) but writes about user-IDs and primary-groups without explaining, why this is important to set up manually. It seems the GUI/doc reflects more the underlying OS-view (/etc/password and /etc/group files) and makes it more complicated than it has to be.

I still do not know how to set up the users, so that they are only allowed for SMB. Is this even possible?

Because I already understood some ZFS-basics I was able to create a pool and a dataset.

But then I wanted to add a SMB-share and set up access permissions and the informations for this
https://www.truenas.com/docs/hub/sharing/smb/smb-share/
https://www.truenas.com/docs/hub/tasks/advanced/editingacls/
are sparse and nearly non-existent.

The doc-page mentions ACLs (access control lists) and ACEs (access control entries) and writes, that ACLs can be assigned to datasets, directories and files.

However, in the GUI there are permissions in path "Storage / Pools / Edit Permissions" and there is "Storage Pools / Edit ACLs" that kind of is doing the same thing. And then there is "Sharing / SMB / Share ACL".

It seems, ACLs can be setup for a filesystem (bad wording, probably "dataset" should be used as wording) and for a share.

Why are this different ways existing? Whats the best way of setting up permissions if there are only SMB-shares used on the NAS? Does it matter in this case if an ACL is setup as "filesystem" or "share" and can both setups do the exact same thing? Where are all the fields and their possible data values and the consequences of values explained in detail? Is there an easy way to see all ACLs and ACE (ACL entries) in one place at a glance? And it seems there is no clear distinction between adding an ACL and adding an ACE for an ACL.

Sorry, if this is not only about documentation. But at this moment I can not differentiate between a missing description/explanation in the TrueNAS 12 docs and a missing functionality in TrueNAS 12.

To make sure that users only see the data they are allowed to see it is important to fully understand how user permissions are set-up. This is very important for a NAS that stores sensitive data and that serves several users with different permissions.

But at the moment I do not trust TrueNAS 12 (and my knowledge of TrueNAS 12) for a NAS to store sensitive, protected data.

To look at old docs for FreeNAS 11.x does not help (I do not use FreeNAS and I do not know whats the same/different between FreeNAS 11 and TrueNAS 12).

TrueNAS 12 does use standard building blocks (like ZFS, BSD, Samba, etc.) and glues and "value adds" a middleware and a nice web based GUI.

But as long as the TrueNAS 12 documention is so sparse and superficial like it is now, this middleware looks more like the part of a problem than part of a (good) solution for a NAS. Maybe its easier to install FreeBSD and ZFS and a Samba-server manually? At least I could better understand from the docs of the building-blocks, how to set up a secure system.

If I understand it correctly, the "TrueNAS Documentation Hub" is for the community-version and also the commercial-version of TrueNAS 12. Documentation is part of a product. With the actual quality of the TrueNAS 12 documentation, I would not recommend the commercial product to anyone.

Sorry, if my text maybe sounds harsh. I do appreciate the hard work everyone puts into it (during work time and free time).
@Kris Moore - remember I said a while back, to only expect 1 in 20 or fewer to say if they had a problem?

Classic customer feedback/service stuff. Probably less for open source where "move onto the next thing " is often a better response for a disappointed or.confused user, than saying something.

Read this excellent post by new user @tim64 and also that by @Gcon, carefully. That's the user experience right now, and what we probably all knew would happen, by release day, given the state of docs. I appreciate the resource issue, and the efforts and work that improved things between 12-RC and 12-REL. But its still a problem and a strong deterrent now. Evidently, and factually, and that's just how it is.

Not many users will have the time and will to say anything, they'll mostly be a silent group of "let's try something else" or have bad memories for years tainting any retry.

Can Tim64's post, specifically, be raised in detail to.discuss rather more urgency of fixes for the multiple "angles" of issues it raises, at some internal IX weekly meeting, just because it details in so exact a manner, all that's in need of fixing, with the 2020-10 v12 experience.

Also, can docs be given equal/higher priority to code and enhancements, for U1? Its an excellent half a product. Good thorough docs are the other half.
 
Last edited:

tim64

Neophyte
Joined
Oct 30, 2020
Messages
5
Hi,

And it seems there is no clear distinction between adding an ACL and adding an ACE for an ACL.

I want to give more feedback about this topic because I gave TrueNAS a 2nd (and 3rd) chance this weekend (because I really like the TRUENAS-MINI-3.0-X+) and experimented a lot and I managed somehow to add users that can access SMB shares. I still do not know if its the best way how I did it. etc.

So I want to share one of my main obstacles adding ACLs because, in my opinion, everyone already knowing TrueNAS has probably already internalized this strange UI-behaviour.

Preface:
Users have expectations about a UI based on their past experiences. So a lot of users that have already used a computer for entering data (addresses, customers, users, products, etc.) expect more or less some CRUD (create, read, update, delete) functionality for data records.

So, when I clicked "Edit Filesystem ACL" after creating a new share (which seems to be the same as "Edit Permission" for a pool), I expected to get a form/page where I can create/add an ACL itself and after I created a new ACL I expected to be able to create (CRUD) the entries/members of that ACL (the ACE records).

With this expectation, I got the following page. I have drawn in green and red how I saw that page/form:


acl-diagram.png


The word "User" on the left side connects to the "owner@" on the right side, the word "Group" on the left side connects to the word "group@" on the right side. So all these input fields are optically part of one form (I marked the form with a red border) and one ACL-entry/record.

And because the buttons "SELECT AN ACL PRESET" and "ADD ACL ITEM" look the same and are below the data fields (in their column) they are both doing something for the ACL-data-record. Then "ADD ACL ITEM" clearly (it is at the bottom, like form-buttons usually are) will mean that this button ADD/Create the ACL-record with the input fields above.

It surely does not help for understanding this form, that the form-scrollbar is detached from the form and sits at the right border of the browser-window and that the real "SAVE" button is below the screen horizon and is not visible on screen without scrolling. And I do not have a small screen resolution.

Later I understood, that this one form includes the fields for the ACL itself but also all data-records of its members/entries (ACEs) and that all ACEs are shown in the right column with all their data-fields.

But then my expectation was, that the buttons "ADD ACL ITEM" and "DELETE" are related to the fields/data-record above them (like it is in a typical html form).

It did took some time to realize that the "ADD ACL ITEM" button is completely at the wrong position because it is not related to the data above (like the DELETE-button that is next to it) but adds a new, empty ACE-record that is not saved until I scrolled down and clicked the "SAVE"-button.

And I still do not understand why there is a "CANCEL" button besides the "SAVE" button if the form-data is only saved after pressing the "SAVE" button.

I think this is an example of bad UI design and the UI should be changed. But as long as the UI is not changed (there are probably good reasons for not changing the UI) it is an issue that should be included in the documentation, so new users do not fall easily into this trap (like I did).


P.S. If there is a more appropriate area in the forum for this kind of discussion, please give me a hint.

P.P.S. There are a lot of places where the "action-icons" (i.e. the three dots that open extra masks, functions etc.) are hidden because they are not seen without scrolling because they are in the right column of lists. Thats also an UI-issue that should be explained in the documentation.
 
Top