  
7. Troubleshooting
If something does not work as expected, please go through the following steps:
- Make sure you understand the basics concepts of Sharity. Read the chapter General Concepts if you have not already done that.
- 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 syslog for errors logged by Sharity. The location of the syslog file is platform dependent. Look into the file /etc/syslog.conf and the associated manual page for details.
- Visit our list of known bugs at http://www.obdev.at/Products/SharityBugs.html. Maybe you have discovered a bug which has already been found and a workaround or bugfix is available.
- Reconsider what you did after you gained new knowledge from the above steps.
- If you get until here and things still don't work, you have probably discovered a bug. Please mail a bug report to <sharity-bugs@obdev.at>. And please read section What to include in a Bug Report before writing the report!
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 troubles users have. If you think you have discovered something that might be of interest to others, don't hesitate to mail to our support. Support is free, so there's no risk for you.
If the sharityd daemon crashes, this is definitely a bug. Please report every such incident. See section How to recover from a Daemon Crash for recovery hints.
If you send 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 syslog for related error messages.
- The operating system and version where you deploy Sharity and the type and version of server you connect to.
- A 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.
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:
- 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. You can also send a kill signal to the daemon. In any case be sure to unmount all Sharity mounts beforehand.
- Copy the file sharity.cfg to /tmp/sharity.cfg. This file can be found at /usr/local/sharity/etc/sharity.cfg if you used the defaults during installation.
- 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.
- 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.
- 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.
- Reproduce your problem and write down what you did (e.g. copy the session history from the terminal window).
- Shut down the daemon by unmounting and typing Ctrl-C in the window running the daemon.
- 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.
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, do the following:
- Make sure the daemon is really gone. Use your system's ps command to verify this.
- 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.
- 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 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.
- Use your system's umount command to unmount the stale mounts. You can use mount to display a list of all mounts.
- Shut down and restart the daemon again. It should now be able to start up without errors.
Sharity should be about as fast as the network and the server's disk allows. 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.
- 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 daemons. You should have about 4 such daemons running. If you have 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. I'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 by putting the client under high I/O load!
- You may have a general network problem. If you get very frequent collisions (maybe even with a collapsing network), this is a hint for a broken network card, hub, cabling or just broken driver software.
If browsing for file servers does not work on your setup, please be sure to read and understand the Browsing section in the chapter General Concepts. If you still can't get it running, here are more ideas:
- Browsing depends on network broadcasts which must reach the Local Master Browser. If your computer has multiple network interfaces, it depends on the operating system how broadcasts are handled. On some OSes, they are sent out on all interfaces, on others they go through the first interface only. If your OS sends them out on the first interface it finds, this may not be the interface where the Local Master Browser can be found. In many cases you can determine the interface on which broadcasts are sent with a routing entry for the host "255.255.255.255". E.g. on Linux:
route add -host 255.255.255.255 dev eth1
- You can debug the broadcasts involved with name resolution with tcpdump. The following invocation lists all Netbios Name Service broadcasts on the first ethernet interface:
tcpdump -s 1500 -i eth0 port 137
  
Sharity Manual for version 2.0 | Copyright (C) 1999 by Christian Starkjohann | http://www.obdev.at/
|