Commit 317d6342 authored by Daniel Armbruster's avatar Daniel Armbruster Committed by thomas.forbriger
Browse files

hash value added; manual proceeding

This is a legacy commit from before 2015-05-18.
It may be incomplete as well as inconsistent.
See COPYING.legacy and README.history for details.


SVN Path:     http://gpitrsvn.gpi.uni-karlsruhe.de/repos/TFSoftware/trunk
SVN Revision: 4407
SVN UUID:     67feda4a-a26e-11df-9d6e-31afc202ad0c
parent ed3159dd
......@@ -37,6 +37,7 @@
# 08/01/2012 V0.9 New configuration file syntax. Complete rework. Make use
# of python's configparser module.
# 10/01/2012 V0.9.1 added copy section for single rsync command settings
# 16/01/2012 V0.9.2 hash key within backup section available
#
# =============================================================================
"""
......@@ -60,7 +61,7 @@ elif sys.version_info >= (3,):
else:
sys.stderr.write("csback2cron: Incompatible python version.\n")
__version__ = "V0.9.1"
__version__ = "V0.9.2"
__subversion__ = "$Id$"
__license__ = "GPLv2"
__author__ = "Daniel Armbruster"
......@@ -197,6 +198,8 @@ class BackupConverter(Converter):
self.line += ' -R'
if self.sectionDict['followlinks']:
self.line += ' -f'
if self.sectionDict['hash']:
self.line += ' --hash '+self.sectionDict['hash'].strip()
for regex in self.sectionDict['exclude']:
self.line += ' -e "'+regex.strip()+'"'
self.line += ' -t '+self.sectionDict['targetdir']+' '+ \
......@@ -332,6 +335,7 @@ class Processor():
backup['exclude'] = []
if self.config.has_option(key, 'exclude'):
backup['exclude'] = self.config.get(key, 'exclude',raw=1).split(", ")
backup['hash'] = self.config.get(key, 'hash')
backup['recursive'] = self.config.getboolean(key, 'recursive')
backup['logging'] = self.config.getboolean(key, 'logging')
backup['followlinks'] = self.config.getboolean(key, 'followlinks')
......@@ -451,7 +455,7 @@ class Processor():
sys.stdout.write("csback2cron: " + self.crontabfile + " written.\n")
DEFAULTS = {'logging': 'yes', 'recursive': 'yes', 'followlinks': 'no', \
'tolerant': 'no', 'test': 'yes', 'copy': 'no'}
'tolerant': 'no', 'test': 'yes', 'copy': 'no', 'hash': 'sha256'}
# -----------------------------------------------------------------------------
def main(argv=None):
......
......@@ -23,6 +23,7 @@
\usepackage{fancyhdr}
\usepackage{booktabs}
\usepackage{hyperref}
\usepackage{color}
\usepackage[bf,small]{caption}
\usepackage[round,authoryear]{natbib}
\usepackage{xspace}
......@@ -51,6 +52,7 @@
\newcommand{\EHdC}{\ensuremath{^\circ\text{C}}}
\newcommand{\SUo}{\ensuremath{U_{\text{o}}}}
\newcommand{\SRxcc}{\ensuremath{R_{\text{x}19}}}
\definecolor{darkgray}{rgb}{0.95,0.95,0.95}
%======================================================================
\begin{document}
%%fakesection header
......@@ -80,15 +82,16 @@ Blackforest Observatory (BFO)\\
\section{Overview of \texttt{csback}}
The \texttt{csback} utility is a collection of small python scripts which
provide the possibility to calculate \emph{checksum files} and check the
checksums of the corresponding files from time to time. This manual describes
the installation and configuration of \texttt{csback} which was developed by
Daniel Armbruster.
checksums of the corresponding files from time to time. Because all information
are saved in \texttt{ASCII} files the processes always are transparent. This
manual describes the installation and configuration of \texttt{csback} which was
developed by Daniel Armbruster.
\texttt{csback} was developed both for python2 and python3 and therefore should
be platform independent. Because it uses several already existing unix tools
especially unix users shouldn't have any problems installing \texttt{csback}.
Open Source tools which are used and should be provided or rather installed on
the operating system are:
Open Source tools which are in use and should be provided or rather installed
on the operating system are:
\begin{itemize}
\item \texttt{cron deamon}
\item \texttt{rsync}
......@@ -143,6 +146,321 @@ in your local binary directory. For \texttt{csbackgen.py} use
\texttt{csbackntfy.py} use \texttt{csbackntfy}. Otherwise you might run into
problems while using the \emph{crontab} generated by \texttt{csback2cron}.
\section{Configuration}
Before using \texttt{csback2cron} to generate a \emph{crontab} a
\texttt{csback} configuration file has to be set up. This package already
contains such a configuration file that contains a description of available
commands and configuration options. Afterwards either \texttt{csback2cron} has
to be called with the command
\medskip
\texttt{csback2cron -i path/to/configfile crontab}
\medskip
or before executing \texttt{csback2cron} a \texttt{csback} configuration file
must be copied to \texttt{\$HOME/.csback/csbackrc} so that the command
\medskip
\texttt{csback2cron crontab}
\medskip
is sufficient to generate a \emph{crontab} file with the filename
\texttt{crontab}. Then install the \texttt{crontab} using the appropriated
\emph{crontab} command. Note that a exemplary \texttt{csback} configuration file
comes along with this package.
\subsection{Configuration file syntax}
A \texttt{csback} configuration file may include comments, prefixed by specific
characters (\# and ;). Comments may appear on their own in an otherwise empty
line, or may be entered in lines holding values or section names. In the latter
case, they need to be preceded by a whitespace character to be recognized as a
comment. For backwards compatibility, only ; starts an inline comment, while \#
does not.
A configuration file consists of sections, led by a \texttt{[section]} header
and followed by \texttt{name: value} entries; \texttt{name=value} is also
accepted. Note that leading whitespace is removed from values.
\subsection{Configuration parameters}
\subsubsection{\texttt{copy} configuration}
Within a \texttt{[copy]} section a copy rule section headers can be defined. The
only option which is available within a \texttt{[copy]} section is the
\texttt{keys} entry. An exemplary line looks like
\medskip
\texttt{keys = copy1, copy2, copy3}
\medskip
which defines three copy rule sections named \texttt{copy1}, \texttt{copy2} and
\texttt{copy3}. Now the three copy rule sections must be defined.
\begin{verbatim}
[copy_copy1]
cronexpr = */30 * * * *
srcdir = /data/
targetdir = /data.bak/
exclude = *.log, tmp*
specialcommands = --recursive --links
[copy_copy2]
cronexpr = * */1 * * *
srcdir = /etc
targetdir = /media/usb/bak/
specialcommands = --keep-dirlinks
[copy_copy3]
cronexpr = * * 5 * *
srcdir = /directory/with/source
targetdir = /directory/to/save
\end{verbatim}
Every copy rule section's name includes the prefix \texttt{copy\_}. A minimal
copy rule section setup is \texttt{[copy\_copy3]}. It only contains obligatory
entries that are:
\begin{itemize}
\item \texttt{cronexpr}: Here the copy process can be scheduled. A valid cron
expression should be provided. A good introduction to cron expressions is
\url{http://en.wikipedia.org/wiki/Cron}.
\item \texttt{srcdir}: Directory path to source files.
\item \texttt{targetpath}: Directory path for copied source files.
\end{itemize}
To avoid ambiguities always enter absolut pathes. Optional copy rule section
entries are:
\begin{itemize}
\item \texttt{exclude}: A comma separated list of patterns for files and
directories which were excluded if matching one of the patterns. Because the
\texttt{csback} toolkit falls back to \texttt{rsync} to copy files read the
\texttt{rsync} man page \url{http://rsync.samba.org/ftp/rsync/rsync.html} for
more information on patterns.
\item \texttt{specialcommands}: A whitespace separate list of patterns for
additional \texttt{rsync} options.
\end{itemize}
\subsubsection{\texttt{backup} configuration}
\texttt{[backup]} section rules are provided to enable the full
\texttt{csback} backup process. This means first to copy the files with
\texttt{rsync} if desired, then generating checksum files with the checksum
calculated of files located in \texttt{srcdir} and afterwards check the
checksums of files backed up in \texttt{targetdir} with the checksums available
in the checksum file generated before. Though both the copy process and the
check process might be switched off it is recommended to proceed in this order
to make sure that files backed up are registered in the corresponding checksum
file.
As in a \texttt{[copy]} section in a \texttt{[backup]} section backup rule
section headers can be defined. The only entry which can be defined is the
\texttt{keys} attribute. A exemplary back \texttt{[backup]} section will look
as follows:
\begin{verbatim}
[backup]
keys= backup1, backup2, backup3
\end{verbatim}
Next the appropriated backup section rules must be set up.
\begin{verbatim}
[backup_backup1]
cronexpr = * */10 * * *
copy = yes
copy-exclude = *.log, *.tmp
srcdir = /data1/
targetdir = /data1.bak/
exclude = .*.log$, .*`date '+%j'`$
logging = no
test = no
[backup_backup2]
cronexpr = * */11 * * *
copy = yes
copy-exclude = *log
srcdir = /data2/
targetdir = /media/data2.bak/
recursive = no
test = yes
tolerant = yes
logging = yes
[backup_backup3]
cronexpr = 30 12 * * *
srcdir = /data3/
exclude = .*.log$, .*tmp[1-5], ^dirname$
targetdir = /data3.bak/
recursive = yes
followlinks = yes
test = yes
tolerant = no
\end{verbatim}
As already within the \texttt{[copy]} rule sections within a \texttt{[backup]}
rule section there are obligatory entries and auxiliary entries. Obligatory
entries are:
\begin{itemize}
\item \texttt{cronexpr}: Cron expression. See \dots
\item \texttt{srcdir}: Directory path to source files.
\item \texttt{targetdir}: Directory path for backup files.
\end{itemize}
Entries which already have a default value and so are customizable if desired
are:
\begin{itemize}
\item \texttt{copy}: Setting the value to \texttt{yes} will enable a copy
process with \texttt{rsync} before generating or rather updating checksum files.
\item \texttt{copy-exclude}:
\item \texttt{recursive}:
\item \texttt{followlinks}:
\item \texttt{test}:
\item \texttt{tolerant}:
\end{itemize}<++>
\subsubsection{\texttt{test} configuration}
\subsubsection{\texttt{mail} configuration}
\onecolumn
\begin{appendix}
\section{Programs}
\subsection{\texttt{csback2cron}}
\begin{verbatim}
Version: V0.9.1
License: GPLv2
$Id$
Author: Daniel Armbruster
Usage: csback2cron [-v|--verbose] [-o|--overwrite] [-i|--infile CONFIGFILE]
<CRONTABFILENAME>
or: csback2cron -h|--help
-------------------------------------------------------------------------------
-v|--verbose Be verbose.
-h|--help Display this help.
-i|--infile ARG If ARG is the path to csbackrc - the configuration file for
the csback crontab generation.
If this argument wasn't passed csback2cron assumes
~/.csback/csbackrc as default path to the configuration
file.
-o|--overwrite Overwrite already existing crontab.
<CRONTABFILENAME> Outputfilename of the generated crontab.
-------------------------------------------------------------------------------
Notice that csback2cron does not check any logical values e.g. pathes and/or
cron expressions.
\end{verbatim}
\subsection{\texttt{csbackgen}}
\begin{verbatim}
Version: V0.4
License: GPLv2
$Id$
Author: Daniel Armbruster
Usage: csbackgen [-v|--verbose] [-e REGEX [-e REGEX [...]]]
[-R|--notrecursive] [-d|--debug] [-f|--followlinks]
[-t|--target ROOTDIR] [-l|--logging] [--hash ARG]
[-L|--lock] PATH
or: csbackgen -h|--help
-------------------------------------------------------------------------------
-v|--verbose Be verbose.
-h|--help Display this help.
-e REGEX While generating a checksumfile exclude files matching
REGEX(s).
-R|--notrecursive Do not generate checksumfiles for subdirectories of PATH.
-d|--debug Debug mode. Be really verbose.
-f|--followlinks Follow symbolic links. Only available if option -R is not
set. Note that this option can lead to infinite
recursion.
-t|--target ROOTDIR Root target directory for checksumfile. The checksumfile
will be put to the appropiated location as the files had
in PATH or rather Paths' subdirectories. So target must
have the same subdirectory structure as PATH.
-l|--logging Switch on logging to files. Logfiles will be located in
/var/log/ .
--hash ARG Set the hash function algorithm. Valid values are:
sha224, sha256, sha384, sha512. (default: sha256)
-L|--lock Lock the directories working at. This flag is useful in
case csbackgen was run simultaneously with other csback
processes working in the same directory. Setting this
option avoids checksumfile access problems which might
occur.
PATH Path to generate checksumfile(s) for including its
subdirectories if option '-R' is not set.
-------------------------------------------------------------------------------
csbackgen.py will either generate a checksumfile if still no checksumfile is
available or in case there is an existing checksumfile csbackgen.py will append
the not yet registered files to the current checksumfile. In the latter case
csbackgen.py is working in its update mode.
Notice that in case PATH contains subdirectories and either option '-R' is set
or the subdirectory is excluded by a matching regular expression every
subdirectory will contain a checksumfile.
\end{verbatim}
\subsection{\texttt{csbackchk}}
\begin{verbatim}
Version: V0.2
License: GPLv2
$Id$
Author: Daniel Armbruster
Usage: csbackchk [-v|--verbose] [-e REGEX [-e REGEX [...]]]
[-R|--notrecursive] [-d|--debug] [-f|--followlinks]
[-t|--tolerant] [-l|--logging] [-L|--lock] [SOURCEPATH] PATH
or: csbackchk -h|--help
-------------------------------------------------------------------------------
-v|--verbose Be verbose.
-h|--help Display this help.
-e REGEX While checking a checksumfile(s) exclude files and
directories matching REGEX(s).
-R|--notrecursive Do not search in subdirectories of PATH.
-d|--debug Debug mode. Be really verbose.
-f|--followlinks Follow symbolic links. Only available if option -R is not
set. Note that this option can lead to infinite recursion.
-t|--tolerant Be tolerant.
While checking don't report anything if a file listed in
the checksumfile is missing. This flag is useful if a test
of a directory is executed but this directory is realized
e.g. as a ring buffer.
-l|--logging Switch on logging to files. Logfiles will be located in
/var/log/ .
-L|--lock Lock the directories working at. This flag is useful in
case csbackchk was run simultaneously with other csback
processes working in the same directory. Setting this
option avoids checksumfile access problems which might
occur.
SOURCEPATH Optional sourcepath for comparison with files backed up in
PATH. PATH and its subdirectories (if option '-R' had not
been selected) must contain the csback checksumfile(s).
Note that the directory structure (if option '-R' is not
set) bellow SOURCEPATH should be equal to those in PATH
because otherwise the files won't be found.
If SOURCEPATH is not passed a check of files located in
PATH with its checksumfiles will be performed.
PATH Path to perform check with its checksumfile(s). If option
'-R' had not been set the check will be performed
additionally for PATHs' subdirectories.
\end{verbatim}
\subsection{\texttt{csbackntfy}}
\begin{verbatim}
Version: V0.2
License: GPLv2
$Id$
Author: Daniel Armbruster
Usage: csbackntfy [-v|--verbose] [-d|--debug] [-l|--logging] -P|--port ARG
-H|--host ARG -u|--username ARG -p|--password ARG
-r|--receiver ADDRESS [-r|--receiver ADDRESS [...]]
-s|--sender ADDRESS [PATH [PATH [...]]]
or: csbackntfy [-v|--verbose] [-d|--debug] [-l|--logging] -n|--nagios
[PATH [PATH [...]]]
or: csbackntfy -h|--help
-------------------------------------------------------------------------------
-v|--verbose Be verbose.
-h|--help Display this help.
-d|--debug Debug mode. Be really verbose.
-l|--logging Switch on logging to logfile. Logfile(s) will be located in
/var/log/ .
-r|--receiver ADDR Email address(es) of the receiver(s). (obligatory)
-s|--sender ADDR Email address of the sender (Sending over SMTP).
(obligatory)
-P|--port ARG SMTP port.
-H|--host ARG Hostname of the SMTP server.
-u|--username ARG Username for SMTP server login.
-p|--password ARG Password for SMTP server login.
-n|--nagios Use csbackntfy in it's nagios mode and print the current
status in a simple line to stdout.
PATH Path(s) of the logfile(s) to check. If not specified the
logfiles in /var/log/ were investigated.
\end{verbatim}
\end{appendix}
\end{document}
% ----- END OF manual.tex -----
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment