Index: borgbackup2/.editorconfig =================================================================== --- borgbackup2.orig/.editorconfig +++ /dev/null @@ -1,11 +0,0 @@ -# EditorConfig is awesome: https://editorconfig.org/ - -root = true - -[*] -end_of_line = lf -charset = utf-8 -indent_style = space -indent_size = 4 -insert_final_newline = true -trim_trailing_whitespace = true Index: borgbackup2/.gitattributes =================================================================== --- borgbackup2.orig/.gitattributes +++ /dev/null @@ -1,5 +0,0 @@ -borg/_version.py export-subst - -*.py diff=python -docs/usage/*.rst.inc merge=ours -docs/man/* merge=ours Index: borgbackup2/.github/FUNDING.yml =================================================================== --- borgbackup2.orig/.github/FUNDING.yml +++ /dev/null @@ -1,6 +0,0 @@ -# These are supported funding model platforms - -github: borgbackup -liberapay: borgbackup -open_collective: borgbackup -custom: ['https://www.borgbackup.org/support/fund.html'] Index: borgbackup2/.github/ISSUE_TEMPLATE.md =================================================================== --- borgbackup2.orig/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,54 +0,0 @@ - - -## Have you checked the BorgBackup docs, FAQ, and open GitHub issues? - -No - -## Is this a bug/issue report or a question? - -Bug/Issue/Question - -## System information. For client/server mode, post info for both machines. - -#### Your Borg version (borg -V). - -#### Operating system (distribution) and version. - -#### Hardware/network configuration and filesystems used. - -#### How much data is handled by Borg? - -#### Full Borg command line that led to the problem (leave out excludes and passwords). - - -## Describe the problem you're observing. - -#### Can you reproduce the problem? If so, describe how. If not, describe troubleshooting steps you took before opening the issue. - -#### Include any warnings/errors/backtraces from the system logs - - Index: borgbackup2/.github/PULL_REQUEST_TEMPLATE =================================================================== --- borgbackup2.orig/.github/PULL_REQUEST_TEMPLATE +++ /dev/null @@ -1,8 +0,0 @@ -Thank you for contributing code to Borg; your help is appreciated! - -Before you submit a pull request, please make sure it complies with the -guidelines in our documentation: - -https://borgbackup.readthedocs.io/en/latest/development.html#contributions - -**Please remove the text above before submitting your pull request.** Index: borgbackup2/.github/workflows/backport.yml =================================================================== --- borgbackup2.orig/.github/workflows/backport.yml +++ /dev/null @@ -1,37 +0,0 @@ -name: Backport pull request - -on: - pull_request_target: - types: [closed] - issue_comment: - types: [created] - -permissions: - contents: write # so it can comment - pull-requests: write # so it can create pull requests - -jobs: - backport: - name: Backport pull request - runs-on: ubuntu-24.04 - - # Only run when pull request is merged - # or when a comment starting with `/backport` is created by someone other than the - # https://github.com/backport-action bot user (user id: 97796249). Note that if you use your - # own PAT as `github_token`, that you should replace this id with yours. - if: > - ( - github.event_name == 'pull_request_target' && - github.event.pull_request.merged - ) || ( - github.event_name == 'issue_comment' && - github.event.issue.pull_request && - github.event.comment.user.id != 97796249 && - startsWith(github.event.comment.body, '/backport') - ) - steps: - - uses: actions/checkout@v4 - - name: Create backport pull requests - uses: korthout/backport-action@v3 - with: - label_pattern: '^port/(.+)$' Index: borgbackup2/.github/workflows/black.yaml =================================================================== --- borgbackup2.orig/.github/workflows/black.yaml +++ /dev/null @@ -1,15 +0,0 @@ -# https://black.readthedocs.io/en/stable/integrations/github_actions.html#usage -# See also what we use locally in requirements.d/codestyle.txt — this should be the same version here. - -name: Lint - -on: [push, pull_request] - -jobs: - lint: - runs-on: ubuntu-22.04 - steps: - - uses: actions/checkout@v4 - - uses: psf/black@stable - with: - version: "~= 24.0" Index: borgbackup2/.github/workflows/ci.yml =================================================================== --- borgbackup2.orig/.github/workflows/ci.yml +++ /dev/null @@ -1,395 +0,0 @@ -# badge: https://github.com/borgbackup/borg/workflows/CI/badge.svg?branch=master - -name: CI - -on: - push: - branches: [ master ] - tags: - - '2.*' - pull_request: - branches: [ master ] - paths: - - '**.py' - - '**.pyx' - - '**.c' - - '**.h' - - '**.yml' - - '**.toml' - - '**.cfg' - - '**.ini' - - 'requirements.d/*' - - '!docs/**' - -jobs: - lint: - - runs-on: ubuntu-22.04 - timeout-minutes: 5 - - steps: - - uses: actions/checkout@v4 - - uses: chartboost/ruff-action@v1 - - security: - - runs-on: ubuntu-24.04 - timeout-minutes: 5 - - steps: - - uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: '3.10' - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install bandit[toml] - - name: Run Bandit - run: | - bandit -r src/borg -c pyproject.toml - - asan_ubsan: - - runs-on: ubuntu-24.04 - timeout-minutes: 25 - needs: [security] - - steps: - - uses: actions/checkout@v4 - with: - # Just fetching one commit is not enough for setuptools-scm, so we fetch all. - fetch-depth: 0 - fetch-tags: true - - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: '3.12' - - - name: Install system packages - run: | - sudo apt-get update - sudo apt-get install -y pkg-config build-essential - sudo apt-get install -y libssl-dev libacl1-dev libxxhash-dev liblz4-dev libzstd-dev - - - name: Install Python dependencies - run: | - python -m pip install --upgrade pip - pip install -r requirements.d/development.txt - - - name: Build Borg with ASan/UBSan - # Build the C/Cython extensions with AddressSanitizer and UndefinedBehaviorSanitizer enabled. - # How this works: - # - The -fsanitize=address,undefined flags inject runtime checks into our native code. If a bug is hit - # (e.g., buffer overflow, use-after-free, out-of-bounds, or undefined behavior), the sanitizer prints - # a detailed error report to stderr, including a stack trace, and forces the process to exit with - # non-zero status. In CI, this will fail the step/job so you will notice. - # - ASAN_OPTIONS/UBSAN_OPTIONS configure the sanitizers' runtime behavior (see below for meanings). - env: - CFLAGS: "-O1 -g -fno-omit-frame-pointer -fsanitize=address,undefined" - CXXFLAGS: "-O1 -g -fno-omit-frame-pointer -fsanitize=address,undefined" - LDFLAGS: "-fsanitize=address,undefined" - # ASAN_OPTIONS controls AddressSanitizer runtime tweaks: - # - detect_leaks=0: Disable LeakSanitizer to avoid false positives with CPython/pymalloc in short-lived tests. - # - strict_string_checks=1: Make invalid string operations (e.g., over-reads) more likely to be detected. - # - check_initialization_order=1: Catch uses that depend on static initialization order (C++). - # - detect_stack_use_after_return=1: Detect stack-use-after-return via stack poisoning (may increase overhead). - ASAN_OPTIONS: "detect_leaks=0:strict_string_checks=1:check_initialization_order=1:detect_stack_use_after_return=1" - # UBSAN_OPTIONS controls UndefinedBehaviorSanitizer runtime: - # - print_stacktrace=1: Include a stack trace for UB reports to ease debugging. - # Note: UBSan is recoverable by default (process may continue after reporting). If you want CI to - # abort immediately and fail on the first UB, add `halt_on_error=1` (e.g., UBSAN_OPTIONS="print_stacktrace=1:halt_on_error=1"). - UBSAN_OPTIONS: "print_stacktrace=1" - # PYTHONDEVMODE enables additional Python runtime checks and warnings. - PYTHONDEVMODE: "1" - run: pip install -e . - - - name: Run tests under sanitizers - env: - ASAN_OPTIONS: "detect_leaks=0:strict_string_checks=1:check_initialization_order=1:detect_stack_use_after_return=1" - UBSAN_OPTIONS: "print_stacktrace=1" - PYTHONDEVMODE: "1" - # Ensure the ASan runtime is loaded first to avoid "ASan runtime does not come first" warnings. - # We discover libasan/libubsan paths via gcc and preload them for the Python test process. - # the remote tests are slow and likely won't find anything useful - run: | - set -euo pipefail - export LD_PRELOAD="$(gcc -print-file-name=libasan.so):$(gcc -print-file-name=libubsan.so)" - echo "Using LD_PRELOAD=$LD_PRELOAD" - pytest -v --benchmark-skip -k "not remote" - - posix_tests: - - needs: [lint, security] - permissions: - contents: read - id-token: write - attestations: write - strategy: - fail-fast: true - # noinspection YAMLSchemaValidation - matrix: >- - ${{ fromJSON( - github.event_name == 'pull_request' && '{ - "include": [ - {"os": "ubuntu-22.04", "python-version": "3.10", "toxenv": "mypy"}, - {"os": "ubuntu-22.04", "python-version": "3.11", "toxenv": "docs"}, - {"os": "ubuntu-22.04", "python-version": "3.10", "toxenv": "py310-fuse2"}, - {"os": "ubuntu-24.04", "python-version": "3.14", "toxenv": "py314-fuse3"} - ] - }' || '{ - "include": [ - {"os": "ubuntu-22.04", "python-version": "3.10", "toxenv": "mypy"}, - {"os": "ubuntu-22.04", "python-version": "3.11", "toxenv": "docs"}, - {"os": "ubuntu-22.04", "python-version": "3.10", "toxenv": "py310-fuse2"}, - {"os": "ubuntu-22.04", "python-version": "3.11", "toxenv": "py311-fuse2", "binary": "borg-linux-glibc235-x86_64-gh"}, - {"os": "ubuntu-22.04-arm", "python-version": "3.11", "toxenv": "py311-fuse2", "binary": "borg-linux-glibc235-arm64-gh"}, - {"os": "ubuntu-24.04", "python-version": "3.12", "toxenv": "py312-fuse3"}, - {"os": "ubuntu-24.04", "python-version": "3.13", "toxenv": "py313-fuse3"}, - {"os": "ubuntu-24.04", "python-version": "3.14", "toxenv": "py314-fuse3"}, - {"os": "macos-13", "python-version": "3.11", "toxenv": "py311-none", "binary": "borg-macos-13-x86_64-gh"}, - {"os": "macos-14", "python-version": "3.11", "toxenv": "py311-none", "binary": "borg-macos-14-arm64-gh"} - ] - }' - ) }} - env: - TOXENV: ${{ matrix.toxenv }} - - runs-on: ${{ matrix.os }} - timeout-minutes: 120 - - steps: - - uses: actions/checkout@v4 - with: - # Just fetching one commit is not enough for setuptools-scm, so we fetch all. - fetch-depth: 0 - fetch-tags: true - - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v5 - with: - python-version: ${{ matrix.python-version }} - - - name: Cache pip - uses: actions/cache@v4 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('requirements.d/development.txt') }} - restore-keys: | - ${{ runner.os }}-pip- - ${{ runner.os }}- - - - name: Install Linux packages - if: ${{ runner.os == 'Linux' }} - run: | - sudo apt-get update - sudo apt-get install -y pkg-config build-essential - sudo apt-get install -y libssl-dev libacl1-dev libxxhash-dev liblz4-dev libzstd-dev - sudo apt-get install -y libfuse-dev fuse || true # Required for Python llfuse module - sudo apt-get install -y libfuse3-dev fuse3 || true # Required for Python pyfuse3 module - sudo apt-get install -y bash zsh fish # for shell completion tests - sudo apt-get install -y rclone openssh-server curl - - - name: Install macOS packages - if: ${{ runner.os == 'macOS' }} - run: | - brew unlink pkg-config@0.29.2 || true - brew bundle install - - - name: Configure OpenSSH SFTP server (test only) - if: ${{ runner.os == 'Linux' }} - run: | - sudo mkdir -p /run/sshd - sudo useradd -m -s /bin/bash sftpuser || true - # Create SSH key for the CI user and authorize it for sftpuser - mkdir -p ~/.ssh - chmod 700 ~/.ssh - test -f ~/.ssh/id_ed25519 || ssh-keygen -t ed25519 -N '' -f ~/.ssh/id_ed25519 - sudo mkdir -p /home/sftpuser/.ssh - sudo chmod 700 /home/sftpuser/.ssh - sudo cp ~/.ssh/id_ed25519.pub /home/sftpuser/.ssh/authorized_keys - sudo chown -R sftpuser:sftpuser /home/sftpuser/.ssh - sudo chmod 600 /home/sftpuser/.ssh/authorized_keys - # Allow publickey auth and enable Subsystem sftp - sudo sed -i 's/^#\?PasswordAuthentication .*/PasswordAuthentication no/' /etc/ssh/sshd_config - sudo sed -i 's/^#\?PubkeyAuthentication .*/PubkeyAuthentication yes/' /etc/ssh/sshd_config - if ! grep -q '^Subsystem sftp' /etc/ssh/sshd_config; then echo 'Subsystem sftp /usr/lib/openssh/sftp-server' | sudo tee -a /etc/ssh/sshd_config; fi - # Ensure host keys exist to avoid slow generation on first sshd start - sudo ssh-keygen -A - # Start sshd (listen on default 22 inside runner) - sudo /usr/sbin/sshd -D & - # Add host key to known_hosts so paramiko trusts it - ssh-keyscan -H localhost 127.0.0.1 | tee -a ~/.ssh/known_hosts - # Start ssh-agent and add our key so paramiko can use the agent - eval "$(ssh-agent -s)" - ssh-add ~/.ssh/id_ed25519 - # Export SFTP test URL for tox via GITHUB_ENV - echo "BORG_TEST_SFTP_REPO=sftp://sftpuser@localhost:22/borg/sftp-repo" >> $GITHUB_ENV - - - name: Install and configure MinIO S3 server (test only) - if: ${{ runner.os == 'Linux' }} - run: | - set -e - arch=$(uname -m) - case "$arch" in - x86_64|amd64) srv_url=https://dl.min.io/server/minio/release/linux-amd64/minio; cli_url=https://dl.min.io/client/mc/release/linux-amd64/mc ;; - aarch64|arm64) srv_url=https://dl.min.io/server/minio/release/linux-arm64/minio; cli_url=https://dl.min.io/client/mc/release/linux-arm64/mc ;; - *) echo "Unsupported arch: $arch"; exit 1 ;; - esac - curl -fsSL -o /usr/local/bin/minio "$srv_url" - curl -fsSL -o /usr/local/bin/mc "$cli_url" - sudo chmod +x /usr/local/bin/minio /usr/local/bin/mc - export PATH=/usr/local/bin:$PATH - # Start MinIO on :9000 with default credentials (minioadmin/minioadmin) - MINIO_DIR="$GITHUB_WORKSPACE/.minio-data" - MINIO_LOG="$GITHUB_WORKSPACE/.minio.log" - mkdir -p "$MINIO_DIR" - nohup minio server "$MINIO_DIR" --address ":9000" >"$MINIO_LOG" 2>&1 & - # Wait for MinIO port to be ready - for i in $(seq 1 60); do (echo > /dev/tcp/127.0.0.1/9000) >/dev/null 2>&1 && break; sleep 1; done - # Configure client and create bucket - mc alias set local http://127.0.0.1:9000 minioadmin minioadmin - mc mb --ignore-existing local/borg - # Export S3 test URL for tox via GITHUB_ENV - echo "BORG_TEST_S3_REPO=s3:minioadmin:minioadmin@http://127.0.0.1:9000/borg/s3-repo" >> $GITHUB_ENV - - - name: Install Python requirements - run: | - python -m pip install --upgrade pip setuptools wheel - pip install -r requirements.d/development.txt - - - name: Install borgbackup - run: | - pip install -e . - - - name: run tox env - env: - XDISTN: "4" - run: | - # do not use fakeroot, but run as root. avoids the dreaded EISDIR sporadic failures. see #2482. - #sudo -E bash -c "tox -e py" - tox --skip-missing-interpreters - - - name: Upload coverage to Codecov - uses: codecov/codecov-action@v4 - env: - OS: ${{ runner.os }} - python: ${{ matrix.python-version }} - with: - token: ${{ secrets.CODECOV_TOKEN }} - env_vars: OS, python - - - name: Build Borg fat binaries (${{ matrix.binary }}) - if: ${{ matrix.binary && startsWith(github.ref, 'refs/tags/') }} - run: | - pip install 'pyinstaller==6.14.2' - mkdir -p dist/binary - pyinstaller --clean --distpath=dist/binary scripts/borg.exe.spec - - - name: Smoke-test the built binary (${{ matrix.binary }}) - if: ${{ matrix.binary && startsWith(github.ref, 'refs/tags/') }} - run: | - pushd dist/binary - echo "single-file binary" - chmod +x borg.exe - ./borg.exe -V - echo "single-directory binary" - chmod +x borg-dir/borg.exe - ./borg-dir/borg.exe -V - tar czf borg.tgz borg-dir - popd - - - name: Prepare binaries (${{ matrix.binary }}) - if: ${{ matrix.binary && startsWith(github.ref, 'refs/tags/') }} - run: | - mkdir -p artifacts - if [ -f dist/binary/borg.exe ]; then - cp dist/binary/borg.exe artifacts/${{ matrix.binary }} - fi - if [ -f dist/binary/borg.tgz ]; then - cp dist/binary/borg.tgz artifacts/${{ matrix.binary }}.tgz - fi - echo "binary files" - ls -l artifacts/ - - - name: Attest binaries provenance (${{ matrix.binary }}) - if: ${{ matrix.binary && startsWith(github.ref, 'refs/tags/') }} - uses: actions/attest-build-provenance@v3 - with: - subject-path: 'artifacts/*' - - - name: Upload binaries (${{ matrix.binary }}) - if: ${{ matrix.binary && startsWith(github.ref, 'refs/tags/') }} - uses: actions/upload-artifact@v4 - with: - name: ${{ matrix.binary }} - path: artifacts/* - if-no-files-found: error - - windows_tests: - - if: false # can be used to temporarily disable the build - runs-on: windows-latest - timeout-minutes: 120 - needs: posix_tests - - env: - PY_COLORS: 1 - - defaults: - run: - shell: msys2 {0} - - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - - uses: msys2/setup-msys2@v2 - with: - msystem: UCRT64 - update: true - - - name: Install system packages - run: ./scripts/msys2-install-deps development - - - name: Build python venv - run: | - # building cffi / argon2-cffi in the venv fails, so we try to use the system packages - python -m venv --system-site-packages env - . env/bin/activate - # python -m pip install --upgrade pip - # pip install --upgrade setuptools build wheel - pip install pyinstaller==6.14.2 - - - name: Build - run: | - # build borg.exe - . env/bin/activate - pip install -e . - pyinstaller -y scripts/borg.exe.spec - # build sdist and wheel in dist/... - python -m build - - - uses: actions/upload-artifact@v4 - with: - name: borg-windows - path: dist/borg.exe - - - name: Run tests - run: | - ./dist/borg.exe -V - . env/bin/activate - borg -V - python -m pytest -n4 --benchmark-skip -vv -rs -k "not remote" - - - name: Upload coverage to Codecov - uses: codecov/codecov-action@v4 - env: - OS: ${{ runner.os }} - python: '3.11' - with: - token: ${{ secrets.CODECOV_TOKEN }} - env_vars: OS, python Index: borgbackup2/.github/workflows/codeql-analysis.yml =================================================================== --- borgbackup2.orig/.github/workflows/codeql-analysis.yml +++ /dev/null @@ -1,69 +0,0 @@ -# CodeQL semantic code analysis engine - -name: "CodeQL" - -on: - push: - branches: [ master ] - pull_request: - # The branches below must be a subset of the branches above - branches: [ master ] - schedule: - - cron: '39 2 * * 5' - -jobs: - analyze: - name: Analyze - runs-on: ubuntu-22.04 - permissions: - actions: read - contents: read - security-events: write - - strategy: - fail-fast: false - matrix: - language: [ 'cpp', 'python' ] - # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ] - # Learn more about CodeQL language support at https://git.io/codeql-language-support - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - with: - # Just fetching one commit is not enough for setuptools-scm, so we fetch all. - fetch-depth: 0 - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: 3.11 - - name: Cache pip - uses: actions/cache@v4 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('requirements.d/development.txt') }} - restore-keys: | - ${{ runner.os }}-pip- - ${{ runner.os }}- - - name: Install requirements - run: | - sudo apt-get update - sudo apt-get install -y pkg-config build-essential - sudo apt-get install -y libssl-dev libacl1-dev libxxhash-dev liblz4-dev libzstd-dev - # Initializes the CodeQL tools for scanning. - - name: Initialize CodeQL - uses: github/codeql-action/init@v3 - with: - languages: ${{ matrix.language }} - # If you wish to specify custom queries, you can do so here or in a config file. - # By default, queries listed here will override any specified in a config file. - # Prefix the list here with "+" to use these queries and those in the config file. - # queries: ./path/to/local/query, your-org/your-repo/queries@main - - name: Build and install Borg - run: | - python3 -m venv ../borg-env - source ../borg-env/bin/activate - pip3 install -r requirements.d/development.txt - pip3 install -ve . - - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v3 Index: borgbackup2/.github/workflows/freebsd14.yml =================================================================== --- borgbackup2.orig/.github/workflows/freebsd14.yml +++ /dev/null @@ -1,120 +0,0 @@ -name: FreeBSD 14 CI - -on: - push: - branches: [ master ] - tags: - - '2.*' - pull_request: - branches: [ master ] - paths: - - '**.py' - - '**.pyx' - - '**.c' - - '**.h' - - '**.yml' - - '**.toml' - - '**.cfg' - - '**.ini' - - 'requirements.d/*' - - '!docs/**' - -jobs: - freebsd-14: - name: FreeBSD 14 tests and build - permissions: - contents: read - id-token: write - attestations: write - runs-on: ubuntu-24.04 - continue-on-error: true - steps: - - name: Check out repository - uses: actions/checkout@v4 - with: - fetch-depth: 0 - fetch-tags: true - - - name: Run on FreeBSD 14 - id: freebsd - uses: cross-platform-actions/action@v0.26.0 - with: - operating_system: freebsd - version: '14.2' - # Use bash for consistent scripting - shell: bash - # Increase resources a bit for building Cython extensions - cpu_count: 3 - memory: 8G - run: | - set -euxo pipefail - # Update package catalog and install dependencies - export IGNORE_OSVERSION=yes - sudo -E pkg update -f - sudo -E pkg install -y xxhash liblz4 zstd pkgconf - sudo -E pkg install -y fusefs-libs || true - sudo -E pkg install -y fusefs-libs3 || true - sudo -E pkg install -y rust - sudo -E pkg install -y git bash # fakeroot causes lots of troubles on freebsd - sudo -E pkg install -y python310 py310-sqlite3 - sudo -E pkg install -y python311 py311-sqlite3 py311-pip py311-virtualenv - - # Ensure python3 and pip point to the chosen version - sudo ln -sf /usr/local/bin/python3.11 /usr/local/bin/python3 || true - sudo ln -sf /usr/local/bin/python3.11 /usr/local/bin/python || true - sudo ln -sf /usr/local/bin/pip3.11 /usr/local/bin/pip3 || true - sudo ln -sf /usr/local/bin/pip3.11 /usr/local/bin/pip || true - - # Create and activate venv - python -m venv .venv - . .venv/bin/activate - - # Build prerequisites - python -V - pip -V - python -m pip install --upgrade pip wheel - # Install dev requirements and project in editable mode - python -m pip install -r requirements.d/development.txt - python -m pip install -e . - - # Run tests (skip benchmarks which are slow on CI) - python -m pytest -n auto --benchmark-skip - - # Only build PyInstaller binaries for tags - if [[ "${GITHUB_REF:-}" == refs/tags/* ]]; then - python -m pip install 'pyinstaller==6.14.2' - mkdir -p dist/binary - pyinstaller --clean --distpath=dist/binary scripts/borg.exe.spec - # Smoke-test the built binaries and package dir-mode as tarball - pushd dist/binary - echo "single-file binary" - chmod +x borg.exe - ./borg.exe -V - echo "single-directory binary" - chmod +x borg-dir/borg.exe - ./borg-dir/borg.exe -V - tar czf borg.tgz borg-dir - popd - # Prepare artifacts - mkdir -p artifacts - if [ -f dist/binary/borg.exe ]; then - cp -v dist/binary/borg.exe artifacts/borg-freebsd-14-x86_64-gh - fi - if [ -f dist/binary/borg.tgz ]; then - cp -v dist/binary/borg.tgz artifacts/borg-freebsd-14-x86_64-gh.tgz - fi - fi - - - name: Upload FreeBSD artifacts - if: startsWith(github.ref, 'refs/tags/') - uses: actions/upload-artifact@v4 - with: - name: freebsd14-dist - path: artifacts/* - if-no-files-found: ignore - - - name: Attest provenance for FreeBSD artifacts - if: startsWith(github.ref, 'refs/tags/') - uses: actions/attest-build-provenance@v3 - with: - subject-path: 'artifacts/*' Index: borgbackup2/.gitignore =================================================================== --- borgbackup2.orig/.gitignore +++ /dev/null @@ -1,30 +0,0 @@ -MANIFEST -docs/_build -build -dist -.tox -src/borg/compress.c -src/borg/crypto/low_level.c -src/borg/item.c -src/borg/chunkers/buzhash.c -src/borg/chunkers/buzhash64.c -src/borg/chunkers/reader.c -src/borg/checksums.c -src/borg/platform/darwin.c -src/borg/platform/freebsd.c -src/borg/platform/linux.c -src/borg/platform/syncfilerange.c -src/borg/platform/posix.c -src/borg/platform/windows.c -src/borg/_version.py -*.egg-info -*.pyc -*.pyd -*.so -.idea/ -.junie/ -.vscode/ -borg.exe -.coverage -.coverage.* -.vagrant Index: borgbackup2/.mailmap =================================================================== --- borgbackup2.orig/.mailmap +++ /dev/null @@ -1,14 +0,0 @@ -Abdel-Rahman -Brian Johnson -Carlo Teubner -Mark Edgington -Leo Famulari -Marian Beermann -Thomas Waldmann -Dan Christensen -Antoine Beaupré -Hartmut Goebel -Michael Gajda -Milkey Mouse -Ronny Pfannschmidt -Stefan Tatschner Index: borgbackup2/AUTHORS =================================================================== --- borgbackup2.orig/AUTHORS +++ borgbackup2/AUTHORS @@ -1,5 +1,5 @@ -Email addresses listed here are not intended for support. -Please see the `support section`_ instead. +E-mail addresses listed here are not intended for support, please see +the `support section`_ instead. .. _support section: https://borgbackup.readthedocs.io/en/stable/support.html Index: borgbackup2/Brewfile =================================================================== --- borgbackup2.orig/Brewfile +++ borgbackup2/Brewfile @@ -2,11 +2,11 @@ brew 'zstd' brew 'lz4' brew 'xxhash' -brew 'openssl@3' +brew 'openssl@3.0' # osxfuse (aka macFUSE) is only required for "borg mount", -# but won't work on GitHub Actions' workers. -# It requires installing a kernel extension, so some users +# but won't work on github actions' workers. +# it requires installing a kernel extension, so some users # may want it and some won't. #cask 'osxfuse' Index: borgbackup2/MANIFEST.in =================================================================== --- borgbackup2.orig/MANIFEST.in +++ borgbackup2/MANIFEST.in @@ -1,6 +1,6 @@ -# The files we need to include in the sdist are handled automatically by +# stuff we need to include into the sdist is handled automatically by # setuptools_scm - it includes all git-committed files. -# But we want to exclude some committed files/directories not needed in the sdist: +# but we want to exclude some committed files/dirs not needed in the sdist: exclude .editorconfig .gitattributes .gitignore .mailmap Vagrantfile prune .github include src/borg/platform/darwin.c src/borg/platform/freebsd.c src/borg/platform/linux.c src/borg/platform/posix.c Index: borgbackup2/PKG-INFO =================================================================== --- /dev/null +++ borgbackup2/PKG-INFO @@ -0,0 +1,214 @@ +Metadata-Version: 2.4 +Name: borgbackup +Version: 2.0.0b19 +Summary: Deduplicated, encrypted, authenticated and compressed backups +Author: The Borg Collective (see AUTHORS file) +Maintainer-email: Thomas Waldmann +License-Expression: BSD-3-Clause +Project-URL: Homepage, https://borgbackup.org/ +Project-URL: Bug Tracker, https://github.com/borgbackup/borg/issues +Project-URL: Documentation, https://borgbackup.readthedocs.io/ +Project-URL: Repository, https://github.com/borgbackup/borg +Project-URL: Changelog, https://github.com/borgbackup/borg/blob/master/docs/changes.rst +Keywords: backup,borgbackup +Classifier: Development Status :: 4 - Beta +Classifier: Environment :: Console +Classifier: Intended Audience :: System Administrators +Classifier: Operating System :: POSIX :: BSD :: FreeBSD +Classifier: Operating System :: POSIX :: BSD :: OpenBSD +Classifier: Operating System :: POSIX :: BSD :: NetBSD +Classifier: Operating System :: MacOS :: MacOS X +Classifier: Operating System :: POSIX :: Linux +Classifier: Programming Language :: Python +Classifier: Programming Language :: Python :: 3 +Classifier: Programming Language :: Python :: 3.10 +Classifier: Programming Language :: Python :: 3.11 +Classifier: Programming Language :: Python :: 3.12 +Classifier: Programming Language :: Python :: 3.13 +Classifier: Programming Language :: Python :: 3.14 +Classifier: Topic :: Security :: Cryptography +Classifier: Topic :: System :: Archiving :: Backup +Requires-Python: >=3.10 +License-File: LICENSE +License-File: AUTHORS +Requires-Dist: borghash~=0.1.0 +Requires-Dist: borgstore~=0.3.0 +Requires-Dist: msgpack<=1.1.1,>=1.0.3 +Requires-Dist: packaging +Requires-Dist: platformdirs<5.0.0,>=3.0.0; sys_platform == "darwin" +Requires-Dist: platformdirs<5.0.0,>=2.6.0; sys_platform != "darwin" +Requires-Dist: argon2-cffi +Provides-Extra: llfuse +Requires-Dist: llfuse>=1.3.8; extra == "llfuse" +Provides-Extra: pyfuse3 +Requires-Dist: pyfuse3>=3.1.1; extra == "pyfuse3" +Provides-Extra: nofuse +Dynamic: description +Dynamic: license-file + + +What is BorgBackup? +------------------- + +BorgBackup (short: Borg) is a deduplicating backup program. +Optionally, it supports compression and authenticated encryption. + +The main goal of Borg is to provide an efficient and secure way to back up data. +The data deduplication technique used makes Borg suitable for daily backups +since only changes are stored. +The authenticated encryption technique makes it suitable for backups to targets not +fully trusted. + +See the `installation manual`_ or, if you have already +downloaded Borg, ``docs/installation.rst`` to get started with Borg. +There is also an `offline documentation`_ available, in multiple formats. + +.. _installation manual: https://borgbackup.readthedocs.org/en/stable/installation.html +.. _offline documentation: https://readthedocs.org/projects/borgbackup/downloads + +Main features +~~~~~~~~~~~~~ + +**Space efficient storage** + Deduplication based on content-defined chunking is used to reduce the number + of bytes stored: each file is split into a number of variable length chunks + and only chunks that have never been seen before are added to the repository. + + A chunk is considered duplicate if its id_hash value is identical. + A cryptographically strong hash or MAC function is used as id_hash, e.g. + (hmac-)sha256. + + To deduplicate, all the chunks in the same repository are considered, no + matter whether they come from different machines, from previous backups, + from the same backup or even from the same single file. + + Compared to other deduplication approaches, this method does NOT depend on: + + * file/directory names staying the same: So you can move your stuff around + without killing the deduplication, even between machines sharing a repo. + + * complete files or time stamps staying the same: If a big file changes a + little, only a few new chunks need to be stored - this is great for VMs or + raw disks. + + * The absolute position of a data chunk inside a file: Stuff may get shifted + and will still be found by the deduplication algorithm. + +**Speed** + * performance-critical code (chunking, compression, encryption) is + implemented in C/Cython + * local caching + * quick detection of unmodified files + +**Data encryption** + All data can be protected client-side using 256-bit authenticated encryption + (AES-OCB or chacha20-poly1305), ensuring data confidentiality, integrity and + authenticity. + +**Obfuscation** + Optionally, borg can actively obfuscate e.g. the size of files / chunks to + make fingerprinting attacks more difficult. + +**Compression** + All data can be optionally compressed: + + * lz4 (super fast, low compression) + * zstd (wide range from high speed and low compression to high compression + and lower speed) + * zlib (medium speed and compression) + * lzma (low speed, high compression) + +**Off-site backups** + Borg can store data on any remote host accessible over SSH. If Borg is + installed on the remote host, big performance gains can be achieved + compared to using a network filesystem (sshfs, nfs, ...). + +**Backups mountable as filesystems** + Backup archives are mountable as userspace filesystems for easy interactive + backup examination and restores (e.g. by using a regular file manager). + +**Easy installation on multiple platforms** + We offer single-file binaries that do not require installing anything - + you can just run them on these platforms: + + * Linux + * macOS + * FreeBSD + * OpenBSD and NetBSD (no xattrs/ACLs support or binaries yet) + * Cygwin (experimental, no binaries yet) + * Linux Subsystem of Windows 10 (experimental) + +**Free and Open Source Software** + * security and functionality can be audited independently + * licensed under the BSD (3-clause) license, see `License`_ for the + complete license + +Easy to use +~~~~~~~~~~~ + +For ease of use, set the BORG_REPO environment variable:: + + $ export BORG_REPO=/path/to/repo + +Create a new backup repository (see ``borg repo-create --help`` for encryption options):: + + $ borg repo-create -e repokey-aes-ocb + +Create a new backup archive:: + + $ borg create Monday1 ~/Documents + +Now doing another backup, just to show off the great deduplication:: + + $ borg create -v --stats Monday2 ~/Documents + Repository: /path/to/repo + Archive name: Monday2 + Archive fingerprint: 7714aef97c1a24539cc3dc73f79b060f14af04e2541da33d54c7ee8e81a00089 + Time (start): Mon, 2022-10-03 19:57:35 +0200 + Time (end): Mon, 2022-10-03 19:57:35 +0200 + Duration: 0.01 seconds + Number of files: 24 + Original size: 29.73 MB + Deduplicated size: 520 B + + +Helping, Donations and Bounties, becoming a Patron +-------------------------------------------------- + +Your help is always welcome! + +Spread the word, give feedback, help with documentation, testing or development. + +You can also give monetary support to the project, see there for details: + +https://www.borgbackup.org/support/fund.html + +Links +----- + +* `Main Web Site `_ +* `Releases `_, + `PyPI packages `_ and + `ChangeLog `_ +* `Offline Documentation `_ +* `GitHub `_ and + `Issue Tracker `_. +* `Web-Chat (IRC) `_ and + `Mailing List `_ +* `License `_ +* `Security contact `_ + +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). + +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 `Security contact`_ (or +see ``docs/support.rst`` in the source distribution). + + Index: borgbackup2/README.rst =================================================================== --- borgbackup2.orig/README.rst +++ borgbackup2/README.rst @@ -3,7 +3,7 @@ Please note that this is the README for borg2 / master branch. -For the stable version's docs, please see here: +For the stable version's docs, please see there: https://borgbackup.readthedocs.io/en/stable/ @@ -14,7 +14,7 @@ Thus, **DO NOT USE BORG2 FOR YOUR PRODUCTION BACKUPS!** Please help with testing it, but set it up *additionally* to your production backups. -TODO: the screencasts need a remake using borg2, see here: +TODO: the screencasts need a remake using borg2, see there: https://github.com/borgbackup/borg/issues/6303 @@ -35,7 +35,7 @@ downloaded Borg, ``docs/installation.rst`` to get started with Borg. There is also an `offline documentation`_ available, in multiple formats. -.. _installation manual: https://borgbackup.readthedocs.io/en/master/installation.html +.. _installation manual: https://borgbackup.readthedocs.org/en/stable/installation.html .. _offline documentation: https://readthedocs.org/projects/borgbackup/downloads Main features @@ -78,7 +78,7 @@ authenticity. **Obfuscation** - Optionally, Borg can actively obfuscate, e.g., the size of files/chunks to + Optionally, borg can actively obfuscate e.g. the size of files / chunks to make fingerprinting attacks more difficult. **Compression** @@ -91,13 +91,13 @@ * lzma (low speed, high compression) **Off-site backups** - Borg can store data on any remote host accessible over SSH. If Borg is - installed on the remote host, significant performance gains can be achieved - compared to using a network file system (sshfs, NFS, ...). - -**Backups mountable as file systems** - Backup archives are mountable as user-space file systems for easy interactive - backup examination and restores (e.g., by using a regular file manager). + Borg can store data on any remote host accessible over SSH. If Borg is + installed on the remote host, big performance gains can be achieved + compared to using a network filesystem (sshfs, nfs, ...). + +**Backups mountable as filesystems** + Backup archives are mountable as userspace filesystems for easy interactive + backup examination and restores (e.g. by using a regular file manager). **Easy installation on multiple platforms** We offer single-file binaries that do not require installing anything - @@ -108,7 +108,7 @@ * FreeBSD * OpenBSD and NetBSD (no xattrs/ACLs support or binaries yet) * Cygwin (experimental, no binaries yet) - * Windows Subsystem for Linux (WSL) on Windows 10/11 (experimental) + * Linux Subsystem of Windows 10 (experimental) **Free and Open Source Software** * security and functionality can be audited independently @@ -130,7 +130,7 @@ $ borg create Monday1 ~/Documents -Now do another backup, just to show off the great deduplication:: +Now doing another backup, just to show off the great deduplication:: $ borg create -v --stats Monday2 ~/Documents Repository: /path/to/repo @@ -144,31 +144,31 @@ Deduplicated size: 520 B -Helping, donations and bounties, becoming a Patron +Helping, Donations and Bounties, becoming a Patron -------------------------------------------------- Your help is always welcome! Spread the word, give feedback, help with documentation, testing or development. -You can also give monetary support to the project, see here for details: +You can also give monetary support to the project, see there for details: https://www.borgbackup.org/support/fund.html Links ----- -* `Main website `_ +* `Main Web Site `_ * `Releases `_, `PyPI packages `_ and - `Changelog `_ -* `Offline documentation `_ + `ChangeLog `_ +* `Offline Documentation `_ * `GitHub `_ and - `Issue tracker `_. -* `Web chat (IRC) `_ and - `Mailing list `_ -* `License `_ -* `Security contact `_ + `Issue Tracker `_. +* `Web-Chat (IRC) `_ and + `Mailing List `_ +* `License `_ +* `Security contact `_ Compatibility notes ------------------- @@ -178,7 +178,7 @@ NOT RELEASED DEVELOPMENT VERSIONS HAVE UNKNOWN COMPATIBILITY PROPERTIES. -THIS IS SOFTWARE IN DEVELOPMENT, DECIDE FOR YOURSELF WHETHER IT FITS YOUR NEEDS. +THIS IS SOFTWARE IN DEVELOPMENT, DECIDE YOURSELF WHETHER IT FITS YOUR NEEDS. Security issues should be reported to the `Security contact`_ (or see ``docs/support.rst`` in the source distribution). @@ -187,9 +187,9 @@ |doc| |build| |coverage| |bestpractices| -.. |doc| image:: https://readthedocs.org/projects/borgbackup/badge/?version=master +.. |doc| image:: https://readthedocs.org/projects/borgbackup/badge/?version=stable :alt: Documentation - :target: https://borgbackup.readthedocs.io/en/master/ + :target: https://borgbackup.readthedocs.org/en/stable/ .. |build| image:: https://github.com/borgbackup/borg/workflows/CI/badge.svg?branch=master :alt: Build Status (master) Index: borgbackup2/SECURITY.md =================================================================== --- borgbackup2.orig/SECURITY.md +++ borgbackup2/SECURITY.md @@ -2,7 +2,7 @@ ## Supported Versions -These Borg releases are currently supported with security updates. +These borg releases are currently supported with security updates. | Version | Supported | |---------|--------------------| @@ -14,6 +14,6 @@ ## Reporting a Vulnerability -See here: +See there: https://borgbackup.readthedocs.io/en/latest/support.html#security-contact Index: borgbackup2/Vagrantfile =================================================================== --- borgbackup2.orig/Vagrantfile +++ /dev/null @@ -1,434 +0,0 @@ -# -*- mode: ruby -*- -# vi: set ft=ruby : - -# Automated creation of testing environments/binaries on miscellaneous platforms - -$cpus = Integer(ENV.fetch('VMCPUS', '8')) # create VMs with that many cpus -$xdistn = Integer(ENV.fetch('XDISTN', '8')) # dispatch tests to that many pytest workers -$wmem = $xdistn * 256 # give the VM additional memory for workers [MB] - -def packages_debianoid(user) - return <<-EOF - export DEBIAN_FRONTEND=noninteractive - # this is to avoid grub asking about which device it should install to: - echo "set grub-pc/install_devices /dev/sda" | debconf-communicate - apt-get -y -qq update - apt-get -y -qq dist-upgrade - # for building borgbackup and dependencies: - apt install -y pkg-config - apt install -y libssl-dev libacl1-dev libxxhash-dev liblz4-dev libzstd-dev || true - apt install -y libfuse-dev fuse || true - apt install -y libfuse3-dev fuse3 || true - apt install -y locales || true - sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen - usermod -a -G fuse #{user} - chgrp fuse /dev/fuse - chmod 666 /dev/fuse - apt install -y fakeroot build-essential git curl - apt install -y python3-dev python3-setuptools virtualenv - # for building python: - apt install -y zlib1g-dev libbz2-dev libncurses5-dev libreadline-dev liblzma-dev libsqlite3-dev libffi-dev - EOF -end - -def packages_freebsd - return <<-EOF - # in case the VM has no hostname set - hostname freebsd - # install all the (security and other) updates, base system - freebsd-update --not-running-from-cron fetch install - # for building borgbackup and dependencies: - pkg install -y xxhash liblz4 zstd pkgconf - pkg install -y fusefs-libs || true - pkg install -y fusefs-libs3 || true - pkg install -y rust - pkg install -y git bash # fakeroot causes lots of troubles on freebsd - pkg install -y python310 py310-sqlite3 - pkg install -y python311 py311-sqlite3 py311-pip py311-virtualenv - # make sure there is a python3/pip3/virtualenv command - ln -sf /usr/local/bin/python3.11 /usr/local/bin/python3 - ln -sf /usr/local/bin/pip-3.11 /usr/local/bin/pip3 - ln -sf /usr/local/bin/virtualenv-3.11 /usr/local/bin/virtualenv - # make bash default / work: - chsh -s bash vagrant - mount -t fdescfs fdesc /dev/fd - echo 'fdesc /dev/fd fdescfs rw 0 0' >> /etc/fstab - # make FUSE work - echo 'fuse_load="YES"' >> /boot/loader.conf - echo 'vfs.usermount=1' >> /etc/sysctl.conf - kldload fusefs - sysctl vfs.usermount=1 - pw groupmod operator -M vagrant - # /dev/fuse has group operator - chmod 666 /dev/fuse - # install all the (security and other) updates, packages - pkg update - yes | pkg upgrade - echo 'export BORG_OPENSSL_PREFIX=/usr' >> ~vagrant/.bash_profile - # (re)mount / with acls - mount -o acls / - EOF -end - -def packages_openbsd - return <<-EOF - hostname "openbsd77.localdomain" - echo "$(hostname)" > /etc/myname - echo "127.0.0.1 localhost" > /etc/hosts - echo "::1 localhost" >> /etc/hosts - echo "127.0.0.1 $(hostname) $(hostname -s)" >> /etc/hosts - echo "https://ftp.eu.openbsd.org/pub/OpenBSD" > /etc/installurl - ftp https://cdn.openbsd.org/pub/OpenBSD/$(uname -r)/$(uname -m)/comp$(uname -r | tr -d .).tgz - tar -C / -xzphf comp$(uname -r | tr -d .).tgz - rm comp$(uname -r | tr -d .).tgz - pkg_add bash - chsh -s bash vagrant - pkg_add xxhash - pkg_add lz4 - pkg_add zstd - pkg_add git # no fakeroot - pkg_add rust - pkg_add openssl%3.4 - pkg_add py3-pip - pkg_add py3-virtualenv - echo 'export BORG_OPENSSL_NAME=eopenssl30' >> ~vagrant/.bash_profile - EOF -end - -def packages_netbsd - return <<-EOF - echo 'http://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/$arch/9.3/All' > /usr/pkg/etc/pkgin/repositories.conf - pkgin update - pkgin -y upgrade - pkg_add zstd lz4 xxhash git - pkg_add rust - pkg_add bash - chsh -s bash vagrant - echo "export PROMPT_COMMAND=" >> ~vagrant/.bash_profile # bug in netbsd 9.3, .bash_profile broken for screen - echo "export PROMPT_COMMAND=" >> ~root/.bash_profile # bug in netbsd 9.3, .bash_profile broken for screen - pkg_add pkg-config - # pkg_add fuse # llfuse supports netbsd, but is still buggy. - # https://bitbucket.org/nikratio/python-llfuse/issues/70/perfuse_open-setsockopt-no-buffer-space - pkg_add py311-sqlite3 py311-pip py311-virtualenv py311-expat - ln -s /usr/pkg/bin/python3.11 /usr/pkg/bin/python - ln -s /usr/pkg/bin/python3.11 /usr/pkg/bin/python3 - ln -s /usr/pkg/bin/pip3.11 /usr/pkg/bin/pip - ln -s /usr/pkg/bin/pip3.11 /usr/pkg/bin/pip3 - ln -s /usr/pkg/bin/virtualenv-3.11 /usr/pkg/bin/virtualenv - ln -s /usr/pkg/bin/virtualenv-3.11 /usr/pkg/bin/virtualenv3 - EOF -end - -def package_update_openindiana - return <<-EOF - echo "nameserver 1.1.1.1" > /etc/resolv.conf - # needs separate provisioning step + reboot to become effective: - pkg update - EOF -end - -def packages_openindiana - return <<-EOF - pkg install gcc-13 git - pkg install pkg-config libxxhash - pkg install python-313 - ln -sf /usr/bin/python3.13 /usr/bin/python3 - ln -sf /usr/bin/python3.13-config /usr/bin/python3-config - python3 -m ensurepip - ln -sf /usr/bin/pip3.13 /usr/bin/pip3 - pip3 install virtualenv - # let borg's pkg-config find openssl: - pfexec pkg set-mediator -V 3 openssl - EOF -end - -def install_pyenv(boxname) - return <<-EOF - echo 'export PYTHON_CONFIGURE_OPTS="${PYTHON_CONFIGURE_OPTS} --enable-shared"' >> ~/.bash_profile - echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile - echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile - . ~/.bash_profile - curl -s -L https://raw.githubusercontent.com/yyuu/pyenv-installer/master/bin/pyenv-installer | bash - echo 'eval "$(pyenv init --path)"' >> ~/.bash_profile - echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc - echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc - echo 'eval "$(pyenv init -)"' >> ~/.bashrc - echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc - EOF -end - -def install_pythons(boxname) - return <<-EOF - . ~/.bash_profile - echo "PYTHON_CONFIGURE_OPTS: ${PYTHON_CONFIGURE_OPTS}" - pyenv install 3.13.8 - pyenv rehash - EOF -end - -def build_sys_venv(boxname) - return <<-EOF - . ~/.bash_profile - cd /vagrant/borg - virtualenv --python=python3 borg-env - EOF -end - -def build_pyenv_venv(boxname) - return <<-EOF - . ~/.bash_profile - cd /vagrant/borg - # use the latest 3.13 release - pyenv global 3.13.8 - pyenv virtualenv 3.13.8 borg-env - ln -s ~/.pyenv/versions/borg-env . - EOF -end - -def install_borg(fuse) - return <<-EOF - . ~/.bash_profile - cd /vagrant/borg - . borg-env/bin/activate - pip install -U wheel # upgrade wheel, might be too old - cd borg - pip install -r requirements.d/development.lock.txt - python3 scripts/make.py clean - # install borgstore WITH all options, so it pulls in the needed - # requirements, so they will also get into the binaries built. #8574 - pip install borgstore[sftp,s3] - pip install -e .[#{fuse}] - EOF -end - -def install_pyinstaller() - return <<-EOF - . ~/.bash_profile - cd /vagrant/borg - . borg-env/bin/activate - pip install 'pyinstaller==6.14.2' - EOF -end - -def build_binary_with_pyinstaller(boxname) - return <<-EOF - . ~/.bash_profile - cd /vagrant/borg - . borg-env/bin/activate - cd borg - pyinstaller --clean --distpath=/vagrant/borg scripts/borg.exe.spec - echo 'export PATH="/vagrant/borg:$PATH"' >> ~/.bash_profile - cd .. && tar -czvf borg.tgz borg-dir - EOF -end - -def run_tests(boxname, skip_env) - return <<-EOF - . ~/.bash_profile - cd /vagrant/borg/borg - . ../borg-env/bin/activate - if which pyenv 2> /dev/null; then - # for testing, use the earliest point releases of the supported python versions: - pyenv global 3.13.8 - pyenv local 3.13.8 - fi - # otherwise: just use the system python - # some OSes can only run specific test envs, e.g. because they miss FUSE support: - export TOX_SKIP_ENV='#{skip_env}' - if which fakeroot 2> /dev/null; then - echo "Running tox WITH fakeroot -u" - fakeroot -u tox --skip-missing-interpreters - else - echo "Running tox WITHOUT fakeroot -u" - tox --skip-missing-interpreters - fi - EOF -end - -def fs_init(user) - return <<-EOF - # clean up (wrong/outdated) stuff we likely got via rsync: - rm -rf /vagrant/borg/borg/.tox 2> /dev/null - rm -rf /vagrant/borg/borg/borgbackup.egg-info 2> /dev/null - rm -rf /vagrant/borg/borg/__pycache__ 2> /dev/null - find /vagrant/borg/borg/src -name '__pycache__' -exec rm -rf {} \\; 2> /dev/null - chown -R #{user} /vagrant/borg - touch ~#{user}/.bash_profile ; chown #{user} ~#{user}/.bash_profile - echo 'export LANG=en_US.UTF-8' >> ~#{user}/.bash_profile - echo 'export LC_CTYPE=en_US.UTF-8' >> ~#{user}/.bash_profile - echo 'export XDISTN=#{$xdistn}' >> ~#{user}/.bash_profile - EOF -end - -Vagrant.configure(2) do |config| - # use rsync to copy content to the folder - config.vm.synced_folder ".", "/vagrant/borg/borg", :type => "rsync", :rsync__args => ["--verbose", "--archive", "--delete", "--exclude", ".python-version"], :rsync__chown => false - # do not let the VM access . on the host machine via the default shared folder! - config.vm.synced_folder ".", "/vagrant", disabled: true - - config.vm.provider :virtualbox do |v| - #v.gui = true - v.cpus = $cpus - end - - config.vm.define "noble" do |b| - b.vm.box = "bento/ubuntu-24.04" - b.vm.provider :virtualbox do |v| - v.memory = 1024 + $wmem - end - b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant") - b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant") - b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("noble") - b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse") - b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("noble", ".*none.*") - end - - config.vm.define "jammy" do |b| - b.vm.box = "ubuntu/jammy64" - b.vm.provider :virtualbox do |v| - v.memory = 1024 + $wmem - end - b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant") - b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant") - b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("jammy") - b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse") - b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("jammy", ".*none.*") - end - - config.vm.define "trixie" do |b| - b.vm.box = "debian/testing64" - b.vm.provider :virtualbox do |v| - v.memory = 1024 + $wmem - end - b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant") - b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant") - b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("trixie") - b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("trixie") - b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("trixie") - b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse") - b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller() - b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("trixie") - b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("trixie", ".*none.*") - end - - config.vm.define "bookworm32" do |b| - b.vm.box = "generic-x32/debian12" - b.vm.provider :virtualbox do |v| - v.memory = 1024 + $wmem - end - b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant") - b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant") - b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("bookworm32") - b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("bookworm32") - b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("bookworm32") - b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse") - b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller() - b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("bookworm32") - b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("bookworm32", ".*none.*") - end - - config.vm.define "bookworm" do |b| - b.vm.box = "debian/bookworm64" - b.vm.provider :virtualbox do |v| - v.memory = 1024 + $wmem - end - b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant") - b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant") - b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("bookworm") - b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("bookworm") - b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("bookworm") - b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse") - b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller() - b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("bookworm") - b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("bookworm", ".*none.*") - end - - config.vm.define "bullseye" do |b| - b.vm.box = "debian/bullseye64" - b.vm.provider :virtualbox do |v| - v.memory = 1024 + $wmem - end - b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant") - b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant") - b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("bullseye") - b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("bullseye") - b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("bullseye") - b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse") - b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller() - b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("bullseye") - b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("bullseye", ".*none.*") - end - - config.vm.define "freebsd13" do |b| - b.vm.box = "generic/freebsd13" - b.vm.provider :virtualbox do |v| - v.memory = 1024 + $wmem - end - b.ssh.shell = "sh" - b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant") - b.vm.provision "packages freebsd", :type => :shell, :inline => packages_freebsd - b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("freebsd13") - b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("freebsd13") - b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("freebsd13") - b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse") - b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller() - b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("freebsd13") - b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("freebsd13", ".*(fuse3|none).*") - end - - config.vm.define "freebsd14" do |b| - b.vm.box = "generic/freebsd14" - b.vm.provider :virtualbox do |v| - v.memory = 1024 + $wmem - end - b.ssh.shell = "sh" - b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant") - b.vm.provision "packages freebsd", :type => :shell, :inline => packages_freebsd - b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("freebsd14") - b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("freebsd14") - b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("freebsd14") - b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse") - b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller() - b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("freebsd14") - b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("freebsd14", ".*(fuse3|none).*") - end - - config.vm.define "openbsd7" do |b| - b.vm.box = "l3system/openbsd77-amd64" - b.vm.provider :virtualbox do |v| - v.memory = 1024 + $wmem - end - b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant") - b.vm.provision "packages openbsd", :type => :shell, :inline => packages_openbsd - b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("openbsd7") - b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("nofuse") - b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("openbsd7", ".*fuse.*") - end - - config.vm.define "netbsd9" do |b| - b.vm.box = "generic/netbsd9" - b.vm.provider :virtualbox do |v| - v.memory = 4096 + $wmem # need big /tmp tmpfs in RAM! - end - b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant") - b.vm.provision "packages netbsd", :type => :shell, :inline => packages_netbsd - b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("netbsd9") - b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg(false) - b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("netbsd9", ".*fuse.*") - end - - # rsync on openindiana has troubles, does not set correct owner for /vagrant/borg and thus gives lots of - # permission errors. can be manually fixed in the VM by: sudo chown -R vagrant /vagrant/borg ; then rsync again. - config.vm.define "openindiana" do |b| - b.vm.box = "openindiana/hipster" - b.vm.provider :virtualbox do |v| - v.memory = 2048 + $wmem - end - b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant") - b.vm.provision "package update openindiana", :type => :shell, :inline => package_update_openindiana, :reboot => true - b.vm.provision "packages openindiana", :type => :shell, :inline => packages_openindiana - b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("openindiana") - b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("nofuse") - b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("openindiana", ".*fuse.*") - end -end Index: borgbackup2/docs/3rd_party/README =================================================================== --- borgbackup2.orig/docs/3rd_party/README +++ borgbackup2/docs/3rd_party/README @@ -1,5 +1,5 @@ -Here we store third-party documentation, licenses, etc. +Here we store 3rd party documentation, licenses, etc. -Please note that all files inside the "borg" package directory (except those -excluded in setup.py) will be installed, so do not keep docs or licenses +Please note that all files inside the "borg" package directory (except the +stuff excluded in setup.py) will be INSTALLED, so don't keep docs or licenses there. Index: borgbackup2/docs/Makefile =================================================================== --- borgbackup2.orig/docs/Makefile +++ borgbackup2/docs/Makefile @@ -21,7 +21,7 @@ @echo " singlehtml to make a single large HTML file" @echo " pickle to make pickle files" @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and an HTML help project" + @echo " htmlhelp to make HTML files and a HTML help project" @echo " qthelp to make HTML files and a qthelp project" @echo " devhelp to make HTML files and a Devhelp project" @echo " epub to make an epub" Index: borgbackup2/docs/_templates/globaltoc.html =================================================================== --- borgbackup2.orig/docs/_templates/globaltoc.html +++ borgbackup2/docs/_templates/globaltoc.html @@ -1,6 +1,6 @@
- {# Restrict the sidebar ToC depth to two levels while generating command usage pages. + {# Restrict the sidebar toc depth to two levels while generating command usage pages. This avoids superfluous entries for each "Description" and "Examples" heading. #} {% if pagename.startswith("usage/") and pagename not in ( "usage/general", "usage/help", "usage/debug", "usage/notes", Index: borgbackup2/docs/_templates/layout.html =================================================================== --- borgbackup2.orig/docs/_templates/layout.html +++ borgbackup2/docs/_templates/layout.html @@ -1,6 +1,6 @@ {%- extends "basic/layout.html" %} -{# Do this so that Bootstrap is included before the main CSS file. #} +{# Do this so that bootstrap is included before the main css file #} {%- block htmltitle %} {% set script_files = script_files + ["_static/myscript.js"] %} @@ -20,7 +20,7 @@ {{ super() }} {% endblock %} -{# Displays the URL for the homepage if it's set, or the master_doc if it is not. #} +{# Displays the URL for the homepage if it's set or the master_doc if it is not #} {% macro homepage() -%} {%- if theme_homepage %} {%- if hasdoc(theme_homepage) %} @@ -33,7 +33,7 @@ {%- endif %} {%- endmacro %} -{# Displays the URL for the tospage if it's set, or falls back to the homepage macro. #} +{# Displays the URL for the tospage if it's set or falls back to homepage macro #} {% macro tospage() -%} {%- if theme_tospage %} {%- if hasdoc(theme_tospage) %} @@ -46,7 +46,7 @@ {%- endif %} {%- endmacro %} -{# Displays the URL for the projectpage if it's set, or falls back to the homepage macro. #} +{# Displays the URL for the projectpage if it's set or falls back to homepage macro #} {% macro projectlink() -%} {%- if theme_projectlink %} {%- if hasdoc(theme_projectlink) %} @@ -59,7 +59,7 @@ {%- endif %} {%- endmacro %} -{# Displays the next and previous links both before and after the content. #} +{# Displays the next and previous links both before and after content #} {% macro render_relations() -%} {% if prev or next %}
@@ -82,7 +82,7 @@
{%- if sidebars != None %} - {#- New-style sidebar: explicitly include/exclude templates. #} + {#- new style sidebar: explicitly include/exclude templates #} {%- for sidebartemplate in sidebars %} {%- include sidebartemplate %} {%- endfor %} Index: borgbackup2/docs/binaries/00_README.txt =================================================================== --- borgbackup2.orig/docs/binaries/00_README.txt +++ borgbackup2/docs/binaries/00_README.txt @@ -1,100 +1,65 @@ Binary BorgBackup builds ======================== -General notes -------------- - -The binaries are supposed to work on the specified platform without installing anything else. - -There are some limitations, though: -- for Linux, your system must have the same or newer glibc version as the one used for building -- for macOS, you need to have the same or newer macOS version as the one used for building -- for other OSes, there are likely similar limitations - -If you don't find something working on your system, check the older borg releases. - -*.asc are GnuPG signatures - only provided for locally built binaries. -*.exe (or no extension) is the single-file fat binary. -*.tgz is the single-directory fat binary (extract it once with tar -xzf). - -Using the single-directory build is faster and does not require as much space -in the temporary directory as the self-extracting single-file build. - -macOS: to avoid issues, download the file via the command line OR remove the - "quarantine" attribute after downloading: - $ xattr -dr com.apple.quarantine borg-macos1012.tgz +The binaries are supposed to work on the specified platform without installing +any dependencies. Download the correct files -------------------------- -Binaries built on GitHub servers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -borg-linux-glibc235-x86_64-gh Linux AMD/Intel (built on Ubuntu 22.04 LTS with glibc 2.35) -borg-linux-glibc235-arm64-gh Linux ARM (built on Ubuntu 22.04 LTS with glibc 2.35) - -borg-macos-14-arm64-gh macOS Apple Silicon (built on macOS 14 w/o FUSE support) -borg-macos-13-x86_64-gh macOS Intel (built on macOS 13 w/o FUSE support) - +amd64 / x86_64 architecture +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Binaries built locally -~~~~~~~~~~~~~~~~~~~~~~ +borg-linux-glibc236 Linux (built on Debian 12 "Bookworm" with glibc 2.36) +borg-linux-glibc231 Linux (built on Debian 11 "Bullseye" with glibc 2.31) + Note: you can also try them on other Linuxes with other glibc + versions - as long as the glibc is compatible, they will work. + If it doesn't work, try a borg 1.4.x or 1.2.x binary. + +borg-macos1012 macOS (built on macOS Sierra 10.12 with latest macFUSE from brew) + To avoid signing issues download the file via command line OR + remove the "quarantine" attribute after downloading: + $ xattr -dr com.apple.quarantine borg-macos.tgz + +borg-freebsd14 FreeBSD (built on FreeBSD 14) + +*.tgz similar to above, but built as a directory with files, + not as a single self-extracting binary. using the directory + build is faster and doesn't need as much space in the temp + directory as the one-file build. +*.asc GnuPG signatures for * -borg-linux-glibc241-x86_64 Linux (built on Debian 13 "Trixie" with glibc 2.41) -borg-linux-glibc236-x86_64 Linux (built on Debian 12 "Bookworm" with glibc 2.36) -borg-linux-glibc231-x86_64 Linux (built on Debian 11 "Bullseye" with glibc 2.31) - -borg-freebsd-14-x86_64 FreeBSD (built on FreeBSD 14) - -Note: if you don't find a specific binary here, check release 1.4.1 or 1.2.9. Verifying your download ----------------------- -I provide GPG signatures for files which I have built locally on my machines. +Please check the GPG signature to make sure you received the binary as I have +built it. -To check the GPG signature, download both the file and the corresponding -signature (*.asc file) and then (on the shell) type, for example: +To check the GPG signature, download both the binary and the corresponding +*.asc file and then (on the shell) type, e.g.: gpg --recv-keys 9F88FB52FAF7B393 - gpg --verify borgbackup.tar.gz.asc borgbackup.tar.gz + gpg --verify borg-freebsd14.asc borg-freebsd14 The files are signed by: Thomas Waldmann GPG key fingerprint: 6D5B EF9A DD20 7580 5747 B70F 9F88 FB52 FAF7 B393 -My fingerprint is also in the footer of all my BorgBackup mailing list posts. - - -Provenance attestations for GitHub-built binaries -------------------------------------------------- - -For binaries built on GitHub (files with a "-gh" suffix in the name), we publish -an artifact provenance attestation that proves the binary was built by our -GitHub Actions workflow from a specific commit or tag. You can verify this using -the GitHub CLI (gh). Install it from https://cli.github.com/ and make sure you -use a recent version that supports "gh attestation". - -Practical example (Linux, 2.0.0b20 tag): - - curl -LO https://github.com/borgbackup/borg/releases/download/2.0.0b20/borg-linux-glibc235-x86_64-gh - gh attestation verify --repo borgbackup/borg --source-ref refs/tags/2.0.0b20 borg-linux-glibc235-x86_64-gh - -If verification succeeds, gh prints a summary stating the subject (your file), -that it was attested by GitHub Actions, and the job/workflow reference. +My fingerprint is also in the footer of all my borgbackup mailing list posts. Installing ---------- It is suggested that you rename or symlink the binary to just "borg". -If you need "borgfs", just also symlink it to the same binary; it will +If you need "borgfs", just also symlink it to the same binary, it will detect internally under which name it was invoked. On UNIX-like platforms, /usr/local/bin/ or ~/bin/ is a nice place for it, -but you can invoke it from anywhere by providing the full path to it. +but you can invoke it from every place by giving a full path to it. Make sure the file is readable and executable (chmod +rx borg on UNIX-like platforms). @@ -103,7 +68,7 @@ Reporting issues ---------------- -Please first check the FAQ and whether a GitHub issue already exists. +Please first check the FAQ and whether a github issue already exists. If you find a NEW issue, please open a ticket on our issue tracker: @@ -115,6 +80,6 @@ - a good description of what the issue is - a good description of how to reproduce your issue - a traceback with system info (if you have one) -- your precise platform (CPU, 32/64-bit?), OS, distribution, release -- your Python and (g)libc versions +- your precise platform (CPU, 32/64bit?), OS, distribution, release +- your python and (g)libc version Index: borgbackup2/docs/book.rst =================================================================== --- borgbackup2.orig/docs/book.rst +++ borgbackup2/docs/book.rst @@ -5,8 +5,8 @@ Borg documentation ================== -.. When you add an element here, do not forget to add it to index.rst. -.. Note: Some things are in appendices (see latex_appendices in conf.py). +.. when you add an element here, do not forget to add it to index.rst +.. Note: Some things are in appendices (see latex_appendices in conf.py) .. toctree:: :maxdepth: 2 Index: borgbackup2/docs/changes.rst =================================================================== --- borgbackup2.orig/docs/changes.rst +++ borgbackup2/docs/changes.rst @@ -17,7 +17,7 @@ Compatibility notes: -- This is a major "breaking" release that is not compatible with existing repositories. +- this is a major "breaking" release that is not compatible with existing repos. We tried to put all the necessary "breaking" changes into this release, so we hopefully do not need another breaking release in the near future. The changes @@ -33,24 +33,24 @@ you must have followed the upgrade instructions at top of the change log relating to manifest and archive TAMs (borg2 just requires these TAMs now). -- Command-line syntax was changed; scripts and wrappers will need changes: +- command line syntax was changed, scripts and wrappers will need changes: - - You will usually either export BORG_REPO= into your environment or + - you will usually either export BORG_REPO= into your environment or call borg like: "borg -r ". - In the docs, we usually omit "-r ..." for brevity. - - The scp-style REPO syntax was removed; please use ssh://..., #6697 - - ssh:// URLs: Removed support for /~otheruser/, /~/ and /./, #6855. + in the docs, we usually omit "-r ..." for brevity. + - the scp-style REPO syntax was removed, please use ssh://..., #6697 + - ssh:// URLs: removed support for /~otheruser/, /~/ and /./, #6855. New format: - ssh://user@host:port/relative/path - ssh://user@host:port//absolute/path - - -P / --prefix option was removed; please use the similar -a / --match-archives. - - Archive names don't need to be unique anymore. To the contrary: - It is now strongly recommended to use the identical name for borg create + - -P / --prefix option was removed, please use the similar -a / --match-archives. + - archive names don't need to be unique anymore. to the contrary: + it is now strongly recommended to use the identical name for borg create within the same series of archives to make borg work more efficiently. - The name now identifies a series of archives; to identify a single archive, - please use aid:, e.g., borg delete aid:d34db33f - - In case you do NOT want to adopt the "series name" way of naming archives + the name now identifies a series of archive, to identify a single archive + please use aid:, e.g.: borg delete aid:d34db33f + - in case you do NOT want to adopt the "series name" way of naming archives (like "myarchive") as we recommend, but keep using always-changing names (like "myserver-myarchive-20241231"), you can do that, but then you must make use of BORG_FILES_CACHE_SUFFIX and either set it to a constant suffix @@ -60,9 +60,9 @@ greater than the count of different archives series you write to that repo. Usually borg uses a different files cache suffix per archive (series) name and defaults to BORG_FILES_CACHE_TTL=2 because that is sufficient for that. - - The archive ID is always given separately from the repository. - Unlike in borg 1.x, you must not give repo::archive. - - The series name or archive ID is either given as a positional parameter, + - the archive id is always given separately from the repository + (differently than with borg 1.x you must not give repo::archive). + - the series name or archive id is either given as a positional parameter, like: - borg create documents ~/Documents @@ -144,8 +144,8 @@ Change Log 2.x ============== -Version 2.0.0b20 (not released yet) ------------------------------------ +Version 2.0.0b19 (2025-07-02) +----------------------------- Please note: @@ -154,74 +154,6 @@ For upgrade and compatibility hints, please also read the section "Upgrade Notes" above. -New features: - -- fat binary builds on GitHub (see assets on the GitHub releases page): - - - for Linux with glibc 2.35+ (Intel/AMD and ARM64) - - for macOS 14+ (Apple Silicon/ARM64) and macOS 13+ (Intel) - - using GitHub artifact attestations for release binaries, #9134 -- export-tar/import-tar: support for POSIX ACLs (PAX format) -- list --format: add "inode" placeholder -- improved tty-less progress reporting (--progress), #9055 -- BORG_MSGPACK_VERSION_CHECK=no to optionally disable the msgpack version - check; default is "yes", use at your own risk, #9109. - -Fixes: - -- extract: fs flags: use get/set to influence only specific flags, #9039, Linux, FreeBSD, macOS -- transfer: fix borg transfer corrupting the source repo index, #9022 -- legacyrepository: remove auto_recover, #9022 -- fix reading borg 1.x repo index, #9022 -- enable S3/B2 support of borgstore -- mount --show-rc: display main process return code (rc), #8308 -- create: add exception handler for NODUMP-excluded directories, #9032 -- json: include archive keys in JSON lines when requested via --format, #9095 -- ensure valid file URLs are created from Windows paths -- Windows: add missing guards around `preexec_fn=ignore_sigint` - -Other changes: - -- support Python 3.14, msgpack 1.1.2, use Cython 3.1.4 -- require setuptools>=78.1.1, #9042 -- set_flags: remove compression flag support (did not work anyway) -- Brewfile: use openssl@3 -- GitHub Actions: use korthout/backport-action -- tests: - - - add fuzzing tests for chunkers - - add tests for diff output of archives with hard links - - read_only CM: skip test if cmd_immutable is unsuccessful, fixes #9021 - - save space in test_create_* tests - - CI/tests: add SFTP/rclone/S3 repo testing - - CI: add local servers for S3 and SFTP testing - - transfer: add test for unexpected src repo index change, #9022 - - pyproject.toml: correctly define test environments for FUSE testing -- Vagrant: - - - add Debian testing/Trixie box - - add an OpenBSD 7.7 box - - fix OpenIndiana box - - drop macOS 10.12 box (binaries are built on GitHub now) - - use Python 3.13.8 for binary building and tests - - use PyInstaller 6.14.2 for binary building -- docs: - - - update README for binaries - - improve borg help patterns, #7144 - - patterns: clarify scope of default pattern style, #9004 - - extract: document how to use wildcards in PATHs, #8589 - - how to debug borg mount, #5461 - - document what happens when a new keyfile repo is created at the same path, #6230 - - update install docs to include `SETUPTOOLS_SCM_PRETEND_VERSION` - - add Arch Linux to the 'Installing from source' docs - - add systemd-inhibit and examples, #8989 - - code/docs: fix typos and grammar - - -Version 2.0.0b19 (2025-07-02) ------------------------------ - Fixes: - reader: fix corruption issue "forgetting" all-zero bytestrings, #8963 @@ -898,7 +830,6 @@ borg serve --socket # server side (not started automatically!) borg -r socket:///path/to/repo ... # client side - - add get_runtime_dir / BORG_RUNTIME_DIR (contains e.g. .sock and .pid file) - support shell-style alternatives, like: sh:image.{png,jpg}, #7602 Index: borgbackup2/docs/changes_0.x.rst =================================================================== --- borgbackup2.orig/docs/changes_0.x.rst +++ borgbackup2/docs/changes_0.x.rst @@ -11,9 +11,9 @@ - The new default logging level is WARNING. Previously, it was INFO, which was more verbose. Use -v (or --info) to show once again log level INFO messages. See the "general" section in the usage docs. -- For borg create, you need --list (in addition to -v) to see the long file +- for borg create, you need --list (additionally to -v) to see the long file list (was needed so you can have e.g. --stats alone without the long list) -- See below about BORG_DELETE_I_KNOW_WHAT_I_AM_DOING (was: +- see below about BORG_DELETE_I_KNOW_WHAT_I_AM_DOING (was: BORG_CHECK_I_KNOW_WHAT_I_AM_DOING) Bug fixes: @@ -48,7 +48,7 @@ - update progress indication more often (e.g. for borg create within big files or for borg check repo), #500 - finer chunker granularity for items metadata stream, #547, #487 -- borg create --list is now used (in addition to -v) to enable the verbose +- borg create --list now used (additionally to -v) to enable the verbose file list output - display borg version below tracebacks, #532 @@ -86,17 +86,17 @@ Compatibility notes: -- When upgrading to 0.29.0, you need to upgrade client as well as server - installations due to the locking and command-line interface changes; otherwise - you'll get an error message about an RPC protocol mismatch or a wrong command-line +- when upgrading to 0.29.0 you need to upgrade client as well as server + installations due to the locking and commandline interface changes otherwise + you'll get an error msg about a RPC protocol mismatch or a wrong commandline option. - If you run a server that needs to support both old and new clients, it is + if you run a server that needs to support both old and new clients, it is suggested that you have a "borg-0.28.2" and a "borg-0.29.0" command. clients then can choose via e.g. "borg --remote-path=borg-0.29.0 ...". -- The default waiting time for a lock changed from infinity to 1 second for a - better interactive user experience. If the repo you want to access is +- the default waiting time for a lock changed from infinity to 1 second for a + better interactive user experience. if the repo you want to access is currently locked, borg will now terminate after 1s with an error message. - If you have scripts that should wait for the lock for a longer time, use + if you have scripts that shall wait for the lock for a longer time, use --lock-wait N (with N being the maximum wait time in seconds). Bug fixes: Index: borgbackup2/docs/changes_1.x.rst =================================================================== --- borgbackup2.orig/docs/changes_1.x.rst +++ borgbackup2/docs/changes_1.x.rst @@ -73,7 +73,7 @@ for normal production operations - it is only needed once to get the archives in a repository into a good state. All archives have a valid TAM now. -Vulnerability timeline: +Vulnerability time line: * 2023-06-13: Vulnerability discovered during code review by Thomas Waldmann * 2023-06-13...: Work on fixing the issue, upgrade procedure, docs. Index: borgbackup2/docs/conf.py =================================================================== --- borgbackup2.orig/docs/conf.py +++ borgbackup2/docs/conf.py @@ -1,7 +1,7 @@ -# Documentation build configuration file, created by +# documentation build configuration file, created by # sphinx-quickstart on Sat Sep 10 18:18:25 2011. # -# This file is execfile()d with the current directory set to its containing directory. +# This file is execfile()d with the current directory set to its containing dir. # # Note that not all possible configuration values are present in this # autogenerated file. @@ -74,7 +74,7 @@ # default_role = None # The Borg docs contain no or very little Python docs. -# Thus, the primary domain is RST. +# Thus, the primary domain is rst. primary_domain = "rst" # If true, '()' will be appended to :func: etc. cross-reference text. @@ -97,8 +97,8 @@ # -- Options for HTML output --------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of built-in themes. +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. import guzzle_sphinx_theme html_theme_path = guzzle_sphinx_theme.html_theme_path() Index: borgbackup2/docs/deployment/automated-local.rst =================================================================== --- borgbackup2.orig/docs/deployment/automated-local.rst +++ borgbackup2/docs/deployment/automated-local.rst @@ -14,13 +14,13 @@ Overview -------- -A udev rule is created to trigger on the addition of block devices. The rule contains a tag -that triggers systemd to start a one-shot service. The one-shot service executes a script in +An udev rule is created to trigger on the addition of block devices. The rule contains a tag +that triggers systemd to start a oneshot service. The oneshot service executes a script in the standard systemd service environment, which automatically captures stdout/stderr and logs it to the journal. -The script mounts the added block device if it is a registered backup drive and creates -backups on it. When done, it optionally unmounts the filesystem and spins the drive down, +The script mounts the added block device, if it is a registered backup drive, and creates +backups on it. When done, it optionally unmounts the file system and spins the drive down, so that it may be physically disconnected. Configuring the system @@ -29,8 +29,7 @@ First, create the ``/etc/backups`` directory (as root). All configuration goes into this directory. -Find out the ID of the partition table of your backup disk (here assumed to be /dev/sdz):: - +Find out the ID of the partition table of your backup disk (here assumed to be /dev/sdz): lsblk --fs -o +PTUUID /dev/sdz Then, create ``/etc/backups/80-backup.rules`` with the following content (all on one line):: @@ -47,8 +46,8 @@ Type=oneshot ExecStart=/etc/backups/run.sh -Now, create the main backup script, ``/etc/backups/run.sh``. Below is a template; -modify it to suit your needs (e.g., more backup sets, dumping databases, etc.). +Now, create the main backup script, ``/etc/backups/run.sh``. Below is a template, +modify it to suit your needs (e.g. more backup sets, dumping databases etc.). .. code-block:: bash @@ -94,8 +93,8 @@ echo "Disk $uuid is a backup disk" partition_path=/dev/disk/by-uuid/$uuid - # Mount filesystem if not already done. This assumes that if something is already - # mounted at $MOUNTPOINT, it is the backup drive. It will not find the drive if + # Mount file system if not already done. This assumes that if something is already + # mounted at $MOUNTPOINT, it is the backup drive. It won't find the drive if # it was mounted somewhere else. findmnt $MOUNTPOINT >/dev/null || mount $partition_path $MOUNTPOINT drive=$(lsblk --inverse --noheadings --list --paths --output name $partition_path | head --lines 1) @@ -111,8 +110,8 @@ # Set BORG_PASSPHRASE or BORG_PASSCOMMAND somewhere around here, using export, # if encryption is used. - # Because no one can answer these questions non-interactively, it is better to - # fail quickly instead of hanging. + # No one can answer if Borg asks these questions, it is better to just fail quickly + # instead of hanging. export BORG_RELOCATED_REPO_ACCESS_IS_OK=no export BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no @@ -128,8 +127,8 @@ $TARGET::$DATE-$$-system \ / /boot - # /home is often a separate partition/filesystem. - # Even if it is not (add --exclude /home above), it probably makes sense + # /home is often a separate partition / file system. + # Even if it isn't (add --exclude /home above), it probably makes sense # to have /home in a separate archive. borg create $BORG_OPTS \ --exclude 'sh:home/*/.cache' \ @@ -151,16 +150,17 @@ fi Create the ``/etc/backups/autoeject`` file to have the script automatically eject the drive -after creating the backup. Rename the file to something else (e.g., ``/etc/backups/autoeject-no``) -when you want to do something with the drive after creating backups (e.g., running checks). +after creating the backup. Rename the file to something else (e.g. ``/etc/backups/autoeject-no``) +when you want to do something with the drive after creating backups (e.g running check). Create the ``/etc/backups/backup-suspend`` file if the machine should suspend after completing the backup. Don't forget to disconnect the device physically before resuming, otherwise you'll enter a cycle. You can also add an option to power down instead. -Create an empty ``/etc/backups/backup.disks`` file, in which you will register your backup drives. +Create an empty ``/etc/backups/backup.disks`` file, you'll register your backup drives +there. -Finally, enable the udev rules and services: +The last part is actually to enable the udev rules and services: .. code-block:: bash @@ -173,13 +173,13 @@ ------------------------- Connect your backup hard drive. Format it, if not done already. -Find the UUID of the filesystem on which backups should be stored:: +Find the UUID of the file system that backups should be stored on:: lsblk -o+uuid,label -Record the UUID in the ``/etc/backups/backup.disks`` file. +Note the UUID into the ``/etc/backups/backup.disks`` file. -Mount the drive at /mnt/backup. +Mount the drive to /mnt/backup. Initialize a Borg repository at the location indicated by ``TARGET``:: @@ -197,14 +197,14 @@ Security considerations ----------------------- -The script as shown above will mount any filesystem with a UUID listed in -``/etc/backups/backup.disks``. The UUID check is a safety/annoyance-reduction +The script as shown above will mount any file system with an UUID listed in +``/etc/backups/backup.disks``. The UUID check is a safety / annoyance-reduction mechanism to keep the script from blowing up whenever a random USB thumb drive is connected. -It is not meant as a security mechanism. Mounting filesystems and reading repository -data exposes additional attack surfaces (kernel filesystem drivers, -possibly userspace services, and Borg itself). On the other hand, someone +It is not meant as a security mechanism. Mounting file systems and reading repository +data exposes additional attack surfaces (kernel file system drivers, +possibly user space services and Borg itself). On the other hand, someone standing right next to your computer can attempt a lot of attacks, most of which -are easier to do than, e.g., exploiting filesystems (installing a physical keylogger, +are easier to do than e.g. exploiting file systems (installing a physical key logger, DMA attacks, stealing the machine, ...). Borg ensures that backups are not created on random drives that "just happen" Index: borgbackup2/docs/deployment/central-backup-server.rst =================================================================== --- borgbackup2.orig/docs/deployment/central-backup-server.rst +++ borgbackup2/docs/deployment/central-backup-server.rst @@ -5,44 +5,44 @@ Central repository server with Ansible or Salt ============================================== -This section gives an example of how to set up a Borg repository server for multiple +This section will give an example how to set up a borg repository server for multiple clients. Machines -------- -This section uses multiple machines, referred to by their -respective fully qualified domain names (FQDNs). +There are multiple machines used in this section and will further be named by their +respective fully qualified domain name (fqdn). * The backup server: `backup01.srv.local` * The clients: - John Doe's desktop: `johndoe.clnt.local` - - Web server 01: `web01.srv.local` + - Webserver 01: `web01.srv.local` - Application server 01: `app01.srv.local` User and group -------------- -The repository server should have a single UNIX user for all the clients. +The repository server needs to have only one UNIX user for all the clients. Recommended user and group with additional settings: * User: `backup` * Group: `backup` -* Shell: `/bin/bash` (or another shell capable of running the `borg serve` command) +* Shell: `/bin/bash` (or other capable to run the `borg serve` command) * Home: `/home/backup` -Most clients should initiate a backup as the root user to capture all -users, groups, and permissions (e.g., when backing up `/home`). +Most clients shall initiate a backup from the root user to catch all +users, groups and permissions (e.g. when backing up `/home`). Folders ------- -The following directory layout is suggested on the repository server: +The following folder tree layout is suggested on the repository server: * User home directory, /home/backup * Repositories path (storage pool): /home/backup/repos -* Clients’ restricted paths (`/home/backup/repos/`): +* Clients restricted paths (`/home/backup/repos/`): - johndoe.clnt.local: `/home/backup/repos/johndoe.clnt.local` - web01.srv.local: `/home/backup/repos/web01.srv.local` @@ -60,10 +60,10 @@ which could make sense if multiple machines belong to one person which should then have access to all the backups of their machines. -Only one SSH key per client is allowed. Keys are added for ``johndoe.clnt.local``, ``web01.srv.local`` and -``app01.srv.local``. They will access the backup under a single UNIX user account as +There is only one ssh key per client allowed. Keys are added for ``johndoe.clnt.local``, ``web01.srv.local`` and +``app01.srv.local``. But they will access the backup under only one UNIX user account as: ``backup@backup01.srv.local``. Every key in ``$HOME/.ssh/authorized_keys`` has a -forced command and restrictions applied, as shown below: +forced command and restrictions applied as shown below: :: @@ -73,19 +73,19 @@ .. note:: The text shown above needs to be written on a single line! -The options added to the key perform the following: +The options which are added to the key will perform the following: 1. Change working directory 2. Run ``borg serve`` restricted to the client base path 3. Restrict ssh and do not allow stuff which imposes a security risk -Because of the ``cd`` command, the server automatically changes the current -working directory. The client then does not need to know the absolute +Due to the ``cd`` command we use, the server automatically changes the current +working directory. Then client doesn't need to have knowledge of the absolute or relative remote repository path and can directly access the repositories at ``ssh://@/./``. -.. note:: The setup above ignores all client-given command line parameters - that are normally appended to the `borg serve` command. +.. note:: The setup above ignores all client given commandline parameters + which are normally appended to the `borg serve` command. Client ------ @@ -96,15 +96,15 @@ borg init ssh://backup@backup01.srv.local/./pictures -Or with the full path (this should not be used in practice; it is only for demonstration purposes). -The server automatically changes the current working directory to the `` directory. +Or with the full path (should actually never be used, as only for demonstration purposes). +The server should automatically change the current working directory to the `` folder. :: borg init ssh://backup@backup01.srv.local/home/backup/repos/johndoe.clnt.local/pictures -When `johndoe.clnt.local` tries to access a path outside its restriction, the following error is raised. -John Doe tries to back up into the web01 path: +When `johndoe.clnt.local` tries to access a not restricted path the following error is raised. +John Doe tries to back up into the Web 01 path: :: Index: borgbackup2/docs/deployment/hosting-repositories.rst =================================================================== --- borgbackup2.orig/docs/deployment/hosting-repositories.rst +++ borgbackup2/docs/deployment/hosting-repositories.rst @@ -5,21 +5,21 @@ Hosting repositories ==================== -This section shows how to provide repository storage securely for users. +This sections shows how to provide repository storage securely for users. Repositories are accessed through SSH. Each user of the service should -have their own login, which is only able to access that user's files. -Technically, it is possible to have multiple users share one login; +have her own login which is only able to access the user's files. +Technically it would be possible to have multiple users share one login, however, separating them is better. Separate logins increase isolation -and provide an additional layer of security and safety for both the +and are thus an additional layer of security and safety for both the provider and the users. -For example, if a user manages to breach ``borg serve``, they can -only damage their own data (assuming that the system does not have further +For example, if a user manages to breach ``borg serve`` then she can +only damage her own data (assuming that the system does not have further vulnerabilities). Use the standard directory structure of the operating system. Each user -is assigned a home directory, and that user's repositories reside in their +is assigned a home directory and repositories of the user reside in her home directory. The following ``~user/.ssh/authorized_keys`` file is the most important @@ -47,7 +47,7 @@ If any future restriction capabilities are added to authorized_keys files they will be included in this set. -The ``command`` keyword forces execution of the specified command +The ``command`` keyword forces execution of the specified command line upon login. This must be ``borg serve``. The ``--restrict-to-repository`` option permits access to exactly **one** repository. It can be given multiple times to permit access to more than one repository. Index: borgbackup2/docs/deployment/image-backup.rst =================================================================== --- borgbackup2.orig/docs/deployment/image-backup.rst +++ borgbackup2/docs/deployment/image-backup.rst @@ -6,10 +6,10 @@ Backing up disk images can still be efficient with Borg because its `deduplication`_ technique makes sure only the modified parts of the file are stored. Borg also has -optional simple sparse file support for extraction. +optional simple sparse file support for extract. -It is of utmost importance to pin down the disk you want to back up. -Use the disk's SERIAL for that. +It is of utmost importancy to pin down the disk you want to backup. +You need to use the SERIAL for that. Use: .. code-block:: bash @@ -25,10 +25,10 @@ echo "${PARTITIONS[@]}" echo "Disk Identifier: $DISK_ID" - # Use the following line to perform a Borg backup for the full disk: + # Use the following line to perform a borg backup for the full disk: # borg create --read-special disk-backup "$DISK_ID" - # Use the following to perform a Borg backup for all partitions of the disk + # Use the following to perform a borg backup for all partitions of the disk # borg create --read-special partitions-backup "${PARTITIONS[@]}" # Example output: @@ -47,7 +47,7 @@ ------------------------------------ Disk images are as large as the full disk when uncompressed and might not get much -smaller post-deduplication after heavy use because virtually all filesystems do not +smaller post-deduplication after heavy use because virtually all file systems don't actually delete file data on disk but instead delete the filesystem entries referencing the data. Therefore, if a disk nears capacity and files are deleted again, the change will barely decrease the space it takes up when compressed and deduplicated. Depending @@ -115,8 +115,8 @@ mounted, is simply to ``dd`` from ``/dev/zero`` to a temporary file and delete it. This is ill-advised for the reasons mentioned in the ``zerofree`` man page: - - it is slow. - - it makes the disk image (temporarily) grow to its maximal extent. + - it is slow + - it makes the disk image (temporarily) grow to its maximal extent - it (temporarily) uses all free space on the disk, so other concurrent write actions may fail. Virtual machines @@ -129,7 +129,7 @@ reading and writing from the same file. For backing up live VMs use filesystem snapshots on the VM host, which establishes -crash-consistency for the VM images. This means that with most filesystems (that +crash-consistency for the VM images. This means that with most file systems (that are journaling) the FS will always be fine in the backup (but may need a journal replay to become accessible). @@ -145,10 +145,10 @@ in entirety here. Hypervisor snapshots capturing most of the VM's state can also be used for backups and -can be a better alternative to pure filesystem-based snapshots of the VM's disk, since +can be a better alternative to pure file system based snapshots of the VM's disk, since no state is lost. Depending on the application this can be the easiest and most reliable way to create application-consistent backups. -Borg does not intend to address these issues due to their huge complexity and +Borg doesn't intend to address these issues due to their huge complexity and platform/software dependency. Combining Borg with the mechanisms provided by the platform (snapshots, hypervisor features) will be the best approach to start tackling them. Index: borgbackup2/docs/deployment/non-root-user.rst =================================================================== --- borgbackup2.orig/docs/deployment/non-root-user.rst +++ borgbackup2/docs/deployment/non-root-user.rst @@ -6,29 +6,29 @@ Backing up using a non-root user ================================ -This section describes how to run Borg as a non-root user and still be able to -back up every file on the system. +This section describes how to run borg as a non-root user and still be able to +backup every file on the system. -Normally, Borg is run as the root user to bypass all filesystem permissions and -be able to read all files. However, in theory this also allows Borg to modify or -delete files on your system (for example, in case of a bug). +Normally borg is run as the root user to bypass all filesystem permissions and +be able to read all files. But in theory this also allows borg to modify or +delete files on your system, in case of a bug for example. -To eliminate this possibility, we can run Borg as a non-root user and give it read-only +To eliminate this possibility, we can run borg as a non-root user and give it read-only permissions to all files on the system. Using Linux capabilities inside a systemd service ================================================= -One way to do so is to use Linux `capabilities +One way to do so, is to use linux `capabilities `_ within a systemd service. -Linux capabilities allow us to grant parts of the root user’s privileges to -a non-root user. This works on a per-thread level and does not grant permissions +Linux capabilities allow us to give parts of the privileges the root user has to +a non-root user. This works on a per-thread level and does not give the permission to the non-root user as a whole. -For this, we need to run the backup script from a systemd service and use the `AmbientCapabilities +For this we need to run our backup script from a systemd service and use the `AmbientCapabilities `_ option added in systemd 229. @@ -46,21 +46,21 @@ AmbientCapabilities=CAP_DAC_READ_SEARCH -The ``CAP_DAC_READ_SEARCH`` capability gives Borg read-only access to all files and directories on the system. +The ``CAP_DAC_READ_SEARCH`` capability gives borg read-only access to all files and directories on the system. This service can then be started manually using ``systemctl start``, a systemd timer or other methods. Restore considerations ====================== -Use the root user when restoring files. If you use the non-root user, ``borg extract`` will -change ownership of all restored files to the non-root user. Using ``borg mount`` will not allow the -non-root user to access files it would not be able to access on the system itself. +When restoring files, the root user should be used. When using the non-root user, borg extract will +change all files to be owned by the non-root user. Using borg mount will not allow the non-root user +to access files that it would not have access to on the system itself. -Other than that, you can use the same restore process you would use when running the backup as root. +Other than that, the same restore process, that would be used when running the backup as root, can be used. .. warning:: - When using a local repository and running Borg commands as root, make sure to use only commands that do not - modify the repository itself, such as extract or mount. Modifying the repository as root will break it for the - non-root user, since some files inside the repository will then be owned by root. + When using a local repo and running borg commands as root, make sure to only use commands that do not + modify the repo itself, like extract or mount. Modifying the repo using the root user will break + the repo for the non-root user, since some files inside the repo will now be owned by root. Index: borgbackup2/docs/deployment/pull-backup.rst =================================================================== --- borgbackup2.orig/docs/deployment/pull-backup.rst +++ borgbackup2/docs/deployment/pull-backup.rst @@ -6,12 +6,12 @@ Backing up in pull mode ======================= -Typically the Borg client connects to a backup server using SSH as a transport +Typically the borg client connects to a backup server using SSH as a transport when initiating a backup. This is referred to as push mode. -However, if you require the backup server to initiate the connection, or prefer +If you however require the backup server to initiate the connection or prefer it to initiate the backup run, one of the following workarounds is required to -allow such a pull-mode setup. +allow such a pull mode setup. A common use case for pull mode is to back up a remote server to a local personal computer. @@ -19,38 +19,38 @@ SSHFS ===== -Assume you have a pull backup system set up with Borg, where a backup server -pulls data from the target via SSHFS. In this mode, the backup client's filesystem -is mounted remotely on the backup server. Pull mode is even possible if +Assuming you have a pull backup system set up with borg, where a backup server +pulls the data from the target via SSHFS. In this mode, the backup client's file +system is mounted remotely on the backup server. Pull mode is even possible if the SSH connection must be established by the client via a remote tunnel. Other network file systems like NFS or SMB could be used as well, but SSHFS is very simple to set up and probably the most secure one. There are some restrictions caused by SSHFS. For example, unless you define UID and GID mappings when mounting via ``sshfs``, owners and groups of the mounted -filesystem will probably change, and you may not have access to those files if -Borg is not run with root privileges. +file system will probably change, and you may not have access to those files if +BorgBackup is not run with root privileges. -SSHFS is a FUSE filesystem and uses the SFTP protocol, so there may also be -unsupported features that the actual implementations of SSHFS, libfuse, and -SFTP on the backup server do not support, like filename encodings, ACLs, xattrs, -or flags. Therefore, there is no guarantee that you can restore a system +SSHFS is a FUSE file system and uses the SFTP protocol, so there may be also +other unsupported features that the actual implementations of sshfs, libfuse and +sftp on the backup server do not support, like file name encodings, ACLs, xattrs +or flags. So there is no guarantee that you are able to restore a system completely in every aspect from such a backup. .. warning:: - To mount the client's root filesystem you will need root access to the - client. This contradicts the usual threat model of Borg, where - clients do not need to trust the backup server (data is encrypted). In pull + To mount the client's root file system you will need root access to the + client. This contradicts to the usual threat model of BorgBackup, where + clients don't need to trust the backup server (data is encrypted). In pull mode the server (when logged in as root) could cause unlimited damage to the - client. Therefore, pull mode should be used only with servers you fully + client. Therefore, pull mode should be used only from servers you do fully trust! .. warning:: - Additionally, while chrooted into the client's root filesystem, - code from the client will be executed. Therefore, you should do this only when - you fully trust the client. + Additionally, while being chrooted into the client's root file system, + code from the client will be executed. Thus, you should only do that when + fully trusting the client. .. warning:: Index: borgbackup2/docs/development.rst =================================================================== --- borgbackup2.orig/docs/development.rst +++ borgbackup2/docs/development.rst @@ -8,7 +8,7 @@ This chapter will get you started with Borg development. Borg is written in Python (with a little bit of Cython and C for -the performance-critical parts). +the performance critical parts). Contributions ------------- @@ -52,14 +52,14 @@ requests (if you don't have GitHub or don't want to use it you can send smaller patches via the borgbackup mailing list to the maintainers). -Stable releases are maintained on maintenance branches named ``x.y-maint``, e.g., +Stable releases are maintained on maintenance branches named ``x.y-maint``, eg. the maintenance branch of the 1.4.x series is ``1.4-maint``. Most PRs should be filed against the ``master`` branch. Only if an issue affects **only** a particular maintenance branch a PR should be filed against it directly. -While discussing/reviewing a PR it will be decided whether the +While discussing / reviewing a PR it will be decided whether the change should be applied to maintenance branches. Each maintenance branch has a corresponding *backport/x.y-maint* label, which will then be applied. @@ -105,8 +105,8 @@ Previously (until release 1.0.10) Borg used a `"merge upwards" `_ model where -most minor changes and fixes were committed to a maintenance branch -(e.g. 1.0-maint), and the maintenance branch(es) were regularly merged +most minor changes and fixes where committed to a maintenance branch +(eg. 1.0-maint), and the maintenance branch(es) were regularly merged back into the main development branch. This became more and more troublesome due to merges growing more conflict-heavy and error-prone. @@ -439,7 +439,7 @@ - Check version number of upcoming release in ``CHANGES.rst``. - Render ``CHANGES.rst`` via ``make html`` and check for markup errors. - Verify that ``MANIFEST.in``, ``pyproject.toml`` and ``setup.py`` are complete. -- Run these commands, check git status for files that might need to be added, and commit:: +- Run these commands and commit:: python scripts/make.py build_usage python scripts/make.py build_man @@ -448,8 +448,6 @@ git tag -s -m "tagged/signed release X.Y.Z" X.Y.Z -- Push the release PR branch to GitHub, make a pull request. -- Also push the release tag. - Create a clean repo and use it for the following steps:: git clone borg borg-clean @@ -458,9 +456,8 @@ It will also reveal uncommitted required files. Moreover, it makes sure the vagrant machines only get committed files and do a fresh start based on that. -- Optional: run tox and/or binary builds on all supported platforms via vagrant, - check for test failures. This is now optional as we do platform testing and - binary building on GitHub. +- Run tox and/or binary builds on all supported platforms via vagrant, + check for test failures. - Create sdist, sign it, upload release to (test) PyPi: :: @@ -471,12 +468,11 @@ Note: the signature is not uploaded to PyPi any more, but we upload it to github releases. -- When GitHub CI looks good on the release PR, merge it and then check "Actions": - GitHub will create binary assets after the release PR is merged within the - CI testing of the merge. Check the "Upload binaries" step on Ubuntu (AMD/Intel - and ARM64) and macOS (Intel and ARM64), fetch the ZIPs with the binaries. -- Unpack the ZIPs and test the binaries, upload the binaries to the GitHub - release page (borg-OS-SPEC-ARCH-gh and borg-OS-SPEC-ARCH-gh.tgz). +- Put binaries into dist/borg-OSNAME and sign them: + + :: + + scripts/sign-binaries 201912312359 - Close the release milestone on GitHub. - `Update borgbackup.org @@ -493,7 +489,7 @@ - pypi dist package and signature - Standalone binaries (see above for how to create them). - - For macOS binaries **with** FUSE support, document the macFUSE version - in the README of the binaries. macFUSE uses a kernel extension that needs - to be compatible with the code contained in the binary. + - For macOS, document the macFUSE version in the README of the binaries. + macFUSE uses a kernel extension that needs to be compatible with the + code contained in the binary. - A link to ``CHANGES.rst``. Index: borgbackup2/docs/faq.rst =================================================================== --- borgbackup2.orig/docs/faq.rst +++ borgbackup2/docs/faq.rst @@ -8,19 +8,19 @@ Usage & Limitations ################### -What is the difference between a repository on an external hard drive and a repository on a server? ---------------------------------------------------------------------------------------------------- +What is the difference between a repo on an external hard drive vs. repo on a server? +------------------------------------------------------------------------------------- If Borg is running in client/server mode, the client uses SSH as a transport to -talk to a remote agent, which is another Borg process (Borg is also installed on -the server) started automatically by the client. The Borg server performs -storage-related, low-level repository operations (list, load, and store objects), +talk to the remote agent, which is another Borg process (Borg is installed on +the server, too) started automatically by the client. The Borg server is doing +storage-related low-level repo operations (list, load and store objects), while the Borg client does the high-level stuff: deduplication, encryption, compression, dealing with archives, backups, restores, etc., which reduces the amount of data that goes over the network. -When Borg is writing to a repo on a locally mounted remote filesystem, e.g. -SSHFS, the Borg client can only perform filesystem operations and has no agent +When Borg is writing to a repo on a locally mounted remote file system, e.g. +SSHFS, the Borg client only can do file system operations and has no agent running on the remote side, so *every* operation needs to go over the network, which is slower. @@ -29,7 +29,7 @@ Yes, you can! Even simultaneously. -Can I back up to multiple swapped backup targets? +Can I back up to multiple, swapped backup targets? -------------------------------------------------- It is possible to swap your backup disks if each backup medium is assigned its @@ -43,41 +43,41 @@ - ``borg repo-create repo1 --encryption=X`` - ``borg repo-create repo2 --encryption=X --other-repo=repo1`` -- Optionally, create a snapshot to have stable and identical input data for both borg create runs. +- maybe do a snapshot to have stable and same input data for both borg create. - client machine ---borg create---> repo1 - client machine ---borg create---> repo2 -This will create distinct (different repository ID) but related repositories. +This will create distinct (different repo ID), but related repositories. Related means using the same chunker secret and the same id_key, thus producing -the same chunks / the same chunk IDs if the input data is the same. +the same chunks / the same chunk ids if the input data is the same. -The two independent borg create invocations mean there is no error propagation +The 2 independent borg create invocations mean that there is no error propagation from repo1 to repo2 when done like that. -An alternative is to use ``borg transfer`` to copy backup archives -from repo1 to repo2. This is likely a bit more efficient and the archives would be identical, -but it may suffer from potential error propagation. - -Warning: Using Borg with multiple repositories that have identical repository IDs (such as -creating 1:1 repository copies) is not supported and can lead to various issues, -for example cache coherency issues, malfunction, or data corruption. +An alternative way would be to use ``borg transfer`` to copy backup archives +from repo1 to repo2. Likely a bit more efficient and the archives would be identical, +but suffering from potential error propagation. + +Warning: using borg with multiple repositories with identical repository ID (like when +creating 1:1 repository copies) is not supported and can lead to all sorts of issues, +like e.g. cache coherency issues, malfunction, data corruption. "this is either an attack or unsafe" warning -------------------------------------------- About the warning: - Cache or information obtained from the security directory is newer than the - repository — this is either an attack or unsafe (multiple repositories with the same ID) + Cache, or information obtained from the security directory is newer than + repository - this is either an attack or unsafe (multiple repos with same ID) "unsafe": If not following the advice from the previous section, you can easily run into this by yourself by restoring an older copy of your repository. -"attack": An attacker may have replaced your repo with an older copy, trying to -trigger AES counter reuse and break your repo encryption. +"attack": maybe an attacker has replaced your repo by an older copy, trying to +trick you into AES counter reuse, trying to break your repo encryption. -Borg users have also reported that file system issues (e.g., hardware issues or I/O errors causing -the file system to become read-only) can cause this warning, see :issue:`7853`. +Borg users have also reported that fs issues (like hw issues / I/O errors causing +the fs to become read-only) can cause this warning, see :issue:`7853`. If you decide to ignore this and accept unsafe operation for this repository, you could delete the manifest-timestamp and the local cache: @@ -88,7 +88,7 @@ rm ~/.config/borg/security/REPO_ID/manifest-timestamp borg repo-delete --cache-only -This is an unsafe and unsupported way to use Borg. You have been warned. +This is an unsafe and unsupported way to use borg, you have been warned. Which file types, attributes, etc. are *not* preserved? ------------------------------------------------------- @@ -150,11 +150,7 @@ ---------------------------------------------- While backing up your data over the network, your machine should not go to sleep. -On Linux you can use `systemd-inhibit` to avoid that. On macOS you can use `caffeinate`. - -``systemd-inhibit borg create ...`` - -``caffeinate -i borg create ...`` +On macOS you can use `caffeinate` to avoid that. How can I compare contents of an archive to my local filesystem? ----------------------------------------------------------------- @@ -391,26 +387,6 @@ Make sure that only you have access to the Borg config directory. - -Note about creating multiple keyfile repositories at the same path ------------------------------------------------------------------- - -If you create a new keyfile-encrypted repository at the same filesystem -path multiple times (for example, when a previous repository at that path -was moved away or unmounted), Borg will not overwrite or reuse the existing -key file in your keys directory. Instead, it creates a new key file by -appending a numeric suffix to the base name (e.g., .2, .3, ...). - -This means you may see multiple key files like: - -- ~/.config/borg/keys/home_user_backup -- ~/.config/borg/keys/home_user_backup.2 -- ~/.config/borg/keys/home_user_backup.3 - -Each of these corresponds to a distinct repository created at the same -path at different times. This behavior avoids accidental key reuse or -overwrite. - .. _home_data_borg: How important is the $HOME/.local/share/borg directory? Index: borgbackup2/docs/index.rst =================================================================== --- borgbackup2.orig/docs/index.rst +++ borgbackup2/docs/index.rst @@ -6,7 +6,7 @@ .. include:: ../README.rst -.. When you add an element here, do not forget to add it to book.rst. +.. when you add an element here, do not forget to add it to book.rst .. toctree:: :maxdepth: 2 Index: borgbackup2/docs/installation.rst =================================================================== --- borgbackup2.orig/docs/installation.rst +++ borgbackup2/docs/installation.rst @@ -82,9 +82,9 @@ .. _Ubuntu packages: https://launchpad.net/ubuntu/+source/borgbackup .. _Ubuntu PPA: https://launchpad.net/~costamagnagianfranco/+archive/ubuntu/borgbackup -Please ask package maintainers to build a package or, if you can package/ +Please ask package maintainers to build a package or, if you can package / submit it yourself, please help us with that! See :issue:`105` on -GitHub to follow up on packaging efforts. +github to followup on packaging efforts. **Current status of package in the repositories** @@ -106,12 +106,12 @@ .. note:: Releases are signed with an OpenPGP key, see :ref:`security-contact` for more instructions. -Borg x86/x64 AMD/Intel compatible binaries (generated with `pyinstaller`_) +Borg x86/x64 amd/intel compatible binaries (generated with `pyinstaller`_) are available on the releases_ page for the following platforms: * **Linux**: glibc >= 2.28 (ok for most supported Linux releases). Older glibc releases are untested and may not work. -* **macOS**: 10.12 or newer (To avoid signing issues, download the file via +* **MacOS**: 10.12 or newer (To avoid signing issues download the file via command line **or** remove the ``quarantine`` attribute after downloading: ``$ xattr -dr com.apple.quarantine borg-macosx64.tgz``) * **FreeBSD**: 12.1 (unknown whether it works for older releases) @@ -191,19 +191,6 @@ After you have installed the dependencies, you can proceed with steps outlined under :ref:`pip-installation`. -Arch Linux -++++++++++ - -Install the runtime and build dependencies:: - - pacman -S python python-pip python-virtualenv openssl acl xxhash lz4 zstd base-devel - pacman -S fuse2 # needed for llfuse - pacman -S fuse3 # needed for pyfuse3 - -Note that Arch Linux specifically doesn't support -`partial upgrades `__, -so in case some packages cannot be retrieved from the repo, run with ``pacman -Syu``. - Debian / Ubuntu +++++++++++++++ @@ -428,10 +415,6 @@ Ensure to install the dependencies as described within :ref:`source-install`. -Version metadata is obtained dynamically at install time using ``setuptools-scm``. -Please ensure that your git repo either has correct tags, or provide the version -manually using the ``SETUPTOOLS_SCM_PRETEND_VERSION`` environment variable. - :: # get borg from github @@ -441,15 +424,11 @@ virtualenv --python=$(which python3) borg-env source borg-env/bin/activate # always before using! - # install borg dependencies into virtualenv + # install borg + dependencies into virtualenv cd borg pip install -r requirements.d/development.txt pip install -r requirements.d/docs.txt # optional, to build the docs - # set a borg version if setuptools-scm fails to do so automatically - export SETUPTOOLS_SCM_PRETEND_VERSION= - - # install borg into virtualenv pip install -e . # in-place editable mode or pip install -e .[pyfuse3] # in-place editable mode, use pyfuse3 Index: borgbackup2/docs/internals.rst =================================================================== --- borgbackup2.orig/docs/internals.rst +++ borgbackup2/docs/internals.rst @@ -4,7 +4,7 @@ Internals ========= -The internals chapter describes and analyzes most of the inner workings +The internals chapter describes and analyses most of the inner workings of Borg. Borg uses a low-level, key-value store, the :ref:`repository`, and @@ -20,17 +20,17 @@ (multiple backups and even multiple hosts), both on data and file metadata, using :ref:`chunks` created by the chunker using the Buzhash_ algorithm ("buzhash" and "buzhash64" chunker) or a simpler -fixed block size algorithm ("fixed" chunker). +fixed blocksize algorithm ("fixed" chunker). To perform the repository-wide deduplication, a hash of each chunk is checked against the :ref:`chunks cache `, which is a -hash table of all chunks that already exist. +hash-table of all chunks that already exist. .. figure:: internals/structure.png :figwidth: 100% :width: 100% - Layers in Borg. At the very top, commands are implemented, using + Layers in Borg. On the very top commands are implemented, using a data access layer provided by the Archive and Item classes. The "key" object provides both compression and authenticated encryption used by the data access layer. The "key" object represents Index: borgbackup2/docs/internals/data-structures.rst =================================================================== --- borgbackup2.orig/docs/internals/data-structures.rst +++ borgbackup2/docs/internals/data-structures.rst @@ -63,7 +63,7 @@ ~~~~ Repository object IDs (which are used as key into the key-value store) are -byte strings of fixed length (256-bit, 32 bytes), computed like this:: +byte-strings of fixed length (256bit, 32 bytes), computed like this:: key = id = id_hash(plaintext_data) # plain = not encrypted, not compressed, not obfuscated @@ -79,10 +79,10 @@ A repo object has a structure like this: -* 32-bit meta size -* 32-bit data size -* 64-bit xxh64(meta) -* 64-bit xxh64(data) +* 32bit meta size +* 32bit data size +* 64bit xxh64(meta) +* 64bit xxh64(data) * meta * data @@ -90,8 +90,8 @@ needing to decrypt anything (which would require the borg key). The overall size of repository objects varies from very small (a small source -file will be stored as a single repository object) to medium (big source files will -be cut into medium-sized chunks of some MB). +file will be stored as a single repo object) to medium (big source files will +be cut into medium sized chunks of some MB). Metadata and data are separately encrypted and authenticated (depending on the user's choices). @@ -102,7 +102,7 @@ Repo object metadata ~~~~~~~~~~~~~~~~~~~~ -Metadata is a MessagePack-encoded (and encrypted/authenticated) dict with: +Metadata is a msgpacked (and encrypted/authenticated) dict with: - ctype (compression type 0..255) - clevel (compression level 0..255) Index: borgbackup2/docs/internals/frontends.rst =================================================================== --- borgbackup2.orig/docs/internals/frontends.rst +++ borgbackup2/docs/internals/frontends.rst @@ -11,8 +11,8 @@ even for point releases (1.1.x), and there is no documentation beyond the code and the internals documents. Borg does on the other hand provide an API on a command-line level. In other words, a frontend should -(for example) create a backup archive by invoking :ref:`borg_create`, provide command-line parameters/options -as needed, and parse JSON output from Borg. +(for example) create a backup archive just invoke :ref:`borg_create`, give commandline parameters/options +as needed and parse JSON output from borg. Important: JSON output is expected to be UTF-8, but currently borg depends on the locale being configured for that (must be a UTF-8 locale and *not* "C" or "ascii"), so that Python will choose to encode to UTF-8. Index: borgbackup2/docs/internals/security.rst =================================================================== --- borgbackup2.orig/docs/internals/security.rst +++ borgbackup2/docs/internals/security.rst @@ -24,7 +24,7 @@ attacker has any and all access to the repository, including interactive manipulation (man-in-the-middle) for remote repositories. -Furthermore, the client environment is assumed to be persistent across +Furthermore the client environment is assumed to be persistent across attacks (practically this means that the security database cannot be deleted between attacks). @@ -37,8 +37,8 @@ structural information such as the object graph (which archives refer to what chunks) -The attacker can always impose a denial of service by definition (they could -block connections to the repository, or delete it partly or entirely). +The attacker can always impose a denial of service per definition (he could +forbid connections to the repository, or delete it partly or entirely). .. _security_structural_auth: Index: borgbackup2/docs/introduction.rst =================================================================== --- borgbackup2.orig/docs/introduction.rst +++ borgbackup2/docs/introduction.rst @@ -1,8 +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. +.. 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 Index: borgbackup2/docs/man_intro.rst =================================================================== --- borgbackup2.orig/docs/man_intro.rst +++ borgbackup2/docs/man_intro.rst @@ -13,7 +13,7 @@ BorgBackup (short: Borg) is a deduplicating backup program. Optionally, it supports compression and authenticated encryption. -The main goal of Borg is to provide an efficient and secure way to back up data. +The main goal of Borg is to provide an efficient and secure way to back data up. The data deduplication technique used makes Borg suitable for daily backups since only changes are stored. The authenticated encryption technique makes it suitable for backups to targets not @@ -22,7 +22,7 @@ Borg stores a set of files in an *archive*. A *repository* is a collection of *archives*. The format of repositories is Borg-specific. Borg does not distinguish archives from each other in any way other than their name, -it does not matter when or where archives were created (e.g., different hosts). +it does not matter when or where archives were created (e.g. different hosts). EXAMPLES -------- Index: borgbackup2/docs/misc/benchmark-crud.txt =================================================================== --- borgbackup2.orig/docs/misc/benchmark-crud.txt +++ borgbackup2/docs/misc/benchmark-crud.txt @@ -1,9 +1,9 @@ borg benchmark crud =================== -Here is an example of borg benchmark crud output. +Here is some example of borg benchmark crud output. -I ran it on my laptop: Core i5-4200U, 8 GB RAM, SATA SSD, Linux, ext4 filesystem. +I ran it on my laptop, Core i5-4200u, 8GB RAM, SATA SSD, Linux, ext4 fs. "src" as well as repo is local, on this SSD. $ BORG_PASSPHRASE=secret borg init --encryption repokey-blake2 repo Index: borgbackup2/docs/misc/create_chunker-params.txt =================================================================== --- borgbackup2.orig/docs/misc/create_chunker-params.txt +++ borgbackup2/docs/misc/create_chunker-params.txt @@ -3,53 +3,53 @@ --chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE -CHUNK_MIN_EXP and CHUNK_MAX_EXP provide the exponent N for the 2^N minimum and -maximum chunk sizes. Required: CHUNK_MIN_EXP < CHUNK_MAX_EXP. +CHUNK_MIN_EXP and CHUNK_MAX_EXP give the exponent N of the 2^N minimum and +maximum chunk size. Required: CHUNK_MIN_EXP < CHUNK_MAX_EXP. Defaults: 19 (2^19 == 512KiB) minimum, 23 (2^23 == 8MiB) maximum. -Currently, specifying a maximum greater than 23 is not supported. +Currently it is not supported to give more than 23 as maximum. HASH_MASK_BITS is the number of least-significant bits of the rolling hash that need to be zero to trigger a chunk cut. Recommended: CHUNK_MIN_EXP + X <= HASH_MASK_BITS <= CHUNK_MAX_EXP - X, X >= 2 (this allows the rolling hash some freedom to make its cut at a place -determined by the window's contents rather than the minimum/maximum chunk size). +determined by the windows contents rather than the min/max. chunk size). -Default: 21 (statistically, chunks will be about 2^21 == 2MiB in size). +Default: 21 (statistically, chunks will be about 2^21 == 2MiB in size) HASH_WINDOW_SIZE: the size of the window used for the rolling hash computation. -Must be an odd number. Default: 4095B. +Must be an odd number. Default: 4095B Trying it out ============= I backed up a VM directory to demonstrate how different chunker parameters -affect repository size, index size/chunk count, compression, and deduplication. +influence repo size, index size / chunk count, compression, deduplication. -repo-sm: ~64 KiB chunks (16 bits chunk mask), min chunk size 1 KiB (2^10B) - (these are Attic/Borg 0.23 internal defaults) +repo-sm: ~64kiB chunks (16 bits chunk mask), min chunk size 1kiB (2^10B) + (these are attic / borg 0.23 internal defaults) -repo-lg: ~1MiB chunks (20 bits chunk mask), min chunk size 64 KiB (2^16B) +repo-lg: ~1MiB chunks (20 bits chunk mask), min chunk size 64kiB (2^16B) -repo-xl: 8MiB chunks (2^23B max chunk size), min chunk size 64 KiB (2^16B). - The chunk mask bits were set to 31, so it (almost) never triggers. +repo-xl: 8MiB chunks (2^23B max chunk size), min chunk size 64kiB (2^16B). + The chunk mask bits was set to 31, so it (almost) never triggers. This degrades the rolling hash based dedup to a fixed-offset dedup as the cutting point is now (almost) always the end of the buffer (at 2^23B == 8MiB). The repo index size is an indicator for the RAM needs of Borg. In this special case, the total RAM needs are about 2.1x the repo index size. -You see the index size of repo-sm is 16x larger than that of repo-lg, which corresponds +You see index size of repo-sm is 16x larger than of repo-lg, which corresponds to the ratio of the different target chunk sizes. Note: RAM needs were not a problem in this specific case (37GB data size). - But imagine you have 37TB of such data and much less than 42GB RAM, - then you should use the "lg" chunker parameters so you need only - 2.6GB RAM. Or even larger chunks than shown for "lg" (see "xl"). + But just imagine, you have 37TB of such data and much less than 42GB RAM, + then you should use the "lg" chunker params so you only need + 2.6GB RAM. Or even bigger chunks than shown for "lg" (see "xl"). You also see compression works better for larger chunks, as expected. -Deduplication works worse for larger chunks, also as expected. +Duplication works worse for larger chunks, also as expected. small chunks ============ Index: borgbackup2/docs/misc/internals-picture.txt =================================================================== --- borgbackup2.orig/docs/misc/internals-picture.txt +++ borgbackup2/docs/misc/internals-picture.txt @@ -1,5 +1,5 @@ -BorgBackup from 10,000 m -======================== +BorgBackup from 10.000m +======================= +--------+ +--------+ +--------+ |archive0| |archive1| ... |archiveN| Index: borgbackup2/docs/misc/prune-example.txt =================================================================== --- borgbackup2.orig/docs/misc/prune-example.txt +++ borgbackup2/docs/misc/prune-example.txt @@ -1,9 +1,9 @@ borg prune visualized ===================== -Assume it is 2016-01-01. Today's backup has not yet been made. You have +Assume it is 2016-01-01, today's backup has not yet been made, you have created at least one backup on each day in 2015 except on 2015-12-19 (no -backup was made on that day), and you started backing up with Borg on +backup made on that day), and you started backing up with borg on 2015-01-01. This is what borg prune --keep-daily 14 --keep-monthly 6 --keep-yearly 1 @@ -91,17 +91,17 @@ not considered for this rule, because that backup was already kept because of the daily rule. -2015-12-17 is kept to satisfy the --keep-daily 14 rule, because no backup was +2015-12-17 is kept to satisfy the --keep-daily 14 rule - because no backup was made on 2015-12-19. If a backup had been made on that day, it would not keep the one from 2015-12-17. -We did not include weekly, hourly, minutely, or secondly rules to keep this +We did not include weekly, hourly, minutely or secondly rules to keep this example simple. They all work in basically the same way. The weekly rule is easy to understand roughly, but hard to understand in all -details. If you are interested, read "ISO 8601:2000 standard week-based year". +details. If interested, read "ISO 8601:2000 standard week-based year". -The 13weekly and 3monthly rules are two different strategies for keeping one backup +The 13weekly and 3monthly rules are two different strategies for keeping one every quarter of a year. There are `multiple ways` to define a quarter-year; borg prune recognizes two: @@ -113,12 +113,12 @@ March 31, April 1st to June 30th, July 1st to September 30th, and October 1st to December 31st form the quarters. -If the subtleties of the definition of a quarter-year don't matter to you, a +If the subtleties of the definition of a quarter year don't matter to you, a short summary of behavior is: -* --keep-13weekly favors keeping backups at the beginning of Jan, Apr, Jul, +* --keep-13weekly favors keeping backups at the beginning of Jan, Apr, July, and Oct. -* --keep-3monthly favors keeping backups at the end of Dec, Mar, Jun, and Sep. +* --keep-3monthly favors keeping backups at the end of Dec, Mar, Jun, and Sept. * Both strategies will have some overlap in which backups are kept. * The differences are negligible unless backups considered for deletion were created weekly or more frequently. Index: borgbackup2/docs/quickstart.rst =================================================================== --- borgbackup2.orig/docs/quickstart.rst +++ borgbackup2/docs/quickstart.rst @@ -7,7 +7,7 @@ This chapter will get you started with Borg and covers various use cases. -A step-by-step example +A step by step example ---------------------- .. include:: quickstart_example.rst.inc @@ -20,10 +20,10 @@ mount an archive to restore from a backup. *Repositories* are filesystem directories acting as self-contained stores of archives. -Repositories can be accessed locally via path or remotely via SSH. Under the hood, +Repositories can be accessed locally via path or remotely via ssh. Under the hood, repositories contain data blocks and a manifest that tracks which blocks are in each archive. If some data hasn't changed between backups, Borg simply -references an already-uploaded data chunk (deduplication). +references an already uploaded data chunk (deduplication). .. _about_free_space: @@ -43,7 +43,7 @@ Also helpful: -- use `borg repo-space` to reserve some disk space that can be freed when the filesystem +- use `borg repo-space` to reserve some disk space that can be freed when the fs does not have free space any more. - if you use LVM: use a LV + a filesystem that you can resize later and have some unallocated PEs you can add to the LV. @@ -64,8 +64,8 @@ For a local repository always use the same user to invoke borg. -For a remote repository: always use e.g., ssh://borg@remote_host. You can use this -from different local users; the remote user running borg and accessing the +For a remote repository: always use e.g. ssh://borg@remote_host. You can use this +from different local users, the remote user running borg and accessing the repo will always be `borg`. If you need to access a local repository from different users, you can use the Index: borgbackup2/docs/quickstart_example.rst.inc =================================================================== --- borgbackup2.orig/docs/quickstart_example.rst.inc +++ borgbackup2/docs/quickstart_example.rst.inc @@ -7,12 +7,12 @@ $ borg -r /path/to/repo create docs ~/src ~/Documents -3. The next day, create a new archive using the same archive name:: +3. The next day create a new archive using the same archive name:: $ borg -r /path/to/repo create --stats docs ~/src ~/Documents - This backup will be much quicker and much smaller, since only new, - never-before-seen data is stored. The ``--stats`` option causes Borg to + This backup will be a lot quicker and a lot smaller since only new, never + before seen data is stored. The ``--stats`` option causes Borg to output statistics about the newly created archive such as the deduplicated size (the amount of unique data not shared with other archives):: @@ -22,7 +22,7 @@ Time (start): Sat, 2022-06-25 20:21:43 Time (end): Sat, 2022-06-25 20:21:43 Duration: 0.07 seconds - Utilization of maximum archive size: 0% + Utilization of max. archive size: 0% Number of files: 699 Original size: 31.14 MB Deduplicated size: 502 B @@ -44,14 +44,14 @@ $ borg -r /path/to/repo extract aid:b80e24d2 -7. Delete the first archive (please note that this does **not** free repository disk space):: +7. Delete the first archive (please note that this does **not** free repo disk space):: $ borg -r /path/to/repo delete aid:b80e24d2 - Be careful if you use an archive NAME (and not an archive ID), as it might match multiple archives. - Always use ``--dry-run`` and ``--list`` first! + Be careful if you use an archive NAME (and not an archive ID), that might match multiple archives! + Always first use with ``--dry-run`` and ``--list``! -8. Recover disk space by compacting the segment files in the repository:: +8. Recover disk space by compacting the segment files in the repo:: $ borg -r /path/to/repo compact -v Index: borgbackup2/docs/usage.rst =================================================================== --- borgbackup2.orig/docs/usage.rst +++ borgbackup2/docs/usage.rst @@ -9,11 +9,11 @@ Redirecting...