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

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.

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