ProFTPD mini-HOWTO - CreateHome

## ProFTPD's `CreateHome`

What is `CreateHome`?
When a site has many user accounts, with users being added and removed constantly, there is always the associated procedure of creating and removing those user's home directories. And often, in such situations, the user account information is stored in a SQL database or an LDAP server. A `proftpd` daemon can be configured to authenticate against the SQL database or the LDAP server; this would still leave the task of creating the actual home directory for that user to be done.. What would help ease this particular burden on system administrators, though, is the ability to add the account information and have the new user's home directory created on demand. That is, to have a daemon such as `proftpd` create the home directory for the user, if that directory did not already exist.

Now, `proftpd` already has some modules, such as `mod_sql` and `mod_ldap` that already support this home-on-demand creation capability. Each module implements it slightly differently, though. And other authentication modules, such as `mod_radius`, do not support it at all. It was decided then, rather than having authentication modules have largely duplicated code for this feature, to have home-on-demand creation in the core `daemon` itself. And so it is. As of 1.2.8rc2, `proftpd` has the `CreateHome` configuration directive.

How to use `CreateHome`
The description for this configuration directive shows its parameters to be:

      CreateHome off|on [<mode>] [skel <path>] [dirmode <mode>] [uid <uid>] [gid <gid>] [homegid <gid>] [NoRootPrivs]

The first parameter is a simple Boolean, enabling or disabling the `proftpd` daemon's run-time support for home directory creation. The rest of the parameters are optional, and only apply if `CreateHomde` is on.

There is the first mode parameter, used to set the directory mode on the home directory being created. As described in the documentation, if this parameter is omitted the mode used will default to 0700. There is also the `dirmode` mode parameter, which is slightly different. The `dirmode` keyword informs the daemon that the following mode is to be used on directories that may need to be created in order to create the home directory. For example, let's assume that a new user, david, is logging in. User david has been given the home directory `/home/users/d/da/david`. Since this is a new user, the directory does not exist. In fact, `/home/users/d` does not exist. When this happens, `proftpd` will create the `d`, `da`, and `david` directories. A `dirmode` mode would be applied to the `d` and `da` directories, and the mode (no `dirmode` keyword) would be applied to the final `david` directory. To illustrate this, assume that the following `CreateHome` configuration is in use:

      CreateHome on 700 dirmode 711

A directory listing would show only the `/home/users` directory:

      drwxr-xr-x    6 root     root         4096 Jan 31 13:23 /home/users

After user david logs in, a directory listing might show the new directories that have been created:

      drwxr-xr-x    6 root     root         4096 Jan 31 13:23 /home/users
      drwx--x--x    6 root     root         4096 Jan 31 13:23 /home/users/d
      drwx--x--x    6 root     root         4096 Jan 31 13:23 /home/users/d/da
      drwx------    6 david    david        4096 Jan 31 13:23 /home/users/d/da/david

Notice how `/home/users/d` and `/home/users/d/da` have `dirmode` mode of 711 (`rwx--x--x`) while `/home/users/d/da/david` has the mode of 700 (`rwx------`).

As an added feature, `CreateHome` also supports the ability to populate these newly created home directories. This is done by configuring a "skeleton" directory that will contain files (e.g. shell initialization files, documentation, notices, subdirectories, etc) that should be in every new user's home directory. This is done using the `skel` path parameter.

Be sure to read the documentation for the `CreateHome` directive, for there are some restrictions and caveats to both the `dirmode` and `skel` parameters.

The `uid` and `gid` parameters can be used to set the ownership of the newly created parent directories, up to but not including the home directory. By default, those created parent directories are owned by root (UID 0 and GID 0).

The `homegid` parameter can be used to specify the group ownerhsip of the target home directory itself. By default, this home directory will be owned by the user's primary GID.

Here are some examples (from the documentation) to help illustrate how one might use the `CreateHome` configuration directive:

      # Use the CreateHome default settings
      CreateHome on

      # Specify a mode of 711 for the created home directory
      CreateHome on 711

      # Specify a mode of 711, and have the parent directories owned by a specific non-root UID/GID
      CreateHome on 711 uid 100 gid 100

      # Specify a mode of 711, and have the parent directories owned by the UID/GID of the logging-in user
      CreateHome on 711 uid ~ gid ~

      # Specify a skeleton directory
      CreateHome on skel /etc/ftpd/skel

      # No skeleton, but make sure that intermediate directories have 755
      # permissions.
      CreateHome on dirmode 755

      # Skeleton directory, with 700 intermediate directories
      CreateHome on skel /etc/ftpd/skel dirmode 700

      # Explicitly configure everything, CreateHome-wise
      CreateHome on 711 skel /etc/ftpd/skel dirmode 700

      # Explicitly configure everything, CreateHome-wise.  And do NOT use root privileges when
      # creating the parent directories.
      CreateHome on 711 skel /etc/ftpd/skel dirmode 700 NoRootPrivs

When to use `CreateHome`
"What about the prior configuration directives for `mod_sql` and `mod_ldap`?" one asks. The `CreateHome` configuration directive supercedes them. Those previous module-specific directives may well be deprecated in the future, in favor of `CreateHome`. Future authentication modules need not try to reinvent this particular wheel. `CreateHome` was designed for large sites in mind, but can be used any time home-on-demand creation is desired from the FTP daemon.

FAQ

Question: Is it possible to have different permissions for the `CreateHome` mode and dirmode based on the group of the connecting user?
Answer: Yes, if you use the `mod_ifsession` module. For example:

      <IfGroup special>
        CreateHome on 755 dirmode 755
      </IfGroup>

      <IfGroup !special>
        CreateHome on 711 dirmode 711
      </IfGroup>

$Date: 2012-09-05 17:30:05 $