Requirements and Prerequisites
 - Host Platforms
 - Supported Servers
Installing and Removing Sharity 3
 - Installation
 - Upgrading to a new Version
 - Removing Sharity 3
Working with Sharity 3
 - Configuring
 - Logging in and out
 - Authentication with Kerberos
 - Using the Keychain
 - Browsing Resources
 - /CIFS as a Magic Directory
 - Login and Keychain Access from the Command Line
 - Mounting Shares from the Command Line
 - Accessing ACLs
 - General Information
Configuring a Windows PC to share Files
 - Configure the Network
 - Sharing a Directory
 - Name and Browsing Services
Tips and Tricks
 - Help for Configuration Options
 - Make a Permanent Mount
 - Default Login for Domain
 - Set up a Default Account
 - Creating a Debug Log
 - Recovering from a Daemon Crash
 - Debugging Kerberos and AD
Unix Home Directories on SMB Shares
 - Overview
 - Sharity and DirectControl
 - Integrating Sharity with Other Software
 - Limitations
Release Notes
Software License

Unix Home Directories on SMB Shares


If your company runs a mixed network of Windows and Unix workstations, it is tempting to use a common domain infrastructure for both. This common infrastructure is usually provided by Windows Domain Controllers, since it is easier to bind Unix workstations into the Windows domain than the other way around.

In order to bind a Unix computer into the Windows domain, the following problems must be solved:

  • Authentication. When a user logs in on Unix, the system must verify the credentials with the domain controller.
  • Directory Service. Information normally stored in /etc/passwd, /etc/group and similar files must be obtained from the domain controller.
  • Home Directories. If users have their home directory mapped as a network drive when they log in on Windows, they want to have the same home directory when they log in on Unix.
Sharity solves only the home directory issue, but it also needs access to directory information and must authenticate users. For best results, Sharity should integrate with the solutions you have chosen for authentication and directory service.

In the rest of this chapter, we will discuss two approaches. The first approach is Centrify's DirectControl, a commercial solution for Unix to Windows domain integration. In the second approach, we don't suggest particular solutions, but explain Sharity's interfaces to third party software.

Sharity and DirectControl

Centrify's DirectControl is a user friendly solution for Unix to Windows domain integration. Objective Development and Centrify have teamed up to provide a seamless integration of Sharity and DirectControl. This means that
  • Sharity does not need to ask for passwords. It can use DirectControl's authentication information.
  • Sharity can map Windows Security IDs (SID) to Unix user/group IDs (UID/GID) based on DirectControl. It can therefore translate file ownership and Access Control Lists (ACLs) to Unix file attributes if configured to perform this translation.
  • Sharity and DirectControl communicate to agree on a user home directory.
User Profile

Where is the Home Directory?

Speaking about physical location, the user's home directory is hosted by a server. To tell all Windows workstations that the user's home is a network path, the home directory must be configured on a per-user basis in Active Directory. Start "Active Directory Users and Computers", double-click a user and choose "Profile" (see screenshot on the right). You can choose the network path for the home directory there.

Unix computers can't mount the user's home as "Z:" network drive. They must mount it at a particular path in the file system. Furthermore, Unix is built to serve multiple users at once, so the mount point must be individual to each user. It is common practice to name home directories after the user's login name, e.g. /home/james.

Sharity must have control over the home directories folder because it needs to mount there when the user logs in. We achieve this by mounting a special file system on the home directories folder. When a user logs in and the home directory is first accessed, the network path configured in Active Directory is mounted and a symbolic link to this location is created in the home directories folder.

DirectControl Configuration

There is only one requirement for your DirectControl configuration: The Unix home directory for network users must point into a location where Sharity's special home directories file system is mounted and it must end in the user's Unix name. Examples for valid home directory templates in the zone configuration:
We recommend that you add all your users to your DirectControl zones to allow SID to UID/GID mapping for them.

Sharity Configuration

In order to use DirectControl's services, Sharity must link to particular libraries delivered by Centrify. Centrify recommends that you add their library path to the system wide shell profile. If you don't do this or if the profile is not active for startup scripts, add it to Sharity's startup profile at /usr/local/sharity3/var/, e.g. on Linux:
Then you must ensure that the users' home directory is mounted by Sharity. We offer the "x-homes:" file system to make this step easy. Make sure that the "x-homes:" file system is mounted on the network homes folder. This is best done in the file /usr/local/sharity3/var/fstab. If your zone template for the user home is /nethome/$user, add the line /nethome
to this file. The x-homes: file system works only if a CIFS browse file system is mounted (typically at /CIFS, but the path can be customized during installation). The directory /nethome must be created manually with mkdir.

This configuration allows you to log in and have the home directory mounted automatically, e.g.:

login: james
Last login: Fri Nov 3 15:21:29 on tty1
-bash-3.1$ pwd
-bash-3.1$ ls -l /nethome
lrwxrwxrwx 1 james domainusers 1024 Nov 6 18:12 james -> /CIFS/homes[]/james
You may want to optimize some configuration parameters now. Although these parameters can be found in /usr/local/sharity3/etc/config/*.cfg, you should not edit them in these files because they are overwritten with the next upgrade. Permanent configuration changes should go into /usr/local/sharity3/var/local.cfg. Here is an example for this file:
    main = {
        autoUnmountTimeout = 7200000;   // in ms
    cifs = {
        homesLocalHomeDir = "/home/$user";

autoUnmountTimeout: If an automatically mounted directory has not been used for this amount of time, it is unmounted. Since a mount is expensive in terms of system resources, we recommend to configure a non-zero value. An automatic unmount does not cause errors since the directory will be automatically mounted again when accessed.

Convert Windows ACLshomesLocalHomeDir: When the user logs in, Sharity obtains the user's home from Active Directory. If no network path is configured, Sharity must provide a local home directory. The variables $user and $domain will be replaced with the user's home directory and domain respectively.

If you choose "Convert Windows ACLs" in Sharity's Options (see image on the right), Sharity obtains the Security Descriptor and thus Access Control List for each file and convert it to Unix file attributes. Files attributes reflect real owners and groups and the permission flags indicate the access permissions for the owner, group and the special Windows group "Everyone". Please note that obtaining the security descriptor for each file requires additional requests to the server and thus a performance penalty.

Integrating Sharity with Other Software


When Sharity needs to authenticate users to the server, it either needs a password for NTLMv2 authentication or a valid Kerberos ticket for Kerberos authentication. If you bind your computer to the Windows domain, you must make either the password or the Kerberos ticket available to Sharity.

Authenticating with Kerberos. If Kerberos is already configured, Sharity should simply use it without further configuration. However, some installations and setups use a non-standard file name for the credentials cache. In order to accommodate these installations, Sharity can search for the credentials cache. Open the file /usr/local/sharity3/etc/config/cifs.cfg in an editor and search for krb5credCacheTemplate. This option is a shell-style matching pattern. Sharity searches all files matching the pattern and uses the first one which is owned by the current user. If you need to permanently change this setting, consider copying it to the file /usr/local/sharity3/var/local.cfg. See the example given in the previous section.

Authenticating with Password. If you don't want to use Kerberos, you must get hold of the user's password and feed it to the command sharity login, optionally saving it in the keychain as default password. The main problem here is to find a hook where the password can be obtained. If your system uses PAM for authentication, google for pam_extern and pam_script. Both modules can help you to intercept the login procedure.

Directory Service

When looking up a user's home in Active Directory, Sharity must find the entry based on the last path component of the user's Unix home. By default, it searches the directory as SAM Account Name (Windows login name) in AD. You can change the LDAP search filter in the ldapAccountNameSearchTemplate variable in /usr/local/sharity3/etc/config/cifs.cfg. As above, if the change should be permanent, please copy it over to /usr/local/sharity3/var/local.cfg. The value is a template where you can use the variables $user and $domain.

If you activate "Convert Windows ACLs" in the Options section of the GUI, you must provide the mapping in a separate text file at /usr/local/sharity3/var/idmap.cfg. See the prototype of this file for a description of the file format. When you update this file, you must tell Sharity to re-read it. This can either be done by sending the process sharityd a HUP signal or with the command sharity reload.

Home Directories

The x-homes: file system works in the same way as described in the section about DirectControl above. A typical mount command looks like this:
sharity mount /nethome
The domain name is used to look up the user in the appropriate domain. If your users are from multiple domains, one more directory level must be added. Home directories are then created as /nethome/$domain/$user. You tell the x-homes: file system that you want a two level hierarchy by omitting the domain parameter:
sharity mount x-homes: /nethome
Alternatively, if you have only a couple of users, you may want to avoid the "x-homes:" file system and create the symbolic links yourself. Assuming that the user homes are available at the network path \\server\homes\james, \\server\homes\susie, create the following symbolic links in the homes folder:
/home/james -> /CIFS/homes[server]/james
/home/susie -> /CIFS/homes[server]/susie


Hosting the home directories for Unix users on Windows servers brings some limitations: Features normally expected from Unix file systems (and thus home directories) may not be available on Windows. Although Sharity tries to emulate missing features or deviating semantics as good as possbile, you should investigate the following topics:
  • Case Sensitivity. Windows file systems are not case sensitive.
  • File Locking. Sharity currently can't lock files. However, on most platforms file locking succeeds without an error, the file is just not locked on the server.
  • Effective Permissions. Unix permissions displayed by Sharity are either derived from DOS attributes or ACLs. In both cases, information is lost during the mapping and predicting access rights from Unix attributes may give false results.
  • Directory Modification Timestamp. Windows does not update the directory's timestamp when files are added or removed. Unix kernels and applications often base the validity of caches on the directory's timestamp. If the directory is modified through Sharity, modification dates are updated (if permissions allow).
  • Symbolic Links. Sharity can emulate symbolic links by creating files with a special combination of DOS attributes. This option must be enabled manually in the GUI application because it interfers with some Windows system files.
  • Hard Links. Sharity can emulate hard links by copying the file. This is no real emulation, but it is the closest to a hard link which we can do. This option must also be enabled in the GUI configuration.
  • Device Nodes, Unix Domain Sockets, Pipes. Sharity cannot create these types of objects.
  • Accuracy of File Timestamps. Depending on various factors (such as server type, file open status and so on), certain file attributes may be unavailable to Sharity. Only the file's modification date with +/- 2 seconds precision is guaranteed to be valid.

Copyright © 2004 - 2007 by OBJECTIVE DEVELOPMENT Software GmbHprinter friendly version