File: userguide-en.html

package info (click to toggle)
ukopp 4.9-3
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 1,000 kB
sloc: cpp: 10,893; makefile: 66
file content (1103 lines) | stat: -rw-r--r-- 66,602 bytes
parent folder | download | duplicates (3)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>




  <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title></title>
  
  <meta http-equiv="CONTENT-TYPE" content="text/html; charset=ISO-8859-1">
  <meta name="GENERATOR" content="OpenOffice.org 2.4  (Linux)">
  <style type="text/css">
	<!--
		@page { size: 8.5in 11in; margin: 0.79in }
		PRE { font-family: "Luxi Mono", monospace }
		P { margin-bottom: 0.08in }
	-->
	</style></head><body>
<small><small><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><big><big><b><font style="font-size: 11pt;"><big>ukopp user guide</big></font></b></big></big><span style=""></span></font></small></small><font style="font-family: sans-serif;" face="Nimbus Sans L, sans-serif"><font style="font-size: 11pt;">&nbsp;&nbsp; v.4.8<br>
<br>
<a href="#concepts">concepts</a></font></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Nimbus Sans L, sans-serif"><font style="font-size: 11pt;"><br>
<a href="#first%20tryout">first tryout</a><font color="#ff0000"><span style="text-decoration: none;">&nbsp; (1-page primer for
those with RTFM problems)</span></font></font></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Nimbus Sans L, sans-serif"><font style="font-size: 11pt;"><br>
<a href="#toolbar">toolbar buttons</a></font></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Nimbus Sans L, sans-serif"><font style="font-size: 11pt;"><br>
<a href="#file%20menu">file menu</a><a href="#file%20menu"><span style="text-decoration: none;">
</span></a><br>
</font></font>
<a style="font-family: sans-serif;" href="#backup%20menu"><font style="font-family: Bitstream Vera Sans;"><font style="font-size: 11pt;">backup menu</font></font></a><font style="font-family: sans-serif;" face="Nimbus Sans L, sans-serif"><font style="font-size: 11pt;"><br>
<a href="#verify%20menu">verify menu</a></font></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Nimbus Sans L, sans-serif"><font style="font-size: 11pt;"><br>
<a href="#report%20menu">report menu</a></font></font><span style="font-family: sans-serif;">
<br>
</span><font style="font-family: sans-serif;" face="Nimbus Sans L, sans-serif"><font style="font-size: 11pt;"><a href="#restore%20menu">restore menu</a></font></font><span style="font-family: sans-serif;">
<br>
<a href="#format_menu">format menu</a> <br>
</span><font style="font-family: sans-serif;" face="Nimbus Sans L, sans-serif"><font style="font-size: 11pt;"><a href="#specifying%20backup%20job">editing
backup jobs</a></font></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Nimbus Sans L, sans-serif"><font style="font-size: 11pt;"><br>
<a href="#technical%20notes">technical notes</a></font></font><span style="font-family: sans-serif;">
<br>
<br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>License and
Warranty</b></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
</b>Ukopp is a free program licensed under the GNU General Public
License V3 (Free Software Foundation). Ukopp is not warranted for any
purpose, but if you find a bug, I will try to fix it.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
Origin and Contact</b></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
</b>Ukopp originates from the author's web site at: <a href="http://kornelix.com/ukopp">http://kornelix.com/ukopp</a><br>
Other web sites may offer it for download. Modifications could have
been made.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><span style="text-decoration: none;"><span style=""><br>
If you have questions, suggestions or a bug to report: </span></span>kornelix@posteo.de</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
<br>
<big>Introduction</big></b></font><strong style="font-family: sans-serif;"><br>
<br>
Ukopp</strong><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><span style="">
is a </span></font><strong style="font-family: sans-serif;"><b>Linux</b></strong><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><span style="">
program for copying or backing-up disk files to a separate storage
device, e.g. a USB drive or SD memory card. Any disk directory may also
be
used as a backup location. </span></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">You
can </font><strong style="font-family: sans-serif;">select files</strong><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">
to be copied
using a </font><strong style="font-family: sans-serif;">GUI</strong><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">.
You
can navigate through the file system and select files or
directories to include or exclude at any level in the directory
hierarchy. These choices can be saved in a<span style="font-weight: bold;"> </span></font><strong style="font-family: sans-serif; font-weight: bold;">job
file</strong><strong style="font-family: sans-serif; font-weight: normal;"><span style="">
to automate recurring backups</span></strong><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">.
If
new files appear in an included or excluded directory, they are
automatically taken into account. You need to revise the job file only
if you change the directories or make new exceptions within those
directories. </font>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
<br>
Ukopp </font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>copies only
new and modified files</b></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><span style="">:</span></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">
files that have not changed since the last backup are bypassed in
microseconds. A typical daily backup of personal files can be done in a
few seconds. Ukopp can optionally </font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>retain
previous
versions</b></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">
of backup files instead of overwriting them with newer versions. You
can optionally specify the retention time and / or the number of
versions to
retain for each group of included files. You can see these versions in
the
backup directories and recover them if needed.</font><br style="font-family: sans-serif;">
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
Ukopp has a
</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>synchronize</b></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">
function, which is a simple method to keep files in two computers
synchronized using a USB stick or other portable memory. Ukopp copies
the newest version of a file from one device to the other. </font>
<br style="font-family: sans-serif;">
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
Backups
can be verified three ways: full, incremental, and compare. A </font><strong style="font-family: sans-serif;">full
verify</strong><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">
reads all the backup files and reports any files having read errors.
An </font><strong style="font-family: sans-serif;">incremental
verify</strong><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">
reads only those files that have been newly written by a preceding
backup job. This is very fast and provides a high level of security.
A </font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>compare</b></font><strong style="font-family: sans-serif;"><b>
</b></strong><strong style="font-family: sans-serif;">verify</strong><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">
reads all backup files and compares them with their corresponding
disk files. This is normally not necessary, but provides an effective
check that all hardware and software is working correctly.</font><span style="font-family: sans-serif;">
</span><br style="font-family: sans-serif;">
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
You
can <b>report</b> all files in a backup job, or all files in a backup
directory. You can <b>search</b> for file names using wildcards. You
can report the <b>differences</b> between backup files and their
corresponding disk files: files that have been created, deleted, or
modified since the backup was made. These reports are available in
three levels of detail: a list of all changed files, total file and
byte counts per directory, and overall totals.</font><span style="font-family: sans-serif;">
</span><br style="font-family: sans-serif;">
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
For
disaster recovery or file transfer, ukopp has a </font><strong style="font-family: sans-serif;">file
restore</strong><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">
capability. You can select and restore backup files to their original
directories or anywhere else. File owner, permissions, and modification
time are are also
restored, even if the backup device uses a Microsoft FAT file system
(normally the initial state for USB drives).</font><span style="font-family: sans-serif;"></span><br style="font-family: sans-serif;">
<br style="font-family: sans-serif;">
<br style="font-family: sans-serif;">
<a style="font-family: sans-serif;" name="concepts"></a><span style="font-family: sans-serif;"><br>
</span><big><font style="font-family: sans-serif;"><b>Concepts</b></font><span style="font-family: sans-serif;">
</span></big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
<br>
The files in a backup job are specified with include and exclude
records. These have filespecs with optional wildcards placed almost
anywhere. <br>
<br>
Examples:</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans Mono, sans-serif"><br>
</font><big><span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
include /home/* &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; # add all user files </span><br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;
include /root/* &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; # add all root files </span><br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;
include /shared/*/documents/* &nbsp;&nbsp;# add shared document files </span><br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;
exclude */mp3/* &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; # remove files in mp3 directories
</span><br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp;
exclude */.Trash/* &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;# remove trash files
</span><br style="font-family: monospace;">
<br style="font-family: sans-serif;">
</big>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">The
first include adds all files in all users' home directories
and sub-directories. The second include adds all files under the /root
directory.
The third include adds all files under the /shared top directory that
also have an intermediate directory named /documents. The two exclude
records remove all files within all /.Trash and /mp3 directories.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
</b>The <span style="font-weight: bold;">backup target</span> is the
device or directory where the source files are copied-to. <br>
This is the directory of a mounted device or some other specified
directory. <br>
If the target is <big><span style="font-family: monospace;">/media/sdb2</span></big>
(where the device sdb2 is mounted) <br>
and the source files are:&nbsp; <big><span style="font-family: monospace;">/home/&lt;user&gt;/documents/*</span></big>,
<br>
the backup files will be:&nbsp; <big><span style="font-family: monospace;">/media/sdb2/home/&lt;user&gt;/documents/*</span></big>.
<br>
<b><br>
GUI interface:</b> The above records are normally generated using a
file selection dialog. <br>
This is documented in a following section: editing backup jobs.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
File Selection Logic</b></font><span style="font-family: sans-serif;"> <br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans Mono, sans-serif">&nbsp;&nbsp;&nbsp;
loop:</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans Mono, sans-serif"><br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; get next include/exclude record</font><span style="font-family: sans-serif;"> </span><font style="font-family: sans-serif;" face="Bitstream Vera Sans Mono, sans-serif"><br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; if EOF, done</font><span style="font-family: sans-serif;"> </span><font style="font-family: sans-serif;" face="Bitstream Vera Sans Mono, sans-serif"><br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; if include: add all matching
files to backup file set</font><span style="font-family: sans-serif;"> <br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans Mono, sans-serif">&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; if exclude: remove all matching files from backup
file set</font><span style="font-family: sans-serif;"> </span><font style="font-family: sans-serif;" face="Bitstream Vera Sans Mono, sans-serif"><br>
&nbsp;&nbsp;&nbsp; loop-end</font><span style="font-family: sans-serif;">
<br>
<br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>Note that
excludes are effective only against prior includes</b>. They have no
effect on following includes, which are processed afterwards. See the
section on editing backup jobs.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
<br>
Restriction: include records must include at least the first directory
name (top-level) without wildcards (the GUI file-chooser does this
automatically).</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
</b></font><br style="font-family: sans-serif;">
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>Retaining
multiple file versions:</b>
if this option is elected, existing backup files that need updating are
renamed with a version number instead of being overwritten. If the
backup file "foo.bar" is updated, it is renamed to "foo.bar (1)", and
"foo.bar" becomes the newest backup. If it is updated again, "foo.bar"
is renamed to "foo.bar (2)", and so forth. Newer versions have higher
numbers, and the unversioned file is always the current or latest
version. The section on editing job files explains how to specify old
version retention policies.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
Ukopp limitations</b></font><span style="font-family: sans-serif;">
</span><br style="font-family: sans-serif;">
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">&nbsp;&nbsp;&nbsp;
max. 500,000 files in a backup job (compile time constant)</font><span style="font-family: sans-serif;"> </span><br style="font-family: sans-serif;">
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">&nbsp;&nbsp;&nbsp;
max. file retention is 9999 days and 9999 versions</font><span style="font-family: sans-serif;"> </span><br style="font-family: sans-serif;">
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><span style="font-family: sans-serif;">&nbsp;&nbsp;&nbsp; must run as
root user to mount backup device with [mount] button</span></font><span style="font-family: sans-serif;"></span><br style="font-family: sans-serif;">

<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">&nbsp;&nbsp;&nbsp;
must run as root user or use sudo to copy non-owned files<br>
<span style="font-family: sans-serif;"></span></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">&nbsp;&nbsp;&nbsp;
not useful for disk imaging (operating system backup)</font><span style="font-family: sans-serif;"><br style="font-family: sans-serif;">
<br>
<br>
</span><a name="first tryout"></a><font style="font-family: Bitstream Vera Sans;"><b><br>
<big><span style="font-family: sans-serif;">Ukopp
first tryout</span></big></b></font><big><span style="font-family: sans-serif;"></span></big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
<br>
After
installing ukopp, please perform the following short exercise. This may
be
all you need at first. You can enhance your file security and
ultimately save time if you read this whole document. </font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">The
exercise
will check that ukopp functions correctly
on your system and help you become familiar with ukopp usage. </font>
<br style="font-family: sans-serif;">
<ol style="font-family: sans-serif;">
  <li>Choose a backup device or directory. If using a
pluggable device (e.g. USB drive), plug it in. </li>
  <li>Start ukopp: click the desktop launcher or input a
terminal command: $ ukopp.</li>
  <li>Select button [ target ]. The drop-down list shows
disk devices and their mount points if mounted. You can choose one of
these, or input your chosen backup directory.</li>
  <li>Select
button [ mount ] if you need to mount the
backup device. Check that the selected
target device/directory mounts OK. Mount may not work unless you are
root. Use the [root] button to become the root user. This works like
'sudo' - enter your own password. If this does not work on your system,
restart ukopp with 'sudo' or 'su'. <br>
  </li>
  <li>Select button [ edit job ]. </li>
  <li>Erase the default backup job shown (select and
delete, or use the [ clear ] button). </li>
  <li>Select the button [ browse ] at the bottom. </li>
  <li>Navigate through the directories and select the
directories and files to be copied.<br>
    <ul>
      <li>double-click a directory to open it and enable
selection within that directory</li>
      <li>select one or more directories / files, using
left-mouse or Ctrl+left-mouse</li>
      <li>click [ include ] to include the selected
items in the backup job</li>
      <li>click [ exclude ] to exclude the selected
items (previously included from a higher-level directory, and you now
wish to make an exception)</li>
      <li>use the buttons at the top to go back up the
directory hierarchy</li>
      <li>click [ hidden ] to enable / disable the display of
hidden files</li>
      <li>for now, you can ignore the inputs for "Retain old
files" (see editing backup jobs, later)<br>
      </li>
    </ul>
  </li>
  <li>Select the [ done ] button when finished selecting files.</li>
  <li>Inspect the generated include and exclude records<br>
    <ul>
      <li>these may be edited directly if desired (e.g.
erase mistakes or redundancies, change the
order, or even make additions or revisions using the text editor)</li>
      <li>re-enter the file chooser dialog if wanted -
new choices will be appended</li>
      <li>cycle between the editor and file chooser as much as
needed</li>
    </ul>
  </li>
  <li>Set a verify method: choose one of none,
incremental, full, or compare. Use compare until you are confident that
everything is working, then speed things up later by changing to
incremental.</li>
  <li>Select button [ done ] when finished editing the
job. </li>
  <li>If there are errors shown, select [ edit job ] and
fix them (remember that exclude records must follow relevant include
records - excludes are exceptions to prior includes). </li>
  <li>Select menu: Report &gt; get disk files. Inspect
the counts. Be sure the total byte count is within capacity. Look for
zero counts, indicating possible errors. Re-edit if needed. </li>
  <li>Select button: [ run job ]. Backup and verify
should run automatically. Check that the error count is zero.</li>
  <li>Save the job file if desired: menu: File &gt; save
job.</li>
  <li>Select button: [ quit ].</li>
  <li>Next steps: play with the report and restore
functions. </li>
</ol>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<big>Detailed Usage Instructions </big><br>
<br>
</b></font><a style="font-family: sans-serif;" name="toolbar"></a><font style="font-family: Bitstream Vera Sans;"><b><br>
<big><span style="font-family: sans-serif;">Toolbar
buttons</span></big></b></font><big><span style="font-family: sans-serif;">
</span></big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
root<br>
</b>This button restarts ukopp with root privileges if the password
(sudo) is OK. This is necessary to mount a backup device or copy files
that you do not own. If this does not work on you system, restart ukopp using 'sudo' or 'su'. <b><br>
<br>
target <br>
</b><span style="">The drop-down list displays all drives that are
visible to ukopp, with their mount points (if mounted) and
descriptions. Choose one
of these to set the target device and directory for a subsequent backup.
You may also type-in a directory directly. This must be a valid
directory for which you have write permission, and of course there
should be enough space for the backup files. If an unmounted device is
chosen, it will be mounted at a new directory under <span style="font-weight: bold;">/media/sdxx</span> and this
will be the target backup directory unless you change it. If the job
file has a target device and directory specified, ukopp will attempt to
mount this device and directory when the [mount] button is pressed.<span style="font-weight: bold;"><br>
</span><span style="font-weight: bold;"><br>
</span></span></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>
edit job <br>
</b><span style="">Shortcut to the backup job editor (same as menu File
&gt; edit job)</span></font><span style="font-family: sans-serif;">.<br>
<br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>run job <br>
</b><span style="">The current job is executed.</span></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
pause / resume <br>
</b><span style="">The currently running job or menu function may be
paused and resumed. Use this to inspect output on the fly.</span></font><span style="font-family: sans-serif;">
<br>
<br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>kill job </b><span style=""><br>
The currently running function is killed. </span></font>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
clear <br>
</b><span style="">The main window, where messages and reports are
written, is cleared.</span></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
quit <br>
</b><span style="">Exit ukopp.</span></font><span style="font-family: sans-serif;">
<br>
<br>
<br>
</span><a style="font-family: sans-serif;" name="file menu"></a><font style="font-family: Bitstream Vera Sans;"><b><br>
<big><span style="font-family: sans-serif;">File Menu</span></big></b></font><big><span style="font-family: sans-serif;">
</span></big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
open job </b><br>
Open a previously saved backup job file for re-use (edit, run). Default
location is the hidden directory /home/user/.ukopp (or /root/.ukopp). </font>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
edit job <br>
</b>Opens an edit dialog for the current backup job (the last job file
opened). If no file has been opened, internal
default data will be used as a starting point. Editing jobs is
explained in a later <a href="#specifying%20backup%20job">section</a>.</font><span style="font-family: sans-serif;"> </span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
list job </b><span style=""><br>
List the current backup job data and diagnose any errors.</span></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
save job<br>
</b>Save current backup job (with changes) to the same job file that
was last opened. <b><br>
<br>
save job as</b><br>
Save current backup job (with changes) to a selected job file. Default
is the same file that
was last opened, but you may select any file.</font><span style="font-family: sans-serif;"></span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
run job </b><br>
The current backup job is executed. Backup and verify modes are taken
from the job.</font><span style="font-family: sans-serif;">
<br>
<br>
<br>
</span><a style="font-family: sans-serif;" name="backup menu"></a><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<big>Backup
menu </big><br>
<br>
</b></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>backup</b><span style=""> <br>
The backup job is run without verify. You can then run whatever verify
you want. </span></font>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
synchronize</b><span style=""> <br>
This is a bi-directional copy. Files present on one side only (disk or
backup location) are copied to the other side. Files that are present
on both sides will get the newest version copied to the other side.
"Newest" is based on the time of the last file update.</span></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
<br>
Assume you normally use computer A, but you need to use B while
traveling. You can use a portable memory device (SD card, USB stick) to
keep the computer files synchronized.</font>
<ol style="font-family: sans-serif;">
  <li>A and B must have identical backup job files,
naming the same set of backup files. </li>
  <li>Initial synchronization: backup A, move the memory
device to B, restore to B. </li>
  <li>Work with B: create and modify some files. </li>
  <li>Run synchronize on B, move the memory device to A,
run synchronize on A. </li>
  <li>The modifications done on B are now carried over
to A. </li>
  <li>You can update files on both A and B in parallel,
as long as you work on different files between synchronizations.
Synchronize A, then B, then A. Now both will have the same set of
files, and these will be the newest ones present on either A or B.<br>
  </li>
</ol>
<br style="font-family: sans-serif;">
<a style="font-family: sans-serif;" name="verify menu"></a><font style="font-family: Bitstream Vera Sans;"><b><br>
<big><span style="font-family: sans-serif;">Verify
menu</span></big></b></font><big><span style="font-family: sans-serif;">
</span></big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
full </b><span style=""><br>
All backup files are read and checked for errors. </span></font>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
incremental <br>
</b><span style="">New backup files are read and checked for errors.
"New" means any files written by an immediately preceding backup. Files
not
modified are not checked. The backup files are compared with the disk
files as in the "compare" verify described below. Non-matching files
are listed. </span></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
compare </b><span style=""><br>
All backup files having the same modification time and size as their
corresponding files on disk are read and compared with the disk. There
should be no differences. This verifies that ukopp is working
correctly. Other files are read and checked, but not compared to disk.</span></font><span style="font-family: sans-serif;">
<br>
<br>
<br>
</span><a style="font-family: sans-serif;" name="report menu"></a><font style="font-family: Bitstream Vera Sans;"><b><br>
<big><span style="font-family: sans-serif;">Report
menu</span></big></b></font><big><span style="font-family: sans-serif;">
</span></big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
get disk files </b><span style=""><br>
The backup job include and exclude records are listed, along with the
file and byte counts that are added or removed. Look for zero counts,
indicating a possible error. The disk directories are read at the time
this command is executed, and the list of files included in the backup
job is retained in memory. This data is used to determine which backup
files are now out of date and must be copied again from disk. The file
list is static and is not updated by disk activity. The list of "new"
files for a subsequent incremental verify is also reset.</span></font><span style="font-family: sans-serif;">
Note that this is a report to help verify that a backup job is complete
and correct. It is not necessary to run this report before running a
backup job. <br>
<br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>diffs summary
</b><span style=""><br>
Report the total number of files in each category:</span></font><span style="font-family: sans-serif;"> </span><font style="font-family: sans-serif;" face="Bitstream Vera Sans Mono, sans-serif">&nbsp; </font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
</font>
<table style="width: 745px; height: 63px;" border="0" cellpadding="0" cellspacing="0">
  <tbody>
    <tr>
      <td style="font-family: sans-serif;">&nbsp;&nbsp; new files </td>
      <td style="font-family: sans-serif; white-space: nowrap;"> disk
files with no corresponding backup file </td>
    </tr>
    <tr>
      <td style="font-family: sans-serif;">&nbsp;&nbsp; modified
files&nbsp; <br>
      </td>
      <td style="font-family: sans-serif;"> disk and backup files exist
but are not identical
      </td>
    </tr>
    <tr>
      <td style="font-family: sans-serif;">&nbsp;&nbsp; deleted files </td>
      <td style="font-family: sans-serif;"> backup files with no
corresponding disk file </td>
    </tr>
    <tr>
      <td style="font-family: sans-serif;">&nbsp;&nbsp; unchanged </td>
      <td style="font-family: sans-serif;"> disk and backup files exist
and are identical
(same modification time)</td>
    </tr>
  </tbody>
</table>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">
Differences between the disk and the backup files may be caused by disk
updates (file additions, deletions, updates, or moves), or by changes
to the backup job file itself.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
diffs by directory <br>
</b><span style="">The above counts are reported for each directory
having any differences between the disk and backup files. </span></font>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
diffs by file </b><span style=""><br>
List all different files,
grouped in the first three categories above.
If a file is present on both the disk and the backup location, and the
backup file is newer than the disk file, then the file is flagged in a
way that is easy to see. This can be normal if the backup media has
files from another computer that are used to refresh the (older) files
on this computer (see the synchronize function in the <a href="#backup%20menu">backup</a> menu).</span></font><span style="font-family: sans-serif;"></span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
version summary</b><span style=""> <br>
List backup files having old versions retained, with the range of
versions and file ages (days) available. File age is days since the
file was modified.</span></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
expired versions</b><span style=""> <br>
List backup file versions that are expired and will be purged from the
backup medium or location with the next backup run.</span></font><span style="font-family: sans-serif;">
<br>
<br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>list disk
files <br>
</b><span style="">All files in the backup file set are listed in
alphabetic sequence. Use this to check that the correct files are being
backed-up.</span></font><span style="font-family: sans-serif;">
<br>
<br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>list backup
files </b><span style=""><br>
All backup files are listed in alphabetic sequence. A summary of the
space used for prior file versions is also provided.</span></font><span style="font-family: sans-serif;">
<br>
<br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>find files </b><span style=""><br>
Enter a search pattern with optional wildcards (e.g.
</span></font><big><span style="font-family: monospace;">/home/dir*name/file*name</span></big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><span style="">).<br>
All matching disk files and backup files are listed.</span></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
save screen </b><span style=""><br>
The main window, where messages and reports are written, is saved as an
ordinary text file.<br>
</span></font><span style="font-family: sans-serif;">&nbsp;</span><br style="font-family: sans-serif;">
<br style="font-family: sans-serif;">
<a style="font-family: sans-serif;" name="restore menu"></a><font style="font-family: Bitstream Vera Sans;"><b><br>
<big><span style="font-family: sans-serif;">Restore
menu </span></big></b></font>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
setup restore job</b></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
Specify the copy-from location (backup device or location), the copy-to
location, and the files to be restored. <br>
<br>
</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">The copy-from location is the
topmost directory of a tree of files to
be restored.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
</font><span style="font-family: sans-serif;">&nbsp;&nbsp;&nbsp;
example:
</span><big><span style="font-family: monospace;">/home/joeblow/documents
&nbsp;
# backup device mount point is omitted
</span></big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
The copy-to location is an existing disk directory where the tree of
files will be copied-to.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
</font><span style="font-family: sans-serif;">&nbsp;&nbsp;&nbsp;
example 1:
</span><big><span style="font-family: monospace;">/home/joeblow/documents
</span></big><br style="font-family: sans-serif;">
<span style="font-family: sans-serif;">
&nbsp;&nbsp;&nbsp; example 2: </span><big><span style="font-family: monospace;">/home/joeblow/documents/restored
</span></big><br style="font-family: sans-serif;">
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><span style="font-family: sans-serif;">
In example 1, the restored files will go back to the same place they
were when backed-up. </span><br style="font-family: sans-serif;">
<span style="font-family: sans-serif;">In example 2, they will go to a
new place. </span></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br style="font-family: sans-serif;">
</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">Files to be
restored are specified the same way as in a backup job (see the section
below on <a href="#specifying%20backup%20job">editing backup jobs</a>).
<br>
<br>
</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">If
you need to restore multiple trees of files, you can do this in
multiple runs, or you can simply begin the tree at a higher level and
use the file selection dialog to specify multiple sub-trees, with
included and excluded branches.</font><span style="font-family: sans-serif;">
<br>
<br>
Note that files being restored from a backup media will replace the
corresponding files on disk, but other files, not being restored, are
not affected. Thus&nbsp; <big><span style="font-family: monospace;">include
/some/directory/*</span></big>&nbsp; in a restore job will replace all
files in&nbsp; </span><big><span style="font-family: monospace;">/directory/</span></big><span style="font-family: sans-serif;">&nbsp;
that match the files being restored, but other files will be left in
place. If you do not want this, you must delete the files in&nbsp; </span><big><span style="font-family: monospace;">/directory/</span></big><span style="font-family: sans-serif;">&nbsp; before doing the restore.<br>
<br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>list restore
files</b></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
After performing the file restore setup above, use this function to
list all matching files that will be restored, at the locations where
they will be restored. You should check this list carefully to be sure
you are restoring the correct files to the intended locations.</font><span style="font-family: sans-serif;">
<br>
<br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>restore files</b></font><span style="font-family: sans-serif;">
<br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">When
you are satisfied with the restore job specification, use this menu to
start the restore. You will see a running log of the activity. The file
owners, permissions and modification times are also restored, even if
the backup
files are on a Microsoft FAT file system.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
<br>
<a name="format_menu"></a><br>
<big>Format menu</big></b></font><big>
</big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
format device</b></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
This is a convenient way to initialize a portable memory device such as
a USB stick or SD card for use with ukopp. You may select the vfat
(Microsoft) or ext2 (Linux) file system. You may choose from
all known devices, mounted or unmounted. You may
also choose a device label which will show under the device desktop
icon if automatic mounting is enabled. Before format begins, you are
shown which device will be formatted and given an opportunity to stop. <font color="#ff0000"><b>Be sure you format the correct device, since all
data on this device will be lost!</b></font></font><span style="font-family: sans-serif;">
<br>
<br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">Microsoft
vfat works somewhat faster than ext2 for USB devices, for reasons not
clear to me. The disadvantage is that some of the strange file names
typically found in Linux hidden directories are not vfat compatible and
will not copy (error messages are produced and the backup job
continues). Use ext2 if you must copy these files. Use vfat if you must
exchange files with a Windows computer.</font><span style="font-family: sans-serif;">
<br>
<br>
<br>
</span><a style="font-family: sans-serif;" name="specifying backup job"></a><font style="font-family: Bitstream Vera Sans;"><b><br>
<big><span style="font-family: sans-serif;">Editing
backup jobs</span></big></b><big><span style="font-family: sans-serif;">
</span></big></font>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
<br>
The [edit job] button starts the job edit dialog. See the screenshot
below.</font><span style="font-family: sans-serif;"></span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
include and exclude records</b><br>
</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">You may edit the backup job
(the include and exclude records) directly
in the text window. You may also use the browse button to start a file
selection dialog. The dialog has the buttons [include] and [exclude].
The "show hidden" checkbox turns the display of hidden
files on or off. Select one or more directories or files, using
left-mouse or
Ctrl+left-mouse, then press the [include] or [exclude] button. The
selected directories or files will be written into the text window as
include or exclude records. If you select a directory, the entry is
modified to add a wildcard at the next level, e.g. selecting</font><span style="font-family: sans-serif;">&nbsp; <span style="font-weight: bold;">/aaa/bbb/ccc</span>&nbsp; </span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">and
then
pressing [include] generates&nbsp; <span style="font-weight: bold;">/aaa/bbb/ccc/*</span>.<span style=""></span></font><span style="font-family: sans-serif;"><br>
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><span style="font-weight: bold;"></span></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
The include and exclude records allow precise control of the backup
file set, allowing you to quickly converge on the desired results:</font><span style="font-family: sans-serif;"> </span><font style="font-family: sans-serif;" face="Bitstream Vera Sans Mono, sans-serif"><font style="font-size: 9pt;"><br>
</font></font><big><span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
include
/aaa/bbb/* &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; # include file tree under /aaa/bbb/ </span><br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp; exclude /aaa/bbb/ccc/* &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; # exception: exclude the /ccc/ subtree </span><br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp; include /aaa/bbb/ccc/xxx.yyy &nbsp; # exception:
include file /ccc/xxx.yyy
</span><br style="font-family: monospace;">
</big>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
Because of wildcards, newly added files within the scope of existing
include or exclude records are automatically comprehended. In the above
example, if a new file is added in /aaa/bbb/* then it will be
automatically included in the next backup job.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
</b>Here is and example of how to include all files in a direcory but
exclude all subdirectories:<br>
<big><span style="font-family: monospace;">&nbsp; &nbsp; include
/some/directory/*</span><br style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp;&nbsp; exclude
/some/directory/*/*<br>
<br style="font-family: monospace;">
</span></big></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>old file retention policy<br>
</b><span style=""></span></font><span style="font-family: sans-serif;">You
may optionally
enter a retention policy for old backup files. </span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><span style="">If
there is no retention, a modified disk file
replaces the corresponding backup file, and a deleted disk file causes
the corresponding backup file to be deleted. If you wish to retain
previous file versions, you must specify a retention time in days, and
a retention version count. The values in the GUI dialog (days and
versions) apply to each file that is selected when the [include] button
is pressed. </span></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">Old
file versions
are deleted when they are older than BOTH retain rules: if retention is
D days and V versions, old file versions will be deleted only when
older
than D days, and not within the latest V versions. The latest version
is never deleted. You can
disable either of the limits by using zero (retain zero versions or
zero days).</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
<br>
Here are some examples that will hopefully make this clear:</font><span style="font-family: sans-serif;"> </span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
</font><span style="font-family: sans-serif;">&nbsp;&nbsp;&nbsp; retain
10 days and 3 versions: delete
versions older
than 10 days unless one of the 3 newest versions</span><br style="font-family: sans-serif;">
<span style="font-family: sans-serif;">
&nbsp;&nbsp;&nbsp;
retain 10 days and 0 versions: delete all versions older than 10 days </span><br style="font-family: sans-serif;">
<span style="font-family: sans-serif;">
&nbsp;&nbsp;&nbsp;
retain 0 days and 8 versions: retain the 8
newest versions</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"> regardless of age<br>
<br>
If a retention policy is given, the include record in the text box has
"(ddd,vvv)" appended to it, where ddd is the retention days and vvv
the version count.<br>
</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
You
may alternate between editing the text window and using the
file-chooser dialog. When you are done, press [done] to accept. The
include / exclude records will be validated to the extent possible. R<span style="">e-edit
to fix any problems. To change the sequence, cut and paste in the text
window. When you are done, use the report functions "get disk files"
and "list disk files" to </span><b>verify that you have the correct
files!</b></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>[choose target]</b></font><span style="font-family: sans-serif;"></span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">
<span style="font-weight: bold;">button</span><br>
This works like the [target] button on the toolbar, described above.<br>
</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
<b>
verify method</b><br>
Choose one of the radio buttons to determine how ukopp verifies that
the backup copies are free of errors.<span style="font-weight: bold;"></span></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
</b></font>
<table style="width: 760px; height: 72px; font-family: sans-serif;" border="0" cellpadding="0" cellspacing="0">
  <tbody>
    <tr>
      <td style="font-family: sans-serif;"><font style="font-family: sans-serif;">&nbsp;&nbsp; none </font><big> </big></td>
      <td style="font-family: sans-serif;"> no automatic verify after
backup (use the verify menu
instead) </td>
    </tr>
    <tr>
      <td style="font-family: sans-serif;">&nbsp;&nbsp;
incremental&nbsp;&nbsp; <br>
      </td>
      <td style="font-family: sans-serif;"> verify and compare all
files copied by the backup job (new
and modified files) </td>
    </tr>
    <tr>
      <td style="font-family: sans-serif;">&nbsp;&nbsp; full </td>
      <td style="font-family: sans-serif;"> read all backup files to
check data integrity</td>
    </tr>
    <tr>
      <td style="font-family: sans-serif;"><font style="font-family: Bitstream Vera Sans;"><span style="font-family: sans-serif;">&nbsp;&nbsp; compare</span> </font> </td>
      <td style="font-family: sans-serif;"> full + compare all backup
files to corresponding disk
files (if present) </td>
    </tr>
  </tbody>
</table>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>ukopp job
edit dialog<br>
<img style="width: 755px; height: 555px;" alt="" src="images/jobedit.jpeg" vspace="5"><br>
</b></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><span style="font-weight: bold;">Summary:</span>
The [ edit job ] toolbar button pops up the middle window. This can be
edited directly: click anywhere in the text area and start writing. The
right window is the choose files dialog, which is started with the
[ browse ]
button in the middle window. Choose files using the right window, and
the middle window records your choices. You can navigate around the
directory
hierarchy and select any number of files or directories. The hidden
button toggles the display of hidden files. Click one of the include or
exclude buttons to get the selected files added to or removed from the
backup list. Selecting a directory is an implied selection of all its
contained files, thus the selection appears as</font><span style="font-family: monospace;"> /directory/*</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">
in the list of selected files. To make an exception, go down one level,
select some files, and select the opposite include or exclude button.
You can refine the file selections manually if desired. It is sometimes
handy to use wildcards in the directories to make more general and
compact selection criteria.<br>
&nbsp;&nbsp;&nbsp;&nbsp; example:&nbsp; </font><big><span style="font-family: monospace;">exclude
/home/*thunderbird*/Trash</span></big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
This would exclude trashed e-mail even if the
overlying directories change (they do) and even for multiple users. </font>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
<br>
You can add comments (or disable a record) by putting # in column 1.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
Annotated example of a backup job file</b></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
This is an example of what one might do to backup all personal files.
In this example, we avoid backing up stuff that is not important
(browser cache) or stuff that can be automatically regenerated (gnome
thumbnails). Two old file versions should always be retained, and all
revisions up to 10 days.
All files copied during this run should be
read and verified. Files not copied (because they have not changed
since the last backup) are not verified. The backup target or location
is a USB disk that, when plugged-in, mounts at </font><big><span style="font-family: monospace;">/media/disk</span></big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">
(which can be
changed at run time if desired). </font>
<font style="font-family: sans-serif;"><font style="font-size: 9pt;"><br>
</font></font> <big><span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
include
/home/rosi/* (10,2)&nbsp;&nbsp;&nbsp;
(include Rosi's personal files</span>)<br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp; exclude */.thumbnails/* &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;
(omit gnome
thumbnail files)</span><br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp; exclude */firefox/*Cache/* &nbsp;&nbsp;&nbsp; (omit
the
browser
cache files)</span><br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp; verify incremental &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; (verify files copied by each run)</span><br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp; target /dev/sdf1 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp; (use removable USB disk sdf1</span></big>)<br style="font-family: monospace;">
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
The above backup job can be created using the following steps:</font>
<ul style="font-family: sans-serif;">
  <li>click on button [ edit job ] to start the job edit
dialog </li>
  <li>if there is a default job there, clear it out with
the [ clear ] button </li>
  <li>use the [ browse ] button to start the "choose
files" dialog</li>
  <li>navigate to /home, select rosi, enter the old
version retention policy <br>
(10 days, 2 versions), and click the [
include ] button </li>
  <li>click the [ hidden ]
button to expose hidden files </li>
  <li>now choose .thumbnails and click the [ exclude ]
button </li>
  <li>navigate to .mozilla, then to firefox, then to the
directory xxxxx.default </li>
  <li>select the folder Cache and click on the [ exclude
] button </li>
  <li>click on [ done ] for the choose files dialog </li>
  <li><font style="font-family: Bitstream Vera Sans;"><span style="">the
following
text records are now in the edit dialog window:<br>
    </span></font><big><span style="font-family: monospace;">&nbsp;include
/home/rosi/*
    </span><br style="font-family: monospace;">
    <span style="font-family: monospace;">&nbsp;exclude
/home/rosi/.thumbnails/*</span><br style="font-family: monospace;">
    <span style="font-family: monospace;">&nbsp;exclude
/home/rosi/.mozilla/firefox/xxxxx.default/Cache/*</span></big> </li>
  <li>You can edit the records directly to shorten and
add wildcards, if you want.<br>
(e.g. replace xxxxx with * to make the job ignore changes to this name )</li>
  <li>Use the menu: file &gt; save job as &nbsp; to save the job
file for daily re-use<br>
  </li>
</ul>
&nbsp;&nbsp;&nbsp;
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">("xxxxx" means
the random directory name that firefox generates for a user)</font><span style="font-family: sans-serif;"><br>
<br>
<br>
</span><a style="font-family: sans-serif;" name="technical notes"></a><font style="font-family: Bitstream Vera Sans;"><b><br>
<big><span style="font-family: sans-serif;">Technical
Notes</span></big></b></font><big><span style="font-family: sans-serif;">
</span></big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
Symlink files: </b>These are treated like regular files. They are
copied if
included in the backup job. The target file of an included symlink is
NOT automatically included. A target file is included only if it's own
file name is included in the backup job. Symlinks are verified by
checking they are readable using function readlink(). <span style="color: red;">If the target file system is vfat, symlinks will
not copy and will be reported as errors.</span><br>
<br>
<span style="font-weight: bold;"></span><b>Running ukopp as root:</b>
Normally, ukopp will only copy files owned by the user. If files
belonging to root or other users are to
be copied, you must run ukopp as root. Use the [root] button to become
the root user (password required). See the note below about making a
launcher to start ukopp as root user. </font><span style="font-family: sans-serif;"></span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
Command line arguments: </b><b> </b></font>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans Mono, sans-serif"><br>
</font><big><span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
$ ukopp -job jobfile &nbsp; &nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; #
load job file</span><br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp; $ ukopp jobfile &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # load job file</span><br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp; $ ukopp -run jobfile &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; #
load job file and run it</span><br style="font-family: monospace;">
<span style="font-family: monospace;">
&nbsp;&nbsp;&nbsp; $ ukopp -nogui -run jobfile &nbsp;&nbsp;
# run as batch job without window</span><br style="font-family: monospace;">
</big>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
If the jobfile name contains <span style="font-style: normal;">blanks,
quotes are required, e.g.&nbsp; </span></font><big><span style="font-family: monospace;">$ ukopp -job "my ukopp job"</span></big><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
<br>
The&nbsp; -nogui&nbsp; option can be used for a pure command line job
that has no window and will not ask for any user inputs. This can be
used for deferred execution (cron job). The backup location must be
available at the time the job runs.<b><br>
<br>
File type association: </b><span style="">I suggest using the
extension
.ukopp for job files and specifying ukopp as the "start with" program.
Then you can click on a job file and launch ukopp. </span></font>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
Desktop launcher:</b> a desktop launcher may contain a command
like this:</font><span style="font-family: sans-serif;">
<br>
</span><span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;
<big>gksu /usr/bin/ukopp -job myjob.ukopp</big></span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
"gksu" will ask for the sudo password and open the job
file as root.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
All backups are incremental:</b> A backup file is considered identical
to its
corresponding source file if their modification times are the
same. Such files are not backed up. If the modification times
differ by less than 2 seconds they are considered equal. 2 seconds is
the
time resolution for a Microsoft VFAT file system, usually
present by default on USB drives.</font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>
For Linux usage it is best to reformat the USB drive to ext4. </b>It
is theoretical possible that a backup file could have the same
modification time as the corresponding source file but still have
different content. This could happen if the disk file was updated,
copied by ukopp, and updated again within 2 seconds. For use on a
personal computer this is practically impossible. Another possiblility
is that the source or backup file was copied from another computer or
the modification time was manipulated. <br>
<br>
<b>Restoring file owner and permissions: </b>A detachable drive may
not support Linux file owner and permissions (e.g. Microsoft
FAT). The ukopp backup function copies a special file to the backup
location, with the data needed to restore file owner and permissions.
The ukopp restore and synchronize functions use this file.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
Special ukopp files: </b>A directory named ukopp-data is written to
the
backup location. <br>
It contains the following three files: </font> <font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><br>
</font><big><span style="font-family: monospace;">&nbsp;
datetime &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;backup date-time</span><br style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp; poopfile &nbsp; &nbsp;
&nbsp; &nbsp; &nbsp;
&nbsp;owner and permissions data for all files</span><br style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp; jobfile &nbsp; &nbsp;
&nbsp; &nbsp; &nbsp; &nbsp; a
copy of the backup job file used</span><br style="font-family: monospace;">
</big>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif">These are ordinary text files
which you can view with an editor.</font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
Special file types: </b><span style="">pipes, devices, and
sockets are not copied.</span></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
Duplicate files: </b><span style="">If job file "include" records
overlap, resulting in duplicate files in the backup set, this is
reported and the backup does not proceed.</span></font><span style="font-family: sans-serif;">
</span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
</b></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>Finding disk drives:</b><span style=""> the Linux utility </span><span style="">udevinfo</span><span style=""> is used to find block devices
with the characteristics "disk". The file </span><span style="">/etc/mtab</span><span style=""> is used to find mount points for mounted devices. </span></font><span style="font-family: sans-serif;"></span><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
Removing detachable drives:</b><span style=""> To remove a detachable
drive, right click on its desktop or file manager icon, select
"unmount" or "eject" or "safely remove", and wait for the "OK to
remove" message, or the LED on the drive to stop blinking. Pulling the
drive out without doing this can result in data corruption or total
loss. <br>
<br>
</span></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b>File system
cache:</b><span style=""> </span></font><font style="font-family: sans-serif;" color="#000000">The flush() function
is called after each file is copied to insure the file is completely
present on the backup medium and not waiting in the file system cache.
This is a little slower, but insures file system integrity if the job
fails to complete. The verify function uses direct I/O to read files
directly from the medium instead of using the memory cache. This is not
slower for large block I/O, and provides additional insurance that the
data on the medium is valid.<b><br>
</b></font><font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><span style="font-weight: bold;"><br>
NTFS:</span>
this Windows file system can be used as a backup source, but not as a
backup target. This is because the Linux driver for NTFS fails for a
file open() function call with the attribute O_DIRECT, meaning direct
I/O that bypasses memory caching.<br>
<br>
</font><font style="font-family: sans-serif;" color="#000000"><b>Linux
error codes:</b><span style=""> Linux error codes can be
misleading. If an attempt is made to open a file that is already open
and is therefore locked, the error text is "no such file or directory".
I have noticed several such screwups in Linux. This will hopefully
improve
over time. <br>
<br>
</span></font><font style="font-family: sans-serif;" color="#000000"><b>Funny
file names: </b><span style="">Disk
drives formatted with the vfat file system (Microsoft FAT) will not
accept some Linux file names. Notably, files names containing " : " or
" ? " or ending with a blank will fail to copy, and this will be
reported in the backup job. Unless you need Microsoft compatibility,
format the drive with ext2, or avoid copying the weird file names you
can find among the hidden files in your home
directory. </span></font>
<font style="font-family: sans-serif;" face="Bitstream Vera Sans, sans-serif"><b><br>
<br>
Retention and version limits:</b> The retention upper limits are 9999
days
and 9999 versions. Retained versions for a file could reach 9999 before
ukopp
stopped working. These limits are easy to increase, but performance
would start to deteriorate long before this. If you reach 1000 retained
versions it is time to start over (erase the backup medium).<br>
<br>
</font>

</body></html>