From aa62a164d9e918d7cc54c47725e78571e4fb288e Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Mon, 31 Oct 2016 02:36:49 +0100 Subject: [PATCH 01/17] vagrant: do not try to install llfuse on centos6 it breaks everything... --- Vagrantfile | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/Vagrantfile b/Vagrantfile index cf440fb5a..229a9391a 100644 --- a/Vagrantfile +++ b/Vagrantfile @@ -40,8 +40,8 @@ def packages_debianoid EOF end -def packages_redhatted - return <<-EOF +def packages_redhatted(version) + script = <<-EOF yum install -y epel-release yum update -y # for building borgbackup and dependencies: @@ -58,6 +58,13 @@ def packages_redhatted #pip install virtualenv touch ~vagrant/.bash_profile ; chown vagrant ~vagrant/.bash_profile EOF + if version == "centos6" + script += <<-EOF + # avoid that breaking llfuse install breaks borgbackup install under tox: + sed -i.bak '/fuse.txt/d' /vagrant/borg/borg/tox.ini + EOF + end + return script end def packages_darwin @@ -325,7 +332,7 @@ Vagrant.configure(2) do |config| b.vm.provider :virtualbox do |v| v.memory = 768 end - b.vm.provision "install system packages", :type => :shell, :inline => packages_redhatted + b.vm.provision "install system packages", :type => :shell, :inline => packages_redhatted("centos7") b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("centos7_64") b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("centos7_64") b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("centos7_64") @@ -335,7 +342,7 @@ Vagrant.configure(2) do |config| config.vm.define "centos6_32" do |b| b.vm.box = "centos6-32" - b.vm.provision "install system packages", :type => :shell, :inline => packages_redhatted + b.vm.provision "install system packages", :type => :shell, :inline => packages_redhatted("centos6") b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("centos6_32") b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("centos6_32") b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("centos6_32") @@ -348,7 +355,7 @@ Vagrant.configure(2) do |config| b.vm.provider :virtualbox do |v| v.memory = 768 end - b.vm.provision "install system packages", :type => :shell, :inline => packages_redhatted + b.vm.provision "install system packages", :type => :shell, :inline => packages_redhatted("centos6") b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("centos6_64") b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("centos6_64") b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("centos6_64") From f2ed60b80bf3cf8341e1d6a2e6515152c7862538 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Mon, 31 Oct 2016 05:02:19 +0100 Subject: [PATCH 02/17] vagrant: fix fuse test for darwin, fixes #1546 otherwise the "input" dir is root.wheel -rwx------ and gives a PermissionError when trying to access it. --- borg/testsuite/archiver.py | 1 + 1 file changed, 1 insertion(+) diff --git a/borg/testsuite/archiver.py b/borg/testsuite/archiver.py index 3cd317b72..4a39d64a3 100644 --- a/borg/testsuite/archiver.py +++ b/borg/testsuite/archiver.py @@ -211,6 +211,7 @@ class ArchiverTestCaseBase(BaseTestCase): os.environ['BORG_KEYS_DIR'] = self.keys_path os.environ['BORG_CACHE_DIR'] = self.cache_path os.mkdir(self.input_path) + os.chmod(self.input_path, 0o777) # avoid troubles with fakeroot / FUSE os.mkdir(self.output_path) os.mkdir(self.keys_path) os.mkdir(self.cache_path) From 5b0bff196233a5cac0c8d4970016d9ea29275502 Mon Sep 17 00:00:00 2001 From: ololoru Date: Mon, 24 Oct 2016 21:17:58 -0500 Subject: [PATCH 03/17] add windows virtual machine * Default memory size of Windows VM is 2048 mb * Stop using mls-openssh and replace it with cygwin sshd by updating service start path in registry --- Vagrantfile | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/Vagrantfile b/Vagrantfile index cf440fb5a..e99920899 100644 --- a/Vagrantfile +++ b/Vagrantfile @@ -155,6 +155,57 @@ def packages_netbsd EOF end +# Install required cygwin packages and configure environment +# +# Microsoft/EdgeOnWindows10 image has MLS-OpenSSH installed by default, +# which is based on cygwin x86_64 but should not be used together with cygwin. +# In order to have have cygwin compatible bash 'ImagePath' is replaced with +# cygrunsrv of newly installed cygwin +# +# supported cygwin versions: +# x86_64 +# x86 +def packages_cygwin(version) + setup_exe = "setup-#{version}.exe" + + return <<-EOF + mkdir -p /cygdrive/c/cygwin + powershell -Command '$client = new-object System.Net.WebClient; $client.DownloadFile("https://www.cygwin.com/#{setup_exe}","C:\\cygwin\\#{setup_exe}")' + echo ' + REM --- Change to use different CygWin platform and final install path + set CYGSETUP=#{setup_exe} + REM --- Install build version of CygWin in a subfolder + set OURPATH=%cd% + set CYGBUILD="C:\\cygwin\\CygWin" + set CYGMIRROR=ftp://mirrors.kernel.org/sourceware/cygwin/ + set BUILDPKGS=python3,python3-setuptools,binutils,gcc-g++,libopenssl,openssl-devel,git,make,openssh,liblz4-devel,liblz4_1,rsync,curl,python-devel + %CYGSETUP% -q -B -o -n -R %CYGBUILD% -L -D -s %CYGMIRROR% -P %BUILDPKGS% + cd /d C:\\cygwin\\CygWin\\bin + regtool set /HKLM/SYSTEM/CurrentControlSet/Services/OpenSSHd/ImagePath "C:\\cygwin\\CygWin\\bin\\cygrunsrv.exe" + bash -c "ssh-host-config --no" + ' > /cygdrive/c/cygwin/install.bat + cd /cygdrive/c/cygwin && cmd.exe /c install.bat + + echo "alias mkdir='mkdir -p'" > ~/.profile + echo "export CYGWIN_ROOT=/cygdrive/c/cygwin/CygWin" >> ~/.profile + echo 'export PATH=$PATH:$CYGWIN_ROOT/bin' >> ~/.profile + + echo '' > ~/.bash_profile + + cmd.exe /c 'setx /m PATH "%PATH%;C:\\cygwin\\CygWin\\bin"' + source ~/.profile + echo 'db_home: windows' > $CYGWIN_ROOT/etc/nsswitch.conf + EOF +end + +def install_cygwin_venv + return <<-EOF + easy_install-3.4 pip + pip install virtualenv + EOF +end + + def install_pyenv(boxname) return <<-EOF curl -s -L https://raw.githubusercontent.com/yyuu/pyenv-installer/master/bin/pyenv-installer | bash @@ -466,4 +517,31 @@ Vagrant.configure(2) do |config| b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg_no_fuse("netbsd64") b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("netbsd64") end + + config.vm.define "windows10" do |b| + b.vm.box = "Microsoft/EdgeOnWindows10" + b.vm.guest = :windows + b.vm.boot_timeout = 180 + b.vm.graceful_halt_timeout = 120 + + b.ssh.shell = "sh -l" + b.ssh.username = "IEUser" + b.ssh.password = "Passw0rd!" + b.ssh.insert_key = false + + b.vm.provider :virtualbox do |v| + v.memory = 2048 + #v.gui = true + end + + # fix permissions placeholder + b.vm.provision "fix perms", :type => :shell, :privileged => false, :inline => "echo 'fix permission placeholder'" + + b.vm.provision "packages cygwin", :type => :shell, :privileged => false, :inline => packages_cygwin("x86_64") + b.vm.provision :reload + b.vm.provision "cygwin install pip", :type => :shell, :privileged => false, :inline => install_cygwin_venv + b.vm.provision "cygwin build env", :type => :shell, :privileged => false, :inline => build_sys_venv("windows10") + b.vm.provision "cygwin install borg", :type => :shell, :privileged => false, :inline => install_borg_no_fuse("windows10") + b.vm.provision "cygwin run tests", :type => :shell, :privileged => false, :inline => run_tests("windows10") + end end From 1b462cdbed5493bdb1e746e318b7f1157866f8cc Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 2 Nov 2016 03:01:49 +0100 Subject: [PATCH 04/17] vagrant: remove llfuse from tox.ini at a central place --- Vagrantfile | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/Vagrantfile b/Vagrantfile index f8e23bb79..646669afe 100644 --- a/Vagrantfile +++ b/Vagrantfile @@ -40,8 +40,8 @@ def packages_debianoid EOF end -def packages_redhatted(version) - script = <<-EOF +def packages_redhatted + return <<-EOF yum install -y epel-release yum update -y # for building borgbackup and dependencies: @@ -58,13 +58,6 @@ def packages_redhatted(version) #pip install virtualenv touch ~vagrant/.bash_profile ; chown vagrant ~vagrant/.bash_profile EOF - if version == "centos6" - script += <<-EOF - # avoid that breaking llfuse install breaks borgbackup install under tox: - sed -i.bak '/fuse.txt/d' /vagrant/borg/borg/tox.ini - EOF - end - return script end def packages_darwin @@ -130,8 +123,6 @@ def packages_openbsd easy_install-3.4 pip pip3 install virtualenv touch ~vagrant/.bash_profile ; chown vagrant ~vagrant/.bash_profile - # avoid that breaking llfuse install breaks borgbackup install under tox: - sed -i.bak '/fuse.txt/d' /vagrant/borg/borg/tox.ini EOF end @@ -157,8 +148,6 @@ def packages_netbsd easy_install-3.4 pip pip install virtualenv touch ~vagrant/.bash_profile ; chown vagrant ~vagrant/.bash_profile - # fuse does not work good enough (see above), do not install llfuse: - sed -i.bak '/fuse.txt/d' /vagrant/borg/borg/tox.ini EOF end @@ -289,6 +278,8 @@ def install_borg_no_fuse(boxname) rm -rf borg/__pycache__ borg/support/__pycache__ borg/testsuite/__pycache__ pip install -r requirements.d/development.txt pip install -e . + # do not install llfuse into the virtualenvs built by tox: + sed -i.bak '/fuse.txt/d' tox.ini EOF end @@ -383,7 +374,7 @@ Vagrant.configure(2) do |config| b.vm.provider :virtualbox do |v| v.memory = 768 end - b.vm.provision "install system packages", :type => :shell, :inline => packages_redhatted("centos7") + b.vm.provision "install system packages", :type => :shell, :inline => packages_redhatted b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("centos7_64") b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("centos7_64") b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("centos7_64") @@ -393,7 +384,7 @@ Vagrant.configure(2) do |config| config.vm.define "centos6_32" do |b| b.vm.box = "centos6-32" - b.vm.provision "install system packages", :type => :shell, :inline => packages_redhatted("centos6") + b.vm.provision "install system packages", :type => :shell, :inline => packages_redhatted b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("centos6_32") b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("centos6_32") b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("centos6_32") @@ -406,7 +397,7 @@ Vagrant.configure(2) do |config| b.vm.provider :virtualbox do |v| v.memory = 768 end - b.vm.provision "install system packages", :type => :shell, :inline => packages_redhatted("centos6") + b.vm.provision "install system packages", :type => :shell, :inline => packages_redhatted b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("centos6_64") b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("centos6_64") b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("centos6_64") From df7191e55c6e09a8bdd194a5c3688114d549ea2c Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 2 Nov 2016 04:09:16 +0100 Subject: [PATCH 05/17] skip remote tests on cygwin remote is broken and hangs infinitely on cygwin. https://github.com/borgbackup/borg/issues/1268 --- borg/testsuite/archiver.py | 2 +- borg/testsuite/repository.py | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/borg/testsuite/archiver.py b/borg/testsuite/archiver.py index 4a39d64a3..b0fa1a118 100644 --- a/borg/testsuite/archiver.py +++ b/borg/testsuite/archiver.py @@ -1444,7 +1444,7 @@ class ArchiverCheckTestCase(ArchiverTestCaseBase): self.cmd('check', self.repository_location, exit_code=0) self.cmd('extract', '--dry-run', self.repository_location + '::archive1', exit_code=0) - +@pytest.mark.skipif(sys.platform == 'cygwin', reason='remote is broken on cygwin and hangs') class RemoteArchiverTestCase(ArchiverTestCase): prefix = '__testsuite__:' diff --git a/borg/testsuite/repository.py b/borg/testsuite/repository.py index b95093e4a..e217137af 100644 --- a/borg/testsuite/repository.py +++ b/borg/testsuite/repository.py @@ -4,6 +4,8 @@ import sys import tempfile from unittest.mock import patch +import pytest + from ..hashindex import NSIndex from ..helpers import Location, IntegrityError from ..locking import Lock, LockFailed @@ -413,6 +415,7 @@ class RepositoryCheckTestCase(RepositoryTestCaseBase): self.assert_equal(self.repository.get(H(0)), b'data2') +@pytest.mark.skipif(sys.platform == 'cygwin', reason='remote is broken on cygwin and hangs') class RemoteRepositoryTestCase(RepositoryTestCase): def open(self, create=False): @@ -443,6 +446,7 @@ class RemoteRepositoryTestCase(RepositoryTestCase): assert self.repository.borg_cmd(args, testing=False) == ['borg-0.28.2', 'serve', '--umask=077', '--info'] +@pytest.mark.skipif(sys.platform == 'cygwin', reason='remote is broken on cygwin and hangs') class RemoteRepositoryCheckTestCase(RepositoryCheckTestCase): def open(self, create=False): From 7f9a147e46a3d2923b9b4cc2e0d786a2a43f5df9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Thu, 3 Nov 2016 14:03:48 -0400 Subject: [PATCH 06/17] move fork differences to FAQ it seems now that the fork is more of historical value than a current thing. people interested in the differences between borg and attic can look in the FAQ, but I do not see why this is present in the README. a new section regarding compatibility is created to keep that warning in place. --- README.rst | 39 ++++----------------------------------- docs/faq.rst | 29 +++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 35 deletions(-) diff --git a/README.rst b/README.rst index 57af39576..e9a59f4ee 100644 --- a/README.rst +++ b/README.rst @@ -78,8 +78,8 @@ Main features **Free and Open Source Software** * security and functionality can be audited independently - * licensed under the BSD (3-clause) license - + * licensed under the BSD (3-clause) license, see `License`_ for the + complete license Easy to use ----------- @@ -143,37 +143,8 @@ Links `Mailing List `_ * `License `_ -Notes ------ - -Borg is a fork of `Attic`_ and maintained by "`The Borg collective`_". - -.. _Attic: https://github.com/jborg/attic -.. _The Borg collective: https://borgbackup.readthedocs.org/en/latest/authors.html - -Differences between Attic and Borg -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Here's a (incomplete) list of some major changes: - -* more open, faster paced development (see `issue #1 `_) -* lots of attic issues fixed (see `issue #5 `_) -* less chunk management overhead (less memory and disk usage for chunks index) -* faster remote cache resync (useful when backing up multiple machines into same repo) -* compression: no, lz4, zlib or lzma compression, adjustable compression levels -* repokey replaces problematic passphrase mode (you can't change the passphrase nor the pbkdf2 iteration count in "passphrase" mode) -* simple sparse file support, great for virtual machine disk files -* can read special files (e.g. block devices) or from stdin, write to stdout -* mkdir-based locking is more compatible than attic's posix locking -* uses fadvise to not spoil / blow up the fs cache -* better error messages / exception handling -* better logging, screen output, progress indication -* tested on misc. Linux systems, 32 and 64bit, FreeBSD, OpenBSD, NetBSD, Mac OS X - -Please read the `ChangeLog`_ (or ``docs/changes.rst`` in the source distribution) for more -information. - -BORG IS NOT COMPATIBLE WITH ORIGINAL ATTIC (but there is a one-way conversion). +Compatibility notes +=================== EXPECT THAT WE WILL BREAK COMPATIBILITY REPEATEDLY WHEN MAJOR RELEASE NUMBER CHANGES (like when going from 0.x.y to 1.0.0 or from 1.x.y to 2.0.0). @@ -182,8 +153,6 @@ NOT RELEASED DEVELOPMENT VERSIONS HAVE UNKNOWN COMPATIBILITY PROPERTIES. THIS IS SOFTWARE IN DEVELOPMENT, DECIDE YOURSELF WHETHER IT FITS YOUR NEEDS. -Borg is distributed under a 3-clause BSD license, see `License`_ for the complete license. - |doc| |build| |coverage| |bestpractices| .. |doc| image:: https://readthedocs.org/projects/borgbackup/badge/?version=stable diff --git a/docs/faq.rst b/docs/faq.rst index 47d0ce1a2..3622b3cf7 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -512,3 +512,32 @@ Borg intends to be: * do not break compatibility accidentally, without a good reason or without warning. allow compatibility breaking for other cases. * if major version number changes, it may have incompatible changes + +What are the differences between Attic and Borg? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Borg is a fork of `Attic`_ and maintained by "`The Borg collective`_". + +.. _Attic: https://github.com/jborg/attic +.. _The Borg collective: https://borgbackup.readthedocs.org/en/latest/authors.html + +Here's a (incomplete) list of some major changes: + +* more open, faster paced development (see `issue #1 `_) +* lots of attic issues fixed (see `issue #5 `_) +* less chunk management overhead (less memory and disk usage for chunks index) +* faster remote cache resync (useful when backing up multiple machines into same repo) +* compression: no, lz4, zlib or lzma compression, adjustable compression levels +* repokey replaces problematic passphrase mode (you can't change the passphrase nor the pbkdf2 iteration count in "passphrase" mode) +* simple sparse file support, great for virtual machine disk files +* can read special files (e.g. block devices) or from stdin, write to stdout +* mkdir-based locking is more compatible than attic's posix locking +* uses fadvise to not spoil / blow up the fs cache +* better error messages / exception handling +* better logging, screen output, progress indication +* tested on misc. Linux systems, 32 and 64bit, FreeBSD, OpenBSD, NetBSD, Mac OS X + +Please read the `ChangeLog`_ (or ``docs/changes.rst`` in the source distribution) for more +information. + +Borg is not compatible with original attic (but there is a one-way conversion). From 18f3d64e4ca3b775e47083a3b7065f7308f8c877 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Thu, 3 Nov 2016 12:38:31 -0400 Subject: [PATCH 07/17] PDF docs: add logo and fix authors the PDF documentation looks much better with those --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 26d405d11..8087b4300 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -199,12 +199,12 @@ htmlhelp_basename = 'borgdoc' # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'Borg.tex', 'Borg Documentation', - 'see "AUTHORS" file', 'manual'), + 'The Borg Collective', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. -#latex_logo = None +latex_logo = '_static/logo.png' # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. From 5def2350d06b1bdcb5d5ec5e3880bdbaa5bbbc78 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Thu, 3 Nov 2016 12:54:07 -0500 Subject: [PATCH 08/17] fix PDF rendering structure without those changes, all of the toctree document headings do not show up. they are considered to be "below" the last heading of the README file. we also remove the "Notes" section from the readme as there is only one note, regarding the fork. we introduce a stub "introduction" element in the toctree, otherwise it is impossible for the PDF rendered to render the README correctly. this is to workaround a bug in the PDF renderer. --- README.rst | 12 ++++++------ docs/book.rst | 22 ++++++++++++++++++++++ docs/conf.py | 2 +- docs/index.rst | 2 ++ docs/introduction.rst | 8 ++++++++ 5 files changed, 39 insertions(+), 7 deletions(-) create mode 100644 docs/book.rst create mode 100644 docs/introduction.rst diff --git a/README.rst b/README.rst index e9a59f4ee..5044bc4e6 100644 --- a/README.rst +++ b/README.rst @@ -3,7 +3,7 @@ .. highlight:: bash What is BorgBackup? -=================== +------------------- BorgBackup (short: Borg) is a deduplicating backup program. Optionally, it supports compression and authenticated encryption. @@ -20,7 +20,7 @@ downloaded Borg, ``docs/installation.rst`` to get started with Borg. .. _installation manual: https://borgbackup.readthedocs.org/en/stable/installation.html Main features -------------- +~~~~~~~~~~~~~ **Space efficient storage** Deduplication based on content-defined chunking is used to reduce the number @@ -82,7 +82,7 @@ Main features complete license Easy to use ------------ +~~~~~~~~~~~ Initialize a new backup repository and create a backup archive:: @@ -114,7 +114,7 @@ Now doing another backup, just to show off the great deduplication: For a graphical frontend refer to our complementary project `BorgWeb `_. Checking Release Authenticity and Security Contact -================================================== +-------------------------------------------------- `Releases `_ are signed with this GPG key, please use GPG to verify their authenticity. @@ -130,7 +130,7 @@ The public key can be fetched from any GPG keyserver, but be careful: you must use the **full fingerprint** to check that you got the correct key. Links -===== +----- * `Main Web Site `_ * `Releases `_, @@ -144,7 +144,7 @@ Links * `License `_ Compatibility notes -=================== +------------------- EXPECT THAT WE WILL BREAK COMPATIBILITY REPEATEDLY WHEN MAJOR RELEASE NUMBER CHANGES (like when going from 0.x.y to 1.0.0 or from 1.x.y to 2.0.0). diff --git a/docs/book.rst b/docs/book.rst new file mode 100644 index 000000000..33e756839 --- /dev/null +++ b/docs/book.rst @@ -0,0 +1,22 @@ +.. include:: global.rst.inc + +Borg documentation +================== + +.. when you add an element here, do not forget to add it to index.rst + +.. toctree:: + :maxdepth: 3 + + introduction + installation + quickstart + usage + deployment + faq + support + resources + changes + internals + development + authors diff --git a/docs/conf.py b/docs/conf.py index 8087b4300..cd27d3fda 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -198,7 +198,7 @@ htmlhelp_basename = 'borgdoc' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'Borg.tex', 'Borg Documentation', + ('book', 'Borg.tex', 'Borg Documentation', 'The Borg Collective', 'manual'), ] diff --git a/docs/index.rst b/docs/index.rst index 89a907dee..67e7a7663 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,8 @@ Borg Documentation .. include:: ../README.rst +.. when you add an element here, do not forget to add it to book.rst + .. toctree:: :maxdepth: 2 diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 000000000..ab8bd32c4 --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1,8 @@ +Introduction +============ + +.. this shim is here to fix the structure in the PDF + rendering. without this stub, the elements in the toctree of + index.rst show up a level below the README file included + +.. include:: ../README.rst From aeb10d1a85649fcb099898ede07ffb2a63b2de39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Thu, 3 Nov 2016 13:57:49 -0400 Subject: [PATCH 09/17] show URLs in PDF, better font --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index cd27d3fda..8163bc7e1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -193,7 +193,7 @@ htmlhelp_basename = 'borgdoc' #latex_paper_size = 'letter' # The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' +latex_font_size = '12pt' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). @@ -214,7 +214,7 @@ latex_logo = '_static/logo.png' #latex_show_pagerefs = False # If true, show URL addresses after external links. -#latex_show_urls = False +latex_show_urls = 'footnote' # Additional stuff for the LaTeX preamble. #latex_preamble = '' From b4d038878518b7cba3221a87a1110604834d497c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Thu, 3 Nov 2016 14:10:38 -0400 Subject: [PATCH 10/17] move security verification to support section the rationale is to simplify the README file to the bare minimum. security researchers will be able to find the contact information if they look minimally and people installing the software will find a link where relevant (in binary releases only, since all the others have other trust paths) --- README.rst | 16 ---------------- docs/installation.rst | 3 +++ docs/support.rst | 18 ++++++++++++++++++ 3 files changed, 21 insertions(+), 16 deletions(-) diff --git a/README.rst b/README.rst index 5044bc4e6..af05ff04f 100644 --- a/README.rst +++ b/README.rst @@ -113,22 +113,6 @@ Now doing another backup, just to show off the great deduplication: For a graphical frontend refer to our complementary project `BorgWeb `_. -Checking Release Authenticity and Security Contact --------------------------------------------------- - -`Releases `_ are signed with this GPG key, -please use GPG to verify their authenticity. - -In case you discover a security issue, please use this contact for reporting it privately -and please, if possible, use encrypted E-Mail: - -Thomas Waldmann - -GPG Key Fingerprint: 6D5B EF9A DD20 7580 5747 B70F 9F88 FB52 FAF7 B393 - -The public key can be fetched from any GPG keyserver, but be careful: you must -use the **full fingerprint** to check that you got the correct key. - Links ----- diff --git a/docs/installation.rst b/docs/installation.rst index 523f43cdb..ff5cf7d1a 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -64,6 +64,9 @@ and compare that to our latest release and review the :doc:`changes`. Standalone Binary ----------------- +.. note:: Releases are signed with an OpenPGP key, see + :ref:`security-contact` for more instructions. + |project_name| binaries (generated with `pyinstaller`_) are available on the releases_ page for the following platforms: diff --git a/docs/support.rst b/docs/support.rst index 9d64621fc..5ee34de96 100644 --- a/docs/support.rst +++ b/docs/support.rst @@ -56,3 +56,21 @@ As a developer, you can become a Bounty Hunter and win bounties (earn money) by contributing to |project_name|, a free and open source software project. We might also use BountySource to fund raise for some bigger goals. + +.. _security-contact: + +Security +-------- + +In case you discover a security issue, please use this contact for reporting it privately +and please, if possible, use encrypted E-Mail: + +Thomas Waldmann + +GPG Key Fingerprint: 6D5B EF9A DD20 7580 5747 B70F 9F88 FB52 FAF7 B393 + +The public key can be fetched from any GPG keyserver, but be careful: you must +use the **full fingerprint** to check that you got the correct key. + +`Releases `_ are signed with this GPG key, +please use GPG to verify their authenticity. From 19ae2a78701091aaa9df048f9f589ffd234c8653 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Fri, 4 Nov 2016 10:28:53 -0400 Subject: [PATCH 11/17] add FAQ about security --- docs/faq.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/faq.rst b/docs/faq.rst index 3622b3cf7..49b837a12 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -203,6 +203,13 @@ Thus: - have media at another place - have a relatively recent backup on your media +How do I report security issue with |project_name|? +--------------------------------------------------- + +Send a private email to the :ref:`security-contact` if you think you +have discovered a security issue. Please disclose security issues +responsibly. + Why do I get "connection closed by remote" after a while? --------------------------------------------------------- From 0cda9d6bd31f767cdb9026ccd585bc979b29548e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Fri, 4 Nov 2016 10:31:27 -0400 Subject: [PATCH 12/17] add link to security contact in README --- README.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.rst b/README.rst index af05ff04f..e7f892c7b 100644 --- a/README.rst +++ b/README.rst @@ -137,6 +137,9 @@ NOT RELEASED DEVELOPMENT VERSIONS HAVE UNKNOWN COMPATIBILITY PROPERTIES. THIS IS SOFTWARE IN DEVELOPMENT, DECIDE YOURSELF WHETHER IT FITS YOUR NEEDS. +Security issues should be reported to the :ref:`security-contact` (or +see ``docs/suppport.rst`` in the source distribution). + |doc| |build| |coverage| |bestpractices| .. |doc| image:: https://readthedocs.org/projects/borgbackup/badge/?version=stable From 319ecd81bb74788d135c89e844409598f05a270c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Fri, 4 Nov 2016 11:26:02 -0400 Subject: [PATCH 13/17] fix links in standalone README github and standalone docutils don't parse :ref: tags correctly --- README.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index e7f892c7b..2c407c1d3 100644 --- a/README.rst +++ b/README.rst @@ -126,6 +126,7 @@ Links * `Web-Chat (IRC) `_ and `Mailing List `_ * `License `_ +* `Security contact `_ Compatibility notes ------------------- @@ -137,7 +138,7 @@ NOT RELEASED DEVELOPMENT VERSIONS HAVE UNKNOWN COMPATIBILITY PROPERTIES. THIS IS SOFTWARE IN DEVELOPMENT, DECIDE YOURSELF WHETHER IT FITS YOUR NEEDS. -Security issues should be reported to the :ref:`security-contact` (or +Security issues should be reported to the `Security contact`_ (or see ``docs/suppport.rst`` in the source distribution). |doc| |build| |coverage| |bestpractices| From af23eea39dc3e5e97c6262dbccad6e863171d03f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Fri, 4 Nov 2016 20:14:59 -0500 Subject: [PATCH 14/17] fix levels in authors section that way in the TOC, it doesn't look like borg authors are attic --- AUTHORS | 4 ++-- docs/authors.rst | 3 +++ 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/AUTHORS b/AUTHORS index 4788133e4..9749b1c52 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,5 +1,5 @@ -Borg Contributors ("The Borg Collective") -========================================= +Borg authors ("The Borg Collective") +------------------------------------ - Thomas Waldmann - Antoine Beaupré diff --git a/docs/authors.rst b/docs/authors.rst index c368035d6..bca9b5de9 100644 --- a/docs/authors.rst +++ b/docs/authors.rst @@ -1,5 +1,8 @@ .. include:: global.rst.inc +Authors +======= + .. include:: ../AUTHORS License From ec0ef2eaca7b41d71932ac9d54c069fddc5267bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Fri, 4 Nov 2016 21:15:31 -0400 Subject: [PATCH 15/17] remove third level headings, too verbose --- docs/book.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book.rst b/docs/book.rst index 33e756839..679a05223 100644 --- a/docs/book.rst +++ b/docs/book.rst @@ -6,7 +6,7 @@ Borg documentation .. when you add an element here, do not forget to add it to index.rst .. toctree:: - :maxdepth: 3 + :maxdepth: 2 introduction installation From 057ad07d4b5967f82af6ffcac6a45e002cd34093 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Fri, 4 Nov 2016 21:16:41 -0400 Subject: [PATCH 16/17] fix a heading that was incorrectly set --- docs/faq.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq.rst b/docs/faq.rst index 49b837a12..a7fc74b17 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -521,7 +521,7 @@ Borg intends to be: * if major version number changes, it may have incompatible changes What are the differences between Attic and Borg? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------------ Borg is a fork of `Attic`_ and maintained by "`The Borg collective`_". From adfd66d636e56cf21a7027e4169fcaf2d48b0197 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Fri, 4 Nov 2016 21:27:21 -0400 Subject: [PATCH 17/17] restore normal size otherwise code examples overflow --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 8163bc7e1..94e088d5f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -193,7 +193,7 @@ htmlhelp_basename = 'borgdoc' #latex_paper_size = 'letter' # The font size ('10pt', '11pt' or '12pt'). -latex_font_size = '12pt' +#latex_font_size = '12pt' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]).