  
8. 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. You should also have a look at chapter Limitations, maybe Sharity can't do what you are expecting.
- 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 (notcifsumount) 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:
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
On some platforms, 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 from the GNU binutils package.
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.
...if you point your GUI 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...
  
Sharity Manual for version 2.3 | Copyright (C) 1999 by Christian Starkjohann | http://www.obdev.at/
|