The distributed system is made of a series of independent nodes to which the users can access. It is required that they can use the existing resources in any node without explicit access to them (with a shell remote session, for instance). Another requirement is that no prior configuration has to be done.

This requirement is partially covered with the PAM modules (local users management) [3], (LDAP user management) [4] and particularly, [5], which allows the creation of a user directory if the user has logged in for the first time.

However, one of the features of the system is the uniformity of its nodes regarding user management. Therefore, it is required that the users have a basic set of data in all nodes on the first logging. The pam_mkhomedir module does not cover this task, since it only creates the directory (copying the /etc/skel) in the machine where the access was done.

It is necessary to create a mechanism to perform this task. Taking advantage of PAM, a new module complementary to pam_mkhomedir has been created. The module is named pam_mkpolohomedir and uses MarcoPolo for the task.

Module features

The functionality of a PAM module is packaged in a shared object linked in execution time with the rest of the PAM components, as indicated in the configuration files of the module (usually under /etc/pam.d). [1]. The module must be stored in the /lib/security folder.

In this particular task, the module will use MarcoPolo to detect all the available nodes and then will ask for the creation of the directory, as well as some aditional tasks.

All the functionality is implemented in the pam_mkpolohomedir.c file. The module gets the relevant information (name, UID and GID of the user) through the parameters that PAM called the module with [2]. The structure of the code is partially based on the pam_mkhomedir module [6], taking some functions from this module.

int pam_sm_open_session(pam_handle_t * pamh, int flags, int argc
			,const char **argv)
   int retval, ctrl;
   const char *user;
   const struct passwd *pwd;
   struct stat St;
   /* Parse the flag values */
   ctrl = _pam_parse(flags, argc, argv);

   /* Determine the user name so we can get the home directory */
   retval = pam_get_item(pamh, PAM_USER, (const void **) &user);
   if (retval != PAM_SUCCESS || user == NULL || *user == '\0')
      _log_err(LOG_NOTICE, "user unknown");
      return PAM_USER_UNKNOWN;

After the information is gathered, the create_polo_homedir and createdirs search for the nodes (using the Marco binding) and then request to them the creation of the directory.

Directory creation

Each node has an instance of the polousers slave, the service in charge of receiving and processing all the requests. The service is implemented using the Twisted framework, verifiying the identity of each requestor using TLS-based (Transport Layer Security) sockets.

Once the directory is created, the service acknowledges the requestor, which logs the operation. In fact the acknowledgement is done a bit earlier, in order to speed up the process.

A PAM module must implement a series of function which consitute the entry points to it.

  • PAM_EXTERN int pam_sm_open_session(pam_handle_t * pamh, int flags, int argc ,const char **argv)

    It is the function that PAM invokes when the module is linked. It passes as parameters a pam_handle_t structure with all the relevant information about the user who just logged in. The parameters indicated in the PAM configuration files are also included (in this case, the directory permissions and the location of the skeleton directory).

  • PAM_EXTERN int pam_sm_close_session(pam_handle_t * pamh, int flags, int argc, const char **argv)

    It is the function that PAM uses to indicate that the session has finished. In this module, it includes no functionality, however it must be included. .. Es la función que PAM utiliza para indicar al módulo que la sesión ha terminado. En el caso del módulo a crear no se debe realizar ninguna acción en este evento, sin embargo es necesario implementarla debido a que PAM la requiere.

  • struct pam_module _pam_mkhomedir_modstruct

    Defines the module features and entry points. It is only necessary when the linking is statically done.


    1. Morgan and T. Kukuk, The Linux-PAM Module Writers’ Guide., 1.1.2 ed., Aug. 2010.
    1. Morgan and T. Kukuk, The Linux-PAM Module Writers’ Guide, ch. 2. What can be expected by the module., 1.1.2 ed., Aug. 2010.
[3]pam_unix(8) - Linux man pages.
[4]pam_ldap(5) - Linux man pages.
  1. Gunthorpe, pam_mkhomedir(8) - Linux man pages.
  1. Gunthorpe, “PAM Make Home Dir module,” tech. rep., Feb. 1993.