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

Working with Sharity 3


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 "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.

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