manual.tex 24.8 KB
Newer Older
1
2
3
4
5
6
7
8
9
% This is <manual.tex>
% ----------------------------------------------------------------------------
% $Id$
% 
% Propose: Documentation of csback toolkit.

% Copyright (c) 2011 by Daniel Armbruster (BFO Schiltach) 
% 
% REVISIONS and CHANGES 
Daniel Armbruster's avatar
Daniel Armbruster committed
10
11
%    16/01/2012   V0.1    Daniel Armbruster
%    17/01/2012   V0.3    added configuration of optional *nix tools
12
%    18/01/2012   V0.4    time specification file exclusion keys
13
%    31/01/2012   V0.5    corrections and additional appendices added
14
15
16
17
18
19
20
21
22
23
24
% 
% ============================================================================
%
%%fakesection defines 
\documentclass[twoside]{article}
%\usepackage{ngerman}
\usepackage{pslatex}
\usepackage{anysize}
\usepackage{amsmath}
%\usepackage[slantedgreek]{mathtime}
\usepackage{graphicx}
25
\usepackage{verbatim}
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
\usepackage{textfit}
\usepackage{fancyhdr}
\usepackage{booktabs}
\usepackage{hyperref}
\usepackage[bf,small]{caption}
\usepackage[round,authoryear]{natbib}
\usepackage{xspace}
%----------------------------------------------------------------------
\newcommand{\mytitle}{Documentation csback toolkit}
%----------------------------------------------------------------------
\marginsize{2.5cm}{1.5cm}{1.5cm}{1.5cm}
\pagestyle{fancy}
\rhead[\mytitle]{\thepage}
\lhead[\thepage]{\mytitle}
\chead{}
\rfoot[Blackforest Observatory (BFO), \today]
{Daniel Armbruster}
\lfoot[Daniel Armbruster]{Blackforest Observatory (BFO), \today}
\cfoot{}
\sloppy
\columnsep20pt
%======================================================================
\newcommand{\Smu}{\ensuremath{\mu}}
\newcommand{\SO}{\ensuremath{\Omega}}
\newcommand{\SMO}{\ensuremath{\text{M}\Omega}}
\newcommand{\SkO}{\ensuremath{\text{k}\Omega}}
\newcommand{\EHV}{\ensuremath{\text{V}}}
\newcommand{\EHmA}{\ensuremath{\text{mA}}}
\newcommand{\EHA}{\ensuremath{\text{A}}}
\newcommand{\EHdC}{\ensuremath{^\circ\text{C}}}
\newcommand{\SUo}{\ensuremath{U_{\text{o}}}}
\newcommand{\SRxcc}{\ensuremath{R_{\text{x}19}}}
%======================================================================
\begin{document}
%%fakesection header
\twocolumn[
\mbox{ }\par
\vspace{-1.5cm}
%\hrule
\medskip
{\noindent\Large\textbf{\mytitle}\par}
%\smallskip\hrule
\rule{\textwidth}{1pt}
%\bigskip
\par
\begin{raggedleft}
Daniel Armbruster\\
Blackforest Observatory (BFO)\\
\vspace{3pt}
75
\today\ (\mbox{\texttt{$$Revision: 0.5 $$}})\par
76
77
78
79
80
81
82
83
84
85
\end{raggedleft}
\bigskip]
\thispagestyle{plain}
%-------------------------------------------------------------
\tableofcontents
%\listoftables
%\listoffigures
\enlargethispage{12pt}
\section{Overview of \texttt{csback}}
The \texttt{csback} utility is a collection of small python scripts which
86
provide the possibility to calculate \emph{checksum files} and check the
87
checksums of the corresponding files from time to time. Because all information
88
is saved in \texttt{ASCII} files the processes always are transparent. This
89
manual describes the installation and configuration of \texttt{csback} which was
90
developed by \href{mailto:dani.armbruster@gmail.com}{Daniel Armbruster}.
91
92
93
94

\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}.
95
96
Open Source tools which are in use and should be provided or rather installed
on the operating system are:
97
98
99
100
101
102
103
104
\begin{itemize}
\item \texttt{cron deamon}
\item \texttt{rsync}
\item \texttt{syslog-ng}
\item \texttt{logrotate}
\end{itemize}
If you are familiar with writing \texttt{crontabs} using other programs
providing the same functionality as the tools mentioned above should be no
105
106
obstacle. Additionally make sure to use a recent version of your python
interpreter. Prefered are python3 interpreters.
107
108
109
110
111
112
113
114
115
116
117

After setting up a \texttt{csback} configuration file the command
\texttt{csback2cron} generates a crontab. The crontab must be added to the
locally installed \texttt{cron deamon} which is responsible for the scheduling
of backing up files, generating checksums and testing the files integrity from
time to time. The \texttt{csback} logging mechanism sends log information and
status notifications to the operating system's system logger i.e.
\texttt{syslog-ng} which writes the reports to logfiles or sends the results to
\emph{stdout} depending of its configuration. If logging to a logfile is desired
the \texttt{csback} logfile checking tool \texttt{csbackntfy} is able to
investigate the logfile and send a report via email to the admin.
118

119
120
121
122
123
124
125
Actually the work is done by three scripts.
\begin{itemize}
\item \texttt{csbackgen}: Generate or rather update \texttt{csback}
checksum files if there is already an existing checksum file located in the
current directory. Up to now 4 different hashfunction algorithms are provided
which include \emph{sha224}, \emph{sha256}, \emph{sha384}, \emph{sha512}. If a
directory contains subdirectories each subdirectory will contain its own
126
127
checksum file. Checksumfiles are indicated through the filename
\texttt{checksumfile.cs}.
128
129
\item \texttt{csbackchk}: Check the checksums of files listed in the checksum
file. Notice that \texttt{csbackchk} does not check if there are new files in
130
131
132
the directory existing. Always \texttt{csbackchk} will write the results of the
checks performed to a file \texttt{checksumfile.result} which will be located in
same directory the checksumfile is located.
133
\item \texttt{csbackntfy}: Check the \texttt{csback} logfile and send a email
134
135
to the admin that contains the current status.
\end{itemize}
136
\section{Installation}
137
138
139
140
\textbf{Notice:} Up to now only provided for *nix operating systems.

To install the \texttt{csback} toolkit just use the provided \emph{Makefile} and
enter 
141
142
143
\begin{verbatim}
make install
\end{verbatim}
144
145
to the command line. If you prefer the installation by hand just guarantee that
your environment knows the \texttt{csback} scripts. First make the scripts
146
executable. Then use the appropriated names for the softlinks you are creating
147
148
149
150
in your local binary directory. For \texttt{csbackgen.py} use
\texttt{csbackgen}, for \texttt{csbackchk.py} use \texttt{csbackchk} and for
\texttt{csbackntfy.py} use \texttt{csbackntfy}. Otherwise you might run into
problems while using the \emph{crontab} generated by \texttt{csback2cron}.
151
\section{Configuration}
152
153
Before using \texttt{csback2cron} to generate a \emph{crontab} a
\texttt{csback} configuration file has to be set up. This package already
154
contains such a configuration file which contains a description of available
155
156
commands and configuration options. Afterwards either \texttt{csback2cron} has
to be called with the command
157
158
159
\begin{verbatim}
csback2cron -i path/to/configfile crontab
\end{verbatim}
160
161
or before executing \texttt{csback2cron} a \texttt{csback} configuration file
must be copied to \texttt{\$HOME/.csback/csbackrc} so that the command
162
163
164
\begin{verbatim}
csback2cron crontab
\end{verbatim}
165
is sufficient to generate a \emph{crontab} file with the filename
166
167
168
169
\texttt{crontab}. Then install the \texttt{crontab} using the appropriate
\emph{crontab} command. Note that an exemplary \texttt{csbackrc} configuration
file comes along with this package and is appended to this document
\ref{subsec:csbackrc}.
170
171
172

While converting the \texttt{csback} configuration file entries to
\texttt{crontab} lines \texttt{csback2cron} does not perform any logical checks.
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187

\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}
188
Within a \texttt{[copy]} section copy rule section headers can be defined. The
189
190
only option which is available within a \texttt{[copy]} section is the
\texttt{keys} entry. An exemplary line looks like
191
192
193
\begin{verbatim}
keys = copy1, copy2, copy3
\end{verbatim}
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
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
217
entries which are:
218
\begin{itemize}
219
220
221
\item \label{item:cronexpr} \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}.
222
223
224
225
226
227
228
229
230
\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
231
\href{http://rsync.samba.org/ftp/rsync/rsync.html}{\texttt{rsync} man page} for
232
more information on available patterns. \label{item:copy_exclude}
233
234
235
236
237
238
239
240
241
242
243
244
\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
245
246
to make sure that files backed up were copied correctly and registered in the
corresponding checksum file properly.
247
248
249

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
250
251
\texttt{keys} attribute. A exemplary \texttt{[backup]} section looks as
follows:
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
\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
Daniel Armbruster's avatar
Daniel Armbruster committed
286
287
daystart = yes
mtime = 0
288
test = yes
289
hash = sha512
290
291
tolerant = no
\end{verbatim}
292
As already within the \texttt{[copy]} rule sections in a \texttt{[backup]}
293
294
295
rule section there are obligatory entries and auxiliary entries. Obligatory
entries are:
\begin{itemize}
296
\item \texttt{cronexpr}: Cron expression. See section \ref{item:cronexpr}.
297
298
299
\item \texttt{srcdir}: Directory path to source files.
\item \texttt{targetdir}: Directory path for backup files.
\end{itemize}
300
Entries which already have a default value and so are customizable optionally
301
302
303
304
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.
305
306
307
308
309
310
311
312
313
314
315
316
Default value is \texttt{no}.
\item \texttt{copy-exclude}: Provides the same functionality as the
\texttt{exclude} key in a \texttt{[copy]} rule section in section
\ref{item:copy_exclude}.
\item \texttt{exclude}: A comma separated list of \emph{regular expressions}.
Files or directories matching one of those regular expressions will be excluded
both from the checksum file generation or rather updating process and the
integrity check afterwards. Notice that the syntax of the regular expressions
passed here differs from the patterns passed in the \texttt{copy-exclude} key.
If you are not familiar with regular expressions read
\url{http://en.wikipedia.org/wiki/Regular_expression} or
\url{http://www.regular-expressions.info/}. \label{item:exclude}
317
318
319
320
321
322
\item \texttt{daystart}: If set to \texttt{yes} then measure times (for
\texttt{amin}, \texttt{atime}, \texttt{cmin}, \texttt{ctime}, \texttt{mmin}, and
\texttt{mtime}) from the beginning of today rather than from 24 hours ago.
Default value is \texttt{no}.
\item \texttt{amin}: Exclude files which were last accessed \texttt{N} minutes
ago.
323
\item  \texttt{atime}: Exclude files which were accessed at least \texttt{N}*24
324
325
326
327
328
329
330
331
332
333
hours ago. To match \texttt{atime} +1, a file has to have been accessed at least
two days ago.
\item \texttt{cmin}: Exclude files which status was last changed \texttt{N}
minutes ago.
\item \texttt{ctime}:Exclude files which status was last changed \texttt{N}*24
hours ago.
\item \texttt{mmin}: Exclude files which data was last modified \texttt{N}
minutes ago.
\item \texttt{mtime}: Exclude files which data was last modified \texttt{N}*24
hours ago.
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
\item \texttt{recursive}: Recursive mode. If set to \texttt{yes} generating
checksum files for subdirectories is enabled. Notice that this key refers as
well to \texttt{rsync} if the \texttt{copy} key from above is set to
\texttt{yes}. Default value is \texttt{yes}. \label{item:recursive}
\item \texttt{followlinks}: If a directory contains links and this key is set to
\texttt{yes} then files will be listed to the checksum file. \texttt{csbackgen}
will generate checksum files for directories linked into \texttt{srcdir} or one
of its subdirectories. (If the \texttt{recursive} key is set to \texttt{yes}.)
Notice that this key refers as well to \texttt{rsync} if the \texttt{copy} key
from above is set to \texttt{yes}. Default value is \texttt{no}.
\item \texttt{hash}: Select a hash function algorithm for \texttt{csbackgen}.
Available values are \texttt{sha224}, \texttt{sha256}, \texttt{sha384} and
\texttt{sha512}. Default is \texttt{sha256}. \label{followlinks}
\item \texttt{test}: Enable check of the copied files integrity. Default value
is \texttt{yes}.
\item \texttt{tolerant}: Be tolerant. If set to \texttt{yes} \texttt{csbackchk}
only will issue a \emph{WARNING} to the system logger if a file listed in a
checksum file is not available anymore. Else a \emph{ERROR} will be send. This
key might be useful if \texttt{csback} is used on a filesystem that works as a
ring buffer. Default is \texttt{no}. Notice that the \texttt{csback} logging
mechanism must be enabled by setting the \texttt{logging} key from below to
\texttt{yes}. \label{item:tolerant}
\item \texttt{logging}: Enable the \texttt{csback} logging mechanism. Log
reports will be send to the system logger. A default \texttt{syslog-ng V3.0}
configuration file comes along with \texttt{csback} which send the log messages
to a file named \texttt{csback.log} located in \texttt{/var/log/}. Default value
is \texttt{yes}. Logging is strongly recommended. For an advanced
\texttt{syslog-ng} configuration read the
\href{http://www.balabit.com/dl/guides/syslog-ng-v3.0-guide-admin-en.pdf}
{\emph{syslog-ng Administrator Guide}}. \label{item:logging}
\end{itemize}

366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
\paragraph{Description of time specification}
\begin{itemize}
\item Time specification parameters all take a list of whitespace separated
parameters.
\item Files matching the time specification will be excluded from checksum
generation process. The syntax is similar to the commands of the Unix
\texttt{find} tool. Fractional parameters are not supported. See also the
\href{http://www.gnu.org/software/findutils/manual/html_mono/find.html}
{find man page}.
\item Allowed parameters are:
\begin{enumerate}
\item \texttt{+N}$\quad$for greater/older than \texttt{N},
\item \texttt{-N}$\quad$for less/younger than \texttt{N},
\item \texttt{N}$\quad\;\,$ for exactly \texttt{N}.
\end{enumerate}
\item If several \texttt{+N} (for greater than \texttt{N}) or \texttt{-N} (for
less than \texttt{N}) values are passed with one parameter the last one will
overwrite the previous values. Notice that passing several \texttt{N} arguments
is supported.
\item \texttt{cmin} and \texttt{ctime} arguments are evaluated platform
dependent i.e. time of most recent metadata change on Unix, or the time of
creation on Windows.
\end{itemize}

\paragraph{Examples for time specification}
\begin{itemize}
\item 
\begin{verbatim}
mmin -10 +3
\end{verbatim}
Exclude files which were last modified from 3 to 10 minutes ago.
\item
\begin{verbatim}
daystart yes
mtime 1
\end{verbatim}
Daniel Armbruster's avatar
Daniel Armbruster committed
402
Exclude files which were last modified yesterday.
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
\item 
\begin{verbatim}
amin -2
\end{verbatim}
Exclude files which were last read within the last 2 minutes.
\item
\begin{verbatim}
amin -2 +10
\end{verbatim}
Exclude all files which were last read more than ten minutes ago and within the
last 2 minutes.
\item
\begin{verbatim}
mtimes 5 8 +20
\end{verbatim}
Exclude all files which were last modified from 5*24h to 6*24h ago, from 8*24h
to 9*24h ago and more then 20*24h ago.
\item
\begin{verbatim}
atimes 0
\end{verbatim}
Exclude all files which were last read from 0 (now) to 24h ago.
\end{itemize}

427
\subsubsection{\texttt{test} configuration}
428
\texttt{[test]} rule sections are provided to test the files integrity from time
429
to time. The checksums of files listed in its directory's checksum file will be
430
compared to the registered checksum and so either a \emph{WARNING}, an
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
\emph{ERROR} or a \emph{CRITICAL} log message will be send to the systems logger
if \texttt{logging} is enabled. First the test rule section headers must be
defined using the \texttt{keys} option within a \texttt{[test]} section. For
example:
\begin{verbatim}
[tests]
keys = test1, test2
\end{verbatim}
so that the list of test rule section headers is comma separated. Then the
exemplary test rule sections must be defined.
\begin{verbatim}
[test_test1]
cronexpr = 50 3 * * * 
dir = /data3.bak/
tolerant = yes

[test_test2]
cronexpr = @daily
srcdir = /media/srcdir/
dir = /data2.bak/
tolerant = yes
recursive = no
logging = no
\end{verbatim}
Obligatory keys are:
\begin{itemize}
\item \texttt{cronexpr}: For a description see \ref{item:cronexpr}.
\item \texttt{dir}: The checksums of registered files will be compared to the
checksum available in the checksum file. If \texttt{logging} is enabled
\texttt{csback} will either send an \emph{ERROR} or a \emph{CRITICAL} message to
the system logger if the check was not successful.
\end{itemize}
Additionally there are some optional keys which include:
\begin{itemize}
\item \texttt{srcdir}: Optional source directory of files and subdirectories
(if the \texttt{recursive} key is set to \texttt{yes}) in which their checksums
will be compared to the checksum file located in \texttt{dir} or one of its
subdirectories. Notice to perform a test successfully the subdirectory structure
of \texttt{dir} and \texttt{srcdir} must be equal.
\item \texttt{exclude}: Exclude files or subdirectories of tests matching one of
the comma separated \emph{regular expressions} passed here. For further
information see section \ref{item:exclude}.
\item \texttt{recursive}: Disable testing integrity of files located in
subdirectories of \texttt{dir}. See also \ref{item:recursive}.
\item \texttt{followlinks}: While testing follow links both to subdirectories
and files. See also \ref{followlinks}.
\item \texttt{tolerant}: See \ref{item:tolerant}.
\item \texttt{logging}: Enable the \texttt{csback} logging mechanism. See also
\ref{item:logging}.
\end{itemize}
481
482
483
The result of the checks performed will be send to a logfile named
\texttt{checksumfile.result} which will be created in the directory the checksum
file is located.
484

485
\subsubsection{\texttt{mail} configuration}
486
487
488
489
490
491
492
493
494
495
496
497
498
499
Within a \texttt{[mail]} section the \texttt{csback} logfile checking mechanism
can be configured. There are nearly only obligatory keys. So if a \texttt{[mail]}
section in a \texttt{csback} configuration file had been defined all keys must
be set carefully to guarantee a correct functionality. \texttt{csbackntfy} does
not work yet together with a local SMTP server.
\begin{itemize}
\item \texttt{cronexpr}: Cron expression to schedule the \texttt{csback} notify
mechanism. See also \ref{item:cronexpr}.
\item \texttt{sender}: Email address of the sender.
\item \texttt{receivers}: Comma separated list of receiver email addresses.
\item \texttt{host}: Hostname of the SMTP server.
\item \texttt{port}: Port of the SMTP server.
\item \texttt{username}: Username for SMTP server.
\item \texttt{password}: Password of \texttt{username} for SMTP server. Remember
500
501
to grant read access only to the appropriate user for the \texttt{csback}
configuration file to prevent abusing the password.
502
503
504
505
\end{itemize}
The only optional key within a \texttt{[mail]} section is the \texttt{logging}
key. If logging for \texttt{csbackntfy} is desired set the value to
\texttt{yes} else to \texttt{no}. Default value is \texttt{no}.
506

507

Daniel Armbruster's avatar
Daniel Armbruster committed
508
\section{Configuration of optional *nix tools}
509
\texttt{csback} makes use of reliable *nix tools i.e. the syslog
Daniel Armbruster's avatar
Daniel Armbruster committed
510
511
512
server \texttt{syslog-ng}, \texttt{rsync} or \texttt{cron} deamon. In this
section a basic configuration of some of that tools is available. Configuring
these tools properly is necessary for a stable functionality of \texttt{csback}.
513
514
515
516

\subsection{\texttt{crontab} and \texttt{cron}}
After generating a \texttt{crontab} with \texttt{csback2cron} the
\texttt{crontab} must be added to the locally installed \texttt{cron} deamon.
517
The command
518
519
520
521
522
523
524
\begin{verbatim}
crontab <CRONTABFILENAME>
\end{verbatim}
will install the \texttt{crontab}. \texttt{crontab} itself is the name of the so
called program that installs, deinstalls or lists the tables used to drive the
\texttt{cron} deamon. With 
\begin{verbatim}
525
crontab -r
526
527
528
529
530
\end{verbatim}
the table will be deinstalled.

\subsection{\texttt{syslog-ng}}
The \texttt{csback} toolkit comes along with a basic configuration file
531
532
533
534
535
536
537
538
539
540
541
\texttt{csback\_syslog-ng.conf} for the syslog server \texttt{syslog-ng}
\ref{subsec:syslog-ng.conf}. Because \texttt{csback} only sends its log messages
to the system logger any different implementation i.e. \texttt{rsyslog} might be
used. The only prerequisite the server must fulfil is to listen on
\texttt{localhost} on \texttt{tcp port 3333}. To guarantee that
\texttt{csbackntfy} does its work properly the syslog deamon should send the log
messages to the file \texttt{/var/log/csback.log}. All these prerequisites are
fulfilled if the configuration file \texttt{csback\_syslog-ng.conf} which comes
along with this package will be installed. So add to the \texttt{syslog-ng}
configuration file (usually \texttt{/etc/syslog-ng/syslog-ng.conf}) the
following line 
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
\begin{verbatim}
include "/path/to/cfgfile/csback_syslog-ng.conf";
\end{verbatim}
Afterwards restart the \texttt{syslog} deamon.
\begin{verbatim}
sudo /etc/init.d/syslog-ng restart
\end{verbatim}

\subsection{\texttt{logrotate}}
To avoid accumulating log messages in \texttt{/var/log/csback.log} and to delete
log messages after a certain time period the program \texttt{logrotate} should
be installed on your system. Usually \texttt{logrotate} is called and scheduled
from the \texttt{cron} deamon once per day. The main configuration file is
\texttt{/etc/logrotate.conf}, other configuration files are included from
\texttt{/etc/logrotate.d/} directory. Ensure that \texttt{/etc/logrotate.conf}
contains the line
\begin{verbatim}
include /etc/logrotate.d
\end{verbatim}
Next set a link to \texttt{csback\_logrotate.conf} in
562
563
564
565
\texttt{/etc/logrotate.d/} (see appendix \ref{subsec:logrotate.conf}) or copy
this file to \texttt{/etc/logrotate.d/} directory. The next time
\texttt{logrotate} will be executed it'll check the logfile rotation
configuration of \texttt{csback.log}.
566

567
\newpage
568
569
570
571
\onecolumn
\begin{appendix}
\section{Programs}
\subsection{\texttt{csback2cron}}
572
\verbatiminput{csback2cron.help}
573
574

\subsection{\texttt{csbackgen}}
575
\verbatiminput{csbackgen.help}
576
577

\subsection{\texttt{csbackchk}}
578
\verbatiminput{csbackchk.help}
579
580

\subsection{\texttt{csbackntfy}}
581
\verbatiminput{csbackntfy.help}
582

583
584
585
586
587
588
589
590
591
592
593
594
595
596
\section{Configuration files}
\subsection{\texttt{csbackrc}}
\label{subsec:csbackrc}
\verbatiminput{../csbackrc}

\subsection{\texttt{csback\_syslog-ng.conf}}
\label{subsec:syslog-ng.conf}
\verbatiminput{../csback_syslog-ng.conf}

\subsection{\texttt{csback\_logrotate.conf}}
\label{subsec:logrotate.conf}
\verbatiminput{../csback_logrotate.conf}

\end{appendix}
597
598
\end{document}
% ----- END OF manual.tex -----