8. Troubleshooting

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 http://www.obdev.at/products/sharity/support.html. It contains the most up-to-date information.
4. Visit our list of known bugs at http://www.obdev.at/products/sharity/support.html. 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 http://www.obdev.at/products/sharity/support.html for more information.

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

• 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.).

8.2 How to create a Debug Log

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.

8.3 How to recover from a Daemon Crash

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 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:

  HkeyLocalMachine\System\CurrentControlSet\Services\LanmanServer\Parameters\SizReqBuf

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

    nmblookup -M -

    nmblookup -S -M YOUR_DOMAIN_NAME

There's one final nmblookup command which can be useful

    nmblookup -U WINS_IP_ADDRESS 'YOUR_DOMAIN_NAME#1b'

8.6 If rm -r does not delete all files

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

    dataCacheTimeNoLock = 0;

    requestOplock = no;

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

• Not to use the GUI file manager
• Ask the vendor of this file manager to fix the problem
• Configure Sharity to disallow browsing.

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