Sharity 3 Manual

Sharity Logo

Copyright © 2004 - 2007 by OBJECTIVE DEVELOPMENT Software GmbH

http://www.obdev.at/


Table of Contents


Table of Contents

Introduction

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

Troubleshooting
     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


Sharity 3 Introduction

Sharity is a network file system client. "Client" means that it is used to access file resources (shares) in the network, it does NOT provide network access to your local resources. Sharity implements the SMB (Server Message Block) protocol which is (for instance) used by all versions of Windows to share files over the network. This protocol is also known under the name CIFS (Common Internet File System). Sharity can mount SMB shares in the Unix file system transparently.

Features

<< Back to Table of Contents


Requirements and Prerequisites

These are the requirements for the full installation including the Kerberos module. If you don't install the Kerberos module for Sharity, you don't need Kerberos installed with the operating system.

Host Platforms

Solaris

HP-UX

AIX

IRIX

Tru64 Unix

Linux

FreeBSD

OpenBSD

Mac OS X

Mac OS X is now supported, but it is not our primary target platform. This means that we will (probably) not implement a Cocoa or Carbon based GUI. However, we provide a binary for this platform and a GUI based on the Fast Light ToolKit (FLTK).

Supported SMB/CIFS Servers

<< Back to Table of Contents


Installing and Removing Sharity 3

Installation

These are the Generic Unix instructions. If you use an installer package on Mac OS X, read the instructions given by the installer instead.
  1. Be sure to have the following information at hand:
  2. Download Sharity from our web site: http://www.obdev.at/products/sharity/. Packages are available in tar.gz format for all supported platforms. Please choose the Sharity 3 package which suits your operating system and processor type.
  3. Unpack the package. You need gzip and tar. Both tools are distributed with most operating systems. If you lack one of them, please download gzip from http://www.gzip.org/ or gnutar from http://www.gnu.org/software/tar/. You can unpack the package with the command
    gzcat PACKAGE.tar.gz | tar xf -
  4. This will create a directory with the same name as the package (except the .tar.gz extension) in the current directory. Change to the newly created directory and run the setup script as root user:
    ./setup
    It is important that you run this script from the current directory.
  5. The setup script will guide you through the installation. Please follow the instructions given by the script.
  6. Sharity 3 comes with a built-in trial mode which allows one connection (one mounted share), one installation and one user. During the beta phase we may provide free expiring demo license keys on our web site. If you have a license key, install it from the command line:
    sharity license license-key
    or through the GUI application "sharitygui".
To install Kerberos and Active Directory support for Sharity, please repeat the steps above for the Sharity 3 Kerberos Module (named sharity-mod-krb).

If you have gone through these steps and no errors occurred, Sharity 3 is installed on your system. You should now start the Sharity GUI in an X session. Sharity will use the GUI to ask for passwords when required. The Sharity GUI is installed in the binaries directory and has the name "sharitygui".

Once the GUI is running, you can start browsing your network at the browse directory. By default, this is at /CIFS.

Upgrading to a new Version

When a new version becomes available, you can upgrade in the same way as described above. The setup script will ask you whether you want to upgrade or perform a new install. A new install will give you a clean start while an upgrade preserves your preferences and settings. The upgrade skips most of the questions and uses the answers given during the original install. Please note that upgrading from Sharity 2 to 3 is not possible, you need to install from scratch.

Removing Sharity 3

The Sharity package contains the script "uninstall" along with the "setup" script described above. Run this "uninstall" script to remove Sharity. The script will ask you for the path where Sharity was installed.

A copy of the "uninstall" script is also available at Sharity's installation directory. If you use this instance of the script, make a backup copy before you run it because it will destroy itself (it is part of the installation, after all).

<< Back to Table of Contents


Working with Sharity 3

Configuring

All fundamental configuration information is asked during installation. More is usually not required to get Sharity working to the point where you can browse network resources, log in to servers and shares and access files on mounted shares.

All install time configurations (except the installation file system paths) can be changed in the Sharity GUI, section "Options". For more information about the various configuration options please click the Help Button (the button with the question mark) to open the Help Window.

Help Button

Logging in and out

Login dialogIn order to access files, you must prove your identity to the computer which serves the files. This is called "authentication" and usually implemented by providing a user name and password (the credentials). If you run the GUI application, you don't need to log in to servers or shares explicitly. Sharity will automatically pop up a window asking you for credentials when required. These credentials will be remembered (in volatile storage - the logins will be lost during a restart) for future requests. To store your credentials permanently, use the Keychain explained below.

The GUI section "Logins" lists all servers and shares for which you currently have credentials. Clicking the "Logout" button will destroy your in-memory representation of the credentials so that Sharity has to ask again when it needs a resource from the server or share.

Authentication with Kerberos

The Windows 2000 domain (implemented by Windows 2000 and 2003 domain controllers) uses Kerberos for authentication. The advantage for users is that you only need to log in once, usually when you start your session at the computer. From then on you can use all resources which belong to the Kerberos domain. The required authentication is performed automatically behind the scenes without user intervention, provided that you have installed the Kerberos module for Sharity.

Kerberos can perform its magic only if your system is built and configured to use it. When you log in to your computer, it must use your name and password to obtain a "Kerberos Ticket" from a central trusted authority, the Key Distribution Center (KDC). This initial ticket, the "Ticket Granting Ticket", is equivalent to your credentials and is available to all applications you run (contrary to your password, which will never be disclosed to any of your programs).

If your system is configured to use Kerberos and you already have a Ticket Granting Ticket which can be used to log in to a server, Sharity will not ask you for credentials. Instead it will use the Kerberos mechanisms, obtain all required Kerberos tickets and log in to the server. You will notice the Kerberos login in the Sharity GUI, section "Logins", by the word "Kerberos" in the "Authentication" column.

Kerberos is a rather complex system and it must be configured correctly in order to work. Please ask your system administrator for how to bind your computer into the Kerberos domain. More information about Kerberos and a good link collection can be found at Wikipedia.

If you want Kerberos for authentication and also integrate the Unix machines entirely into the Windows domain, consider Centrify's DirectControl. This is an easy to install and easy to manage software package including Kerberos.

Using the Keychain

It can be annoying to have to type a password for every server you connect. Or it can even be impossible to type it because an unattended process such as a web server needs access. Sharity has a powerful mechanism to help in this situation: the keychain. Password based credentials can be permanently stored in the keychain and can even be made the default credentials for a domain or other users.

To add credentials to the keychain, first log in as usual. The credentials will be listed in the "Logins" section of the GUI. Then click the "Add to Keychain" button to add the password and user name to the keychain. Sharity will automatically switch to the "Keychain" section to show the stored credentials (keys).

The newly stored credentials will only be used for the server or share for which they have been stored. This is indicated by the URL displayed for the key. By choosing appropriate functions from the "Actions" popup, you can make a key default for the domain or workgroup or allow other users to read it. Credentials for servers are listed as "smb://servername" while default credentials for a domain are listed in capital letters as "smb://DOMAINNAME".

Pass Phrase DialogInformation in the keychain is stored encrypted in a file on your computer's hard disk. You have been asked to provide an encryption password during installation which is used for this purpose. The encryption password can be changed at any time using the action "Set master pass phrase for key chain..." in the GUI or with the shell command "sharity keychain setpass".

In order to allow unattended operation, Sharity also stores your encryption password (the master pass phrase) encrypted in the file. It cannot use the master pass phrase itself for this encryption for obvious reasons. Instead, a machine password is built from machine specific information. As long as the machine specific data does not change, Sharity can use the keychain without user interaction. However, after an upgrade of Sharity or after a restore from a backup, it may be necessary to re-enter the master pass phrase to recover the keychain.

Browsing Resources

During installation, you had to choose a directory where the "Network Browser" is mounted. The default for this choice is /CIFS. We will refer to this directory as /CIFS throughout the documentation. If your choice was different, please replace /CIFS with your choice when you read the text.

The /CIFS directory has the same purpose as the "Network Neighborhood" in Windows. After startup, it has two subdirectories: "entire_network" and "active_directory" (the latter is only available with the Sharity Kerberos module installed). Listing the directory "entire_network" lists all Netbios domains and workgroups known by computers in your local network segment. Going deeper into the hierarchy, the domain/workgroup directories list all servers known for that domain or workgroup. And finally, listing a server directory shows all shares of that server. The shares are represented by symbolic links which point to a place where the share is automatically mounted when accessed. Example:

    # ls -l /CIFS/
    total 0
    dr-xr-xr-x  2 root  root  16  2 Jun 22:48 active_directory
    dr-xr-xr-x  3 root  root  24  2 Jun 22:48 entire_network

    # ls -l /CIFS/entire_network/
    total 0
    dr-xr-xr-x  4 root  root  32  2 Jun 22:50 workgroup

    # ls -l /CIFS/entire_network/workgroup/
    total 0
    dr-xr-xr-x  2 root  root  16  2 Jun 22:51 ibook
    dr-xr-xr-x  7 root  root  56  2 Jun 22:51 server

    # ls -l /CIFS/entire_network/workgroup/server/
    total 6
    lrwxrwxrwt  1 root  root  1024  2 Jun 22:52 docs -> /CIFS/docs[server]
    lrwxrwxrwt  1 root  root  1024  2 Jun 22:52 ftp -> /CIFS/ftp[server]
    lrwxrwxrwt  1 root  root  1024  2 Jun 22:52 web -> /CIFS/web[server]

The "active_directory" entry in /CIFS will only be populated if your computer is configured to use Kerberos in a Windows 2000 domain. In this case it will list the domains known by the domain controller. Simply list the domain to see what is inside...

Browsing of domains and servers is based on Netbios broadcasts. These mechanisms may fail if there are no computers with the required knowledge in your network segment to answer the broadcast or if Netbios has been disabled by your administrator. In this case you can resort to the "active_directory" browser or manually configure the resources you want. Manual configuration is done in the GUI section "Resources". Click the Help Button in this section for more information about adding resources.

/CIFS as a Magic Directory

The /CIFS directory is more than just the entry point for browsing. If you know the name of a server and share in your network, You can automatically mount it just by accessing it, e.g.:
ls -l /CIFS/docs\[server\]/
(Note: You may have to escape the square brackets from your shell as in the example above.) This command mounts the share \\server\docs (Windows notation) at /CIFS/docs[server] and lists its contents. From now on, docs[server] will be listed as a directory in /CIFS. In other words, automounted shares are listed in /CIFS as well. This is also the mechanism how the resource browsers in "entire_network" and "active_directory" automount shares.

Instead of mounting a share in the file system, you can utilize the automounter. For instance, if you want to have \\server\docs available in your home directory under the name "myserver" simply make a symbolic link:

ln -s /CIFS/docs\[server\] ~/myserver
All mounts and automounts are listed in the GUI section "Mounts". To remove any mount or automount, just click the "Unmount" button while the mount is selected in the list.

Login and Keychain Access from the Command Line

So far we assumed that you always run the Sharity GUI. This may be not possible (if you have no X11 available) or it may not be desirable (e.g. if you use ssh or telnet to remote control the computer). Without the GUI running, Sharity has no means to ask for credentials when required. This means that the credentials must be known beforehand when you want to access a resource. This can be accomplished (1) with the command "sharity login", (2) by storing the credentials in the keychain or (3) by using Kerberos. See the output of "sharity login -h" or "sharity man login" for more information about logging in from the command line.

Most GUI actions have analogous shell commands. See the command "sharity -h" for a list of available commands. For more information about a particular command, type "sharity command -h" or "sharity man command".

Some common examples:

To log in to a particular server:

sharity login smb://myserver
To store your login at server "myserver" in the keychain:
sharity login -s smb://myserver
To list the contents of your keychain:
sharity keychain
To remove a particular password from the keychain:
sharity keychain delete smb://myserver
To change your master pass phrase:
sharity keychain setpass

Mounting Shares from the Command Line

The preferred way to mount shares is by symbolic links into the /CIFS directory as explained above. This method ensures that each object is mounted only once, regardless how many points in the file system refer to it.

However, if you really need to establish a low level mount of a share on a particular directory, it can be done like this (e.g.):

sharity mount smb://server/docs /mountpoint
The directory /mountpoint must exist when the mount command is executed and it must be owned by the user who performs the mount. For more information about the sharity mount subcommand type sharity man mount.

Mounts established in this way are not permanent: They are gone after the next reboot or restart of Sharity. If you want to make a mount permanent, the sharity mount command must be run during system boot. Sharity provides a mechanism for that: The contents of the file /usr/local/sharity3/var/fstab are passed to sharity mount line by line when Sharity starts up.

Accessing ACLs

Windows Access Control Lists (ACLs) can be read and modified by Sharity from the command line. Since there are no general Unix commands for ACL manipulation, we had to provide our own mechanism. (There may be commands available in particular Unix flavors, but these are add-ons which usually work only for particular disk file systems.)

To read the ACL for a file or directory use the command

sharity acl get path
To add an entry to an ACL use (e.g.):
sharity acl add allow friend@domain.com "Read data" file.txt
Convert Windows ACLsFor more information about ACL manipulation, please see the output of the command "sharity acl -h" or "sharity man acl".

Manipulation of ACLs in human readable form (instead of security identifiers) requires the Sharity Kerberos module.

By default, Unix file attributes are not related to Windows ACLs. They are computed from the file's DOS flags such as "System" or "Write Protected". File owner and group are always copied from the current user.

If a service for translation of Windows Security IDs (SIDs) to Unix user and group IDs is available (such as e.g. Centrify's DirectControl), Sharity can compute Unix file attributes from Windows ACLs. See the option "Convert Windows ACLs" in Sharity's Options dialog.

General Information

The GUI section "Sharity" displays version information about the software and the properties of the license key in use. This is also the place where a new license key can be entered.

<< Back to Table of Contents


Configuring a Windows PC to share Files

Many unexperienced users have problems configuring their Windows PC to share files. The definitive reference for this type of questions is the documentation that comes with your Windows operating system, of course. We have compiled this guide for those who want a short, technically oriented recipe. It is a mixture of setup instructions and a trouble shooting guide (you would not read this section if you had no problems, would you?).

Configure the Network

First make sure that the network is up and running. The Unix computer must "see" the Windows box over the net. Test basic interconnectivity with "ping" from Unix or from Windows. It's best to start with IP addresses. This works even without any name service, e.g. (if 192.168.1.55 is the IP address of the other computer):
ping 192.168.1.55
If ping works, IP connectivity is established. If not, right-click the "Network Neighborhood" on the Windows desktop, choose "Properties", double-click your network interface adapter and click the "Properties" button. You will now see a window with various services and protocols. One of them is TCP/IP networking. Browse the properties of TCP/IP to see whether everything looks OK. Use the Windows help where appropriate. Note that you need to be an administrator in order to change any settings!

Once you have ping and thus basic IP networking running, check TCP. This is best done from the Unix command line with "telnet". With the example IP address from above that would be:

telnet 192.168.1.55 139
This command tries to establish a connection to TCP port 139. There are three possible results:

(1) The port can be reached and everything works as expected:

$ telnet 192.168.1.55 139
Trying 192.168.1.55...
Connected to 192.168.1.55.
Escape character is '^]'.
Everything is OK and you can quit the session by typing the escape character and then "q".

(2) The port is not "listening":

$ telnet 192.168.1.55 139
Trying 192.168.1.55...
telnet: connect to address 192.168.1.55: Connection refused
telnet: Unable to connect to remote host
In this case the server service is probably not started on the Windows side or the server has Netbios over TCP disabled. Go to the list of services and protocols as described above, but instead of inspecting TCP/IP, have a look at "File and Print Services for Microsoft Networks". Check that they are installed and active.

(3) The port is not reachable:

$ telnet 192.168.1.55 139
Trying 192.168.1.55...
Then it hangs waiting for a reply. After a couple of minutes it prints:
telnet: connect to address 192.168.1.55: Operation timed out
telnet: Unable to connect to remote host
In this case a firewall is probably blocking the connection. Please make sure to allow access to TCP ports 139 and 445 and UDP ports 137 and 138 in your Windows firewall.

If the server does not allow Netbios over TCP, Sharity can still connect. Please repeat the steps above with port number 445 instead of 139 to verify that the CIFS port is "open".

Sharing a Directory

Once you have TCP/IP networking running, you can make directories available on the network. Choose a directory in the Windows Explorer, right-click it and choose "Sharing and Security". The dialog which follows depends heavily on the Windows version you are running. Read the Windows help for how to share the folder and what properties to set.

It will help you to know that SMB/CIFS has two modes of operation: User Level security and Share Level security. In user level security, users authenticate to the server and then have access to all shares available on the server. Each user has a separate private password. In share level security, each share has a separate password and everybody who knows this share password is granted access. It's the same password for all users and no user name is required. Windows 95, 98 and ME are primarily built for share level security. The server operating systems (NT, 2000 Server and 2003 Server) as well as Windows 2000 Professional and XP Professional all prefer user level security. XP Home Edition uses a kind of faked user level security: It asks for a user name and password, but accepts login only if an empty password is provided.

Name and Browsing Services

After configuring the network and exporting a share, you should in principle be able to access the files in the share with Sharity. However, there are two more possible obstacles: the name service and the browsing service.

Since you want to access the Windows computer by name, there must be a service which maps the name to the appropriate IP address. Windows traditionally used Netbios Name service for this purpose. With Windows 2000, Microsoft has migrated to DNS (Domain Name Service), though. Netbios is usually still supported. If your network uses DNS, you can verify name resolution with ping or telnet. Using the computer name instead of the IP address should work. If you rely on Netbios, there is no standard utility available for testing, you need a special tool like "nmblookup" which is part of the Samba distribution. If your network uses a WINS server, make sure that the WINS setting is the same in Sharity and on the PC.

If the name service works, accessing a share through /CIFS/share[computer] should work. Browsing the network in the "entire_network" directory requires an other service: the Local Master Browse server (LMB). This service is elected dynamically among all Windows computers and other computers running an SMB server (such as e.g. Samba servers). The LMB service is usually enabled on computers where file and printer sharing is enabled. As a last resort, you can install Samba on your own Unix computer to ensure that there is an LMB. The easiest way to circumvent browsing problems, however, is to enter the resources manually in the Sharity GUI.

<< Back to Table of Contents


Tips and Tricks

Help for Configuration Options

Sharity is configured in the Graphic User Interface (GUI). Open the GUI window and change to section "Options". You will see a couple of options. Click the button with the question mark in the bottom left corner (the help button) for more information about these options.

Hint: The help button works in all sections of the GUI and shows a section specific help.

Make a Permanent Mount

All mounts established with "sharity mount" from the command line or with the mounts dialog in the GUI vanish after a reboot. We do not recommend mounting in a startup script because it requires that a user's password is somehow stored on the machine.

There is a much more elegant solution. Use the automounter in /CIFS with a symbolic link. Say you want to have the share smb://server/share permanently available at the path /myshare, create a symbolic link like this:

ln -s /CIFS/share\[server\] /myshare
(Note that the square brackets must be escaped from the shell.) When a user comes to /myshare, the share is automatically mounted and the Sharity GUI brings up a password dialog (unless the user is already logged in or has a password stored).

Default Login for Domain

It may be annoying to type your password again and again. Sharity has a mechanism to prevent this: The keychain. Passwords for shares, servers and even for entire domains can be stored there.

Let's assume that you need to access a couple of servers and have the same password on all of them. You want to store the password in a way so that it is tried first for each login in your domain or workgroup. This can be arranged in the following way:

  1. Login to one server.
  2. Open the GUI and change to section "Logins".
  3. Select the login to the server in question and click "Add to Keychain".
  4. The GUI has switched to section "Keychain". Select the newly created record and choose "Make selected key the default for domain" from the "Actions" menu.
Please note: The procedure outlined above works only as described if the server identifies as member of a domain. Some servers don't. If the "domain" property of the key is a single question mark, the server has not identified. In this case the key is made the default for all domains.

Hint: All this can be done from the command line as well. Here is an example:

sharity login -s smb://server
sharity keychain default smb://server
See "sharity man login" and "sharity man keychain" for details.

Set up a Default Account

Sharity relays security semantics of CIFS to the user: All users who want to access a server must authenticate to this server. This may be inconvenient. Consider an environment where thousands of users need access to a public share. You don't care about security since the share is read-only and contains public information anyway.

You can make all users go through the same account on the server. This is accomplished by storing the login in the keychain and then allow all users to use it. With the GUI, perform the following steps:

  1. Login to one server.
  2. Open the GUI and change to section "Logins".
  3. Select the login to the server in question and click "Add to Keychain".
  4. The GUI has switched to section "Keychain". Select the newly created record and choose "Publish selected key to all users" from the "Actions" menu.
If you need to use different accounts for some users, store passwords for them before you publish a key. Sharity always prefers more specific passwords in the keychain over more general ones.

The same effect can be achieved from the command line, e.g.:

sharity login -s smb://server
sharity keychain publish smb://server
See "sharity man login" and "sharity man keychain" for details.

<< Back to Table of Contents


Troubleshooting

Creating a Debug Log

If you reported a bug or problem to our support, we may ask you for a debug log of the session. In this case please do the following:
  1. Set up a clear starting point. This may consist of unmounting the share to make sure to reset internal status. Don't forget to delete or rename any "/tmp/sharity-debug.log" files from previous runs.
  2. Enable debugging. This can be done (as root) with the magic words
    sharity debug file logLevelsDebug
    in a shell window. If we have asked you to use a different debug setting, please use that instead.
  3. Prepare to reproduce the problem. Do all the necessary steps to set up the situation where you can reproduce whatever you reported (e.g. mount shares, log in users etc).
  4. Record the size of the file "/tmp/sharity-debug.log". This will give us a hint where to search for your problem.
  5. Reproduce the problem with as little operations as possible. Record all operations you did and what error messages you received. Please be EXACT with this task. EXACT means EXACT with no omissions or errors!
  6. Stop debugging (as root) with
    sharity debug syslog
  7. Compress and mail us the file /tmp/sharity-debug.log.
A note of caution: The log file may contain traces of secret information or even passwords. Please don't access any secrets and change passwords after creating the debug log. If you leak secret information in this way, we decline any liability.

Recovering from a Daemon Crash

Sharity consists of two parts: A user interface which does all the interaction with the user and a daemon which performs the real work in background. While a crash of the user interface has no serious consequences, a daemon crash may cause a lot of trouble: If the Sharity daemon crashed or if you killed it accidentally, all mounts served by Sharity will hang. But don't panic: You can usually recover from that. If you can afford it, the easiest way is an immediate reboot. If a reboot is not possible, try to umount the Sharity mounts with the system's umount (or unmount) utility. Use the "-f" option to force the umount if it is available. If this is not sufficient, start the Sharity service with (default installation path assumed):
/usr/local/sharity3/sbin/sharity.init start
Then try to unmount with the system's umount or unmount again. When you eventually managed to get rid of all Sharity mounts, simply kill the daemon. [You should never ever kill sharityd, except in this particular situation!] Then start it again and the service should be restored.

Unmounting may fail with a "Device or resource busy" error message. This means that an application is still using a mount. The umount will not succeed before you have killed that application. To find out which application is busy on the mount please use the "lsof" or "fuser" utility. The source code to "lsof" is freely availabe.

Debugging Kerberos and Active Directory

Kerberos and Active Directory functions are implemented in a separate per-user daemon. This daemon (sharity-userd) can be debugged separately, without running any other parts of Sharity. However, it may need special environment variable settings in order to work. To get a shell with these environment variables set, do the following (as user, unless you want to debug root logins):
/usr/local/sharity3/sbin/sharity.init testshell
This will put you into an "sh" type shell. You can start your favorite shell from there.

Before we actually start with sharity-userd, make sure that you have a valid Kerberos ticket. Type "klist" to show your Kerberos tickets and use "kinit" to login if required. Assuming that you have a valid Ticket Granting Ticket, you can do

sbin/sharity-userd getUserPrincipal
to display your Kerberos principal name. To acquire credentials for a particular server, do
sbin/sharity-userd getKrb5Auth <server-principal>
where "<server-principal>" is the Kerberos principal for the server. This name is usually constructed from the server name as "servername$@REALM" where the realm is usually the uppercase version of the domain name. For example:
bash$ sbin/sharity-userd getKrb5Auth 'pdc1$@TEST.HOME'
authenticator for pdc1$@TEST.HOME is:
odalloc/alloc: 0000: 6e 82 04 5a 30 82 04 56 a0 03 02 01 05 a1 03 02
odalloc/alloc: 0010: 01 0e a2 07 03 05 00 00 00 00 00 a3 82 03 99 61
[...]
odalloc/alloc: 0450: 36 84 00 8c 0c 7d f3 e9 58 7e 2b bd 98 e9
session key is:
odalloc/alloc: 0000: 09 35 a9 f4 4a 97 ed 60 42 11 ca d7 95 f7 e3 aa
If you succeed with these steps, a Kerberos login should work. If it does not, please make sure that you use the default credentials cache (environment variable KRB5CCNAME not set). Since Sharity is started at boot time, it cannot inherit your environment settings.

To test access to Active Directory, try

sbin/sharity-userd ldapQuery <domain> 1 objectClass=user
where "<domain>" is replaced with your Active Directory domain. For example:
bash$ sbin/sharity-userd ldapQuery test.home 1 objectClass=user
userd/db0: trying ldap connect to pdc1.test.home port 3268
userd/db0: SASL Interaction: challenge=Authorization Name prompt=...
userd/db0: SASL Interaction: defaultRes=
entry 0 dn = CN=TsInternetUser,CN=Users,DC=sub1,DC=test,DC=home
    cn = TsInternetUser
    displayName = TsInternetUser
    instanceType = 0
    distinguishedName = CN=TsInternetUser,CN=Users,DC=sub1,DC=test,DC=home
    objectCategory = CN=Person,CN=Schema,CN=Configuration,DC=test,DC=home
    objectClass = top
         person
         organizationalPerson
         user
[...]

If this command succeeds, too, you should be able to browse Active Directory through Sharity. If one of the commands fails, the error message should give you a hint to the cause of the problem.

<< Back to Table of Contents


Unix Home Directories on SMB Shares

Overview

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:

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 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:
/nethome/$domain/$user
/nethome/$user
/home/net/$user
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/local-profile.sh, e.g. on Linux:
LD_LIBRARY_PATH=/usr/share/centrifydc/kerberos/lib:$LD_LIBRARY_PATH
LD_LIBRARY_PATH=/usr/share/centrifydc/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
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
x-homes:company.com /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
Password:
Last login: Fri Nov 3 15:21:29 on tty1
-bash-3.1$ pwd
/nethome/james
-bash-3.1$ ls -l /nethome
lrwxrwxrwx 1 james domainusers 1024 Nov 6 18:12 james -> /CIFS/homes[server.mycompany.com]/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

Authentication

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 x-homes:company.com /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
...

Limitations

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:

<< Back to Table of Contents


Release Notes

The following list is in reverse order: New entries are added at the top.

New in Version 3.3

Bugs Fixed:

New Features:

New in Version 3.2

Bugs Fixed:

New Features:

New in Version 3.1

Bugs Fixed:

New Features:

New in Version 3.0

The following features have been added since Sharity 2:

<< Back to Table of Contents


Software License

Sharity 3
End User License Agreement

Version 2006-06-08

IMPORTANT: THIS END USER LICENSE AGREEMENT ("EULA") IS A LEGAL AGREEMENT BETWEEN YOU AND OBJECTIVE DEVELOPMENT. READ IT CAREFULLY BEFORE USING THE SOFTWARE. IT PROVIDES A LICENSE TO USE THE SOFTWARE AND CONTAINS WARRANTY INFORMATION AND LIABILITY DISCLAIMERS. BY INSTALLING, COPYING, OR OTHERWISE USING THE SOFTWARE, YOU AGREE TO BE BOUND BY THE TERMS OF THIS AGREEMENT. IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT, DO NOT INSTALL OR USE THE SOFTWARE.

1 DEFINITIONS

1.1 "OBJECTIVE DEVELOPMENT" means OBJECTIVE DEVELOPMENT Software GmbH.

1.2 "SOFTWARE" means the software program(s) and associated software components supplied by OBJECTIVE DEVELOPMENT herewith, and corresponding documentation, associated media, printed materials, and online or electronic documentation.

1.3 "LICENSE KEY" is a character string representing a license grant in condensed form. A LICENSE KEY contains information about, but not limited to:

2 LICENSE GRANTS

2.1 Installation and Use. You may install and use ("RUN") a copy of the SOFTWARE on as many computers as the limitations and license type encoded in the LICENSE KEY allow (see also section 3 below).

2.2 Network Installation. You may also install a copy of the SOFTWARE on a network server, used to RUN the SOFTWARE on your other computers over an internal network. However, you must acquire and dedicate licenses for each separate computer on which the SOFTWARE is RUN from the server.

3 LICENSE TYPES

3.1 Trial Mode. As long as no LICENSE KEY has been installed in order to establish a specific kind of license grant, you may RUN the SOFTWARE exclusively for test- and evaluation purposes in Trial Mode (if available). Trial Mode makes only a limited set of features available.

3.2 Home User License. The Home User License is restricted to private, non-commercial use.

3.3 Business License. The Business License allows you to RUN the SOFTWARE in a commercial environment.

3.4 Demo License. The Demo License allows you to RUN the SOFTWARE in a commercial, non-private environment for test and evaluation pruposes. Demo Licenses are valid for a period of one month, unless the LICENSE KEY encodes a different expiration date.

4 LICENSE RESTRICTIONS

4.1 Distribution. You may not distribute copies of the SOFTWARE or the LICENSE KEY to third parties.

4.2 Secrecy. As the owner of a LICENSE KEY you are responsible for keeping this key secret. If any third party gets access to your LICENSE KEY due to willful or negligent act, you are liable for the damage that arises to OBJECTIVE DEVELOPMENT.

4.3 Reproduction. Except for backup and installation purposes the SOFTWARE must not be reproduced on any type of media (including, but not limited to, CD-ROM, DVD or internet download) without the formal approval from OBJECTIVE DEVELOPMENT.

4.4 Prohibition on Reverse Engineering, Decompilation, and Disassembly. You may not reverse engineer, decompile, or disassemble the SOFTWARE, except and only to the extent that such activity is expressly permitted by applicable law notwithstanding this limitation.

4.5 Not for Resale Software. If the SOFTWARE or the LICENSE KEY is labeled "Not for Resale" or "NFR", then you may not sell it or otherwise transfer it for value.

4.6 Rental. You may not rent, lease, or lend the SOFTWARE or otherwise encumber any copy of the SOFTWARE, or any of the rights granted herein.

4.7 Transfer. You may not transfer your rights under this EULA to another end user without OBJECTIVE DEVELOPMENT's prior written consent. If such consent is obtained, you may permanently transfer this License to another end user provided you transfer the entire SOFTWARE and the LICENSE KEY to such end user, and you do not retain any copies. The recipient of such transfer must agree to all terms and conditions of this EULA.

4.8 Reservation of Rights. OBJECTIVE DEVELOPMENT retains all rights not expressly granted.

4.9 Non-Exclusive Rights. Your license rights under this EULA are non-exclusive.

5 COPYRIGHT AND OWNERSHIP

The SOFTWARE is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. The SOFTWARE is licensed, not sold.

6 TERM AND TERMINATION

6.1 Term. This EULA shall continue indefinitely. However, OBJECTIVE DEVELOPMENT may terminate this EULA and revoke the granted license if you fail to comply with any of its terms and conditions. In such event, you must destroy all copies of the SOFTWARE.

6.2 Survival of Terms. All provisions regarding secrecy, confidentiality and limitation of liability shall survive termination of this agreement.

7 DISCLAIMER OF WARRANTY AND LIABILITY

LIMITED WARRANTY. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, OBJECTIVE DEVELOPMENT AND ITS SUPPLIERS HEREBY DISCLAIM ALL WARRANTIES, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE, AND THE PROVISION OF OR FAILURE TO PROVIDE SUPPORT SERVICES. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE OTHERS, WHICH VARY FROM STATE/JURISDICTION TO STATE/JURISDICTION.

LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL OBJECTIVE DEVELOPMENT OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE OR THE PROVISION OF OR FAILURE TO PROVIDE SUPPORT SERVICES, EVEN IF OBJECTIVE DEVELOPMENT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN ANY CASE, OBJECTIVE DEVELOPMENT'S ENTIRE LIABILITY UNDER ANY PROVISION OF THIS EULA SHALL BE LIMITED TO THE AMOUNT ACTUALLY PAID BY YOU FOR THE SOFTWARE.

8 MISCELLANEOUS TERMS

8.1 Severability. In case a provision of these terms and conditions should be or become partly or entirely invalid, ineffective, or not executable, the validity of all other provisions shall not be affected.

8.2 Applicable Law. This agreement is governed by the laws of the Republic of Austria.

8.3 Responsible Courts. The responsible courts in Vienna/Austria will have exclusive jurisdiction regarding all disputes in connection with this agreement.

<< Back to Table of Contents