usage: scdbackup_askme infosource [options|searchtexts] This program reads information about a backup created by scdbackup. It then allows to query those informations and eventually assists in restoring files from backup to disk. Information source may be one of the following: * a backup configuration directory containing files ./highest_level , ./level_*/content_file_list.gz , ./level_*/vanished_file_list.gz and ./level_*/complete_dir_list.gz . * a set of media containing directory ./added_by_scdbackup with files content_file_list.gz , vanished_file_list.gz and complete_dir_list.gz . The media get prompted. * a file created by scdbackup option -content_list_adr or -complete_list_adr. * an ASKME script together with eventually available ASKME_level_* from the same directory which represent older levels of the backup. General options (search and restore options are listed separately): -help prints this text -hilfe gibt diesen Text in deutscher Sprache aus (prints this text in german language) -fat_tree loads as much file attributes as possible. This doubles or triples memory consumption. Works only as program argument but not in dialog or from file. -id prints a message about this backup -count prints the number of volumes -list prints the parts and their items. With -fat_tree: level sizes. -list:# prints a single part (e.g. -list:3) -statistics[:"long"|:levelnumber] show statistics about whole backup or about a single level. "long" shows all levels in detail. A level is reported by three lines. They describe the content of the level, the already deleted files among this content, and the already replaced files. -levelall lookup all levels (else: show only youngest match) -nolevel do not look in older levels -level_reset revoke -levelall or -nolevel -volumewise[:mode] controls output order of volumes and levels. Modes: volume_ascending ... report volumes in ascending order levels_ascending ... report levels in ascending order on [or no mode] ... volumes and levels in ascending order off ...... levels in descending order, no volume sorting -suball lookup all sub items and levels (else: show one per part) -fast do not look for sub items -sub_reset revoke -suball or -fast -outdated:code how to deal with file objects which are still on some some backup media but removed or replaced on disk: hide ... do not deliver outdated file objects show ... deliver valid and outdated file objects only ... do not deliver valid file objects -dialog after all arguments are processed, enter dialog mode. In this mode you may enter searchtexts or any of the options described here. One per line. -dialog_reset revoke -dialog (works only if given as argument) -deutsch issue dialog messages in german language -english issue dialog messages in english language (default) -page:len[:width] prompt user after len output lines (0=no prompt). width (default 80) can adjust line number computation to the output terminal's line width. -use_stdin use raw standard input even if libreadline is available -use_readline use libreadline for dialog if available -history:textline copy textline into libreadline history. This command itself is not copied to the history list. -pkt_output[:on|:off] direct output to stdout and prefix each line by a short header which tells channel id and a mode number. Each such output packet is finalized by a newline. Channel ids are 'R:' for result lines, 'I:' for notes and error messages, 'M:' for -mark texts. Bit 0 of the mode number tells wether the newline is also part of the packet payload. Example of a info message with newline: I:1: enter option or search text : -pkt_output:on is intended for use by frontend programs. -logfile:channel:fileaddress copy output of a channel to the given file. channel may be 'R','I','M' as with -pkt_output or '.' for the consolidated -pkt_output stream. -mark:text if text is not empty it will get put out each time an option or search is completed. -prog:text use text as this program's name in subsequent messages -prog_help:text use text as this program's name and perform -help -prog_hilfe:text use text as this program's name and perform -hilfe -result_format:code:...:code compose format of result output from levhdr ... level headline levno .... level number in result lines volno .... volume number target ... target address (content list only) target_esc target address with escaped '=' and '\' source ... source address expr ..... search text resp. expression Defaults: ASKME -result_format:levhdr:volno:source:expr Content lists -result_format:levhdr:volno:target:source -read_pickiness:code behavior with problems when reading infosource: zero ... try to keep on reading as long as possible low .... ignore minor inconsistencies in the infosource high ... abort on the first inconsistency in infosource Only the first -read_pickiness argument gets effective. -no_dir_list Do not read complete_dir_list.gz -media_mode:[+-]:option:... set rules how to handle media when the program demands a particular volume. Options are: mount_umount use external commands to unmount the previous volume and to mount the new one. load_eject use external commands to unload the previous volume and to load the new one. on_abort_try perform unload even in abort situations -media_cmd_mount:command a command and eventual fixed arguments to be executed rather than command mount. It will get the mount point directory as additional argument. -media_cmd_umount:command like -media_cmd_mount but replacing command umount -media_cmd_load:command like -media_cmd_mount but replacing command eject -t -media_cmd_eject:command like -media_cmd_mount but replacing command eject -status[:mode|:filter] report the current settings of persistent options. Modes: short... print only important or altered options long ... print options even if they have default settings long_history like long plus -history: lines Filters begin with '-' and are compared literally against the output lines of -status:long_history. A line is put out only if its start matches the filter. Try these example filters -status:-res , -status:-restore , -status:-restore_mode If neither mode nor filter is given, mode 'short' is assumed. -status_history_max:number maximum number of history lines to be reported with -status:long_history -options_from_file:fileaddress reads lines from the given file and executes them as program options. -abort_handler:option:... controls handling of program abort by system signals. Anything other than "on" or "on:extra_verbous" should only be used in case of severe system deficiencies: on .... signals get caught, unclean file states get cleared as far as possible and then the program ends off ... signals lead to immediate end of the program ignore signals are rejected as far as possible and the program continues. This may cause single files to have corrupted content. handler_abort abort immediately on further signals which arrive after start of abort handling handler_repeat restart abort handling on further signals extra_verbous report about the particular actions and decisions of abort handling # any text is ignored. In dialog mode the input line will be stored in the eventual readline history, nevertheless. -info_source:addresse gets only into effect if given as first argument. Usually the prefix -info_source: is not needed. -version tells program and version number -end end program immediately The options -help, -hilfe, -prog_help, -prog_hilfe are recognized even if given as first argument instead of an infosource. Options with parameters accept not only ':' but also ' ' as separator. ' ' might be convenient in dialog but has to be protected from the shell parser if given as argument. Option -page causes a user prompt after the given number of result lines. Empty input resumes output until the next prompt. Other input may be: @ suppresses pageing until the current option or search is done @@ suppresses further result output but continues the search @@@ aborts the current search or option @skip suppresses -volumewise matching and -restore of the current volume other aborts the current search or option and executes input as new search or option Searching Depending on the information source the search capabilities differ: * With ASKME, filenames resp. directories are looked up in the volume item lists. If the searchtext or a directory above is found then a result line according to -result_format is printed. If filename is a directory and an item below this address is found, then the action depends on -suball and -fast. The search functions only apply to the lines which are visible with -list. Therefore one cannot search in ASKME for a file name of which only a parent directory is listed. Pattern matching search modes are available but of limited use. * Information read from content-vanish-list files forms a detailed tree model in which any file object can be found that is covered by the lists. Additionally this model can tell the target addresses on the backup media and not only the source addresses on hard disk. This model is well suited for pattern matching search modes. Therefore -search_sh is the default mode after loading it. If a directory address is matched it will be reported for any volume that contains one of its non-directory fileobjects. With option -suball every single non-directory below the found one will be reported. If nothing is found on the newest level then usually the older levels are searched. This behavior depends on -levelall and -nolevel . The search is done on either the source addresses as they were given at backup time or the target adresses as they are in the backup volumes. -search_source search on source addresses (default) This option also adds :source: to -result_format. -search_target search on target addresses. Targets may get listed multiple times if they come from different sources. This option also adds :target: to -result_format. -search:searchtext prevent searchtext from being understood as option or comment (usually the prefix -search: is not needed) Search comparison modes: -search_fgrep try to find searchtext as arbitrary piece of source -search_grep searchtext is regular expression (^\/vids\/.*) -search_sh searchtext is shell parser pattern (/vids/*) -search_shpat like -search_sh but without the special handling of '/' -search_shname like -search_sh but for leafname, not for absolute path. This mode searches further below matched directories. -search_reset search by comparing start pieces of searchtext and items Navigation options: -cd:searchtext defines the working directory for -search_sh by the first directory match of searchtext. It is prepended to any searchtext which does not begin with '/'. -search_sh and related options handle file names '..' and '.' as usual in unix-style filesystems. -cd resets working directory to the read-in working directory resp. in -search_target mode to '/' -pwd tells the current working directory -ls:searchtext gives an overview of known addresses. searchtext is like with -search_sh. All levels and volumes are reported but any match is reported only once. Matched directories list their complete content. -ls same as -ls:. -ls_d:searchtext like -ls but with no directory content reported. Empty directories get reported (unlike -ls or normal search). -ls_d same as -ls_d:* (and nearly the same as -ls) -find:searchtext lists matching files below current working directory. searchtext is as with -search_shname. Empty directories get listed. -find same as -find:* Restoring -------------------------------------------------------------------------- Important: Restoring will eventually temporarily widen the owner's access permissions of existing files. You cannot protect an *own* file from overwriting by taking away any permissions of the file itself or of your *own* directories above. Since the superuser usually has ownership privileges with all files, no permission settings can protect a file from being overwritten by the superuser (but -restore_mode:+:overwrite_off or -protect will do) -------------------------------------------------------------------------- Restore is currently suitable only for runs based on a tree model and only for mountable ISO-9660 backups. It needs to be enabled by -restore_mode:-:enable_restore or by any -restore_mode: that does not start with '+' or '-'. Restore operations copy from backup address to restore address. This text refers "source" and "target" addresses in quotation marks because these terms stem from the backup situation. Now in the restore situation their meaning gets inverted. "target" is actually part of the backup address (i.e. the origin of the copy). By default "source" is a decisive part of the restore address (i.e. the destination of the copy). Restore options: -restore_from:path defines the directory path which is prepended to the "target" address to form the backup address. path is also used for eventual load-mount-umount-eject operations. -restore_skip:path defines the starting part of the restore address which is to be cut off before -restore_to does its work. The restore address is either derived from "source" or from "target", depending on -restore_mode:use_target. If the skip path does not match the start of the restore address then this considered an error as if the file would not exist on the backup media. -restore_to:path defines the directory path which is prepended to the emerging restore address after eventual -restore_skip has cut off its part. -restore_asylum:path defines the location where restore mode overwrite_by_move shall save the overwritten files. The asylum address is obtained by prepending path to the full absolute address of the overwritten file object. -restore:searchtext locate matching file objects and copy them to the according restore address. Matching directories get restored including all their sub files. Matching is done by the same rules as with -search -restore_mode:[+-]:option:... sets properties of restore operations. If the first character after -restore_mode: is '+' then all mentioned options get added to the existing properties. If that first character is '-' then _all_ mentioned options get reset to default. Else the whole -restore_mode is reset before the mentioned options get added. Options are: on_search perform restore operations with any search (else only with -restore:...) use_target compose restore address from "target" silent_file do not report about single files verbous_volume report about mount_umount,load_eject verbous_action report in detail about actions open_dir_for_owner rwx-permission for directory owner overwrite_off do not overwrite existing files overwrite_by_unlink overwrite existing files, unlink overwrite_by_truncation truncate and overwrite data files overwrite_by_move move existing files to -restore_asylum obey_permissions do not widen owner permissions of parent directories. This can hamper restore ! disable_restore disable restore operations temporarily ban_restore disable restore operations forever on_error_ignore continue operation after partial error on_error_prompt ask for instructions after partial error on_error_exit abort program after partial error after_error_exit continue operation, abort when done on_error_keep do not remove incompletely restored file after error keep_ownership superuser shall not adjust owner,group fresh_timestamps do not copy atime and mtime from backup update_state_sparse avoid to update -resume_state_file with each file. Update at dialog time. This devalues _dirty file tracing. update_state_dsync push the _dirty info to disk by fsync This is slow and puts load on the disk. simulate_existence debugging option simulate_action debugging option simulate_mount debugging option -restore_pre_prompt:command a program and eventual fixed arguments to be executed before the prompt for a new backup volume. Four arguments will get appended: level, volume, backup address of next match, and its restore address. If command begins with '@' then it will be exceuted even if -restore_mode:+:simulate_mount is set. -restore_post_prompt:command like -restore_pre_prompt but to be executed after the user input to the prompt for a new backup volume. -resume[:level[:volume[:restore_or_search_option]]] resumes a previous -restore or volumewise -search at the level and volume where it was aborted. If level is given, the operation is resumed at volume 1 of this level, unless a volume is given as second argument. If the next component begins with "-restore:" or "-search:" then this operation is resumed instead of the most recent operation. -resume_last_source:address sets the absolute source address of the file object where exactly to resume within the given level and volume. If the address is not matched in the first volume of a resumed operation, then this first volume gets skipped and the following volumes get restored normally. -resume_last_dirty:address sets the absolute restore address of an eventual file object that is neither in its pre-restore state nor restored properly. The file object itself is completely questionable. The directories above might have too generous permissions for their owner (nobody else) or (if created newly) too sparse permissions for anybody. On next -resume, a non-empty last dirty address causes a warning. In dialog mode a confirmation request is made. In non-dialog mode the program aborts. -resume_last_lv:level[:volume] sets the level and eventually volume for the next -resume if this has no own level given. -resume_opt_text:restore_or_search_option sets the default operation to be performed by the next -resume if this has no own restore_or_search_option given. -resume_state_files:fileaddress defines a family of files which will get updated at various stages of -restore or volumwise search. fileaddress is later suitable for -resume_from_file. filedaddress itself will hold a -status:long_history report which defines the search environment and calls the other files of the family, which get updated more often: fileaddress"_opt" contains current -resume_opt_text fileaddress"_src" contains current -resume_last_source fileaddress"_lv" contains -resume with current level and volume. fileaddress"_dirty" contains current -resume_last_dirty The reason for this scattering is to simplify manipulation of the resume parameters. Note: the commands s*backup_askme use an own file family tmp/askme_resume_state* and will get confused if you use -resume_state_files yourself. -resume_from_file:fileaddress much like -options_from_file but allowed to be the first argument of the program and able to set the info source to be loaded. fileaddress should point to a family of files created by -resume_state_files . -resume_state_to_file write current (possibly artificial) resume state to state files. -protect:path prevent restore address path and any restore below path even if overwriting in general is allowed. If a file object with address path exists, then not only the literal path is protected but also any other path that leads to this file object's inode and device number. If path leads to a symbolic link, the link target is protected, too. The protection of link target and inode is recorded when the option is executed. Subsequently changed link targets or inodes on disk will not be protected by that aspect of protection. Literal path, the recorded link targets, and the recorded inodes are still protected then. Protections given as program arguments get recorded before any restore or search operation is performed. The number of protections is not limited. Nevertheless: use this option sparsely because it is expensive at restore time. -shadow:path like -protect but not causing an error condition if a restore operation gets rejected. Thus a restore will continue even if in -restore_mode:-:on_error_ignore . -shadow is intended for applications as protection from unwantedly overwriting themselves. -shadow options are reported only with -status:long Example (search oak.jpg on all backup levels) : scdbackup_askme /cdrom/ASKME -levelall /home/pictures/trees/oak.jpg Example (load incremental configuration, start dialog): scdbackup_askme $HOME/backup_configuration -levelall -dialog Dialog input: /*/*/trees/oak* -search_shpat *trees/oak* -search_shname oak* More complex patterns: Filenames which begin with A,B,C,K,W, or Z either in capital or in small letters, the second character may not be a digit, the suffix must be 3 characters: [A-CKWZa-ckwz][!0-9]*.??? Filenamess which consist of "DSC", 5 digits and a 3 character suffix: DSC[0-9][0-9][0-9][0-9][0-9].??? Restore directory with original source address /home/pictures/tree together with all its files from backup volumes back to disk: -restore_from:/cdrom -restore_skip:/home/pictures -restore_to:/home/test/restored_pictures -media_mode:load_eject:mount_umount -restore_mode:overwrite_off -restore:/home/pictures/trees This will create directory /home/test/restored_pictures/trees . You will get prompted for backup volumes to be inserted in /cdrom . It will not be possible to overwrite existing files. Example (load incremental information from backup media): scdbackup_askme /cdrom/added_by_scdbackup -levelall -dialog