Table of ContentOverview PagePrevious PageNext Page

8. Troubleshooting

If something does not work as expected, please go through the following steps:
  1. Make sure you understand the basics concepts of Sharity. Read the chapter General Concepts if you have not already done that. You should also have a look at chapter Limitations, maybe Sharity can't do what you are expecting.
  2. If Sharity reports an error, look up the error message in the appendix Error Messages to see whether there's more information about the message available. Also look into the system log for errors logged by Sharity. The location of the system log file is platform dependent. Look into the file /etc/syslog.conf and the associated manual page for details.
  3. Search our knowledge base at It contains the most up-to-date information.
  4. Visit our list of known bugs at Maybe you have discovered a bug which has already been found and a workaround or bugfix is available.
  5. Reconsider what you did after you gained new knowledge from the above steps.
  6. If you get until here and things still don't work, you have probably discovered a bug. Please submit a bugreport. See for more information.
Individual support is expensive in terms of time and effort. Please be sure to go through the above steps before you ask for support. On the other hand, support incidents give valuable information about the problems users have. If you think you have discovered something that might be of interest to others, don't hesitate to contact our support. Support is free for business customers, so there's no risk for you. Reporting bugs is free for everyone, of course!

If the sharityd daemon crashes, this is definitely a bug. Sharity will send an e-mail to the root user when it starts after a crash. It will tell you what we need to track down the problem. Please follow the instructions in the e-mail! For recovery hints, see section How to recover from a Daemon Crash.

8.1 What to include in a Bug Report

If you decide to mail a bugreport, please include:
  • A description of your problem: What you do, what you would expect and what happens instead.
  • If errors occur, the exact error text. Also look into the system log for related error messages.
  • The operating system and version where you deploy Sharity and the type and version of server you connect to. Sharity is available for many different operating systems!
  • A short description of your network topology (routers between you and the server, domain concept, etc.).
Not all of the above is always needed. Please use your common sense to find out what we might need. And please re-read your mail before you send it to see whether it's understandable.

8.2 How to create a Debug Log

During a support incident, we may ask you to create a debug log which contains more information about your problem. A debug log is created as follows:
  1. Unmount everything mounted with Sharity and shut down the daemon. This can be done by calling the startup script (sharity.init) with the option stop:

    /usr/local/sharity/sbin/sharity.init stop

    You can also send a kill signal to the daemon. In any case be sure to unmount all Sharity mounts beforehand.

  2. Copy the file sharity.cfg to /tmp/sharity.cfg. This file can be found at /usr/local/sharity/etc/ if you used the defaults during installation.
  3. Edit the file /tmp/sharity.cfg. In section main there's a variable named logLevels. You should enable all logLevels you have been told to. LogLevels can be enabled by deleting the remark-sign (consisting of two slashes) in front of them.
  4. Start the daemon in debug-mode and redirect standard error output to a file. In a Bourne compatible shell, this can be done with:

    /usr/local/sharity/sbin/sharityd -d -f /tmp/sharity.cfg 2>/tmp/logfile

    In a C or compatible shell, the redirection is done with >& instead of 2>.
    Alternatively, you can omit the redirection and copy the logged data from the terminal window.

  5. If you want to see the logged information, you can either pipe the daemon's standard error through tee or run

    tail -f /tmp/logfile

    in a second window.

  6. Reproduce your problem and write down what you did (e.g. copy the session history from the terminal window).
  7. Shut down the daemon by unmounting and typing Ctrl-C in the window running the daemon. Be sure to unmount before you stop the daemon!
  8. Mail us the logfile and the description of what you did, which error occured etc. Please use file compression if the logfile is large! If it's very large, please discuss it with us. Maybe you can disable some not so important logLevels to reduce the size by an order of magnitude.
Important Note:The logfile may contain confidential information in hex-dumps. Please be careful not to use unencrypted passwords and not to access confidential files when you create logfiles. If unencrypted passwords can't be avoided, either create a dummy-account with a dummy-password for the test or edit out the password from the hex-dump. Even if passwords are encrypted, the logLevel uiTrace (if enabled) contains your password in clear-text in the hex-dump.

8.3 How to recover from a Daemon Crash

If the daemon crashes, all mountpoints served by Sharity will become unusable. Every access to one of these mountpoints will hang the accessing process. You will not be able to unmount or restart the daemon cleanly because the mountpoints are still busy. To get back into a clean state, you have two choices: either reboot the machine (recommended for non-experts!) or do the following:
  1. Make sure the daemon is really gone. Use your system's ps command to verify this.
  2. Make sure that the port used by Sharity for NFS is available. Sharity uses UDP port 991 for this purpose by default. The value can be configured in sharity.cfg. Use your sustem's netstat command to verify that this UDP port is available.
  3. Restart the daemon. It will allocate the same port again. If it can't, it will log an error to the syslog and use a random free port. This procedure won't work if Sharity can't get the same port as before. The daemon probably tries to mount things at startup. This may fail.
  4. Use your system's umount command (notcifsumount) to unmount the stale mounts. You can use mount to display a list of all mounts.
  5. Shut down and restart the daemon again. It should now be able to start up without errors.

8.4 If the Performance is less than expected...

Sharity should be about as fast as the network and the server's disk allow. Transfer rates of 500k/s to 1MB/s on 10Mbit Ethernet and 2MB/s to 5MB/s on 100Mbit Ethernet should be achievable. If you get much less, here's a list of possible causes:
  • Sharity needs relatively much CPU time per transferred data block. If you have a slow CPU (e.g. an Intel 486), the performance may suffer noticable. This should rarely be a problem with today's CPUs.
  • NT is said to be tuned "not quite to the optimum" for TCP/IP. But fortunately the paramters can be changed in the registry. The registry entry is:


    MS Technet recommends 3904 hex. Some customers report better experiences with 1400 hex. The optimum value seems to depend on your network. In any case, both values yield a substantially better TCP/IP performance. (Thanks to Joachim Schastok for this information!)

  • Writing data through Sharity depends very much on the kernel's NFS optimizations. Most important is the write pipeline: It keeps sending data to Sharity, even if Sharity did not reply with a success status to the kernel. This pipeline is usually accomplished by the biod or nfsiod daemons. You should have about 4 such daemons running. If you have much more, you may get buffer overflows in the connection between Sharity and the kernel, if you have less, the pipeline may be too short.
  • The write pipeline may be disturbed by attribute reads from the kernel. You may try to increase the NFS kernel attribute cache time in the server-section of the GUI. This reduces the number of attribute reads done by the kernel, thus improving the write performance. Please read the associated help for security notes, if you change this setting!
  • Sharity talks to the kernel through a UDP socket. This socket has a limited amount of data buffer. Sharity already tries to set the buffer to a maximum, but if an overflow occurs, the transfer is interrupted for one NFS-timeout (which can be configured). You can try to reduce the initial NFS timeout in this case.
  • The server may be too slow. We've seen a server with an Intel 486 which was fast enough for the network bandwidth of 10Mbit. After an optimization, the throughput went down by a factor of 10. It turned out that the CPU was too slow for the higher packet rate and the network card driver lost packets. The throughput could be fixed (i.e. increased by a factor of 10) by putting the client under heavy I/O load!
  • You may have a general network problem. If you get very frequent collisions (maybe even a collapsing network), this is a hint for a broken network card, hub, cabling or just broken driver software.

8.5 If Browsing does not work

If browsing for file servers does not work on your setup, please be sure to check your configuration settings for the "browser" browser's domain and the WINS server (in the "CIFS Browsers" and "CIFS General" sections of the GUI respectively). If you are sure that both are correct, it's possible that there are no Windows or Samba computers in your network segment which can provide the browse service Sharity needs.

If there is no browse server available in your network segment (or at least not reliably available), simply install Samba on your machine. It provides the browse service required by Sharity. Our Support Page may list recommended Samba packages for particular platforms.

If browsing still does not work even after installing samba, you can use samba's commandline tools to debug the problem. The nmblookup tool is most useful for this purpose. The command

    nmblookup -M YOUR_DOMAIN_NAME
looks for the master browser of your domain. The command
    nmblookup -M -
looks for all master browsers of all domains in your network segment. Sharity does not only need the master browser's IP address, it also needs its name. You can check whether Sharity can obtain the name of the master browser with
    nmblookup -S -M YOUR_DOMAIN_NAME
which also looks up the node status of your master browser.

There's one final nmblookup command which can be useful

This command looks up the domain controller with WINS. If Sharity can't find anything else, it will fall back to the domain controller, if it finds it.

8.6 If rm -r does not delete all files

On some platforms, recursive file deletion with rm -r may fail on directories containing many files. This is a problem in the translation between NFS (used to communicate with the kernel) and CIFS (used with the server). NFS, with its stateless design, expects that it can continue every directory listing after any file it has already read. The continuation points are communicated by cookies, unique numbers identifying the files. However, there is no such thing as a unique cookie in CIFS. Sharity therefore simply uses the file indices as cookie values.

You may already suspect the problem here: if the rm program reads (let's say) 100 files, deletes them and then continues the search for more files at file index 101, index 101 won't refer to the same file as it did before deleting the first 100 files. Index 101 is now the file with index 1, because the first 100 files have already been deleted.

Sharity applies a couple of workarounds for this problem. However, these workarounds work only if the application and the kernel behave "reasonably". "Reasonably" means that the entire directory content is read within a short timeframe and that directory reads are continued where the previous read ended. Some platforms (most notably Openstep) have an rm implementation which breaks these reasonable assumptions. rm -r may fail on these platforms.

If you rely on rm -r to work even for large directories on such a platform, you may try to increase the variable dirCacheTime in the file /usr/local/sharity/etc/sharity.cfg. Or you may use the rm implementation from the GNU fileutils package.

8.7 Managing concurrent access to files

By default, Sharity does not guarantee consistent file content during concurrent accesses from different hosts (no open-to-close consistency). If you read files at the same time they are written on an other host, you probably need open-to-close consistency. This can be achieved with configuration changes in the file /usr/local/sharity/etc/sharity.cfg. The first thing you have to change is
    dataCacheTimeNoLock = 0;
Search for the variable and change the setting. An other topic are Opportunistic Locks. This is a feature in CIFS which ensures cache consistency. Unfortunately, there seems to be a bug in Windows NT 4.0 which allows Sharity to acquire a "batch opportunistic lock" although the file is open on NT. As a workaround, you should disable opportunistic locks completely. Set
    requestOplock = no;
(caution: this variable occurs multiple times).

Note: You don't need to change the settings as described above if concurrent accesses are performed from the same host. E.g. there is no problem if the writing and the reading application both run on the same Unix box accessing the files through Sharity.

8.8 If you can't use the browser because...

...if you point your GUI file manager to the /CIFS directory, you are asked for the passwords of all your servers (and you have many...). This is, unfortunately, a misbehaviour of your GUI file manager. It reads directory contents in advance, which forces Sharity to connect to all servers. Sharity can't work around this problem without loss of features. Your choices are:
  • Not to use the GUI file manager
  • Ask the vendor of this file manager to fix the problem
  • Configure Sharity to disallow browsing.
For more information about the last option, please see the online help of Sharity's browser configuration.

If you have servers which export MANY shares, you may also want to disable browsing to avoid that all shares are mounted once the server's contents are listed.

An other situation where you might want to disable browsing is if you run a recursive backup on your machine's root directory. You don't want to have your entire network on the backup, after all...

Table of ContentOverview PagePrevious PageNext Page

Sharity Manual 2.9 Beta 7 | Copyright (C) 2004 OBJECTIVE DEVELOPMENT Software GmbH |