mirror
/
borg
mirror of https://github.com/borgbackup/borg.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Merge pull request #273 from yagebu/master 

docs: Some small fixes
This commit is contained in:
TW 2015-10-15 10:56:48 +02:00
parent 256f89e697 da926f2eb4
commit ba7e365238
4 changed files with 42 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/installation.rst
View File

@ -91,7 +91,7 @@ Check https://github.com/borgbackup/borg/releases for available binaries.
Debian Jessie / Ubuntu 14.04 preparations (git/pypi) Debian Jessie / Ubuntu 14.04 preparations (git/pypi)
---------------------------------------------------- ----------------------------------------------------
.. parsed-literal:: ::
# Python 3.x (>= 3.2) + Headers, Py Package Installer, VirtualEnv # Python 3.x (>= 3.2) + Headers, Py Package Installer, VirtualEnv
apt-get install python3 python3-dev python3-pip python-virtualenv apt-get install python3 python3-dev python3-pip python-virtualenv
@ -121,7 +121,7 @@ Debian Jessie / Ubuntu 14.04 preparations (git/pypi)
Korora / Fedora 21 preparations (git/pypi) Korora / Fedora 21 preparations (git/pypi)
------------------------------------------ ------------------------------------------
.. parsed-literal:: ::
# Python 3.x (>= 3.2) + Headers, Py Package Installer, VirtualEnv # Python 3.x (>= 3.2) + Headers, Py Package Installer, VirtualEnv
sudo dnf install python3 python3-devel python3-pip python3-virtualenv sudo dnf install python3 python3-devel python3-pip python3-virtualenv
@ -178,9 +178,7 @@ In case that creation of the virtual env fails, try deleting this file:
Installation (pypi) Installation (pypi)
------------------- -------------------
This uses the latest (source package) release from PyPi. This uses the latest (source package) release from PyPi. ::
.. parsed-literal::
virtualenv --python=python3 borg-env virtualenv --python=python3 borg-env
source borg-env/bin/activate # always before using! source borg-env/bin/activate # always before using!
@ -190,19 +188,17 @@ This uses the latest (source package) release from PyPi.
# 0.41 and 0.41.1 have unicode issues at install time # 0.41 and 0.41.1 have unicode issues at install time
pip install borgbackup pip install borgbackup
Note: we install into a virtual environment here, but this is not a requirement. .. note:: We install into a virtual environment here, but this is not a requirement.
Installation (git) Installation (git)
------------------ ------------------
This uses latest, unreleased development code from git. This uses latest, unreleased development code from git.
While we try not to break master, there are no guarantees on anything. While we try not to break master, there are no guarantees on anything. ::
.. parsed-literal:: # get borg from github
git clone https://github.com/borgbackup/borg.git
# get |project_name| from github, install it
git clone |git_url|
virtualenv --python=python3 borg-env virtualenv --python=python3 borg-env
source borg-env/bin/activate # always before using! source borg-env/bin/activate # always before using!
@ -218,4 +214,4 @@ While we try not to break master, there are no guarantees on anything.
# optional: run all the tests, on all supported Python versions # optional: run all the tests, on all supported Python versions
fakeroot -u tox fakeroot -u tox
Note: as a developer or power user, you always want to use a virtual environment. .. note:: As a developer or power user, you always want to use a virtual environment.

6
docs/quickstart.rst
View File

@ -100,17 +100,17 @@ Backup compression
Default is no compression, but we support different methods with high speed Default is no compression, but we support different methods with high speed
or high compression: or high compression:
If you have a quick repo storage and you want a little compression: If you have a quick repo storage and you want a little compression: ::
$ borg create --compression lz4 /mnt/backup::repo ~ $ borg create --compression lz4 /mnt/backup::repo ~
If you have a medium fast repo storage and you want a bit more compression (N=0..9, If you have a medium fast repo storage and you want a bit more compression (N=0..9,
0 means no compression, 9 means high compression): 0 means no compression, 9 means high compression): ::
$ borg create --compression zlib,N /mnt/backup::repo ~ $ borg create --compression zlib,N /mnt/backup::repo ~
If you have a very slow repo storage and you want high compression (N=0..9, 0 means If you have a very slow repo storage and you want high compression (N=0..9, 0 means
low compression, 9 means high compression): low compression, 9 means high compression): ::
$ borg create --compression lzma,N /mnt/backup::repo ~ $ borg create --compression lzma,N /mnt/backup::repo ~

55
docs/usage.rst
View File

@ -369,64 +369,67 @@ Examples
Additional Notes Additional Notes
================ ----------------
Here are misc. notes about topics that are maybe not covered in enough detail in the usage section. Here are misc. notes about topics that are maybe not covered in enough detail in the usage section.
--read-special --read-special
-------------- ~~~~~~~~~~~~~~
The option --read-special is not intended for normal, filesystem-level (full or The option ``--read-special`` is not intended for normal, filesystem-level (full or
partly-recursive) backups. You only give this option if you want to do something partly-recursive) backups. You only give this option if you want to do something
rather ... special - and if you have hand-picked some files that you want to treat rather ... special -- and if you have hand-picked some files that you want to treat
that way. that way.
`borg create --read-special` will open all files without doing any special treatment ``borg create --read-special`` will open all files without doing any special
according to the file type (the only exception here are directories: they will be treatment according to the file type (the only exception here are directories:
recursed into). Just imagine what happens if you do `cat filename` - the content they will be recursed into). Just imagine what happens if you do ``cat
you will see there is what borg will backup for that filename. filename`` --- the content you will see there is what borg will backup for that
filename.
So, for example, symlinks will be followed, block device content will be read, So, for example, symlinks will be followed, block device content will be read,
named pipes / UNIX domain sockets will be read. named pipes / UNIX domain sockets will be read.
You need to be careful with what you give as filename when using --read-special, You need to be careful with what you give as filename when using ``--read-special``,
e.g. if you give /dev/zero, your backup will never terminate. e.g. if you give ``/dev/zero``, your backup will never terminate.
The given files' metadata is saved as it would be saved without --read-special The given files' metadata is saved as it would be saved without
(e.g. its name, its size [might be 0], its mode, etc.) - but additionally, also ``--read-special`` (e.g. its name, its size [might be 0], its mode, etc.) - but
the content read from it will be saved for it. additionally, also the content read from it will be saved for it.
Restoring such files' content is currently only supported one at a time via --stdout Restoring such files' content is currently only supported one at a time via
option (and you have to redirect stdout to where ever it shall go, maybe directly ``--stdout`` option (and you have to redirect stdout to where ever it shall go,
into an existing device file of your choice or indirectly via dd). maybe directly into an existing device file of your choice or indirectly via
``dd``).
Example Example
~~~~~~~ ~~~~~~~
Imagine you have made some snapshots of logical volumes (LVs) you want to backup. Imagine you have made some snapshots of logical volumes (LVs) you want to backup.
Note: For some scenarios, this is a good method to get "crash-like" consistency .. note::
(I call it crash-like because it is the same as you would get if you just hit the
reset button or your machine would abrubtly and completely crash). For some scenarios, this is a good method to get "crash-like" consistency
This is better than no consistency at all and a good method for some use cases, (I call it crash-like because it is the same as you would get if you just
but likely not good enough if you have databases running. hit the reset button or your machine would abrubtly and completely crash).
This is better than no consistency at all and a good method for some use
cases, but likely not good enough if you have databases running.
Then you create a backup archive of all these snapshots. The backup process will Then you create a backup archive of all these snapshots. The backup process will
see a "frozen" state of the logical volumes, while the processes working in the see a "frozen" state of the logical volumes, while the processes working in the
original volumes continue changing the data stored there. original volumes continue changing the data stored there.
You also add the output of `lvdisplay` to your backup, so you can see the LV sizes You also add the output of ``lvdisplay`` to your backup, so you can see the LV
in case you ever need to recreate and restore them. sizes in case you ever need to recreate and restore them.
After the backup has completed, you remove the snapshots again. After the backup has completed, you remove the snapshots again. ::
::
$ # create snapshots here $ # create snapshots here
$ lvdisplay > lvdisplay.txt $ lvdisplay > lvdisplay.txt
$ borg create --read-special /mnt/backup::repo lvdisplay.txt /dev/vg0/*-snapshot $ borg create --read-special /mnt/backup::repo lvdisplay.txt /dev/vg0/*-snapshot
$ # remove snapshots here $ # remove snapshots here
Now, let's see how to restore some LVs from such a backup. Now, let's see how to restore some LVs from such a backup. ::
$ borg extract /mnt/backup::repo lvdisplay.txt $ borg extract /mnt/backup::repo lvdisplay.txt
$ # create empty LVs with correct sizes here (look into lvdisplay.txt). $ # create empty LVs with correct sizes here (look into lvdisplay.txt).

4
setup.py
View File

@ -184,8 +184,8 @@ class build_api(Command):
print("auto-generating API documentation") print("auto-generating API documentation")
with open("docs/api.rst", "w") as doc: with open("docs/api.rst", "w") as doc:
doc.write(""" doc.write("""
Borg Backup API documentation API Documentation
============================= =================
""") """)
for mod in glob('borg/*.py') + glob('borg/*.pyx'): for mod in glob('borg/*.py') + glob('borg/*.pyx'):
print("examining module %s" % mod) print("examining module %s" % mod)