HELIOS Base addendum


1 dt tools
1.1 Command descriptions

1.2 Additional information

1.3 Using "dt" for backup/restore



About the product
This chapter describes the "dt tools", which mimic the functionality of most major UNIX commands for handling files, while maintaining the integrity of the desktop database. "dt tools" also provide access to Mac specific file information and streams from a UNIX prompt.

Important: The "dt" program does not consider any file locking and can therefore also copy files in use. In order to avoid damage, consider this and make sure nobody is working concurrently on these particular files before manipulating them with "dt".

Why do I need the "dt tools"?
If you need to access files which are stored in a HELIOS volume via host scripts or commands, there are a lot of reasons for using the "dt tools".

Note: Host commands means any access under UNIX, e.g. any script or program (like a backup program), which accesses files stored in a HELIOS volume.

Any manipulation of a file or folder inside a HELIOS volume using ordinary UNIX commands like "cp", "mv", "rm" or other programs, will cause inconsistencies between volume information and the related desktop database, and you may lose addtional data, e.g. file streams. Especially restoring files from a backup will cause such an inconsistency.
In the following sections, you will find more information on this problem, and on how the "dt tools" help avoid it.
NTFS file streams support
Files and directories in the Windows/NTFS environment may have a certain number of file streams. File streams contain meta data such as document title, subject, author, etc., similar to the resource fork of a Mac file.
The "dt tools" can handle Windows NTFS file streams. While accessing a file on the network that has been created in the Windows/NTFS environment, e.g. renaming or moving it on a HELIOS server, all pertinent file streams are considered as well.
Also, file attributes such as Archive, Hidden, System, Creation date, label settings, etc. are also preserved when using the "dt tools". In addition, a fast file search can be performed via the desktop database, with file ID support.
Use the utilities whenever you would (usually) use any of the following UNIX commands (if either source and/or destination files/folders are located in a HELIOS volume):
You may use the "dt tools" even if the source or destination is not located in a HELIOS volume, or if you are not sure about this. The "dt tools" automatically select the proper mode of operation, e.g. if source and destination are no volumes "dt" acts exactly like the corresponding UNIX program.
It is required to use the "dt tools" together with EtherShare, PCShare and/or ImageServer. These HELIOS products have improved verification mechanisms to recognize potentially harmful configurations, and will disable access to volumes for which consistency between volume and desktop information cannot be assured. In addition, warning or error messages are logged to the system error log file, which may help you locate the cause of the problem.
What are the differences to standard UNIX
commands?
Just to help you understand the possible error messages and the specific behavior of the "dt tools", here are the main differences to standard UNIX commands:
Before you try and use any of the "dt" commands, you should be well familiar with the corresponding UNIX commands. If you need more information about how the "dt tools" work and how problems arise without the utilities, please read the "Technical notes" following each command description, and 1.2 "Additional information".
How to install the "dt tools"
The "dt tools" do not require a special installation procedure.
We do not recommend to sym-link regular "cp", "mv", "rm" commands to the "dt tools". Although this is possible, you should verify your current and future system environment very carefully, to assure proper operation of your programs, scripts and established workflow.
Especially, you should check whether your site uses special HSM (Hierarchical Storage Management), tape robot, or RAID (Redundant Array of Independent Disks) software which may also use their own versions of these UNIX commands. Take into account that different users and script based programs may make use of different shells and environment settings.
Before getting started-
We suggest to check for each HELIOS volume the consistency between the volume information and the volume's desktop database. HELIOS Base offers a rebuild option, namely -s (scan only), which can be used for this purpose (see chapter 7.10 "rebuild" in the Base manual).
Simply issue rebuild -s <volume mount point> for every defined public or private HELIOS volume. Any output of this "scan" indicates a potentially harmful inconsistency between volume and desktop information. You should only continue after having re-synchronized the desktop database by means of an ordinary rebuild.
Take some time to make yourself familiar with the utilities and the way they behave inside a HELIOS volume, between different HELIOS volumes, and between non-HELIOS and HELIOS volumes.
Notes about error messages
The "dt tools" use standard error messages starting with the program name (including the command argument), followed by the file or directory currently processed, and the error message, e.g.:
dt rm notHere may result in the error message:
dt rm: notHere: no such file or directory
The error messages used are similar to the errors issued by the standard UNIX commands. Please note that you may encounter additional error messages regarding resource fork, streams, or desktop database.
In some cases the "dt tools" may issue error messages displaying the full path of a file name instead of the passed relative one. This is due to the fact that the desktop database always needs absolute file names instead of relative ones. In this case, you may see the completely resolved (including symbolic links) absolute path name in the error message.
1.1 Command descriptions
General remarks
For the following command descriptions, the knowledge of the functionality of the corresponding UNIX commands is assumed. Please refer to your UNIX manual if you are not familiar with the commands.
If you do not need or want to know, how the "dt tools" operate, you only need to read the main command description for each UNIX command which is emulated by the "dt tools". The technical description following each command is meant for advanced users or system administrators, and explains some details or the special behavior of the respective command.
With very few exceptions, "dt" behaves identically on all platforms supported by HELIOS. Please note that, for this reason, some platform-specific options could not be implemented.
For all commands, the standard UNIX permissions apply when accessing, removing, or overwriting a file.
"dt" checks each passed argument for the following names:
.Desktop
.DeskServer
.rsrc
These files are handled implicitly by "dt" and there is no need to specify them directly. You should never move, copy, or remove these files with other commands, as e.g. the standard UNIX tools. Do not manipulate them at all.

Note: In the following, the term "volume" is used for a directory that is defined as a HELIOS volume which contains a desktop database (in contrast to a simple UNIX "directory"). Likewise, the term "volume root" referes to the top level folder of a HELIOS volume. The "HELIOS Applications" volume, for example, is by default defined to reside in "/usr/local/helios/public", which is its "volume root" directory under UNIX.

"dt" will recognize a HELIOS volume by locating its desktop database ".Desktop" file.
"dt" will recognize access to HELIOS volumes from another server only by means of available ".DeskServer" files.
"dt" will process data, resource and file stream parts of files/folders in HELIOS volumes. If no resource information exists, "dt" will be able to create at least minimum information. Especially copy or move operations may require more free space on destination file systems.
The following command modes are supported:
rm Remove a file or directory (UNIX "rm").
rmdir Remove directory (if empty) (UNIX "rmdir").
mv Move/rename a file or directory (UNIX "mv").
cp Copy a file or directory (UNIX "cp").
set Set or change the Mac or Windows
specific file attributes.
ls List contents of a directory including Mac
or Windows specific file attributes (UNIX "ls").
mkdir Create a directory (UNIX "mkdir").
touch Create a file or set its access time (UNIX
"touch").
upd Force update of HELIOS volume view.
chmod Change or assign the mode of a file (UNIX
"chmod").
chown/ Set the user and group ID of a file
chgrp (UNIX "chown", "chgrp").
idinfo Display database information for the passed ID.
iddump Display database information of all IDs for the
passed volume.
dt
If called without any argument, "dt" prints the usage line:
Usage: dt { rm | rmdir | mv | cp | set | ls | mkdir | touch | upd | chmod | chown | chgrp | idinfo | iddump }
Calling "dt" with the command argument but no further arguments, prints the usage for the specific command.
Many "dt tools" support the new options:
-X = Suppress desktop close delay
-y = Force scanning for streams
-E = Send events to notification server:
Suppress desktop close delay
(-X option) Usually, the desktop of a volume is kept open for about 30 sec. when being used by "dt" in order to avoid overhead (desktop database completely open/closed). This is because further access is to be expected. However, for certain applications it is not advisable to block the desktop for a volume that long. Hence, with the -X option set, the desktop is closed immediately.
Force scanning for streams
(-y option) Force scanning for streams that are not specified in the resource information of a file. If additional streams exist for a file but the file information is not marked for streams, this option checks the entire ".rsrc" directory if streams are detected for the current file. To avoid unnecessary search operations, the standard resource is marked if additional streams are available.
Send events to notification server
(-E option) If this option is specified, file events for all registered services are notified to the notification server.
dt rm
The "dt rm" command removes the directory entry specified by each file argument.
Usage:
dt rm [-firyXE] file
Options:
-f Force removing without prompting the user.
-i Prompt for confirmation for each file. If the
answer begins with
y (yes), the file is deleted,
otherwise the file remains on the server.

-r Recursively remove passed directory and its
subdirectories.

-y Force scanning for streams.
-X Suppress desktop close delay.
-E Send events to notification server.
In case of symbolic links, the link itself and not the file which the link refers to is removed.
If the standard input is not a terminal, the command will operate as if the -f option was set.
Example:
dt rm a.out core
removes the directory entries: "a.out" and "core".
dt rm -rf junk
removes the directory junk and all its contents, without prompting.

Note: Missing resource forks are not reported unless the -v verbose option is set.

The volume root directory is automatically touched to announce the changes to any Mac that has mounted the volume.

When removing a directory using the -r option, "dt" automatically tries to remove any orphan resource forks or file streams. The volume root directory may only be removed if this volume is not in use by any other client, either EtherShare, PCShare, WebShare or the "dt tools", otherwise a "directory not empty" error is issued.

dt rmdir
The "dt rmdir" command will remove the directory entry specified by each dirname operand, provided that this operand refers to an empty directory.
Usage:
dt rmdir [-psyXE] dirname
Options:
-p Allow users to remove the directory dirname and
its parent directories which become empty. A
message is printed on the standard error about
whether the whole path is removed or part of the
path remains for some reason.

-s Suppress the message printed on the standard
error when
-p is in effect.
-y Force scanning for streams.
-X Suppress desktop close delay.
-E Send events to notification server.
dt mv
"dt mv" moves the selected files or directories to a destination file or directory.
Usage:
dt mv [-fiknvzcyXE] f1 f2
dt mv [-fiknvzcyXE] f1 ... fn d1
dt mv [-fiknvzcyXE] d1 d2
The three different usages are provided for the following cases:
Options:
-f Move the file(s) without prompting even if it is
overwriting an existing target. Note that this is
the default if the standard input is not a terminal.

-i Prompt for confirmation for each file. If the
answer begins with y (yes), the file is moved,
otherwise it remains where it is.

-k Keep ID, try to allocate the source ID and use it
for the destination as well (see
1.3 "Using "dt" for backup/restore"). In case
this is impossible, you will only get a warning
if
-v is set. You can use this parameter to
preserve proper working of Mac aliases.

-n No resource forks if no desktop (see
Default resource fork handling).

-v Verbose, display extended warnings.
-z Force zero ID for destination, please refer to
Zero IDs and
1.3 "Using "dt" for backup/restore".

-c Move a file from one HELIOS volume to another
HELIOS volume with a different character set
without converting to the target volume
character set or reporting error messages.

Important: If you do not use the -c option with the "dt mv" and "dt cp" commands, an error message only occurs if you copy/move files from a HELIOS volume to another. Copying/moving from a UNIX directory will not provoke any warning at all.

-y Force scanning for streams.
-X Suppress desktop close delay.
-E Send events to notification server
The behavior of the different UNIX implementations differs if both the -f option and the -i option are set. "dt mv" uses the following rule: if both the -f option and the -i option are set, this is not considered an error; here, the -f option will override the -i option.

Important: If you move a directory between HELIOS volumes, "dt" cannot simply rename just the directory entry. Here, the Mac Finder would have to perform two steps for this operation, namely copying a folder from one volume to the other and then deleting the folder on the source volume. "dt" has a similar task to accomplish. For every file and folder within the directory to move, first the object must be copied to the destination volume and registered in the destination desktop. Then, the moved objects must be deleted from the source volume and unregistered from its desktop database.
This is similar to moving a UNIX directory to a different device, where also all affected files must be copied and then deleted, with the difference that here all resources and streams must be handled, too.

Please note that any Mac file/folder to which aliases are pointing will have lost its connection after successfully been moved between volumes. This would be the same if you used the Mac Finder for this operation. If source and target directory are on different file systems, "dt mv" copies the file and deletes the original; any hard links to other files are lost.
Volume root for both source and destination, is automatically touched to announce the changes to any Mac that has mounted the volume.
Usually, if a file is copied to a directory without a desktop (pure UNIX directory), the file ID is set to zero. When using the -k option, the file ID is maintained (if possible).
dt cp
"dt cp" copies the passed files or directories to a destination file or directory.
Usage:
dt cp [-fikpnvzcyRXE] f1 f2
dt cp [-fikpnvzcyRXE] f1 ... fn d1
dt cp -r [-fikpnvzcyRXE] d1 ... dn-1 dn
The three different usages are provided for the following cases:
Options:
-f Copy the file without prompting even if it is
overwriting an existing target. Note that this is
the default if the standard input is not a terminal.

-i Prompt for confirmation for each file. If the
answer begins with
y (yes), the file is copied,
otherwise it is not.

-k Try to keep desktop ID.
-r Recursively copy passed directory (see -R).
-p Preserve the owner and group IDs, permission
modes, modification and access time.

-n No resource forks if no desktop (see
Default resource fork handling).

-v Verbose, display extended warnings.
-z Force zero ID for destination, please refer to
Zero IDs and
1.3 "Using "dt" for backup/restore".

-c Copy a file from one HELIOS volume to another
HELIOS volume with a different character set
without converting to the target volume
character set or reporting error messages.

-y Force scanning for streams.
-R Recursively copy passed directory while
preserving symbolic links (see
-r).
-X Suppress desktop close delay.
-E Send events to notification server.
The volume root directory for both source and destination, is automatically touched to announce the changes to any Mac that has mounted the volume.
If your source does not have a resource fork, and your destination is a volume, a default resource fork is created. Please do also take into account that every default resource will require 64 bytes, thus using the minimum disk block size on the destination file system. If there is only little free disk space on the destination volume, first check whether the destination file system can store all of the files. You can roughly calculate 1K (fragment size) per file/folder. Consult your UNIX system administrator or the appropriate pages in your UNIX manual for information on how to retrieve more exact information about your file system settings.
dt set
"dt set" modifies the additional file information stored in the file's resource fork. For more information about the flags and fields used here refer to your Mac documentation.
You can use HELIOS Admin to extract the creator/type information an application sets for certain icons. For a description see "Extension Mappings" in the EtherShare manual and the content of "HELIOSDIR/var/conf/suffixes".
Usage:
dt set    [-t type | -c creator | -f file ] file ...
dt set -l label color (0-7) file ...
dt set -v [mini|symbol|name|date|size|type|label|button] dir ...
dt set -a [-][BisrlbpIPS] file ...
dt set -L launchcount file ...
dt set -C file ...
Options:
-t Set the file type for "file" to the passed value.
-c Set the file creator for "file" to the passed
value.

-f Copy file type and creator from "sfile" to "file".
-l Set label color (integer values 0-7).
-v Flag which specifies one of the following
Mac view modes for a folder:
mini symbol name date size type label button
-a Flag which specifies the following modes:
Mac Windows
B bundle
i invisible Hidden
S system System
r readonly Read-Only
l locked (norename,
        nodelete)
b backup
p protected
I inited
P package
s shared
-L Set the file to number of allowed concurrent
program launches, where "integer" is the
number of launches.

-C Clear the file ID numbers in the resource
fork (set to zero) and force the "afpsrv" to
allocate new ID numbers.

Please note that you may list these information using
"dt ls". If you need to set type or creator info with non-printable values, you may as well enter these values as octal values with a preceding backslash ("\"), and use the following escape sequences:
\b backspace
\n newline
\r carriage-return
\t tab
\f form-feed
\E escape
Please note that for both type and creator, all characters including 0 are valid. Each passed creator or type must be exactly 4 bytes long.
Examples:
dt set -t "TEXT" -c "R*ch" file
sets type and creator for file using ASCII values.
dt set -c "\001\002\003\004" file
sets creator for file using octal values.
dt set -f mypic file
copies type and creator from mypic to file.
dt set -ai file
sets the invisible flag for file.
dt set -a-i file
clears the invisible flag for file.
When you call "dt set" for a file without a resource fork, a default resource fork is created that is updated with the passed parameters, even if the destination file is not located in a HELIOS volume.
Please note that "dt set" does not create a missing ".rsrc" directory; use "dt touch" first on the file name in order to force creation of a related ".rsrc" subdirectory where the file's resource information can be stored.
dt ls
For each file that is a directory, the directory content is listed; for each file that is an ordinary file, the name and (optional) resource related information are listed. When no argument is given, the current directory is listed.
Usage:
dt ls [-1FSUacdilmnprstux] { -e [STacdfiopstxy] } file ...
Options:
-1 List one file per line.
-F Append indicator [*/=@|] to names.
-S Sort by file size.
-U Do not sort - list entries in directory order.
-a List all entries, including those beginning with a
dot character ("."), which are normally not listed.

-c Show and sort by ctime (last modification of file
status).
-d Show directory itself instead of contents.
-i Print inode number for each file.
-l Long listing (flags, link count, user, group, size,
date, name).
-m Comma separated list of entries.
-n Like -l, but list numeric UIDs and GIDs.
-p Append indicator [/=@|] to names.
-r Reverse sorting order.
-s Print size of each file as block count.
-t Sort by modification time.
-u Show and sort by last access time.
-x Show entries by lines instead of by columns.
Extended flags (must be called with the -e flag):
-S Show resource file and streams for each entry.
-T Show resource creation time.
-a Yields the same output as -e cfit.
-c Show resource creator.
-d Show resource file name instead of UNIX name.
-f Show resource flags.
d:directory
A:alias

Note: Mac aliases cannot be created with the "dt tools". The internal structure of aliases is not documented by Apple.

B:bundle
P:package
i:invisible
s:system
r:readonly
l:locked
b:backup
p:protected
I:inited
S:shared
-i Show desktop ID.
-o Show nonprintable type and creator characters
octal.
-p Show desktop parent ID.
-s Show combined resource and streams size.
-t Show resource type.
-x List nonprintable type and creator characters
hexadecimal.
-y Force scanning for streams.
Examples:
dt ls /support/temp
abc.mov
This command prints the names of all files in the passed directory "/support/temp".
Sometimes you may wish to include more resource and stream specific information:
dt ls -l -ea /support/temp
-rw-rw-rw- 1 -----r--p-- 5 'MooV' 'TVOD' jon admin 21988 Jan 5 2005 9:34 abc.mov
This command prints the file mode (read-write access for owner, group, and others), the number of links (1), Finder attributes (read-only, protected), Desktop ID (5), type and creator (MooV, TVOD), user (Jon), group (admin), size (21988 bytes), date and file name (abc.mov).
Please note that the output format (e.g. time format) depends on the current settings for the local environment.
"dt ls" uses user and group information from the authentication server (if running), otherwise only UNIX users/ groups are displayed.
dt mkdir
The "dt mkdir" command creates the passed directories including the corresponding resource fork and the desktop database entry.
Usage:
dt mkdir [-m mode] [-pyXE] dir ...
Options:
-m mode Specify the mode to be used when
creating the directory.

-p This option creates "dir" by creating
all the non-existing parent directories first. The
mode given to intermediate directories will be
the difference between 777 and the bits set in
"umask".

-y Force scanning for streams.
-X Suppress desktop close delay.
-E Send events to notification server.
Example:
dt mkdir -m 0444 mydir
creates the directory "mydir" with the passed modes.

Note: If no mode parameter is set, the final directory is created in octal mode 0777 considering the file mode creation mask "umask".

dt touch
The command "touch" sets the access and modification times for the passed files. A file is created if it does not already exist.
Usage:
dt touch [-XE] file ...
Option:
-X Suppress desktop close delay.
-E Send events to notification server.
Example:
dt touch myfile
dt upd
The "upd" command touches the volume directory for the passed file or directory, so that all Macs that have mounted this volume can display the changes. This may be necessary e.g. if a file is created under UNIX and the Mac would display the new icon only after closing and re-opening the corresponding window.
Please note that all "dt" commands automatically update any needed volumes; so this command is only required, if files are created or changed by other, non-"dt" commands. Check if you can adjust your workflow to "dt" commands and thus avoid potentially harmful non-"dt" commands.
Usage:
dt upd [-X] file ... | dir ...
Option:
-X Suppress desktop close delay.
Example:
dt upd myfile

Note: Mac clients only scan for changes every 10 seconds. Usually, folder information are updated within this 10 seconds period. However, depending on folder sizes, number of folders open, foreground applications, etc., this may take longer. Thus, it may take some time after issuing an "upd" command, before the changes become visible on the client. You can either click into the folder window, or close and re-open it in case the displayed information do not seem to be up-to-date. In rare situations, it may be necessary to unmount and remount the volume in question in order to let the Mac flush its cache entries. Make sure that you are using the latest Mac OS and up-to-date AppleTalk/Network drivers.

dt chmod
The "chmod" command changes the permission mode of a file. The mode may be absolute or symbolic.
Usage:
dt chmod [-fRXy] absMode file ...
dt chmod [-fRXy] [ugoa]{+|-|=}[rwxstugo] file ...
Options:
-f Force, do not complain if the mode change fails.
-R Recursively descend through directory
arguments.

-X Suppress desktop close delay.
-y Force scanning for streams.
An absolute mode is specified using octal numbers (0-7), please see the UNIX documentation for a full description.
A symbolic mode specification is a comma-separated list (without any intervening spaces) of symbolic mode expressions of the form:
[who] operator [permissions]
In order to adjust permissions for files/directories and their related resource parts, you must own the directory in question. In case the resource directory does not match the enclosing directory's permissions, "dt chmod" cannot adjust the ".rsrc" directory's permissions. You have to log in as "root" in order to synchronize permissions of the two directories. Please refer to the UNIX documentation for a full description.
Example:
dt chmod 444 file
sets only read permission (0444) to "file".
dt chmod a=rwx,g+s file
sets read ("r"), write ("w"), and execution ("x") permission for all ("a") users, and adds group set-ID mode ("s") for groups' permissions.
dt chown
The "chown" command sets the user ID of the passed file to the new user ID specified by owner, and, optionally, the group ID to the new group.
Usage:
dt chown [-fhRXy] owner[:group] file ...
Options:
-f Do not report errors.
-h If the file is a symbolic link, change the owner of
the symbolic link (not the owner of the file that is
referenced by the symbolic link). This option is
not supported on all platforms.

-R Recursively descend through the directory when
setting the ownership for each file.

-X Suppress desktop close delay.
-y Force scanning for streams.
owner[:group] (use "." or ":")
A user ID and an optional group ID to be assigned. Both IDs may either be specified by the numeric ID or by the corresponding user or group name.
Please note that you need the necessary access rights to change the user or group ID of a file - according to UNIX semantics, only the user id "root" is allowed to change ownership settings.
Example:
dt chown frank:support myfile
changes the owner for myfile to "frank", and the group to "support".
dt chown 100 myfile
changes the owner for myfile to the user defined with the
ID 100.

Important: If the user specified with the "dt chown" command has never been validated by the HELIOS authentication server, it issues the "User not validated" error message. However, all regular UNIX users, e.g. "nobody", "root" are automatically validated.

"dt chown" uses user and group information from the authentication server (if running), otherwise oonly UNIX users/ groups are displayed.
dt chgrp
The "chgrp" command sets the group ID of a given file to that of the new group.
Usage:
dt chgrp [-fhRXy] group file ...
Options:
-f Do not report errors.
-h If the file is a symbolic link, change the group of
the symbolic link (not the group of the file that is
referenced by the symbolic link). This option is
not supported on all platforms.

-R Recursively descend through the directory when
setting the group for each file.

-X Suppress desktop close delay.
-y Force scanning for streams.
A group ID may either be specified by the numeric ID or by the corresponding group name.
Please note that you need the necessary access rights to change the group ID of a file - according to UNIX semantics, only the user id "root" is allowed to change ownership settings.
Examples:
dt chgrp support myfile
changes the group to "support".
dt chgrp 100 myfile
changes the group for myfile to the group defined with the ID 100.
"dt chgrp" uses user and group information from the authentication server (if running), otherwise oonly UNIX users/ groups are displayed.
dt idinfo
The main purpose of this command is problem detecting. The Mac file, or respectively directory ID, is stored in both the file's resource fork and the desktop database. The ID stored in the resource fork may be listed by using the "dt ls" command.
The "idinfo" command may be used to display database information for the passed ID. If there is no difference between the resource data and the corresponding database entry, you should get the same information, otherwise the system administrator should issue a "rebuild" for the specific volume. You can use rebuild -s <volume root> to verify that the volume information is properly reflected in the related desktop database.
Usage:
dt idinfo [-v volume] [-X] id ...
Options:
-v Allows to specify the volume to be used, or any
file or directory inside the target volume.

Note: Each volume has its own ID scope. Therefore, you must specify the correct volume for each ID you request. If you do not specify a volume with the -v option, the current working directory is assumed.

-X Suppress desktop close delay.
Examples:
dt idinfo -v /support 3159
prints the following information:
volume: '/support' id=3159 pid=2 name: 'temp'
specifying the volume detected, the ID, the parent ID for this file, and the corresponding name stored in the database.

Note: Please note that an ID detected in the database that does not have any corresponding file in that volume does not cause any problems or data loss.

dt iddump
Each Mac file on a HELIOS volume has an ID number that is stored in both its resource fork and the desktop database. The "dt iddump" command outputs all file IDs of the volume in question (specify volume path) from the desktop database to "stdout".
Usage:
dt iddump [-X] volume
Option:
-X Suppress desktop close delay.
1.2 Additional information
The information in this section are mainly meant for system administrators who want to integrate the "dt tools" into custom solutions, e.g. backup scripts. You do not need these information for the simple use of the "dt tools" (however, it does not hurt to read on).
Mac files under UNIX
Each HELIOS volume is accompanied by a corresponding desktop database, which holds additional information about each file or directory stored in this volume.
Each file, directory or stream in a HELIOS volume consists of two parts: the "data fork" and the "resource fork".
Though invisible to the Mac user, both parts of a file and the corresponding information in the desktop database are handled transparently and automatically by EtherShare. On Windows, a file consists of a long number of additional streams (but no desktop database info).
If you also use ImageServer and/or PCShare these HELIOS products will also coordinate access to shared files/folders with the HELIOS volume desktop databases, and handle the resources and streams.
Looking at a volume from the UNIX point of view, you will find two files: the data fork as the "normal" UNIX file, and the resource fork in a subdirectory ".rsrc" with the same name, and all corresponding streams.
You will find more information about this in "Directory and file formats" in the EtherShare manual.
Default resource fork handling
Since UNIX files consist of only one part, but Mac files of two (see Mac files under UNIX), each pure UNIX directory ("UNIX-dir") should only have entries without a corresponding resource fork, and in a HELIOS volume ("volume-dir") each entry should have a corresponding resource fork and streams.
If you now copy or move an entry from a "UNIX-dir" into a "volume-dir", "dt" always creates a default resource for this file. This is also the default behavior, if you move or copy a file from one "volume-dir" to the other.
If you copy an entry from a "volume-dir" into a "UNIX-dir", "dt" copies or moves the resource fork and streams as well, even if the resource fork is not needed here. This is done in order to avoid any unintentional data loss. If you do not want to consider the resource forks here, you may use the -n option for the "mv" or "cp" command.
Local and remote desktops
The "dt tools" do not require the desktop server to run on the UNIX server where you issue the commands, but by default the "dt tools" try to connect to the local desktop server on the server where you issue the commands first.
If this volume is already in use (e.g. mounted as a volume on a Mac) the "dt tools" try to connect to the current server which serves this volume. This could be a different server, e.g. if this volume is mounted via NFS. Source and destination are handled completely independently, e.g. a source file for a copy command may be served by a local desktop server, while the destination directory which is located in a NFS-mounted directory is served by another HELIOS desktop server.
The "dt tools" are unable to connect to a desktop server, when the target directory is not mounted by any Mac and no local desktop server is running. In this case start a local desktop server or mount this volume on a Mac.
The "dt tools" will do an extensive verification in order to connect to the proper desktop server. Nevertheless, please verify your environment so that no single HELIOS volume can be accessed at the same time from different HELIOS servers.

Note: In case of different desktop servers being involved in a "move directory" operation, it may be necessary to traverse through directories instead of just moving the directory entry - see dt mv for details.

Mount points and auto-mounter
Double mounts (access to the same directory under different mount points, e.g.:
mount myserver:/usr/es /es
mount myserver:/usr/es /home/user1/es_copy)
This will lead to differences between volume and desktop information, resulting in inconsistencies.
Please note that you may unintentionally cause this problem by accessing an already mounted volume via auto-mounter:
dt cp /net/myserver/usr/etherhare/file1 file2
You may avoid this problem by running auto-mounter on any involved server (source and destination).
Zero IDs
On any mounted volume, the HELIOS file servers automatically detect any file which has an accompanying resource fork with a zero ID (the ID set to numerical zero) when the parent directory is opened from a Mac.
A file without a valid ID does not have any database entry, and therefore, a new desktop database entry is created, and the resource fork is updated using the new ID.
The "dt tools" never create zero ID resource forks in volumes unless you force this behavior using the -z flag for the "cp" and "mv" commands.

Important: This option should only be used by system administrators - it is not intended for normal use.

1.3 Using "dt" for backup/restore
One main purpose of the "dt tools" is to avoid problems when restoring data from a backup device. Here we describe how you should use the "dt tools" for backup/restore purposes:
Backup
You may backup your data as usual directly from your volume. Please make sure that the hidden ".rsrc" directories are included. To prevent backup of incomplete data in files, make sure that the files/folders to be backed up will not be manipulated from other Mac or UNIX applications. Only if you intend to do a complete backup and restore of a HELIOS volume you might include the ".Desktop" file. For the period of time you need to backup and restore this volume, HELIOS must be stopped with "stop-helios".

Important: Do never restore your data directly into the destination volume!

Restore
Please create a restore directory on the same device (partition) where the destination volume resides, e.g. if you intend to restore files into e.g "/data/mypics", create a directory "/data/restore". This "restore" directory must not be defined as a volume, or even being mounted. Now restore your data using your usual restore procedure into this newly created directory "restore". Make sure that you do not restore the ".Desktop" and ".DeskServer" files.

Important: Do never remove these files (".Desktop" and ".DeskServer") from a mounted volume or manipulate them directly. This may cause not only data loss for this volume, but may cause problems for all defined volumes on the server. In case you want to backup/restore these files, make sure that EtherShare and PCShare (if you are sharing volumes) are stopped completely prior to your backup/restore operation. Only if you stop HELIOS by means of "stop-helios" and stop access from other HELIOS servers, intermediate access to these files from HELIOS processes can be prevented.

Finally move the restored files into their final destination. This procedure avoids any data loss and may be used in a mounted destination volume.
Usually, new (unused) file IDs are assigned when you copy files to a backup destination. It may, however, be sensible to keep the file ID (using the -k option). Thus, the file can be re-used with its original ID. This is especially useful if you are using Mac aliases pointing to these files/folders. You should use this option sensibly. In case a complete desktop rebuild has been conducted after your backup operation, aliases may point to the wrong destination.
To avoid any problems, it may be a good idea to run an integrity check for the destination volume by entering rebuild -s on the command line, before restoring any files.


© 2006 HELIOS Software GmbH