| 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 |
|