This chapter describes the function and configuration of the Desktop Server. The Desktop Server is responsible for storing icon and application data for the entire EtherShare Server, and for managing file and directory IDs for network volumes. The Desktop Server is usually invisible to users and has no associated Macintosh application. The exception is the
Rebuild Desktop... option in the EtherShare Admin.
10.2 The Desktop Server Program
The EtherShare Desktop Server system consists of the program "desksrv". It is created in the "$ESDIR" directory during installation. EtherShare is configured to start "desksrv" automatically when UNIX is booted.
"desksrv" manages a database containing icon and application data for the entire EtherShare server, and file and directory ID information for network volumes. The database data are contained in the ".Desktop" file in the root directory of each HFS volume. The file name ".Desktop" is protected by EtherShare, and is normally invisible to Macintosh users.
The application data records in each ".Desktop" file contain the information required to assign documents to the Macintosh applications that created them. The Macintosh's Finder uses this information to start the corresponding application when the user double-clicks on a particular document. Each time a new application is copied into an EtherShare volume, the desktop server creates a new entry in the corresponding desktop database file.
The icon data records in each ".Desktop" file contain icons from all the applications in the volume, sorted by type and creator codes.
In order to let the Finder display icons for documents and applications, each application contains icon images (bitmaps) for its own icons in several sizes and styles, and icons for all the document types it can create. For example, Microsoft Word can create text, glossary, dictionary documents, etc., each with its own icon. Each icon is associated with unique file type and file creator codes. The application's documents normally contain the file type and file creator codes only (stored in their resource forks), but no icons. See
The structure of volumes and files in chapter
9.3 "Directory and file formats" for more information.
Each time a new application is copied into a local Macintosh volume, the Finder copies all of the icons it contains to the volume's desktop file. In the case of EtherShare, the Desktop Server stores them in the ".Desktop" database file, after checking that the same icons are not already stored there.
If you copy documents of an application to your Macintosh without ever having owned the corresponding application, then the icons may appear blank. This is because the icons you see in the Finder are taken from the desktop file and not from the documents, the latter simply supply the correct type/creator codes.
When the Finder or an application needs to open a file, in addition to looking for the specified file name in a named directory and volume, a system option is available to open the file by a reference number instead. This reference number is called the "file ID". The directory path, too, can be specified by its "directory ID". By using file and directory IDs, files can still be found after a user has renamed or moved them. This provides Macintosh users with a lot more flexibility than MS-DOS users, for example.
This principle is used in the "Alias" facility introduced with Macintosh System 7.
Each ".Desktop" file contains file and directory IDs for all the files and directories in the volume. The file ID is also stored in each file's resource file; the directory ID is also stored in each directory's resource file.
The file and directory IDs are allocated when the file or directory is first created, and never change even if the file is renamed or moved to another location. The IDs are normally invisible to the user.
After a period of time, each volume desktop file tends to collect a number of icons which are no longer needed, since the corresponding application has been deleted from the volume. For this reason, you may rebuild your desktop from time to time, i.e. start a process which scans the entire volume for applications and makes sure that the desktop only contains icons for existing ones.
You can rebuild your desktop for local Macintosh volumes (built-in hard disk) by restarting your Macintosh while holding down the
Option and
Command keys. To rebuild the desktop of an EtherShare volume, you must make sure that the volume is not mounted (e.g. with the
Active Users... option in
5.13.2 "Active Users list and sending messages with the EtherShare Admin") and then start the EtherShare Admin application on one of your Macintosh clients, select the volume in the volume list, and choose
Rebuild Desktop... from the
Volume menu (see
Rebuild Desktop in chapter
5.9 "Volume menu").
The rebuild process will always add files to the desktop database in order to allow file name searches in the volume desktop database. This requires that a resource for every file/folder is available.
During an EtherShare desktop rebuild, missing resource directories and resource files are automatically created for all
directories in the EtherShare volume (including the volume root directory); existing directory IDs are verified and missing ones are created.
With
files, missing file IDs are created and existing file IDs are verified. Missing resource files are created as well. The file type in that case, is substituted by a dummy, e.g. "UNIX/UNKN". The generic UNIX icons and extension-mapped icons are created later by the File Server, when the corresponding folder is first opened.
Note that a desktop rebuild with EtherShare 2.6 and the creation of missing resource files may cause difficulties if you try to access these files from an EtherShare 2.2 (or older) server via NFS. Old EtherShare versions cannot display such files properly; the icons are displayed blank. Therefore, you should make sure that in a multi-EtherShare-Server environment, all servers are updated to EtherShare 2.6.
By default, the rebuild program uses two passes to update the volume desktop database. The two pass approach does have the benefit that on volumes where duplicate file/folder-IDs exist (usually resulting from manipulations of files/folders by UNIX commands), files/folders will get an adjusted ID only after the complete desktop is verified, and all other objects will retain their original ID.
File and directory IDs are stored in both the ".Desktop" file and the file's (or directory's) resource file; if the verification detects differences, the IDs from the resource files are assumed to be the correct ones.
While a rebuild is running, it is possible to write to an EtherShare volume. As long as the desktop database is not yet complete, changes to files or folders may result in different file-/folder- IDs issued for objects not yet re-enumerated by rebuild.
To prevent inconsistencies between information stored in the desktop databases of an EtherShare volume and the files/folders on this volume, the rebuild process encountering an RPC timeout will exit immediately. Desktop information for this volume will be incomplete until a rebuild finished successfully.
In case "afpsrv" processes also encounter RPC timeouts, the volume will get secured against write access and will be grayed out in the Chooser's volume list. Opening folders and reading files will still be possible, but creating/renaming/moving files or folders will not be possible any longer. Not even trashing files/folders will be allowed.
RPC timeouts are symptoms which are usually caused by high server or I/O load, slow I/O devices, network or communication problems. Assure that the cause of this problem is solved before restarting EtherShare services. Depending on the severity of the problem, it may be necessary to stop and restart EtherShare services on the server by using the scripts "$ESDIR/stop-atalk now" followed by "$ESDIR/ start-atalk".
In the case of files created by UNIX applications, the resource directories are unnecessary - although they do not affect UNIX applications which access the original files, they take up a certain amount of disk space. Accordingly, it may be better to organize your directories and volumes with separate file systems for UNIX-only and Macintosh files.
Important: We strongly recommend to use the "rebuild" option to put your desktop in order. Do never delete the desktop database under UNIX.
Each time you open an EtherShare volume with the
Chooser, the desktop server checks the logical consistency of the desktop file and may trigger a desktop rebuild if it finds invalid information. This process takes place automatically and in the background. The same check is done, too, for each of the volumes in the volume list "$ESDIR/conf/ afpvolumes" when EtherShare is first started.
Most computers such as the Sun SPARC and IBM RS/6000 use the so-called Motorola byte order, and others such as the DEC Alpha and IBM PC use the Intel byte order. An auto-rebuild also takes place if you mount a volume whose desktop was created by a computer with a different byte order.
Furthermore, the volume's directories must not overlap
or include the directories of other EtherShare volumes.
You should choose the volume mount point carefully to make sure this does not happen. To avoid problems,
EtherShare 2.6 checks for overlapping volumes; volumes will be grayed out if they overlap a volume you have already mounted. You will receive an error message (see later). The EtherShare Admin will check for overlapping volumes as well. Nevertheless, it may happen that existing volumes are not checked and that you are able to create a new volume that overlaps an existing one.
Instead of using the
Rebuild Desktop... option in the EtherShare Admin, you can also call the "rebuild" program from a UNIX shell. There is one particular situation where this may be required:
- If you want to rebuild the ".Desktop" database for your home volume or a private volume. The Desktop Server will create a ".Desktop" database and resource directories the first time you access your home volume from the Chooser, and will rebuild it if it becomes corrupted, but you will not be able to rebuild it manually from EtherShare Admin, since it does not appear in the volume list.
The rebuild program offers an option to clean (delete) resource orphans. As discussed earlier, the File Server creates resource files for files created by UNIX applications when the corresponding folder is opened. However, when you delete a file directly from the UNIX host, the matching resource remains untouched. (But when you delete a file from a Macintosh, the resource file is deleted, too).
So particularly if your EtherShare volume contains a mixture of Macintosh files and UNIX-only files, after a period of time the volume will tend to collect a number of unused resource "orphans", wasting space. Calling the "rebuild" program will automatically delete the resource orphans. You would have to specify the "not clean resource orphans" switch of the "rebuild" program to prevent the program from automatic deletion. Alternatively, you can specify the "nocleanorphans" switch for the "rebuild" program in "atalk.conf", causing orphans to be maintained each time a desktop rebuild takes place (see chapter
10.3 "Parameters of the "rebuild" program").
Call the "rebuild" program from a UNIX shell as follows:
rebuild <switches> <path_of_volume_root>
The available switches are:
-n output to system messages file instead of "stdout"
-o open ".Desktop" file only, repair if corrupted
-f force ".Desktop" file to be rebuilt
(force create is off if you do not specify -f)
-c do not clean resource orphans automatically
(clean orphans is default if you do not specify -c)
-C volume can be converted to another character set
-s scan desktop only
(scan only is off if you do not specify -s)
-v verbose for diagnostics
(verbose is off if you do not specify -v)
-2 2 ID check passes is active by default
(two passes is disabled if you specify -2)
-x volume is exclusively opened for rebuilder
Usually, you call "rebuild" with the "-f" switch, for example:
rebuild -f /usr/local/es/macapps
If you call "rebuild" with the "- C" option, you can specify a new character set, e.g. "MacRoman" or "SJIS":
rebuild - C macroman <path_of_volume_root>
If you want to convert from a new to the old EtherShare character set ("oldes"), call:
rebuild - C oldes <path_of_volume_root>
In the case of CD-ROM volumes, or volumes such as Magneto-Optic (MO) cartridges which have been mounted with the EtherShare Admin as "read-only", the desktop server first checks to see if a valid ".Desktop" file is available on the volume's root. This can be the case, for example, for MO cartridges which were previously mounted under EtherShare as "read-write", allowing a valid desktop to be created.
If a valid ".Desktop" file cannot be found (this will almost always be the case for CD-ROMs), the desktop server creates a temporary desktop file in the host's "/tmp" directory using a unique file name starting with "desksrv...". Since the files on the CD-ROM almost certainly have no resource forks in this case, the Finder will use the information that are available in the extension mapping table or show one of the about 20 generic EtherShare icons.
10.3 Parameters of the "rebuild" program
When it starts, the "rebuild" program first accesses the main configuration file "atalk.conf" to determine its configuration. The "install" program automatically sets up this file with initial values for some of the EtherShare servers. The values can be changed if necessary by using an editor such as vi. See also chapter
5.14 "Editing "atalk.conf" (and other configuration files) manually".
The parameter described below can be defined for "rebuild" in "atalk.conf" (note that the parameter list is preceded by the program name "rebuild:"):
The
cleanorphans switch for the "rebuild" program in "atalk.conf" causes resource orphans to be deleted each time a desktop rebuild takes place (see
Resource orphans in chapter
10.2 "The Desktop Server Program"). This operation requires a certain amount of processing time.
The default for this switch is
cleanorphans.
The
twopass parameter induces the "rebuild" program to run 2 times: in the first session, "rebuild" tries to restore all already-known IDs on the volume and makes records of all conflicts. In the second session, all those files which have caused conflicts are allocated a new ID.
The default for this switch is
twopass.
10.3.1 "rebuild" error messages
The following error messages can be issued by the "rebuild" program:
This is a warning which indicates that some resource information, e.g. icon information, cannot be uncompressed. This could happen e.g. with fonts that have a custom icon:
rebuild[]: /apple2/FremdeSchriften/Fre:a7Schriften/
Helvetica Neu(L63-65,185)/HelveNeuLigCon:
unable to add to desktop, compressed resources
volume %s is currently in use, no exclusive access possible
Someone is already using the volume, i.e. you cannot access exclusively with the
rebuild -x switch.
charset %s for volume %s not found (%s)
This error message leads to a fatal error; the "rebuild" program is stopped.
volume is already using the selected charset, nothing to convert
The current character set was selected anew.
You cannot apply any changes since there is no write access to the volume, e.g. a CD-ROM volume.
10.4 Parameters of the "desksrv" program
When it starts, the Desktop Server program "desksrv" first accesses the main configuration file "atalk.conf" to determine its configuration. The "install" program automatically sets up this file with initial values for some of the EtherShare servers. The values can be changed if necessary by using an editor such as vi. See also chapter
5.14 "Editing "atalk.conf" (and other configuration files) manually".
The parameter described below can be defined for "desksrv" in "atalk.conf" (note that the parameter list is preceded by the program name "desksrv:"):
number is the maximum number of network volumes that can be opened by Macintosh users on the File Server simultaneously.
The default for
number is 128 volumes. Each open volume is only counted once, even if it has been opened by more than one user. The absolute maximum value is 450, but the achievable maximum may be limited by the maximum number of open files for the "desksrv" process allowed by the host. This limit is normally set by "desksrv" for itself automatically. In case of problems, refer to "limit" and "ulimit" in your UNIX documentation for details about how to increase the limit manually for your host.
10.4.1 "desksrv" error and status messages
Although there is a large number of possible messages from "desksrv", we will only describe a few of the more common messages here because the majority of them are non-fatal and simply result in an automatic desktop rebuild. Fatal errors result in "desksrv" stopping, in which case you will see the message "desksrv: stopped".
All messages are written to the system messages file (which can be accessed via the
Lists menu of the EtherShare Admin) and are preceded by the host name, time and date, and the string "desksrv:". If the Desktop Server triggers a desktop rebuild, or if you call the rebuild program manually from a UNIX shell, the message will include the string "rebuild:" instead.
The desktop file is corrupted and will be rebuilt automatically.
unknown file type on open (maybe wrong byte order)
The ".Desktop" file is not a valid desktop, e.g. the desktop file is in Intel byte order and should be in Motorola byte order, or vice versa; it will be rebuilt automatically.
read failed, or write failed
These messages are usually related to volumes mounted over NFS, and point to NFS communications errors.
creation error, too many open files on volume...
"desksrv" has attempted to open more files than the maximum number allowed by your host. The limit is normally set by "desksrv" for itself automatically. Refer to "limit" and "ulimit" in your UNIX documentation for details about how to increase the limit manually for your host.
Macintosh users have attempted to mount more volumes than the presently configured maximum number for the desktop server. Please refer to the description of the
maxdesktop parameter in this chapter for more details. This message is usually associated with a Macintosh Finder error message similar to the following: "the connection could not be made to file server <name> - please contact your system administrator".
no response from host <hostname>
If you access volumes on another EtherShare host through NFS, and the remote ".Desktop" file seems to be already in access, queries will be sent to the remote host's File Server and Desktop Server to check whether they are really in use. The remote ".Desktop" file will not be accessed directly. You will get the "no response..." error message if the remote host does not respond to queries after a suitable timeout. In such cases, the local Desktop Server will take control of the remote ".Desktop" file and rebuild it if necessary.
A message like
desksrv [] : nested desktop
[/data/opi/OPI1] in [/data/opi/.Desktop] indicates that there are overlapping volumes. The message pops up when you try to mount a volume that has a ".Desktop" file in its parent directory.
If you create a file with a too long file name under UNIX, using the Desktop Utilities, "opisrv", or the EtherShare OPI "layout" program which will try to add this file to the desktop, you will receive an error message similar to those listed in the examples below:
desksrv[]: AddId - name too long
opisrv[]: Warning: /apple1/software/Wilhelm Kaiser/Kaiser/R&R-Beilage 8 Seiten, 41 KW/Bilder 41 KW/8 S. Abb. 6 Gianna Nannini.eps.lay: Path too long. This file may not be accessed from a Macintosh workstation.
10.5 "afpsrv" and "desksrv" coordination
"afpsrv" will try 6 times for 5 seconds each to reach the desktop server to retrieve or store information from/to the desktop database of its volumes. Earlier versions of "afpsrv" tried 3 times for 5 seconds. Although even the older values were a very long time for network or RPC connections, we decided to even extend these values.
If "afpsrv" does not get a response from "desksrv" during this period, this indicates a severe problem with the underlying UNIX operating system, UNIX file system or RAID/HSM drivers, or a hardware problem related to SCSI or hard disks.
To prevent inconsistencies between information stored in the desktop databases of an EtherShare volume and the files/folders on this volume, the "afpsrv" client process encountering this timeout will secure this volume (all mounted volumes) against write access. Opening folders and reading files will still be possible, but creating/renaming/ moving files or folders will not be possible any longer. Not even trashing files/folders will be allowed.
Apart from the usual messages issued in the UNIX system error log, "afpsrv" will issue an error message on the client if the communication to "desksrv" fails and inform users that the volume falls back to "read-only" access. The message is:
Volname: localhost: RPC: Timed out
Only readonly access possible
Under certain conditions, an additional error message is issued and the volume is unmounted automatically by the Finder.
Though this message is issued by one "afpsrv" client process only, it is likely that all other "afpsrv" processes may encounter the same problem and therefore, the UNIX system administrator should be notified immediately.
Since applications usually work with temporary files/folders, it may not be possible to save single files. If this problem was only temporary, unmounting all EtherShare volumes and remounting them will make these volumes writable again. If not, this was no temporary problem and is not solved in the meantime the Macintosh volume Chooser will list all volumes grayed out, and no volume will be mountable. Not even "root" will be able to mount any of these volumes.
Depending on the severity of the problem, it may be necessary to stop and restart EtherShare services on the server by using the scripts "$ESDIR/stop-atalk now" followed by "$ESDIR/start-atalk".
Assure that the cause of this problem is solved before restarting EtherShare services.
