Translation(s): English - Italiano

User Private Groups - Sharing and collaborating on directory content with a group

User private groups (UPGs) are a system configuration idiom that allows multiple users of a system to collaborate on files without any permission hassle.

It requires no action on the part of the end-user to work as expected. Files and directories within a group directory can be created, modified, and deleted, and (for the most part) have their permissions modified as usual, whilst being shared with other group members and protected from non-members.

Access is controlled by Un*x groups to which userids can be added or removed.

Introductory User Information (->for inclusion as info text to show during file copying on installations)

(This should be true, but still needs the fixes from below.)

It is easy for multiple users to collaborate on a debian system.

Keep in mind that access permission to a file always depends on your permissions for the file itself and the permissions of the directory path to it. Newly created files in Debian are by default readable for whoever has access to them, just as paper files are, but they are not writable by default. If you want to prevent others to read your files, keep them in a private/ subdirectory. The path into your home directory is not restricted, just as the path others can take to ring your bell at home is not restricted. As a matter of fact, you may post some files on your door for others or to read. For example, many programs read the config files that you deposit in your home path. And fellow users can drop files (for you personally) into your ~/incoming/ directory.

All this can work because in Debian the primary group of created user is by default a user private group (UPG). [The primary group of the user has the same name and ID of the user, without the user explicitly listed as a member in /etc/group (i.e. the gid is listed on the line that defines the user in /etc/passwd, but the user is not explicitly listed as a member of the group in /etc/group.)] This allows to grant write permissions for created files to the owning group by default, because only the creating user (and optionally supervisor users) are members of the private primary group that will own a newly created file. Except, if the file has been created in a group directory...

Group directories (directories with the set-group-id flag) are shared work spaces (that again all users are able to visit). All members of the group that owns the directory can create and write to files in it. Additionally, according to the set-group-id flag, all newly created files in the group directory will belong to the creating user who wrote the file and (this is special) to the group the directory belongs to. The result is that all members of the group can work on the files in their group directory. Other than that, group directories work just like home directories. So if a file for example should be readable only by group members, again, put it into a private/ subdirectory!

Group directories may be set up automatically (created/deleted by the addgroup command with every group) under /home/share, or by regular users themselves within their home directories.

Enabling User Private Groups

Debian has been using (creating) user private groups by default almost from the beginning. However, UPGs where not fully enabled on newly installed systems since release 2.2., because the central umask adjustment for UPGs, as configured in /etc/login.defs, was broken with the inclusion of PAM. This feature was only reintroduced with libpam-umask in release 6.0 (Squeeze).

The user private group idiom requires that the default umask group permissions be read/write with execution allowed. However, the default umask in effect on Debian systems was for some time to grant groups only read access with execution allowed.

The default permissions, which take effect when a file or directory is created, is controlled via the process' umask. There are various ways to change the default umask, the most elegant is probably to disable all particular umask settings for specific shells, display managers, etc., and to use libpam-umask to set it centrally.

To configure libpam-umask until bug 646692 is fixed, append a line to /etc/pam.d/common-session by executing the following:

echo "session optional usergroups" >> /etc/pam.d/common-session

Using User Private Groups

Here is an example for using a "family" group at home: Create the group "family" (sudo addgroup family) and add the appropriate users to it (sudo adduser <user> family).

Until someone patches the group creation tool of the debian system to auto-create appropriate group directories with each group (like home dirs), you need to set up the directories manually:

sudo mkdir -p /home/share/family            #create the group's public directory
sudo chgrp family /home/share/family        #give it to the group
sudo chmod 2775 /home/share/family          #adjust its permissions (sgid)

#create the subdirs
sudo mkdir -p /home/share/family/private
sudo chgrp family /home/share/family/private
sudo chmod 2770 /home/share/family/private

sudo mkdir -p /home/share/family/incoming
sudo chgrp family /home/share/family/incoming
sudo chmod 3773 /home/share/family/incoming

# for each individual user (facilitates working together as peers)
sudo mkdir /home/<user>/incoming
sudo chown <user>:<user> /home/<user>/incoming
sudo chmod 5773 /home/<user>/incoming

# for good measure, consistency, and a standing example also
sudo mkdir /home/<user>/private
sudo chown <user>:<user> /home/<user>/private
sudo chmod 770 /home/<user>/private

Now all family group members can work with each other's files in the group directory without permission hassle.

If you already have an existing directory full of files (pictures/music/whatever), this script might save you some time.

Security Considerations

Granting read/write permissions to groups could result in insecure home directories. If two users both have the same primary group then each user could read and write the other's private files. (Recall that the primary group is the group given by default to newly created files and directories.) The user private group idiom gets it's name because each user is assigned a unique primary group, a group which to which only the user belongs. Therefore, by default, the files created by each user are associated with a group to which only the user belongs so it does not matter that the default group permissions are permissive.

Note that the "default" Debian behavior is to create a new group each time a new userid is created, and to have that new group be the userid's primary group. Hence the stage is set to enable the user private group idiom by changing the system-wide default umask.


Those running Debian systems older than release 6.0 (Squeeze) may need to consider this caution.

Although the user private group idiom configuration described herein is secure on a "stock" Debian system, if there is such a thing, making the changes described herein could highly compromise your system's security. Everything depends on your system's configuration, and how permissions and group ownership has already been set on existing files and directories. Your choice of filesystem may affect the behavior of the setgid bit as applied to directories. Installed packages may alter the system configuration, as may other system administrators. Users may modify their default umask and change the group ownership and permissions of existing files or directories. All of these factors affect the availability of the user private group idiom and, more significantly, the security of the system in place after enabling user private groups.

You can be confident that the user private group system will work on a Debian system with the default filesystem type choice, only the base packages installed, and no per-user or system-wide customization; beyond that you're on your own. Having said all that, the user private group idiom can be a good choice (v.s. ACLs) because it uses the familiar, basic, Un*x permission system to provide a secure way to share files that is easy to enable and administer and is transparent when it comes time to use the shared storage.

How It Works


A UPG can be identified by the following conditions:

  1. A group of the same name as the username
  2. A special case is true: The group is set as the main group of the user (in /etc/passwd) while the user is NOT added to his group
    • in /etc/groups.

      => Allows to detect that a group has been set up explicitly as a UPG even if additional users are added to the group.

  3. UID==GID
    • This was questioned to be a requirement, probably because it was seen that adduser (not skipping IDs that have been taken by non UPG groups when creating users) does not properly fullfill this requirement. However:
    • UID==GID can be of great help if you are looking at a filesystem (removable drive) without knowing the corresponding passwd/groups file.
    • man pam_umask:

      "If the user is not root, and the user ID is equal to the group ID, and the username is the same as primary group name, the umask group bits are set to be the same as owner bits (examples: 022 -> 002, 077 -> 007)."

This definition allows:

  1. To intentionally add one or more (supervisor) users to a (sub-) users UPG and thus allow the supervisor full access to the sub-user's resources (without breaking the umask relaxation UPG scheme).
  2. That the private group can be properly deleted if the corresponding user is deleted (even if supervisor users may still be members of that obsolete group).

setgid directories

Setting the setgid bit (chmod g+s) on a directory causes all files or subdirectories created within that directory to be owned by the group that owns the (parent) directory. The usual behavior is that created files or directories are owned by the creating processes' main group.

If the system's umask gives owning the groups write permissions, group members can create new files and subdirectories, and change file permissions -- including granting execute permission to files.

The setgid bit on a directory also causes all newly created subdirectories to have their setgid bit set, which automatically extends the above properties downward throughout all the project's subdirectories.

When User Private Groups Cannot Be Used

User private groups cannot be used when association with a group is required for another purpose, e.g., content served by a webserver is expected to be associated with the www-data group. In these cases ACLs must be used to share files and directories.

However, in many cases you can avoid ACLs by using the path to restrict access to otherwise "world-writable" data.

/filterdir                      www-data:web-admin rwxrwx---
/filterdir/datadir              web-admin:www-data rwxrwx---
/filterdir/datadir/file-or-dir  www-data:www-data rwxrwxrwx

See Also