aboutsummaryrefslogtreecommitdiff
path: root/doc/beam-module.5in
blob: 99e7a63e963d4ea1c7d31f52978a8b46c51dd1e2 (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
.\" 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 "July 14, 2012" "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 insconsistent 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 DBS-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 consistend values, etc.)

If the configuration is correct, the function shall return
.BR 0 .
Otherwise, it shall produce appropiate 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 "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.