I am setting up a new server based on FreeNAS, a FreeBSD-based operating system. The system has a group, wheel. I have a vague idea that sysadmins should be added to group wheel, and that the group confers ability to use su (superuser). However, I can't find this written down anywhere.
What is the purpose of group wheel? Under what circumstances I should add my users to it? Please also cite FreeBSD documentation which explains this.
It's in the su(1) man page.
PAM is used to set the policy su(1) will use. In particular, by default
only users in the "wheel" group can switch to UID 0 ("root"). This group
requirement may be changed by modifying the "pam_group" section of
/etc/pam.d/su. See pam_group(8) for details on how to modify this set-
ting.
A very ancient version of the man page said:
Only users who are a member of group 0 (normally "wheel") can su to
"root". If group 0 is missing or empty, any user can su to "root".
This allows you to control which users can su. It is not likely that you want every single user of your system to be able to su.
You should add users to the wheel group if they need to use the su command to become root.
As you are using a FreeNAS system, you may want to look at the documentation regarding the Groups interface where it says, regarding the Primary Group drop-down menu,
Unset New Primary Group to access this menu. For security reasons, FreeBSD will not give a user su permissions if wheel is their primary group. To give a user su access, add them to the wheel group in Auxiliary groups.
For more documentation regarding wheel on FreeBSD, see e.g.
section 10.4 of the FreeBSD FAQ: "Why do I get the error, you are not in the correct group to su root when I try to su to root?"
This is a security feature. In order to su to root, or any other account with superuser privileges, the user account must be a member of the wheel group. If this feature were not there, anybody with an account on a system who also found out root's password would be able to gain superuser level access to the system.
section 3.3.1.3 of the FreeBSD Handbook: The Superuser Account
There are several ways to gain superuser privilege. While one can log in as root, this is highly discouraged.
Instead, use su(1) to become the superuser. If - is specified when running this command, the user will also inherit the root user's environment. The user running this command must be in the wheel group or else the command will fail. The user must also know the password for the root user account.
section 3.3.2.1 of the FreeBSD Handbook: adduser
[...] In this example, the user has been invited into the wheel group, allowing them to become the superuser with su(1).
And obviously the manual for su(1) as well.
wheel group is not mentioned there. It is maybe in itself "unimportant" while documenting the action of switching to root with su is more important (and then mentioning the prerequisite of membership in that group, as you say, in passing).