summaryrefslogtreecommitdiffabout
path: root/doc/beam-module.5in
blob: f650c6591d52b279d9ed84b26cbef180471b37c0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
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
.\" This file is part of BEAM -*- nroff -*-
.\" Copyright (C) 2012 Sergey Poznyakoff
.\"
.\" BEAM is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" BEAM is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with BEAM.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH BEAM\-MODULE 5 "January 16, 2013" "BEAM" "BEAM Programmer Reference"
.SH NAME
beam\-module \- format of 
.BR beam (1)
modules
.SH DESCRIPTION
This manual page explains how to write new modules for
.BR beam (1).
.PP
.B Beam
is a modular backup system written in shell.  It is mainly designed to
create incremental backups of file systems using
.BR tar (1),
and restore from such backups.  However, there are special kinds of
data that cannot be reliably backed up using this method.  An example
of these are SQL databases.  Simply archiving the database files while
the database engine is running is not likely to produce a reliable
backup \- such files will most probably be in inconsistent state,
because of eventual transactions not being finished at the time of the
backup.  While stopping the database for the duration of the backup
could produce a consistent backup, it is usually not an option.  The
obvious solution in this case is to create a database
.B dump
using the DBMS-specific software, and archive the created file or files.
.PP
To handle such cases,
.B beam
introduces a special entity, called
.BR "backup item" .
.SS Backup items
A backup item is a set of data that are backed up and restored using a
particular
.BR method .
.PP
In
.B beam
configuration, backup items are identified by unique names.  The
method used to back up an item is defined by the \fIitem\fB_type\fR
configuration keyword.
.SS Modules
For each backup method, defined by \fIitem\fB_type\fR keywords,
.B beam
looks for a shell script, called \fImethod\fB.sh\fR and located in the
.B @LIBDIR@/beam
directory.
.PP
For example, if the configuration file contains:
.sp
.nf
.in +2
backup_items="cfg db"

cfg_type=fs
db_type=mysql
.in
.fi
.sp
then the following files will be loaded:

  @LIBDIR@/beam/fs.sh
  @LIBDIR@/beam/mysql.sh

.PP
These files should provide the functions used to list, back up and
restore the corresponding items.
.SH MODULE FILE FORMAT
Each module file must define the following functions (\fIname\fR
stands for the name of the module):
.TP
.BR \fIname\fB_check( item )
This function is called once for each backup item before starting
backup or restore.  Its purpose is to check whether the configuration
for that particular item is correct (e.g. whether all the mandatory
configuration keywords are defined and have consistent values, etc.)

If the configuration is correct, the function shall return
.BR 0 .
Otherwise, it shall produce appropriate diagnostic messages using
.B error
or
.B abend
(see below) and return a non-zero value.

As an example, consider the
.B check
function from the
.B fs
module.  It verifies whether the two mandatory parameters,
\fIitem\fB_dir\fR and \fIitem\fB_files\fR, are defined:
.sp
.nf
.in +2
fs_check() {
  local rc=0 root files

  eval root=\\$${1}_dir
  eval files=\\$${1}_files

  test \-z "$root" && rc=1 && error "${1}_dir not set" 
  test \-z "$files" && rc=1 && error "${1}_files not set"
  return $rc
}
.in
.fi
.TP
.BR \fIname\fB_list( item , prefix )
Produces a listing of the
.B item
prefixed by
.B prefix .

This function is used by the
.B beam list
command (see
.BR beam\-list (1)).

The following is a simplified example from the
.B fs
module:
.sp
.nf
.in +2
fs_list() {
  local dir files
  
  eval dir=\\$${1}_dir files=\\$${1}_files
  echo "${2}Files and directories in $dir:$files"
}
.in
.fi
.TP
.BR \fIname\fB_backup( item )
This function backs up the given
.BR item .

A very simplified version from
the
.B fs
module illustrates this:
.sp
.nf
.in +2
fs_backup() {
  local basename text root files exclude addopts s e

  basename=$1\-$week\-$round\-$level
  eval dir=\\$${1}_dir files=\\$${1}_files
  
  $dry_run tar $verbose $taroptions \\
    \-f $backup_archive_dir/$basename.$tar_suffix \\
    \-\-listed=$backup_snapshot_dir/$basename.db \\
    \-C $dir $files
}
.TP
.BR \fIname\fB_restore( item )
This function does the opposite to \fIname\fB_backup\fR: it restores
the given item from the backup.
.SH VARIABLES
Apart from the variables defined in
.BR beam.conf (5),
a module can access the following ones:
.TP
.B week
Number of the current week in year, as a two-digit decimal number in
the range 01 to 53.  Weeks are numbered starting with the first Sunday
as the first day of week 01. For more details, see
.BR strftime (3)
conversion
.BR %U .
.TP
.B round
Number of this backup round.  See
.BR beam\-backup (1),
for a detailed discussion.
.TP
.B level
Incremental level of this backup.
.TP
.B dry_run
If the
.B dry\-run
module is enabled, the value of this variable is
.BR echo ,
otherwise it is empty.  Place this variable in front of a shell
command to ensure it will be printed, but not executed when in
.B dry\-run
mode.  For example:
.sp
.nf
.in +2
  $dry_run rm $dbdir/*
.in
.fi
.sp
The
.B dry\-run
mode is enabled by the
.BR \-\-dry\-run " or " \-n
option to
.BR beam\-backup (1)
and
.BR beam\-restore (1).
.TP
.B verbose
In verbose mode, the value of this variable is
.BR \-v ,
otherwise it is empty.  Most programs use the
.B \-v
option to enable the verbose mode, so this variable can be used in
constructing their command lines, e.g.:
.sp
.nf
.in +2
  $dry_run tar $verbose \-c \-f $archive .
.in
.fi
.sp
.TP
.B tarerror
Keeps the number of errors that occurred so far.  Increase this
variable when an error occurred, that cannot be fixed automatically by
the module.  See also the
.B tarcode
function below.
.SH FUNCTIONS
The following functions are available for use in modules:
.TP
.B logit
Writes its arguments to the selected log stream.  The resulting line
is prefixed with the current date.
.TP
.B error
Write its arguments to the standard error, prefixing the line with the
current date.
.TP
.B abend
This function takes 2 or more arguments.  The first argument is a
decimal number, treated as the shell exit code.  The rest of arguments
supplies a diagnostic message.  The function writes that message to
the standard error, and returns the supplied code to the shell.
.TP
.B tarcode
The argument is a decimal return code from a
.BR tar (1)
invocation.  The function prints a human-readable description of the
error code and increases
.B tarerror
if it is equal to or greater than 2.
.SH "SEE ALSO"
.BR beam (1),
.BR beam.conf (5).
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <@PACKAGE_BUGREPORT@>.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:

Return to:

Send suggestions and report system problems to the System administrator.