1Srest Info
1Srest Info
Last Update: 12/18/16
Below are a couple snapshots of the mid December 2016 ver 0.95
of my 1Srest program. It may change a little as it matures,
but this is likely pretty much how it will end up.
Below is the usage screen displayed when no command line arguments are given:
1Srest version 0.95
abort: target path to archive is required as the first argument
usage: ISrest [-f] [-l] [-p] [-x] [-vv] or [-vs#]
with just displays the file header info and exits
-f is primarily a debug and validation tool, which just displays where
structure definitions are. use -f with -v to display structure headers
-l list files that -x would extract
-p set path string to limit List and Xtract operations
-x extract files, without this option just displays catalog
-v verbose mode and -vv is very verbose mode for additional information
-vs# verbose mode to just list structure data for # where 1 <= # <= 7
---------------------------
If you have look at the file format page provided, this may make some sense.
Initially I had a fair amount of trouble locating the data regions and the
-f option helped me work out an algorithm to do that.
The two key options are -L to list the files in the backup and -X to extract them.
The -p option allows some selective Listing and Extraction. One supplies a path,
or partial path, and any file in the archive with a path that matchs the specification
will be Listed and/or extracted. This allows one to extract on a directory path basis.
Below is a listing where a small sample file, IO2drv.bku, is used as the
source file with the -L option to list the contents:
1Srest version 0.95
Backup name: test4
Job 6 Backup Disk 1
Catalog at offset 0x92a7
attempt to step through catalog and locate structure definition regions
start of Structure Definition 1: Disk at 0xa377
start of Structure Definition 2: Dir at 0xc4fe
start of Structure Definition 3: File at 0xe872
start of Structure Definition 4: Comp at 0x10c4c
start of Structure Definition 5: Job at 0x129f6
start of Structure Definition 6: Path at 0x13a96
start of Structure Definition 7: Session at 0x15c9f
data is not compressed
link_data() 7 files 0 comp groups 4 unique paths cum data size 37031
catalog Files listing:
1: C:\Dos\HELP\ALT.TXT 20050421120728 len 1827
2: C:\Dos\HELP\aol.txt 20001212153536 len 3994
3: C:\Dos\text\boatmail.txt 20100510074010 len 9984
4: C:\Dos\text\Negus-P.txt 20051026091858 len 1445
5: D:\Inet\HTML\pdp-doc\1105.HTM 20011207091910 len 1975
6: D:\Inet\HTML\wwhome\Mac-68k.htm 20050204122834 len 7771
7: D:\Inet\HTML\wwhome\msbk-faq.htm 20040131103750 len 10035
display of catalog
Disks with 2 entries
Dirs with 9 entries
Files with 7 entries
Paths with 4 entries
Job data: Job number 6 number of disks 1
Session with 1 entries
----------------------------------------------------------------
The backup file above contains all the data as well as the catalog. You must start
with the media disk containing the catalog to provide the information needed
to restore files. Most of my example data are small single media disk
backups which are easy to work with, but I have done three backups that
span two data files to work out those details. As shown above the program
starts by listing where the various structure definitions are located in the
catalog region. You can view details of these regions by using the -vs#
command line option and optionally also the -v option to make the display
a little more verbose. The # in -vs# is between 1 and 7 to control which
of the data structure regions should be expanded.
These are primarily debug aids, but of interest in case there is a load problem.
All these regions must be parsed before files can be extracted.
The listing above with the -L options shows this backup contained 7 files from
several different directories. The -X option would attempt to extract these
same files.
I am trying to keep this simple, its just a tool. At this date it is unlikely
you will be attempting to restore to the machine the backup was made on. That
was the original intent of the 1-Step program. So for extraction I mangle the
path names. I've done most of my work in Linux, and in that environment I
replace the path delimiter, '\', with the Unix delimiter '/'. The program
no longer extracts to the dos drive letter either, C: and D: are replaced
by C_ and D_ or what ever drive letter was used. These root nodes are created
in the current directory that the program is run in. Sub directories are created
below these root nodes. Files are extracted to these sub directories. All sub
directories in the structure 2 definition, 'Dirs', are created before extractions
begins regardless of whether it a selective extraction or a full extraction.
If this had been a backup that spanned multiple media and did not contain a
catalog the following display would have been seen:
1Srest version 0.95
Backup name: test8 2 disk uncompressed
Job 7 Backup Disk 1
no Catalog on this disk
----------------------------------------------------------------
See the separate document on the 1-Step format if you are interested in the
details. However the Session data in data structure 7 tells the program how
many data disks were used in the backup. If data compression was not used
the files data in structure 3 is sufficient to extract the files. If data
compression was used for the backup the Comp data in structure 4 is also
required. The Disk (in structure 1) and Dir (in structure 2) data are
required to create the path information for the extraction.
If the backup is entirely contained in a single media file things are fairly
straight forward and after loading the catalog all the files can be extracted.
The more interesting case is where there were multiple media files created
by the backup. In this case one needs to start with the media file for the last
disk in the set to load the catalog to memory. Then switch to the first media file
and sequentially open it and each additional media file to extract the files
in the order they were backed up. In general it does not appear to be possible
to extract files if you are missing any of the original media. It depends on
the sequential order to do the extraction, and its hard to extract anything
after the sequence is broken by a missing media file.
I believe I have worked out a system to recover the files from the last disk
in the set if one or more of the others are missing. In a multi media set
the program provides a few interactive prompts. The first asks if you want
to attempt to recover any files it can from the last disk in the set. If you
are desperate, try using 'Y' to this prompt, but its experimental...
'L' and 'A' are safe, and 'N' will extract the full backup per below.
The prudent solution is to say 'N' and start with the 1st media file in the set.
The program will prompt interactively for each of the file names from the
first to the last.Open them and try to do the extract. If all goes well
it will eventually prompt for the last file again which it will reopen to
complete the extraction and exit. Entering an empty file name, ie just pressing
the Enter key at any of the prompts for a file name will abort the process. If a
file name is entered that the program can't find or validate as part of this backup
the prompt will be repeated.
Note the source files can be renamed, I make no attempt to force you to use the
original names. Primarily because they were so long it was painful typing them
in during debugging! However this program does attempt to validate the headers on each
media file and insure that the time stamp matches that of the catalog media file.
I show a typical name below, and mention them in my 1Step-format document.
'Backup Job 6, Disk 1, 16-10-23 02.47.01.1-Step'
It includes the Job #, Disk #, and time stamp with a '1-Step' extension.
A few other thoughts:
I have gotten it to successfully extract data from several small uncompressed backup files.
I have three sample multi-disk backups that use two media files and these
also work successfully.
This is not very user friendly but I intend it to remain a tool that is used from the command line with just a few options to accomplish the task. It is quite possible no one is interested in this anyway.
A source code distribution is available 1Srest.tar.gz
I'd rather you built it yourself than trying to make OS specific downloads available.
Make files for the compilers and OS I have attempted are provided. The linux version has been
tested fairly rigorously. I built an MSDOS version with Microsofts CL compiler, but this only supports 8.3 style file names. It will list a backup's contents, but aborts if asked to extract a file with a longer file name. It turns out google sites won't allow *.exe files in the downloads area so I have provided an LHA archive of a Windows NT console application executable which should run under Win9x or WinXP although I'm not sure about later versions of Windows. This was created with the freely available Open Watcom compiler.
I suspected fairly early on that these backups used some form of LZW compression when compression of the data was requested. It took me a while to work out a solution to this,
but eventually found the Zlib Distribution home page. I downloaded and built this library and after some testing worked out how to use it to decompress
the raw data in the backup files the 1-Step program creates. Its a nice package, and is required to build my 1Srest utility. I used version 1.2.8, the most recent Zlib distribution.
Their linux build works fine when linked with my program. I had to make minor modifications
to their watcom build file to create the WinNT version of 1Srest.exe and provide this makefile
as makefile.w32 in the source distribution.
There are a lot of built in error messages which will probably mean nothing unless you
search the source code or ask me. For instance some of them have to do with the
pre-allocated space I reserve for path names, directory paths and nesting level.
I also validate the fields found in the various free format regions that define structure
definitions. The version 5.3 of 1-Step backup I have used for my trials passes this validation,
but other versions may not.
Hopefully you will not see any errors, but I'm not really very confident that its bug free yet!
Let me know if you try it and get a fatal error message.