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