Debian Codegraph @

docs/manual/intro.rst

raw
1 .. _cedar-intro:
2
3 Introduction
4 ============
5
6 “Only wimps use tape backup: real men just upload their important
7 stuff on ftp, and let the rest of the world mirror it.”--- Linus
8 Torvalds, at the release of Linux 2.0.8 in July of 1996.
9
10 .. _cedar-intro-whatis:
11
12 What is Cedar Backup?
13 ---------------------
14
15 Cedar Backup is a software package designed to manage system backups for
16 a pool of local and remote machines. Cedar Backup understands how to
17 back up filesystem data as well as MySQL and PostgreSQL databases and
18 Subversion repositories. It can also be easily extended to support other
19 kinds of data sources.
20
21 Cedar Backup is focused around weekly backups to a single CD or DVD
22 disc, with the expectation that the disc will be changed or overwritten
23 at the beginning of each week. If your hardware is new enough (and
24 almost all hardware is today), Cedar Backup can write multisession
25 discs, allowing you to add incremental data to a disc on a daily basis.
26
27 Alternately, Cedar Backup can write your backups to the Amazon S3 cloud
28 rather than relying on physical media.
29
30 Besides offering command-line utilities to manage the backup process,
31 Cedar Backup provides a well-organized library of backup-related
32 functionality, written in the Python 3 programming language.
33
34 There are many different backup software systems in the open source world.
35 Cedar Backup aims to fill a niche: it aims to be a good fit for people who need
36 to back up a limited amount of important data on a regular basis. Cedar Backup
37 isn’t for you if you want to back up your huge MP3 collection every night, or
38 if you want to back up a few hundred machines. However, if you administer a
39 small set of machines and you want to run daily incremental backups for things
40 like system configuration, current email, small web sites, source code
41 repositories, or small databases, then Cedar Backup is probably worth your
42 time.
43
44 Cedar Backup has been developed on a Debian GNU/Linux system and is
45 primarily supported on Debian and other Linux systems. However, since it
46 is written in portable Python 3, it should run without problems on just
47 about any UNIX-like operating system. In particular, full Cedar Backup
48 functionality is known to work on Debian and SuSE Linux systems, and
49 client functionality is also known to work on FreeBSD and Mac OS X
50 systems.
51
52 To run a Cedar Backup client, you really just need a working Python 3
53 installation. To run a Cedar Backup master, you will also need a set of
54 other executables, most of which are related to building and writing
55 CD/DVD images or talking to the Amazon S3 infrastructure. A full list of
56 dependencies is provided in :doc:`install`.
57
58 .. _cedar-intro-migrating:
59
60 Migrating from Version 2 to Version 3
61 -------------------------------------
62
63 The main difference between Cedar Backup version 2 and Cedar Backup
64 version 3 is the targeted Python interpreter. Cedar Backup version 2 was
65 designed for Python 2, while version 3 is a conversion of the original
66 code to Python 3. Other than that, both versions are functionally
67 equivalent. The configuration format is unchanged, and you can
68 mix-and-match masters and clients of different versions in the same
69 backup pool. Python 2 has now reached its end of life, and Cedar Backup v2 has
70 been unsupported since 11 Nov 2017.
71
72 A major design goal for version 3 was to facilitate easy migration testing for
73 users, by making it possible to install version 3 on the same server where
74 version 2 was already in use. A side effect of this design choice is that all
75 of the executables, configuration files, and logs changed names in version 3.
76 Where version 2 used ``cback``, version 3 uses ``cback3``: ``cback3.conf``
77 instead of ``cback.conf``, ``cback3.log`` instead of ``cback.log``, etc.
78
79 So, while migrating from version 2 to version 3 is relatively
80 straightforward, you will have to make some changes manually. You will
81 need to create a new configuration file (or soft link to the old one),
82 modify your cron jobs to use the new executable name, etc. You can
83 migrate one server at a time in your pool with no ill effects, or even
84 incrementally migrate a single server by using version 2 and version 3
85 on different days of the week or for different parts of the backup.
86
87 .. _cedar-intro-support:
88
89 How to Get Support
90 ------------------
91
92 Cedar Backup is open source software that is provided to you at no cost.
93 It is provided with no warranty, not even for MERCHANTABILITY or FITNESS
94 FOR A PARTICULAR PURPOSE. However, that said, someone can usually help
95 you solve whatever problems you might see.
96
97 If you experience a problem, your best bet is to file an issue in the
98 issue tracker at GitHub. [1]_ When the source code was hosted at
99 SourceForge, there was a mailing list. However, it was very lightly used
100 in the last years before I abandoned SourceForge, and I have decided not
101 to replace it.
102
103 If you are not comfortable discussing your problem in public or listing
104 it in a public database, or if you need to send along information that
105 you do not want made public, then you can write
106 [email protected]. That mail will go directly to me. If you
107 write the support address about a bug, a “scrubbed” bug report will
108 eventually end up in the public bug database anyway, so if at all
109 possible you should use the public reporting mechanisms. One of the
110 strengths of the open-source software development model is its
111 transparency.
112
113 Regardless of how you report your problem, please try to provide as much
114 information as possible about the behavior you observed and the
115 environment in which the problem behavior occurred. [2]_
116
117 In particular, you should provide: the version of Cedar Backup that you
118 are using; how you installed Cedar Backup (i.e. Debian package, source
119 package, etc.); the exact command line that you executed; any error
120 messages you received, including Python stack traces (if any); and
121 relevant sections of the Cedar Backup log. It would be even better if
122 you could describe exactly how to reproduce the problem, for instance by
123 including your entire configuration file and/or specific information
124 about your system that might relate to the problem. However, please do
125 *not* provide huge sections of debugging logs unless you are sure they
126 are relevant or unless someone asks for them.
127
128 |tip|
129
130 Sometimes, the error that Cedar Backup displays can be rather
131 cryptic. This is because under internal error conditions, the text
132 related to an exception might get propogated all of the way up to the
133 user interface. If the message you receive doesn't make much sense,
134 or if you suspect that it results from an internal error, you might
135 want to re-run Cedar Backup with the ``--stack`` option. This forces
136 Cedar Backup to dump the entire Python stack trace associated with
137 the error, rather than just printing the last message it received.
138 This is good information to include along with a bug report, as well.
139
140 .. _cedar-intro-history:
141
142 History
143 -------
144
145 Cedar Backup began life in late 2000 as a set of Perl scripts called
146 kbackup. These scripts met an immediate need (which was to back up
147 skyjammer.com and some personal machines) but proved to be unstable,
148 overly verbose and rather difficult to maintain.
149
150 In early 2002, work began on a rewrite of kbackup. The goal was to
151 address many of the shortcomings of the original application, as well as
152 to clean up the code and make it available to the general public. While
153 doing research related to code I could borrow or base the rewrite on, I
154 discovered that there was already an existing backup package with the
155 name kbackup, so I decided to change the name to Cedar Backup instead.
156
157 Because I had become fed up with the prospect of maintaining a large volume of
158 Perl code, I decided to abandon that language in favor of Python. At the time,
159 I chose Python mostly because I was interested in learning it, but in
160 retrospect it turned out to be a very good decision.
161
162 Around this same time, skyjammer.com and cedar-solutions.com were
163 converted to run Debian GNU/Linux and I entered the Debian new maintainer
164 queue, so I also made it a goal to implement Debian packages along with a
165 Python source distribution for the new release.
166
167 Version 1.0 of Cedar Backup was released in June of 2002. We immediately
168 began using it to back up skyjammer.com and cedar-solutions.com, where
169 it proved to be much more stable than the original code.
170
171 In the meantime, I continued to improve as a Python programmer and also
172 started doing a significant amount of professional development in Java.
173 It soon became obvious that the internal structure of Cedar Backup 1.0,
174 while much better than kbackup, still left something to be desired. In
175 November 2003, I began an attempt at cleaning up the codebase. I
176 converted all of the internal documentation to use Epydoc, and
177 updated the code to use the newly-released Python logging package
178 after having a good experience with Java's log4j. However, I was still
179 not satisfied with the code, which did not lend itself to the automated
180 regression testing I had used when working with JUnit in my Java code.
181
182 So, rather than releasing the cleaned-up code, I instead began another
183 ground-up rewrite in May 2004. With this rewrite, I applied everything I
184 had learned from other Java and Python projects I had undertaken over
185 the last few years. I structured the code to take advantage of Python's
186 unique ability to blend procedural code with object-oriented code, and I
187 made automated unit testing a primary requirement. The result was the
188 2.0 release, which was cleaner, more compact, better focused, and better
189 documented than any release before it. Utility code is less
190 application-specific, and is now usable as a general-purpose library.
191 The 2.0 release also includes a complete regression test suite of over
192 3800 tests, which will help to ensure that quality is maintained as
193 development continues into the future.
194
195 The 3.0 release of Cedar Backup is a Python 3 conversion of the 2.0 release,
196 with minimal additional functionality. The conversion from Python 2 to Python 3
197 started in mid-2015, about 5 years before the anticipated deprecation of Python
198 2 in 2020. In 2020, the Python package structure, development tooling, and
199 documentation format were modernized, preparing Cedar Backup for the next phase
200 of its life.
201
202 ----------
203
204 *Previous*: :doc:`preface` • *Next*: :doc:`basic`
205
206 ----------
207
208 .. [1]
209 See `<https://github.com/pronovic/cedar-backup3/issues>`__
210
211 .. [2]
212 See Simon Tatham's excellent bug reporting tutorial:
213 `<http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`__ .
214
215 .. |note| image:: images/note.png
216 .. |tip| image:: images/tip.png
217 .. |warning| image:: images/warning.png
218