api: tape restore: avoid throwing away ns mapping, use target_store instead

avoid assembling a hash mapping of namespaces only to not use it,
i.e., throw it away then anyway

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

.gitignore

@@ -1,6 +1,16 @@
 local.mak
 /target
 **/*.rs.bk
+*~
+*.backup
+*.backup[0-9]
+*.backup[0-9][0-9]
+*.old
+*.old[0-9]
+*.old[0-9][0-9]
+*.5
+*.7
+__pycache__/
 /etc/proxmox-backup.service
 /etc/proxmox-backup-proxy.service
 build/

Cargo.toml

@@ -1,7 +1,16 @@
 [package]
 name = "proxmox-backup"
-version = "0.8.10"
+version = "2.2.3"
-authors = ["Dietmar Maurer <dietmar@proxmox.com>"]
+authors = [
+    "Dietmar Maurer <dietmar@proxmox.com>",
+    "Dominik Csapak <d.csapak@proxmox.com>",
+    "Christian Ebner <c.ebner@proxmox.com>",
+    "Fabian Grünbichler <f.gruenbichler@proxmox.com>",
+    "Stefan Reiter <s.reiter@proxmox.com>",
+    "Thomas Lamprecht <t.lamprecht@proxmox.com>",
+    "Wolfgang Bumiller <w.bumiller@proxmox.com>",
+    "Proxmox Support Team <support@proxmox.com>",
+]
 edition = "2018"
 license = "AGPL-3"
 description = "Proxmox Backup"
@@ -9,59 +18,134 @@ homepage = "https://www.proxmox.com"
 
 exclude = [ "build", "debian", "tests/catar_data/test_symlink/symlink1"]
 
+[workspace]
+members = [
+    "pbs-buildcfg",
+    "pbs-client",
+    "pbs-config",
+    "pbs-datastore",
+    "pbs-fuse-loop",
+    "proxmox-rest-server",
+    "proxmox-rrd",
+    "pbs-tape",
+    "pbs-tools",
+
+    "proxmox-backup-banner",
+    "proxmox-backup-client",
+    "proxmox-file-restore",
+    "proxmox-restore-daemon",
+    "pxar-bin",
+]
+
 [lib]
 name = "proxmox_backup"
 path = "src/lib.rs"
 
 [dependencies]
-apt-pkg-native = "0.3.1" # custom patched version
+apt-pkg-native = "0.3.2"
-base64 = "0.12"
+base64 = "0.13"
 bitflags = "1.2.1"
-bytes = "0.5"
+bytes = "1.0"
-chrono = "0.4" # Date and time library for Rust
+cidr = "0.2.1"
 crc32fast = "1"
 endian_trait = { version = "0.6", features = ["arrays"] }
+flate2 = "1.0"
 anyhow = "1.0"
+thiserror = "1.0"
 futures = "0.3"
-h2 = { version = "0.2", features = ["stream"] }
+h2 = { version = "0.3", features = [ "stream" ] }
 handlebars = "3.0"
+hex = "0.4.3"
 http = "0.2"
-hyper = "0.13"
+hyper = { version = "0.14", features = [ "full" ] }
 lazy_static = "1.4"
 libc = "0.2"
-log = "0.4"
+log = "0.4.17"
-nix = "0.16"
+nix = "0.24"
 num-traits = "0.2"
 once_cell = "1.3.1"
-openssl = "0.10"
+openssl = "0.10.38" # currently patched!
 pam = "0.7"
 pam-sys = "0.5"
 percent-encoding = "2.1"
-pin-utils = "0.1.0"
+regex = "1.5.5"
-pathpatterns = "0.1.2"
+rustyline = "9"
-proxmox = { version = "0.3.3", features = [ "sortable-macro", "api-macro", "websocket" ] }
-#proxmox = { git = "ssh://gitolite3@proxdev.maurer-it.com/rust/proxmox", version = "0.1.2", features = [ "sortable-macro", "api-macro" ] }
-#proxmox = { path = "../proxmox/proxmox", features = [ "sortable-macro", "api-macro", "websocket" ] }
-proxmox-fuse = "0.1.0"
-pxar = { version = "0.3.0", features = [ "tokio-io", "futures-io" ] }
-#pxar = { path = "../pxar", features = [ "tokio-io", "futures-io" ] }
-regex = "1.2"
-rustyline = "6"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 siphasher = "0.3"
 syslog = "4.0"
-tokio = { version = "0.2.9", features = [ "blocking", "fs", "dns", "io-util", "macros", "process", "rt-threaded", "signal", "stream", "tcp", "time", "uds" ] }
+tokio = { version = "1.6", features = [ "fs", "io-util", "io-std", "macros", "net", "parking_lot", "process", "rt", "rt-multi-thread", "signal", "time" ] }
-tokio-openssl = "0.4.0"
+tokio-openssl = "0.6.1"
-tokio-util = { version = "0.3", features = [ "codec" ] }
+tokio-stream = "0.1.0"
+tokio-util = { version = "0.7", features = [ "codec", "io" ] }
 tower-service = "0.3.0"
-udev = ">= 0.3, <0.5"
+udev = "0.4"
 url = "2.1"
 #valgrind_request = { git = "https://github.com/edef1c/libvalgrind_request", version = "1.1.0", optional = true }
 walkdir = "2"
 xdg = "2.2"
-zstd = { version = "0.4", features = [ "bindgen" ] }
 nom = "5.1"
+crossbeam-channel = "0.5"
+
+# Used only by examples currently:
+zstd = { version = "0.6", features = [ "bindgen" ] }
+
+pathpatterns = "0.1.2"
+pxar = { version = "0.10.1", features = [ "tokio-io" ] }
+
+proxmox-http = { version = "0.6.1", features = [ "client", "http-helpers", "websocket" ] }
+proxmox-io = "1"
+proxmox-lang = "1.1"
+proxmox-router = { version = "1.2.2", features = [ "cli" ] }
+proxmox-schema = { version = "1.3.1", features = [ "api-macro" ] }
+proxmox-section-config = "1"
+proxmox-tfa = { version = "2", features = [ "api", "api-types" ] }
+proxmox-time = "1.1.2"
+proxmox-uuid = "1"
+proxmox-serde = "0.1"
+proxmox-shared-memory = "0.2"
+proxmox-sys = { version = "0.3", features = [ "sortable-macro" ] }
+proxmox-compression = "0.1"
+
+
+proxmox-acme-rs = "0.4"
+proxmox-apt = "0.8.0"
+proxmox-async = "0.4"
+proxmox-openid = "0.9.0"
+
+pbs-api-types = { path = "pbs-api-types" }
+pbs-buildcfg = { path = "pbs-buildcfg" }
+pbs-client = { path = "pbs-client" }
+pbs-config = { path = "pbs-config" }
+pbs-datastore = { path = "pbs-datastore" }
+proxmox-rest-server = { path = "proxmox-rest-server" }
+proxmox-rrd = { path = "proxmox-rrd" }
+pbs-tools = { path = "pbs-tools" }
+pbs-tape = { path = "pbs-tape" }
+
+# Local path overrides
+# NOTE: You must run `cargo update` after changing this for it to take effect!
+[patch.crates-io]
+#proxmox-acme-rs = { path = "../proxmox-acme-rs" }
+#proxmox-apt = { path = "../proxmox-apt" }
+#proxmox-async = { path = "../proxmox/proxmox-async" }
+#proxmox-compression = { path = "../proxmox/proxmox-compression" }
+#proxmox-borrow = { path = "../proxmox/proxmox-borrow" }
+#proxmox-fuse = { path = "../proxmox-fuse" }
+#proxmox-http = { path = "../proxmox/proxmox-http" }
+#proxmox-io = { path = "../proxmox/proxmox-io" }
+#proxmox-lang = { path = "../proxmox/proxmox-lang" }
+#proxmox-openid = { path = "../proxmox-openid-rs" }
+#proxmox-router = { path = "../proxmox/proxmox-router" }
+#proxmox-schema = { path = "../proxmox/proxmox-schema" }
+#proxmox-section-config = { path = "../proxmox/proxmox-section-config" }
+#proxmox-shared-memory = { path = "../proxmox/proxmox-shared-memory" }
+#proxmox-sys = { path = "../proxmox/proxmox-sys" }
+#proxmox-serde = { path = "../proxmox/proxmox-serde" }
+#proxmox-tfa = { path = "../proxmox/proxmox-tfa" }
+#proxmox-time = { path = "../proxmox/proxmox-time" }
+#proxmox-uuid = { path = "../proxmox/proxmox-uuid" }
+#pxar = { path = "../pxar" }
 
 [features]
 default = []

Makefile

@@ -9,17 +9,44 @@ SUBDIRS := etc www docs
 # Binaries usable by users
 USR_BIN := \
 	proxmox-backup-client 	\
-	pxar
+	proxmox-file-restore	\
+	pxar			\
+	proxmox-tape		\
+	pmtx			\
+	pmt
 
 # Binaries usable by admins
 USR_SBIN := \
-	proxmox-backup-manager
+	proxmox-backup-manager \
+	proxmox-backup-debug \
 
 # Binaries for services:
 SERVICE_BIN := \
 	proxmox-backup-api \
 	proxmox-backup-banner \
-	proxmox-backup-proxy
+	proxmox-backup-proxy \
+	proxmox-daily-update
+
+# Single file restore daemon
+RESTORE_BIN := \
+	proxmox-restore-daemon
+
+SUBCRATES := \
+	pbs-api-types \
+	pbs-buildcfg \
+	pbs-client \
+	pbs-config \
+	pbs-datastore \
+	pbs-fuse-loop \
+	proxmox-rest-server \
+	proxmox-rrd \
+	pbs-tape \
+	pbs-tools \
+	proxmox-backup-banner \
+	proxmox-backup-client \
+	proxmox-file-restore \
+	proxmox-restore-daemon \
+	pxar-bin
 
 ifeq ($(BUILD_MODE), release)
 CARGO_BUILD_ARGS += --release
@@ -35,7 +62,7 @@ endif
 CARGO ?= cargo
 
 COMPILED_BINS := \
-	$(addprefix $(COMPILEDIR)/,$(USR_BIN) $(USR_SBIN) $(SERVICE_BIN))
+	$(addprefix $(COMPILEDIR)/,$(USR_BIN) $(USR_SBIN) $(SERVICE_BIN) $(RESTORE_BIN))
 
 export DEB_VERSION DEB_VERSION_UPSTREAM
 
@@ -43,15 +70,20 @@ SERVER_DEB=${PACKAGE}-server_${DEB_VERSION}_${ARCH}.deb
 SERVER_DBG_DEB=${PACKAGE}-server-dbgsym_${DEB_VERSION}_${ARCH}.deb
 CLIENT_DEB=${PACKAGE}-client_${DEB_VERSION}_${ARCH}.deb
 CLIENT_DBG_DEB=${PACKAGE}-client-dbgsym_${DEB_VERSION}_${ARCH}.deb
+RESTORE_DEB=proxmox-backup-file-restore_${DEB_VERSION}_${ARCH}.deb
+RESTORE_DBG_DEB=proxmox-backup-file-restore-dbgsym_${DEB_VERSION}_${ARCH}.deb
 DOC_DEB=${PACKAGE}-docs_${DEB_VERSION}_all.deb
 
-DEBS=${SERVER_DEB} ${SERVER_DBG_DEB} ${CLIENT_DEB} ${CLIENT_DBG_DEB}
+DEBS=${SERVER_DEB} ${SERVER_DBG_DEB} ${CLIENT_DEB} ${CLIENT_DBG_DEB} \
+     ${RESTORE_DEB} ${RESTORE_DBG_DEB} ${DEBUG_DEB} ${DEBUG_DBG_DEB}
 
 DSC = rust-${PACKAGE}_${DEB_VERSION}.dsc
 
 DESTDIR=
 
-all: cargo-build $(SUBDIRS)
+tests ?= --workspace
+
+all: $(SUBDIRS)
 
 .PHONY: $(SUBDIRS)
 $(SUBDIRS):
@@ -63,19 +95,23 @@ test:
 	$(CARGO) test $(tests) $(CARGO_BUILD_ARGS)
 
 doc:
-	$(CARGO) doc --no-deps $(CARGO_BUILD_ARGS)
+	$(CARGO) doc --workspace --no-deps $(CARGO_BUILD_ARGS)
 
 # always re-create this dir
 .PHONY: build
 build:
+	@echo "Setting pkg-buildcfg version to: $(DEB_VERSION_UPSTREAM)"
+	sed -i -e 's/^version =.*$$/version = "$(DEB_VERSION_UPSTREAM)"/' \
+	  pbs-buildcfg/Cargo.toml
 	rm -rf build
-	rm -f debian/control
+	mkdir build
-	debcargo package --config debian/debcargo.toml --changelog-ready --no-overlay-write-back --directory build proxmox-backup $(shell dpkg-parsechangelog -l debian/changelog -SVersion | sed -e 's/-.*//')
+	cp -a debian \
-	sed -e '1,/^$$/ ! d' build/debian/control > build/debian/control.src
+	  Cargo.toml src \
-	cat build/debian/control.src build/debian/control.in > build/debian/control
+	  $(SUBCRATES) \
-	rm build/debian/control.in build/debian/control.src
+	  docs etc examples tests www zsh-completions \
-	cp build/debian/control debian/control
+	  defines.mk Makefile \
-	rm build/Cargo.lock
+	  ./build/
+	rm -f build/Cargo.lock
 	find build/debian -name "*.hint" -delete
 	$(foreach i,$(SUBDIRS), \
 	    $(MAKE) -C build/$(i) clean ;)
@@ -95,7 +131,9 @@ deb: build
 	lintian $(DEBS)
 
 .PHONY: deb-all
-deb-all: $(DOC_DEB) $(DEBS)
+deb-all: build
+	cd build; dpkg-buildpackage -b -us -uc --no-pre-clean
+	lintian $(DEBS) $(DOC_DEB)
 
 .PHONY: dsc
 dsc: $(DSC)
@@ -103,27 +141,61 @@ $(DSC): build
 	cd build; dpkg-buildpackage -S -us -uc -d -nc
 	lintian $(DSC)
 
+.PHONY: clean distclean deb clean
 distclean: clean
-
+clean: clean-deb
-clean:
 	$(foreach i,$(SUBDIRS), \
 	    $(MAKE) -C $(i) clean ;)
 	$(CARGO) clean
-	rm -rf *.deb *.dsc *.tar.gz *.buildinfo *.changes build
+	rm -f .do-cargo-build
 	find . -name '*~' -exec rm {} ';'
 
+# allows one to avoid running cargo clean when one just wants to tidy up after a packgae build
+clean-deb:
+	rm -rf *.deb *.dsc *.tar.gz *.buildinfo *.changes build/
+
 .PHONY: dinstall
-dinstall: ${DEBS}
+dinstall: ${SERVER_DEB} ${SERVER_DBG_DEB} ${CLIENT_DEB} ${CLIENT_DBG_DEB} \
-	dpkg -i ${DEBS}
+  ${DEBUG_DEB} ${DEBUG_DBG_DEB}
+	dpkg -i $^
 
 # make sure we build binaries before docs
-docs: cargo-build
+docs: $(COMPILEDIR)/dump-catalog-shell-cli $(COMPILEDIR)/docgen
 
 .PHONY: cargo-build
 cargo-build:
-	$(CARGO) build $(CARGO_BUILD_ARGS)
+	rm -f .do-cargo-build
+	$(MAKE) $(COMPILED_BINS)
+
+$(COMPILED_BINS) $(COMPILEDIR)/dump-catalog-shell-cli $(COMPILEDIR)/docgen: .do-cargo-build
+.do-cargo-build:
+	$(CARGO) build $(CARGO_BUILD_ARGS) \
+	    --package proxmox-backup-banner \
+	    --bin proxmox-backup-banner \
+	    --package proxmox-backup-client \
+	    --bin proxmox-backup-client \
+	    --bin dump-catalog-shell-cli \
+	    --bin proxmox-backup-debug \
+	    --package proxmox-file-restore \
+	    --bin proxmox-file-restore \
+	    --package pxar-bin \
+	    --bin pxar \
+	    --package pbs-tape \
+	    --bin pmt \
+	    --bin pmtx \
+	    --package proxmox-restore-daemon \
+	    --bin proxmox-restore-daemon \
+	    --package proxmox-backup \
+	    --bin docgen \
+	    --bin proxmox-backup-api \
+	    --bin proxmox-backup-manager \
+	    --bin proxmox-backup-proxy \
+	    --bin proxmox-daily-update \
+	    --bin proxmox-file-restore \
+	    --bin proxmox-tape \
+	    --bin sg-tape-cmd
+	touch "$@"
 
-$(COMPILED_BINS): cargo-build
 
 .PHONY: lint
 lint:
@@ -140,14 +212,22 @@ install: $(COMPILED_BINS)
 	    install -m755 $(COMPILEDIR)/$(i) $(DESTDIR)$(SBINDIR)/ ; \
 	    install -m644 zsh-completions/_$(i) $(DESTDIR)$(ZSH_COMPL_DEST)/ ;)
 	install -dm755 $(DESTDIR)$(LIBEXECDIR)/proxmox-backup
+	install -dm755 $(DESTDIR)$(LIBEXECDIR)/proxmox-backup/file-restore
+	$(foreach i,$(RESTORE_BIN), \
+	    install -m755 $(COMPILEDIR)/$(i) $(DESTDIR)$(LIBEXECDIR)/proxmox-backup/file-restore/ ;)
+	# install sg-tape-cmd as setuid binary
+	install -m4755 -o root -g root $(COMPILEDIR)/sg-tape-cmd $(DESTDIR)$(LIBEXECDIR)/proxmox-backup/sg-tape-cmd
 	$(foreach i,$(SERVICE_BIN), \
 	    install -m755 $(COMPILEDIR)/$(i) $(DESTDIR)$(LIBEXECDIR)/proxmox-backup/ ;)
 	$(MAKE) -C www install
 	$(MAKE) -C docs install
 
 .PHONY: upload
-upload: ${SERVER_DEB} ${CLIENT_DEB} ${DOC_DEB}
+upload: ${SERVER_DEB} ${CLIENT_DEB} ${RESTORE_DEB} ${DOC_DEB} ${DEBUG_DEB}
 	# check if working directory is clean
 	git diff --exit-code --stat && git diff --exit-code --stat --staged
-	tar cf - ${SERVER_DEB} ${SERVER_DBG_DEB} ${DOC_DEB} | ssh -X repoman@repo.proxmox.com upload --product pbs --dist buster
+	tar cf - ${SERVER_DEB} ${SERVER_DBG_DEB} ${DOC_DEB} ${CLIENT_DEB} \
-	tar cf - ${CLIENT_DEB} ${CLIENT_DBG_DEB} | ssh -X repoman@repo.proxmox.com upload --product "pbs,pve" --dist buster
+	    ${CLIENT_DBG_DEB} ${DEBUG_DEB} ${DEBUG_DBG_DEB} \
+	  | ssh -X repoman@repo.proxmox.com upload --product pbs --dist bullseye
+	tar cf - ${CLIENT_DEB} ${CLIENT_DBG_DEB} | ssh -X repoman@repo.proxmox.com upload --product "pve,pmg,pbs-client" --dist bullseye
+	tar cf - ${RESTORE_DEB} ${RESTORE_DBG_DEB} | ssh -X repoman@repo.proxmox.com upload --product "pve" --dist bullseye

README.rst

@@ -1,3 +1,7 @@
+
+Build & Release Notes
+*********************
+
 ``rustup`` Toolchain
 ====================
 
@@ -13,7 +17,7 @@ Versioning of proxmox helper crates
 
 To use current git master code of the proxmox* helper crates, add::
 
-   git = "ssh://gitolite3@proxdev.maurer-it.com/rust/proxmox"
+   git = "git://git.proxmox.com/git/proxmox"
 
 or::
 
@@ -22,6 +26,7 @@ or::
 to the proxmox dependency, and update the version to reflect the current,
 pre-release version number (e.g., "0.1.1-dev.1" instead of "0.1.0").
 
+
 Local cargo config
 ==================
 
@@ -35,3 +40,103 @@ checksums are not compatible.
 To reference new dependencies (or updated versions) that are not yet packaged,
 the dependency needs to point directly to a path or git source (e.g., see
 example for proxmox crate above).
+
+
+Build
+=====
+on Debian 11 Bullseye
+
+Setup:
+  1. # echo 'deb http://download.proxmox.com/debian/devel/ bullseye main' | sudo tee /etc/apt/sources.list.d/proxmox-devel.list
+  2. # sudo wget https://enterprise.proxmox.com/debian/proxmox-release-bullseye.gpg -O /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
+  3. # sudo apt update
+  4. # sudo apt install devscripts debcargo clang
+  5. # git clone git://git.proxmox.com/git/proxmox-backup.git
+  6. # cd proxmox-backup; sudo mk-build-deps -ir
+
+Note: 2. may be skipped if you already added the PVE or PBS package repository
+
+You are now able to build using the Makefile or cargo itself, e.g.::
+
+  # make deb-all
+  # # or for a non-package build
+  # cargo build --all --release
+
+Design Notes
+************
+
+Here are some random thought about the software design (unless I find a better place).
+
+
+Large chunk sizes
+=================
+
+It is important to notice that large chunk sizes are crucial for performance.
+We have a multi-user system, where different people can do different operations
+on a datastore at the same time, and most operation involves reading a series
+of chunks.
+
+So what is the maximal theoretical speed we can get when reading a series of
+chunks? Reading a chunk sequence need the following steps:
+
+- seek to the first chunk's start location
+- read the chunk data
+- seek to the next chunk's start location
+- read the chunk data
+- ...
+
+Lets use the following disk performance metrics:
+
+:AST: Average Seek Time (second)
+:MRS: Maximum sequential Read Speed (bytes/second)
+:ACS: Average Chunk Size (bytes)
+
+The maximum performance you can get is::
+
+  MAX(ACS) = ACS /(AST + ACS/MRS)
+
+Please note that chunk data is likely to be sequential arranged on disk, but
+this it is sort of a best case assumption.
+
+For a typical rotational disk, we assume the following values::
+
+  AST: 10ms
+  MRS: 170MB/s
+
+  MAX(4MB)  = 115.37 MB/s
+  MAX(1MB)  =  61.85 MB/s;
+  MAX(64KB) =   6.02 MB/s;
+  MAX(4KB)  =   0.39 MB/s;
+  MAX(1KB)  =   0.10 MB/s;
+
+Modern SSD are much faster, lets assume the following::
+
+  max IOPS: 20000 => AST = 0.00005
+  MRS: 500Mb/s
+
+  MAX(4MB)  = 474 MB/s
+  MAX(1MB)  = 465 MB/s;
+  MAX(64KB) = 354 MB/s;
+  MAX(4KB)  =  67 MB/s;
+  MAX(1KB)  =  18 MB/s;
+
+
+Also, the average chunk directly relates to the number of chunks produced by
+a backup::
+
+  CHUNK_COUNT = BACKUP_SIZE / ACS
+
+Here are some staticics from my developer worstation::
+
+  Disk Usage:       65 GB
+  Directories:   58971
+  Files:        726314
+  Files < 64KB: 617541
+
+As you see, there are really many small files. If we would do file
+level deduplication, i.e. generate one chunk per file, we end up with
+more than 700000 chunks.
+
+Instead, our current algorithm only produce large chunks with an
+average chunks size of 4MB. With above data, this produce about 15000
+chunks (factor 50 less chunks).

TODO.rst

@@ -35,3 +35,4 @@ Chores:
 
 Suggestions
 ===========
+

debian/control

@@ -1,123 +1,174 @@
 Source: rust-proxmox-backup
 Section: admin
 Priority: optional
-Build-Depends: debhelper (>= 11),
+Build-Depends: debhelper (>= 12),
- dh-cargo (>= 18),
+ dh-cargo (>= 24),
  cargo:native,
  rustc:native,
  libstd-rust-dev,
  librust-anyhow-1+default-dev,
- librust-apt-pkg-native-0.3+default-dev (>= 0.3.1-~~),
+ librust-apt-pkg-native-0.3+default-dev (>= 0.3.2-~~),
- librust-base64-0.12+default-dev,
+ librust-base64-0.13+default-dev,
  librust-bitflags-1+default-dev (>= 1.2.1-~~),
- librust-bytes-0.5+default-dev,
+ librust-bytes-1+default-dev,
- librust-chrono-0.4+default-dev,
+ librust-cidr-0.2+default-dev (>= 0.2.1-~~),
  librust-crc32fast-1+default-dev,
+ librust-crossbeam-channel-0.5+default-dev,
  librust-endian-trait-0.6+arrays-dev,
  librust-endian-trait-0.6+default-dev,
+ librust-env-logger-0.9+default-dev,
+ librust-flate2-1+default-dev,
+ librust-foreign-types-0.3+default-dev,
  librust-futures-0.3+default-dev,
- librust-h2-0.2+default-dev,
+ librust-h2-0.3+default-dev,
- librust-h2-0.2+stream-dev,
+ librust-h2-0.3+stream-dev,
  librust-handlebars-3+default-dev,
+ librust-hex-0.4+default-dev (>= 0.4.3-~~),
+ librust-hex-0.4+serde-dev (>= 0.4.3-~~),
  librust-http-0.2+default-dev,
- librust-hyper-0.13+default-dev,
+ librust-hyper-0.14+default-dev (>= 0.14.5-~~),
+ librust-hyper-0.14+full-dev (>= 0.14.5-~~),
  librust-lazy-static-1+default-dev (>= 1.4-~~),
  librust-libc-0.2+default-dev,
- librust-log-0.4+default-dev,
+ librust-log-0.4+default-dev (>= 0.4.17-~~) <!nocheck>,
- librust-nix-0.16+default-dev,
+ librust-nix-0.24+default-dev,
  librust-nom-5+default-dev (>= 5.1-~~),
  librust-num-traits-0.2+default-dev,
  librust-once-cell-1+default-dev (>= 1.3.1-~~),
- librust-openssl-0.10+default-dev,
+ librust-openssl-0.10+default-dev (>= 0.10.38-~~),
  librust-pam-0.7+default-dev,
  librust-pam-sys-0.5+default-dev,
  librust-pathpatterns-0.1+default-dev (>= 0.1.2-~~),
  librust-percent-encoding-2+default-dev (>= 2.1-~~),
- librust-pin-utils-0.1+default-dev,
+ librust-pin-project-lite-0.2+default-dev,
- librust-proxmox-0.3+api-macro-dev (>= 0.3.3-~~),
+ librust-proxmox-acme-rs-0.4+default-dev,
- librust-proxmox-0.3+default-dev (>= 0.3.3-~~),
+ librust-proxmox-apt-0.8+default-dev,
- librust-proxmox-0.3+sortable-macro-dev (>= 0.3.3-~~),
+ librust-proxmox-async-0.4+default-dev,
- librust-proxmox-0.3+websocket-dev (>= 0.3.3-~~),
+ librust-proxmox-borrow-1+default-dev,
- librust-proxmox-fuse-0.1+default-dev,
+ librust-proxmox-compression-0.1+default-dev (>= 0.1.1-~~),
- librust-pxar-0.3+default-dev,
+ librust-proxmox-fuse-0.1+default-dev (>= 0.1.1-~~),
- librust-pxar-0.3+futures-io-dev,
+ librust-proxmox-http-0.6+client-dev (>= 0.6.1-~~),
- librust-pxar-0.3+tokio-io-dev,
+ librust-proxmox-http-0.6+default-dev (>= 0.6.1-~~),
- librust-regex-1+default-dev (>= 1.2-~~),
+ librust-proxmox-http-0.6+http-helpers-dev (>= 0.6.1-~~),
- librust-rustyline-6+default-dev,
+ librust-proxmox-http-0.6+websocket-dev (>= 0.6.1-~~),
+ librust-proxmox-io-1+default-dev (>= 1.0.1-~~),
+ librust-proxmox-io-1+tokio-dev (>= 1.0.1-~~),
+ librust-proxmox-lang-1+default-dev (>= 1.1-~~),
+ librust-proxmox-openid-0.9+default-dev,
+ librust-proxmox-router-1+cli-dev (>= 1.2-~~),
+ librust-proxmox-router-1+default-dev (>= 1.2.2-~~),
+ librust-proxmox-schema-1+api-macro-dev (>= 1.3.1-~~),
+ librust-proxmox-schema-1+default-dev (>= 1.3.1-~~),
+ librust-proxmox-schema-1+upid-api-impl-dev (>= 1.3.1-~~),
+ librust-proxmox-section-config-1+default-dev,
+ librust-proxmox-serde-0.1+default-dev,
+ librust-proxmox-shared-memory-0.2+default-dev,
+ librust-proxmox-sys-0.3+default-dev,
+ librust-proxmox-sys-0.3+logrotate-dev,
+ librust-proxmox-sys-0.3+sortable-macro-dev,
+ librust-proxmox-tfa-2+api-dev,
+ librust-proxmox-tfa-2+api-types-dev,
+ librust-proxmox-tfa-2+default-dev,
+ librust-proxmox-time-1+default-dev (>= 1.1.2-~~),
+ librust-proxmox-uuid-1+default-dev,
+ librust-proxmox-uuid-1+serde-dev,
+ librust-pxar-0.10+default-dev (>= 0.10.1-~~),
+ librust-pxar-0.10+tokio-io-dev (>= 0.10.1-~~),
+ librust-regex-1+default-dev (>= 1.5.5-~~),
+ librust-rustyline-9+default-dev,
  librust-serde-1+default-dev,
  librust-serde-1+derive-dev,
+ librust-serde-cbor-0.11+default-dev (>= 0.11.1-~~),
  librust-serde-json-1+default-dev,
  librust-siphasher-0.3+default-dev,
  librust-syslog-4+default-dev,
- librust-tokio-0.2+blocking-dev (>= 0.2.9-~~),
+ librust-thiserror-1+default-dev,
- librust-tokio-0.2+default-dev (>= 0.2.9-~~),
+ librust-tokio-1+default-dev (>= 1.6-~~),
- librust-tokio-0.2+dns-dev (>= 0.2.9-~~),
+ librust-tokio-1+fs-dev (>= 1.6-~~),
- librust-tokio-0.2+fs-dev (>= 0.2.9-~~),
+ librust-tokio-1+io-std-dev (>= 1.6-~~),
- librust-tokio-0.2+io-util-dev (>= 0.2.9-~~),
+ librust-tokio-1+io-util-dev (>= 1.6-~~),
- librust-tokio-0.2+macros-dev (>= 0.2.9-~~),
+ librust-tokio-1+macros-dev (>= 1.6-~~),
- librust-tokio-0.2+process-dev (>= 0.2.9-~~),
+ librust-tokio-1+net-dev (>= 1.6-~~),
- librust-tokio-0.2+rt-threaded-dev (>= 0.2.9-~~),
+ librust-tokio-1+parking-lot-dev (>= 1.6-~~),
- librust-tokio-0.2+signal-dev (>= 0.2.9-~~),
+ librust-tokio-1+process-dev (>= 1.6-~~),
- librust-tokio-0.2+stream-dev (>= 0.2.9-~~),
+ librust-tokio-1+rt-dev (>= 1.6-~~),
- librust-tokio-0.2+tcp-dev (>= 0.2.9-~~),
+ librust-tokio-1+rt-multi-thread-dev (>= 1.6-~~),
- librust-tokio-0.2+time-dev (>= 0.2.9-~~),
+ librust-tokio-1+signal-dev (>= 1.6-~~),
- librust-tokio-0.2+uds-dev (>= 0.2.9-~~),
+ librust-tokio-1+sync-dev (>= 1.6-~~),
- librust-tokio-openssl-0.4+default-dev,
+ librust-tokio-1+time-dev (>= 1.6-~~),
- librust-tokio-util-0.3+codec-dev,
+ librust-tokio-openssl-0.6+default-dev (>= 0.6.1-~~),
- librust-tokio-util-0.3+default-dev,
+ librust-tokio-stream-0.1+default-dev,
+ librust-tokio-util-0.7+codec-dev,
+ librust-tokio-util-0.7+default-dev,
+ librust-tokio-util-0.7+io-dev,
  librust-tower-service-0.3+default-dev,
- librust-udev-0.4+default-dev | librust-udev-0.3+default-dev,
+ librust-udev-0.4+default-dev,
  librust-url-2+default-dev (>= 2.1-~~),
  librust-walkdir-2+default-dev,
  librust-xdg-2+default-dev (>= 2.2-~~),
- librust-zstd-0.4+bindgen-dev,
+ librust-zstd-0.6+bindgen-dev,
- librust-zstd-0.4+default-dev,
+ librust-zstd-0.6+default-dev,
  libacl1-dev,
  libfuse3-dev,
- libsystemd-dev,
+ libsystemd-dev (>= 246-~~),
  uuid-dev,
- debhelper (>= 12~),
+ libsgutils2-dev,
  bash-completion,
- python3-docutils,
+ debhelper (>= 12~),
- python3-pygments,
- rsync,
  fonts-dejavu-core <!nodoc>,
  fonts-lato <!nodoc>,
  fonts-open-sans <!nodoc>,
  graphviz <!nodoc>,
  latexmk <!nodoc>,
+ patchelf,
+ proxmox-widget-toolkit-dev <!nodoc>,
+ pve-eslint (>= 7.18.0-1),
+ python3-docutils,
+ python3-pygments,
  python3-sphinx <!nodoc>,
+ rsync,
  texlive-fonts-extra <!nodoc>,
  texlive-fonts-recommended <!nodoc>,
  texlive-xetex <!nodoc>,
  xindy <!nodoc>
 Maintainer: Proxmox Support Team <support@proxmox.com>
-Standards-Version: 4.4.1
+Standards-Version: 4.5.1
-Vcs-Git: 
+Vcs-Git: git://git.proxmox.com/git/proxmox-backup.git
-Vcs-Browser: 
+Vcs-Browser: https://git.proxmox.com/?p=proxmox-backup.git;a=summary
 Homepage: https://www.proxmox.com
+Rules-Requires-Root: binary-targets
 
 Package: proxmox-backup-server
 Architecture: any
 Depends: fonts-font-awesome,
-         libjs-extjs (>= 6.0.1),
+         libjs-extjs (>= 7~),
+         libjs-qrcodejs (>= 1.20201119),
+         libproxmox-acme-plugins,
+         libsgutils2-2,
          libzstd1 (>= 1.3.8),
          lvm2,
+         openssh-server,
+         pbs-i18n,
+         postfix | mail-transport-agent,
          proxmox-backup-docs,
          proxmox-mini-journalreader,
-         proxmox-widget-toolkit (>= 2.2-4),
+         proxmox-widget-toolkit (>= 3.4-3),
          pve-xtermjs (>= 4.7.0-1),
+         sg3-utils,
          smartmontools,
          ${misc:Depends},
          ${shlibs:Depends},
 Recommends: zfsutils-linux,
+            ifupdown2,
 Description: Proxmox Backup Server daemon with tools and GUI
  This package contains the Proxmox Backup Server daemons and related
  tools. This includes a web-based graphical user interface.
 
 Package: proxmox-backup-client
 Architecture: any
-Depends: ${misc:Depends}, ${shlibs:Depends}
+Depends: qrencode,
+         ${misc:Depends},
+         ${shlibs:Depends},
 Description: Proxmox Backup Client tools
  This package contains the Proxmox Backup client, which provides a
  simple command line tool to create and restore backups.
@@ -125,8 +176,22 @@ Description: Proxmox Backup Client tools
 Package: proxmox-backup-docs
 Build-Profiles: <!nodoc>
 Section: doc
-Depends: libjs-extjs,
+Depends: fonts-font-awesome,
+         libjs-extjs,
+         libjs-mathjax,
          ${misc:Depends},
 Architecture: all
 Description: Proxmox Backup Documentation
  This package contains the Proxmox Backup Documentation files.
+
+Package: proxmox-backup-file-restore
+Architecture: any
+Depends: ${misc:Depends},
+         ${shlibs:Depends},
+Recommends: pve-qemu-kvm (>= 5.0.0-9),
+            proxmox-backup-restore-image,
+Breaks: proxmox-backup-restore-image (<< 0.3.1)
+Description: Proxmox Backup single file restore tools for pxar and block device backups
+ This package contains the Proxmox Backup single file restore client for
+ restoring individual files and folders from both host/container and VM/block
+ device backups. It includes a block device restore driver using QEMU.

debian/control.in

@@ -1,33 +0,0 @@
-Package: proxmox-backup-server
-Architecture: any
-Depends: fonts-font-awesome,
-         libjs-extjs (>= 6.0.1),
-         libzstd1 (>= 1.3.8),
-         lvm2,
-         proxmox-backup-docs,
-         proxmox-mini-journalreader,
-         proxmox-widget-toolkit (>= 2.2-4),
-         pve-xtermjs (>= 4.7.0-1),
-         smartmontools,
-         ${misc:Depends},
-         ${shlibs:Depends},
-Recommends: zfsutils-linux,
-Description: Proxmox Backup Server daemon with tools and GUI
- This package contains the Proxmox Backup Server daemons and related
- tools. This includes a web-based graphical user interface.
-
-Package: proxmox-backup-client
-Architecture: any
-Depends: ${misc:Depends}, ${shlibs:Depends}
-Description: Proxmox Backup Client tools
- This package contains the Proxmox Backup client, which provides a
- simple command line tool to create and restore backups.
-
-Package: proxmox-backup-docs
-Build-Profiles: <!nodoc>
-Section: doc
-Depends: libjs-extjs,
-         ${misc:Depends},
-Architecture: all
-Description: Proxmox Backup Documentation
- This package contains the Proxmox Backup Documentation files.

debian/copyright

@@ -1,4 +1,4 @@
-Copyright (C) 2019 Proxmox Server Solutions GmbH
+Copyright (C) 2019 - 2021 Proxmox Server Solutions GmbH
 
 This software is written by Proxmox Server Solutions GmbH <support@proxmox.com>
 

debian/debcargo.toml

@@ -1,41 +0,0 @@
-overlay = "."
-crate_src_path = ".."
-whitelist = ["tests/*.c"]
-
-# needed for pinutils alpha
-allow_prerelease_deps = true
-
-[source]
-# TODO: update once public
-vcs_git = ""
-vcs_browser = ""
-maintainer = "Proxmox Support Team <support@proxmox.com>"
-section = "admin"
-build_depends = [
-  "debhelper (>= 12~)",
-  "bash-completion",
-  "python3-docutils",
-  "python3-pygments",
-  "rsync",
-  "fonts-dejavu-core <!nodoc>",
-  "fonts-lato <!nodoc>",
-  "fonts-open-sans <!nodoc>",
-  "graphviz <!nodoc>",
-  "latexmk <!nodoc>",
-  "python3-sphinx <!nodoc>",
-  "texlive-fonts-extra <!nodoc>",
-  "texlive-fonts-recommended <!nodoc>",
-  "texlive-xetex <!nodoc>",
-  "xindy <!nodoc>",
-]
-build_depends_excludes = [
-  "debhelper (>=11)",
-]
-
-[packages.lib]
-depends = [
-  "libacl1-dev",
-  "libfuse3-dev",
-  "libsystemd-dev",
-  "uuid-dev",
-]

debian/lintian-overrides

@@ -1,2 +1,2 @@
-proxmox-backup-server: package-installs-apt-sources etc/apt/sources.list.d/pbstest-beta.list
+proxmox-backup-server: package-installs-apt-sources etc/apt/sources.list.d/pbs-enterprise.list
 proxmox-backup-server: systemd-service-file-refers-to-unusual-wantedby-target lib/systemd/system/proxmox-backup-banner.service getty.target

debian/pmt.bc

@@ -0,0 +1,3 @@
+# pmt bash completion
+
+complete -C 'pmt bashcomplete' pmt

debian/pmtx.bc

@@ -0,0 +1,3 @@
+# pmtx bash completion
+
+complete -C 'pmtx bashcomplete' pmtx

debian/postinst

@@ -4,16 +4,73 @@ set -e
 
 #DEBHELPER#
 
+update_sync_job() {
+    job="$1"
+
+    echo "Updating sync job '$job' to make old 'remove-vanished' default explicit.."
+    proxmox-backup-manager sync-job update "$job" --remove-vanished true \
+      || echo "Failed, please check sync.cfg manually!"
+}
+
 case "$1" in
     configure)
+	# need to have user backup in the tape group
+	usermod -a -G tape backup
+
 	# modeled after dh_systemd_start output
 	systemctl --system daemon-reload >/dev/null || true
 	if [ -n "$2" ]; then
+		if dpkg --compare-versions "$2" 'lt' '1.0.7-1'; then
+			# there was an issue with reloading and systemd being confused in older daemon versions
+			# so restart instead of reload if upgrading from there, see commit 0ec79339f7aebf9
+			# FIXME: remove with PBS 2.1
+			echo "Upgrading from older proxmox-backup-server: restart (not reload) daemons"
+			_dh_action=try-restart
+		else
 			_dh_action=try-reload-or-restart
+		fi
 	else
 		_dh_action=start
 	fi
 	deb-systemd-invoke $_dh_action proxmox-backup.service proxmox-backup-proxy.service >/dev/null || true
+
+	if test -n "$2"; then
+		# FIXME: Remove in future version once we're sure no broken entries remain in anyone's files
+		if grep -q -e ':termproxy::[^@]\+: ' /var/log/proxmox-backup/tasks/active; then
+			echo "Fixing up termproxy user id in task log..."
+			flock -w 30 /var/log/proxmox-backup/tasks/active.lock sed -i 's/:termproxy::\([^@]\+\): /:termproxy::\1@pam: /' /var/log/proxmox-backup/tasks/active || true
+		fi
+
+		if dpkg --compare-versions "$2" 'lt' '2.2.2~'; then
+			echo "moving prune schedule from datacenter config to new prune job config"
+			proxmox-backup-manager update-to-prune-jobs-config \
+			    || echo "Failed to move prune jobs, please check manually"
+			true
+		fi
+
+		if dpkg --compare-versions "$2" 'lt' '2.1.3~' && test -e /etc/proxmox-backup/sync.cfg; then
+			prev_job=""
+
+			# read from HERE doc because POSIX sh limitations
+			while read -r key value; do
+				if test "$key" = "sync:"; then
+					if test -n "$prev_job"; then
+						# previous job doesn't have an explicit value
+						update_sync_job "$prev_job"
+					fi
+					prev_job=$value
+				else
+					prev_job=""
+				fi
+			done <<EOF
+$(grep -e '^sync:' -e 'remove-vanished' /etc/proxmox-backup/sync.cfg)
+EOF
+			if test -n "$prev_job"; then
+				# last job doesn't have an explicit value
+				update_sync_job "$prev_job"
+			fi
+		fi
+	fi
     ;;
 
     abort-upgrade|abort-remove|abort-deconfigure)

debian/prerm

@@ -6,5 +6,6 @@ set -e
 
 # modeled after dh_systemd_start output
 if [ -d /run/systemd/system ] && [ "$1" = remove ]; then
-    deb-systemd-invoke stop 'proxmox-backup-banner.service' 'proxmox-backup-proxy.service' 'proxmox-backup.service' >/dev/null || true
+    deb-systemd-invoke stop 'proxmox-backup-banner.service' 'proxmox-backup-proxy.service' \
+        'proxmox-backup.service' 'proxmox-backup-daily-update.timer' >/dev/null || true
 fi

debian/proxmox-backup-debug.bc

@@ -0,0 +1,8 @@
+# proxmox-backup-debug bash completion
+
+# see http://tiswww.case.edu/php/chet/bash/FAQ
+# and __ltrim_colon_completions() in /usr/share/bash-completion/bash_completion
+# this modifies global var, but I found no better way
+COMP_WORDBREAKS=${COMP_WORDBREAKS//:}
+
+complete -C 'proxmox-backup-debug bashcomplete' proxmox-backup-debug

debian/proxmox-backup-docs.links

@@ -1 +1,6 @@
 /usr/share/doc/proxmox-backup/proxmox-backup.pdf /usr/share/doc/proxmox-backup/html/proxmox-backup.pdf
+/usr/share/javascript/extjs /usr/share/doc/proxmox-backup/html/prune-simulator/extjs
+/usr/share/javascript/extjs /usr/share/doc/proxmox-backup/html/lto-barcode/extjs
+/usr/share/fonts-font-awesome/ /usr/share/doc/proxmox-backup/html/lto-barcode/font-awesome
+/usr/share/javascript/extjs /usr/share/doc/proxmox-backup/html/api-viewer/extjs
+/usr/share/javascript/mathjax /usr/share/doc/proxmox-backup/html/_static/mathjax

debian/proxmox-backup-file-restore.bash-completion

@@ -0,0 +1 @@
+debian/proxmox-file-restore.bc proxmox-file-restore

debian/proxmox-backup-file-restore.bc

@@ -0,0 +1,8 @@
+# proxmox-file-restore bash completion
+
+# see http://tiswww.case.edu/php/chet/bash/FAQ
+# and __ltrim_colon_completions() in /usr/share/bash-completion/bash_completion
+# this modifies global var, but I found no better way
+COMP_WORDBREAKS=${COMP_WORDBREAKS//:}
+
+complete -C 'proxmox-file-restore bashcomplete' proxmox-file-restore

debian/proxmox-backup-file-restore.install

@@ -0,0 +1,4 @@
+usr/bin/proxmox-file-restore
+usr/share/man/man1/proxmox-file-restore.1
+usr/share/zsh/vendor-completions/_proxmox-file-restore
+usr/lib/x86_64-linux-gnu/proxmox-backup/file-restore/proxmox-restore-daemon

debian/proxmox-backup-file-restore.postinst

@@ -0,0 +1,74 @@
+#!/bin/sh
+
+set -e
+
+update_initramfs() {
+    # regenerate initramfs for single file restore VM
+    INST_PATH="/usr/lib/x86_64-linux-gnu/proxmox-backup/file-restore"
+    CACHE_PATH="/var/cache/proxmox-backup/file-restore-initramfs.img"
+    CACHE_PATH_DBG="/var/cache/proxmox-backup/file-restore-initramfs-debug.img"
+
+    # cleanup first, in case proxmox-file-restore was uninstalled since we do
+    # not want an unuseable image lying around
+    rm -f "$CACHE_PATH"
+
+    if [ ! -f "$INST_PATH/initramfs.img" ]; then
+        echo "proxmox-backup-restore-image is not installed correctly, skipping update" >&2
+        exit 0
+    fi
+
+    echo "Updating file-restore initramfs..."
+
+    # avoid leftover temp file
+    cleanup() {
+        rm -f "$CACHE_PATH.tmp" "$CACHE_PATH_DBG.tmp"
+    }
+    trap cleanup EXIT
+
+    mkdir -p "/var/cache/proxmox-backup"
+    cp "$INST_PATH/initramfs.img" "$CACHE_PATH.tmp"
+
+    # cpio uses passed in path as offset inside the archive as well, so we need
+    # to be in the same dir as the daemon binary to ensure it's placed in /
+    ( cd "$INST_PATH"; \
+        printf "./proxmox-restore-daemon" \
+        | cpio -o --format=newc -A -F "$CACHE_PATH.tmp" )
+    mv -f "$CACHE_PATH.tmp" "$CACHE_PATH"
+
+    if [ -f "$INST_PATH/initramfs-debug.img" ]; then
+        echo "Updating file-restore debug initramfs..."
+        cp "$INST_PATH/initramfs-debug.img" "$CACHE_PATH_DBG.tmp"
+        ( cd "$INST_PATH"; \
+            printf "./proxmox-restore-daemon" \
+            | cpio -o --format=newc -A -F "$CACHE_PATH_DBG.tmp" )
+        mv -f "$CACHE_PATH_DBG.tmp" "$CACHE_PATH_DBG"
+    fi
+
+    trap - EXIT
+}
+
+case "$1" in
+    configure)
+        # in case restore daemon was updated
+        update_initramfs
+    ;;
+
+    triggered)
+        if [ "$2" = "proxmox-backup-restore-image-update" ]; then
+            # in case base-image was updated
+            update_initramfs
+        else
+            echo "postinst called with unknown trigger name: \`$2'" >&2
+        fi
+    ;;
+
+    abort-upgrade|abort-remove|abort-deconfigure)
+    ;;
+
+    *)
+        echo "postinst called with unknown argument \`$1'" >&2
+        exit 1
+    ;;
+esac
+
+exit 0

debian/proxmox-backup-file-restore.triggers

@@ -0,0 +1 @@
+interest-noawait proxmox-backup-restore-image-update

debian/proxmox-backup-server.bash-completion

@@ -1 +1,5 @@
 debian/proxmox-backup-manager.bc proxmox-backup-manager
+debian/proxmox-backup-debug.bc proxmox-backup-debug
+debian/proxmox-tape.bc proxmox-tape
+debian/pmtx.bc pmtx
+debian/pmt.bc pmt

debian/proxmox-backup-server.install

@@ -1,16 +1,40 @@
 etc/proxmox-backup-proxy.service /lib/systemd/system/
 etc/proxmox-backup.service /lib/systemd/system/
 etc/proxmox-backup-banner.service /lib/systemd/system/
-etc/pbstest-beta.list /etc/apt/sources.list.d/
+etc/proxmox-backup-daily-update.service /lib/systemd/system/
+etc/proxmox-backup-daily-update.timer /lib/systemd/system/
+etc/pbs-enterprise.list /etc/apt/sources.list.d/
 usr/lib/x86_64-linux-gnu/proxmox-backup/proxmox-backup-api
 usr/lib/x86_64-linux-gnu/proxmox-backup/proxmox-backup-proxy
 usr/lib/x86_64-linux-gnu/proxmox-backup/proxmox-backup-banner
+usr/lib/x86_64-linux-gnu/proxmox-backup/proxmox-daily-update
+usr/lib/x86_64-linux-gnu/proxmox-backup/sg-tape-cmd
+usr/sbin/proxmox-backup-debug
 usr/sbin/proxmox-backup-manager
+usr/bin/pmtx
+usr/bin/pmt
+usr/bin/proxmox-tape
 usr/share/javascript/proxmox-backup/index.hbs
 usr/share/javascript/proxmox-backup/css/ext6-pbs.css
-usr/share/javascript/proxmox-backup/images/logo-128.png
+usr/share/javascript/proxmox-backup/images
-usr/share/javascript/proxmox-backup/images/proxmox_logo.png
 usr/share/javascript/proxmox-backup/js/proxmox-backup-gui.js
+usr/share/man/man1/proxmox-backup-debug.1
 usr/share/man/man1/proxmox-backup-manager.1
 usr/share/man/man1/proxmox-backup-proxy.1
+usr/share/man/man1/proxmox-tape.1
+usr/share/man/man1/pmtx.1
+usr/share/man/man1/pmt.1
+usr/share/man/man5/acl.cfg.5
+usr/share/man/man5/datastore.cfg.5
+usr/share/man/man5/user.cfg.5
+usr/share/man/man5/remote.cfg.5
+usr/share/man/man5/sync.cfg.5
+usr/share/man/man5/verification.cfg.5
+usr/share/man/man5/media-pool.cfg.5
+usr/share/man/man5/tape.cfg.5
+usr/share/man/man5/tape-job.cfg.5
+usr/share/zsh/vendor-completions/_proxmox-backup-debug
 usr/share/zsh/vendor-completions/_proxmox-backup-manager
+usr/share/zsh/vendor-completions/_proxmox-tape
+usr/share/zsh/vendor-completions/_pmtx
+usr/share/zsh/vendor-completions/_pmt

debian/proxmox-backup-server.maintscript

@@ -0,0 +1 @@
+rm_conffile /etc/apt/sources.list.d/pbstest-beta.list 1.0.0~ proxmox-backup-server

debian/proxmox-backup-server.udev

@@ -0,0 +1,18 @@
+# do not edit this file, it will be overwritten on update
+
+# persistent storage links: /dev/tape/{by-id,by-path}
+
+ACTION=="remove", GOTO="persistent_storage_tape_end"
+ENV{UDEV_DISABLE_PERSISTENT_STORAGE_RULES_FLAG}=="1", GOTO="persistent_storage_tape_end"
+
+# also see: /lib/udev/rules.d/60-persistent-storage-tape.rules
+
+SUBSYSTEM=="scsi_generic", SUBSYSTEMS=="scsi", ATTRS{type}=="1", IMPORT{program}="scsi_id --sg-version=3 --export --whitelisted -d $devnode", \
+  SYMLINK+="tape/by-id/scsi-$env{ID_SERIAL}-sg"
+
+# iSCSI devices from the same host have all the same ID_SERIAL,
+# but additionally a property named ID_SCSI_SERIAL.
+SUBSYSTEM=="scsi_generic", SUBSYSTEMS=="scsi", ATTRS{type}=="1", ENV{ID_SCSI_SERIAL}=="?*", \
+  SYMLINK+="tape/by-id/scsi-$env{ID_SCSI_SERIAL}-sg"
+
+LABEL="persistent_storage_tape_end"

debian/proxmox-tape.bc

@@ -0,0 +1,3 @@
+# proxmox-tape bash completion
+
+complete -C 'proxmox-tape bashcomplete' proxmox-tape

debian/rules

@@ -38,13 +38,22 @@ override_dh_auto_install:
 	    LIBDIR=/usr/lib/$(DEB_HOST_MULTIARCH)
 
 override_dh_installsystemd:
+	dh_installsystemd -pproxmox-backup-server  proxmox-backup-daily-update.timer
 	# note: we start/try-reload-restart services manually in postinst
 	dh_installsystemd --no-start --no-restart-after-upgrade
 
-# workaround https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=933541
+override_dh_fixperms:
-# TODO: remove once available (Debian 11 ?)
+	dh_fixperms --exclude sg-tape-cmd
-override_dh_dwz:
+
-	dh_dwz --no-dwz-multifile
+override_dh_strip:
+	dh_strip
+	for exe in $$(find \
+	    debian/proxmox-backup-client/usr \
+	    debian/proxmox-backup-server/usr \
+	    debian/proxmox-backup-file-restore \
+	    -executable -type f); do \
+	  debian/scripts/elf-strip-unused-dependencies.sh "$$exe" || true; \
+	done
 
 override_dh_compress:
 	dh_compress -X.pdf

debian/scripts/elf-strip-unused-dependencies.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+binary=$1
+
+exec 3< <(ldd -u "$binary" | grep -oP '[^/:]+$')
+
+patchargs=""
+dropped=""
+while read -r dep; do
+    dropped="$dep $dropped"
+    patchargs="--remove-needed $dep $patchargs"
+done <&3
+exec 3<&-
+
+if [[ $dropped == "" ]]; then
+    exit 0
+fi
+
+echo -e "patchelf '$binary' - removing unused dependencies:\n $dropped"
+patchelf $patchargs $binary

defines.mk

@@ -5,6 +5,7 @@ LIBDIR = $(PREFIX)/lib
 LIBEXECDIR = $(LIBDIR)
 DATAROOTDIR = $(PREFIX)/share
 MAN1DIR = $(PREFIX)/share/man/man1
+MAN5DIR = $(PREFIX)/share/man/man5
 DOCDIR = $(PREFIX)/share/doc/proxmox-backup
 JSDIR = $(DATAROOTDIR)/javascript/proxmox-backup
 SYSCONFDIR = /etc

docs/Makefile

@@ -1,19 +1,81 @@
 include ../defines.mk
 
 GENERATED_SYNOPSIS := 						\
+	proxmox-tape/synopsis.rst				\
 	proxmox-backup-client/synopsis.rst			\
 	proxmox-backup-client/catalog-shell-synopsis.rst 	\
 	proxmox-backup-manager/synopsis.rst			\
+	proxmox-backup-debug/synopsis.rst			\
+	proxmox-file-restore/synopsis.rst			\
 	pxar/synopsis.rst					\
-	backup-protocol-api.rst					\
+	pmtx/synopsis.rst					\
-	reader-protocol-api.rst
+	pmt/synopsis.rst					\
+	config/media-pool/config.rst				\
+	config/tape/config.rst					\
+	config/tape-job/config.rst				\
+	config/user/config.rst					\
+	config/remote/config.rst				\
+	config/sync/config.rst					\
+	config/verification/config.rst				\
+	config/acl/roles.rst					\
+	config/datastore/config.rst
 
-MANUAL_PAGES := 			\
+MAN1_PAGES := 				\
 	pxar.1				\
+	pmtx.1				\
+	pmt.1				\
+	proxmox-tape.1			\
 	proxmox-backup-proxy.1		\
 	proxmox-backup-client.1		\
-	proxmox-backup-manager.1
+	proxmox-backup-manager.1	\
+	proxmox-file-restore.1		\
+	proxmox-backup-debug.1
 
+MAN5_PAGES :=				\
+	media-pool.cfg.5		\
+	tape.cfg.5			\
+	tape-job.cfg.5			\
+	acl.cfg.5			\
+	user.cfg.5			\
+	remote.cfg.5			\
+	sync.cfg.5			\
+	verification.cfg.5		\
+	datastore.cfg.5
+
+PRUNE_SIMULATOR_FILES := 					\
+	prune-simulator/index.html				\
+	prune-simulator/documentation.html			\
+	prune-simulator/clear-trigger.png			\
+	prune-simulator/prune-simulator.js
+
+PRUNE_SIMULATOR_JS_SOURCE :=						\
+	/usr/share/javascript/proxmox-widget-toolkit-dev/Toolkit.js	\
+	prune-simulator/prune-simulator_source.js
+
+LTO_BARCODE_JS_SOURCE :=						\
+	/usr/share/javascript/proxmox-widget-toolkit-dev/Toolkit.js	\
+	lto-barcode/code39.js						\
+	lto-barcode/prefix-field.js					\
+	lto-barcode/label-style.js					\
+	lto-barcode/tape-type.js					\
+	lto-barcode/paper-size.js					\
+	lto-barcode/page-layout.js					\
+	lto-barcode/page-calibration.js					\
+	lto-barcode/label-list.js					\
+	lto-barcode/label-setup.js					\
+	lto-barcode/lto-barcode.js
+
+LTO_BARCODE_FILES :=						\
+	lto-barcode/index.html					\
+	lto-barcode/lto-barcode-generator.js
+
+API_VIEWER_SOURCES=				\
+	api-viewer/index.html			\
+	api-viewer/apidoc.js
+
+API_VIEWER_FILES :=							\
+	api-viewer/apidata.js						\
+	/usr/share/javascript/proxmox-widget-toolkit-dev/APIViewer.js	\
 
 # Sphinx documentation setup
 SPHINXOPTS    =
@@ -28,19 +90,10 @@ COMPILEDIR := ../target/debug
 SPHINXOPTS    += -t devbuild
 endif
 
-
 # Sphinx internal variables.
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
 
-all: ${MANUAL_PAGES}
+all: ${MAN1_PAGES} ${MAN5_PAGES}
-
-# Extract backup protocol docs
-backup-protocol-api.rst: ${COMPILEDIR}/dump-backup-api
-	${COMPILEDIR}/dump-backup-api >$@
-
-# Extract reader protocol docs
-reader-protocol-api.rst: ${COMPILEDIR}/dump-reader-api
-	${COMPILEDIR}/dump-backup-api >$@
 
 # Build manual pages using rst2man
 
@@ -50,6 +103,80 @@ pxar/synopsis.rst: ${COMPILEDIR}/pxar
 pxar.1: pxar/man1.rst  pxar/description.rst pxar/synopsis.rst
 	rst2man $< >$@
 
+
+pmtx/synopsis.rst: ${COMPILEDIR}/pmtx
+	${COMPILEDIR}/pmtx printdoc > pmtx/synopsis.rst
+
+pmtx.1: pmtx/man1.rst  pmtx/description.rst pmtx/synopsis.rst
+	rst2man $< >$@
+
+
+pmt/synopsis.rst: ${COMPILEDIR}/pmt
+	${COMPILEDIR}/pmt printdoc > pmt/synopsis.rst
+
+pmt.1: pmt/man1.rst  pmt/description.rst pmt/options.rst pmt/synopsis.rst
+	rst2man $< >$@
+
+config/datastore/config.rst: ${COMPILEDIR}/docgen
+	${COMPILEDIR}/docgen datastore.cfg >$@
+
+datastore.cfg.5: config/datastore/man5.rst config/datastore/config.rst config/datastore/format.rst
+	rst2man $< >$@
+
+config/user/config.rst: ${COMPILEDIR}/docgen
+	${COMPILEDIR}/docgen user.cfg >$@
+
+user.cfg.5: config/user/man5.rst config/user/config.rst config/user/format.rst
+	rst2man $< >$@
+
+config/remote/config.rst: ${COMPILEDIR}/docgen
+	${COMPILEDIR}/docgen remote.cfg >$@
+
+remote.cfg.5: config/remote/man5.rst config/remote/config.rst config/remote/format.rst
+	rst2man $< >$@
+
+config/sync/config.rst: ${COMPILEDIR}/docgen
+	${COMPILEDIR}/docgen sync.cfg >$@
+
+sync.cfg.5: config/sync/man5.rst config/sync/config.rst config/sync/format.rst
+	rst2man $< >$@
+
+config/verification/config.rst: ${COMPILEDIR}/docgen
+	${COMPILEDIR}/docgen verification.cfg >$@
+
+verification.cfg.5: config/verification/man5.rst config/verification/config.rst config/verification/format.rst
+	rst2man $< >$@
+
+config/acl/roles.rst: ${COMPILEDIR}/docgen
+	${COMPILEDIR}/docgen "config::acl::Role" >$@
+
+acl.cfg.5: config/acl/man5.rst config/acl/roles.rst config/acl/format.rst
+	rst2man $< >$@
+
+config/media-pool/config.rst: ${COMPILEDIR}/docgen
+	${COMPILEDIR}/docgen media-pool.cfg >$@
+
+media-pool.cfg.5: config/media-pool/man5.rst config/media-pool/config.rst config/media-pool/format.rst
+	rst2man $< >$@
+
+config/tape/config.rst: ${COMPILEDIR}/docgen
+	${COMPILEDIR}/docgen tape.cfg >$@
+
+tape.cfg.5: config/tape/man5.rst config/tape/config.rst config/tape/format.rst
+	rst2man $< >$@
+
+config/tape-job/config.rst: ${COMPILEDIR}/docgen
+	${COMPILEDIR}/docgen tape-job.cfg >$@
+
+tape-job.cfg.5: config/tape-job/man5.rst config/tape-job/config.rst config/tape-job/format.rst
+	rst2man $< >$@
+
+proxmox-tape/synopsis.rst: ${COMPILEDIR}/proxmox-tape
+	${COMPILEDIR}/proxmox-tape printdoc > proxmox-tape/synopsis.rst
+
+proxmox-tape.1: proxmox-tape/man1.rst proxmox-tape/description.rst proxmox-tape/synopsis.rst
+	rst2man $< >$@
+
 proxmox-backup-client/synopsis.rst: ${COMPILEDIR}/proxmox-backup-client
 	${COMPILEDIR}/proxmox-backup-client printdoc > proxmox-backup-client/synopsis.rst
 
@@ -68,9 +195,49 @@ proxmox-backup-manager.1: proxmox-backup-manager/man1.rst  proxmox-backup-manage
 proxmox-backup-proxy.1: proxmox-backup-proxy/man1.rst  proxmox-backup-proxy/description.rst
 	rst2man $< >$@
 
+proxmox-file-restore/synopsis.rst: ${COMPILEDIR}/proxmox-file-restore
+	${COMPILEDIR}/proxmox-file-restore printdoc > proxmox-file-restore/synopsis.rst
+
+proxmox-file-restore.1: proxmox-file-restore/man1.rst  proxmox-file-restore/description.rst proxmox-file-restore/synopsis.rst
+	rst2man $< >$@
+
+proxmox-backup-debug/synopsis.rst: ${COMPILEDIR}/proxmox-backup-debug
+	${COMPILEDIR}/proxmox-backup-debug printdoc > proxmox-backup-debug/synopsis.rst
+
+proxmox-backup-debug.1: proxmox-backup-debug/man1.rst  proxmox-backup-debug/description.rst proxmox-backup-debug/synopsis.rst
+	rst2man $< >$@
+
+.PHONY: onlinehelpinfo
+onlinehelpinfo:
+	@echo "Generating OnlineHelpInfo.js..."
+	$(SPHINXBUILD) -b proxmox-scanrefs -Q $(ALLSPHINXOPTS) $(BUILDDIR)/scanrefs
+	@echo "Build finished. OnlineHelpInfo.js is in $(BUILDDIR)/scanrefs."
+
+api-viewer/apidata.js: ${COMPILEDIR}/docgen
+	${COMPILEDIR}/docgen apidata.js >$@
+
+api-viewer/apidoc.js: ${API_VIEWER_FILES}
+	cat ${API_VIEWER_FILES} >$@.tmp
+	mv $@.tmp $@
+
+prune-simulator/prune-simulator.js: ${PRUNE_SIMULATOR_JS_SOURCE}
+	cat ${PRUNE_SIMULATOR_JS_SOURCE} >$@.tmp
+	mv $@.tmp $@
+
+lto-barcode/lto-barcode-generator.js: ${LTO_BARCODE_JS_SOURCE}
+	cat ${LTO_BARCODE_JS_SOURCE} >$@.tmp
+	mv $@.tmp $@
+
 .PHONY: html
-html: ${GENERATED_SYNOPSIS}
+html: ${GENERATED_SYNOPSIS} images/proxmox-logo.svg custom.css conf.py ${PRUNE_SIMULATOR_FILES} ${LTO_BARCODE_FILES} ${API_VIEWER_SOURCES}
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	install -m 0644 custom.js custom.css images/proxmox-logo.svg $(BUILDDIR)/html/_static/
+	install -dm 0755 $(BUILDDIR)/html/prune-simulator
+	install -m 0644 ${PRUNE_SIMULATOR_FILES} $(BUILDDIR)/html/prune-simulator
+	install -dm 0755 $(BUILDDIR)/html/lto-barcode
+	install -m 0644 ${LTO_BARCODE_FILES} $(BUILDDIR)/html/lto-barcode
+	install -dm 0755 $(BUILDDIR)/html/api-viewer
+	install -m 0644 ${API_VIEWER_SOURCES} $(BUILDDIR)/html/api-viewer
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
@@ -89,12 +256,15 @@ epub3: ${GENERATED_SYNOPSIS}
 	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
 
 clean:
-	rm -r -f *~ *.1 ${BUILDDIR} ${GENERATED_SYNOPSIS}
+	rm -r -f *~ *.1 ${BUILDDIR} ${GENERATED_SYNOPSIS} api-viewer/apidata.js
+	rm -f api-viewer/apidoc.js lto-barcode/lto-barcode-generator.js prune-simulator/prune-simulator.js
 
 
-install_manual_pages: ${MANUAL_PAGES}
+install_manual_pages: ${MAN1_PAGES} ${MAN5_PAGES}
 	install -dm755 $(DESTDIR)$(MAN1DIR)
-	for i in ${MANUAL_PAGES}; do install -m755 $$i $(DESTDIR)$(MAN1DIR)/ ; done
+	for i in ${MAN1_PAGES}; do install -m755 $$i $(DESTDIR)$(MAN1DIR)/ ; done
+	install -dm755 $(DESTDIR)$(MAN5DIR)
+	for i in ${MAN5_PAGES}; do install -m755 $$i $(DESTDIR)$(MAN5DIR)/ ; done
 
 install_html: html
 	install -dm755 $(DESTDIR)$(DOCDIR)

docs/_ext/proxmox-scanrefs.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+
+# debugging stuff
+from pprint import pprint
+
+from typing import cast
+
+import json
+import re
+
+import os
+import io
+from docutils import nodes
+
+from sphinx.builders import Builder
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
+
+# refs are added in the following manner before the title of a section (note underscore and newline before title):
+# .. _my-label:
+#
+# Section to ref
+# --------------
+#
+#
+# then referred to like (note missing underscore):
+# "see :ref:`my-label`"
+#
+# the benefit of using this is if a label is explicitly set for a section,
+# we can refer to it with this anchor #my-label in the html,
+# even if the section name changes.
+#
+# see https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
+
+def scan_extjs_files(wwwdir="../www"): # a bit rough i know, but we can optimize later
+    js_files = []
+    used_anchors = []
+    logger.info("scanning extjs files for onlineHelp definitions")
+    for root, dirs, files in os.walk("{}".format(wwwdir)):
+        #print(root, dirs, files)
+        for filename in files:
+            if filename.endswith('.js'):
+                js_files.append(os.path.join(root, filename))
+    for js_file in js_files:
+        fd = open(js_file).read()
+        allmatch = re.findall("(?:onlineHelp:|get_help_tool\s*\()\s*[\'\"](.*?)[\'\"]", fd, re.M)
+        for match in allmatch:
+            anchor = match
+            anchor = re.sub('_', '-', anchor) # normalize labels
+            logger.info("found onlineHelp: {} in {}".format(anchor, js_file))
+            used_anchors.append(anchor)
+
+    return used_anchors
+
+
+def setup(app):
+    logger.info('Mapping reference labels...')
+    app.add_builder(ReflabelMapper)
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
+class ReflabelMapper(Builder):
+    name = 'proxmox-scanrefs'
+
+    def init(self):
+        self.docnames = []
+        self.env.online_help = {}
+        self.env.online_help['pbs_documentation_index'] = {
+            'link': '/docs/index.html',
+            'title': 'Proxmox Backup Server Documentation Index',
+        }
+        # Disabled until we find a sensible way to scan proxmox-widget-toolkit
+        # as well
+        #self.env.used_anchors = scan_extjs_files()
+
+        if not os.path.isdir(self.outdir):
+            os.mkdir(self.outdir)
+
+        self.output_filename = os.path.join(self.outdir, 'OnlineHelpInfo.js')
+        self.output = io.open(self.output_filename, 'w', encoding='UTF-8')
+
+    def write_doc(self, docname, doctree):
+            for node in doctree.traverse(nodes.section):
+                #pprint(vars(node))
+
+                if hasattr(node, 'expect_referenced_by_id') and len(node['ids']) > 1: # explicit labels
+                    filename = self.env.doc2path(docname)
+                    filename_html = re.sub('.rst', '.html', filename)
+
+                    # node['ids'][0] contains a normalized version of the
+                    # headline.  If the ref and headline are the same
+                    # (normalized) sphinx will set the node['ids'][1] to a
+                    # generic id in the format `idX` where X is numeric. If the
+                    # ref and headline are not the same, the ref name will be
+                    # stored in node['ids'][1]
+                    if re.match('^id[0-9]*$', node['ids'][1]):
+                        labelid = node['ids'][0]
+                    else:
+                        labelid = node['ids'][1]
+
+                    title = cast(nodes.title, node[0])
+                    logger.info('traversing section {}'.format(title.astext()))
+                    ref_name = getattr(title, 'rawsource', title.astext())
+
+                    if (ref_name[:7] == ':term:`'):
+                        ref_name = ref_name[7:-1]
+
+                    self.env.online_help[labelid] = {'link': '', 'title': ''}
+                    self.env.online_help[labelid]['link'] = "/docs/" + os.path.basename(filename_html) + "#{}".format(labelid)
+                    self.env.online_help[labelid]['title'] = ref_name
+
+            return
+
+
+    def get_outdated_docs(self):
+        return 'all documents'
+
+    def prepare_writing(self, docnames):
+        return
+
+    def get_target_uri(self, docname, typ=None):
+        return ''
+
+    def validate_anchors(self):
+        #pprint(self.env.online_help)
+        to_remove = []
+
+        # Disabled until we find a sensible way to scan proxmox-widget-toolkit
+        # as well
+        #for anchor in self.env.used_anchors:
+        #    if anchor not in self.env.online_help:
+        #        logger.info("[-] anchor {} is missing from onlinehelp!".format(anchor))
+        #for anchor in self.env.online_help:
+        #    if anchor not in self.env.used_anchors and anchor != 'pbs_documentation_index':
+        #        logger.info("[*] anchor {} not used! deleting...".format(anchor))
+        #        to_remove.append(anchor)
+        #for anchor in to_remove:
+        #   self.env.online_help.pop(anchor, None)
+        return
+
+    def finish(self):
+        # generate OnlineHelpInfo.js output
+        self.validate_anchors()
+
+        self.output.write("const proxmoxOnlineHelpInfo = ")
+        self.output.write(json.dumps(self.env.online_help, indent=2))
+        self.output.write(";\n")
+        self.output.close()
+        return

docs/_templates/index-sidebar.html

@@ -0,0 +1,11 @@
+<h3>Navigation</h3>
+{{ toctree(includehidden=theme_sidebar_includehidden, collapse=True, titles_only=True) }}
+{% if theme_extra_nav_links %}
+<hr />
+<h3>Links</h3>
+<ul>
+    {% for text, uri in theme_extra_nav_links.items() %}
+    <li class="toctree-l1"><a href="{{ uri }}">{{ text }}</a></li>
+    {% endfor %}
+</ul>
+{% endif %}

docs/_templates/sidebar-header.html

@@ -0,0 +1,7 @@
+ <p class="logo">
+    <a href="index.html">
+        <img class="logo" src="_static/proxmox-logo.svg" alt="Logo">
+    </a>
+</p>
+<h1 class="logo logo-name"><a href="index.html">Proxmox Backup</a></h1>
+<hr style="width:100%;">

docs/api-viewer/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
+    <title>Proxmox Backup Server API Documentation</title>
+
+    <link rel="stylesheet" type="text/css" href="extjs/theme-crisp/resources/theme-crisp-all.css">
+    <script type="text/javascript" src="extjs/ext-all.js"></script>
+    <script type="text/javascript" src="apidoc.js"></script>
+</head>
+<body></body>
+</html>

docs/backup-client.rst

@@ -0,0 +1,798 @@
+Backup Client Usage
+===================
+
+The command line client for Proxmox Backup Server is called
+:command:`proxmox-backup-client`.
+
+.. _client_repository:
+
+Backup Repository Locations
+---------------------------
+
+The client uses the following format to specify a datastore repository
+on the backup server (where username is specified in the form of user@realm):
+
+  [[username@]server[:port]:]datastore
+
+The default value for ``username`` is ``root@pam``. If no server is specified,
+the default is the local host (``localhost``).
+
+You can specify a port if your backup server is only reachable on a non-default
+port (for example, with NAT and port forwarding configurations).
+
+Note that if the server uses an IPv6 address, you have to write it with square
+brackets (for example, `[fe80::01]`).
+
+You can pass the repository with the ``--repository`` command line option, or
+by setting the ``PBS_REPOSITORY`` environment variable.
+
+Below are some examples of valid repositories and their corresponding real
+values:
+
+================================ ================== ================== ===========
+Example                          User               Host:Port          Datastore
+================================ ================== ================== ===========
+mydatastore                      ``root@pam``       localhost:8007     mydatastore
+myhostname:mydatastore           ``root@pam``       myhostname:8007    mydatastore
+user@pbs@myhostname:mydatastore  ``user@pbs``       myhostname:8007    mydatastore
+user\@pbs!token@host:store       ``user@pbs!token`` myhostname:8007    mydatastore
+192.168.55.55:1234:mydatastore   ``root@pam``       192.168.55.55:1234 mydatastore
+[ff80::51]:mydatastore           ``root@pam``       [ff80::51]:8007    mydatastore
+[ff80::51]:1234:mydatastore      ``root@pam``       [ff80::51]:1234    mydatastore
+================================ ================== ================== ===========
+
+Environment Variables
+---------------------
+
+``PBS_REPOSITORY``
+  The default backup repository.
+
+``PBS_PASSWORD``
+  When set, this value is used as the password for the backup server.
+  You can also set this to an API token secret.
+
+``PBS_PASSWORD_FD``, ``PBS_PASSWORD_FILE``, ``PBS_PASSWORD_CMD``
+  Like ``PBS_PASSWORD``, but read data from an open file descriptor, a file
+  name or from the `stdout` of a command, respectively. The first defined
+  environment variable from the order above is preferred.
+
+``PBS_ENCRYPTION_PASSWORD``
+  When set, this value is used to access the secret encryption key (if
+  protected by password).
+
+``PBS_ENCRYPTION_PASSWORD_FD``, ``PBS_ENCRYPTION_PASSWORD_FILE``, ``PBS_ENCRYPTION_PASSWORD_CMD``
+  Like ``PBS_ENCRYPTION_PASSWORD``, but read data from an open file descriptor,
+  a file name or from the `stdout` of a command, respectively. The first
+  defined environment variable from the order above is preferred.
+
+``PBS_FINGERPRINT``
+  When set, this value is used to verify the server certificate (only used if
+  the system CA certificates cannot validate the certificate).
+
+
+.. Note:: Passwords must be valid UTF-8 and may not contain newlines. For your
+   convenience, Proxmox Backup Server only uses the first line as password, so
+   you can add arbitrary comments after the first newline.
+
+
+Output Format
+-------------
+
+.. include:: output-format.rst
+
+
+.. _client_creating_backups:
+
+Creating Backups
+----------------
+
+This section explains how to create a backup from within the machine. This can
+be a physical host, a virtual machine, or a container. Such backups may contain
+file and image archives. There are no restrictions in this case.
+
+.. Note:: If you want to backup virtual machines or containers on Proxmox VE,
+   see :ref:`pve-integration`.
+
+For the following example, you need to have a backup server set up, have working
+credentials, and know the repository name.
+In the following examples, we use ``backup-server:store1``.
+
+.. code-block:: console
+
+  # proxmox-backup-client backup root.pxar:/ --repository backup-server:store1
+  Starting backup: host/elsa/2019-12-03T09:35:01Z
+  Client name: elsa
+  skip mount point: "/boot/efi"
+  skip mount point: "/dev"
+  skip mount point: "/run"
+  skip mount point: "/sys"
+  Uploaded 12129 chunks in 87 seconds (564 MB/s).
+  End Time: 2019-12-03T10:36:29+01:00
+
+This will prompt you for a password, then upload a file archive named
+``root.pxar`` containing all the files in the ``/`` directory.
+
+.. Caution:: Please note that proxmox-backup-client does not
+   automatically include mount points. Instead, you will see a short
+   ``skip mount point`` message for each of them. The idea is to
+   create a separate file archive for each mounted disk. You can
+   explicitly include them using the ``--include-dev`` option
+   (i.e. ``--include-dev /boot/efi``). You can use this option
+   multiple times for each mount point that should be included.
+
+The ``--repository`` option can get quite long and is used by all commands. You
+can avoid having to enter this value by setting the environment variable
+``PBS_REPOSITORY``. Note that if you would like this to remain set over
+multiple sessions, you should instead add the below line to your ``.bashrc``
+file.
+
+.. code-block:: console
+
+  # export PBS_REPOSITORY=backup-server:store1
+
+After this, you can execute all commands without having to specify the
+``--repository`` option.
+
+A single backup is allowed to contain more than one archive. For example, if
+you want to back up two disks mounted at ``/mnt/disk1`` and ``/mnt/disk2``:
+
+.. code-block:: console
+
+  # proxmox-backup-client backup disk1.pxar:/mnt/disk1 disk2.pxar:/mnt/disk2
+
+This creates a backup of both disks.
+
+If you want to use a namespace for the backup target you can add the `--ns`
+parameter:
+
+.. code-block:: console
+
+  # proxmox-backup-client backup disk1.pxar:/mnt/disk1 disk2.pxar:/mnt/disk2 --ns a/b/c
+
+The backup command takes a list of backup specifications, which include the
+archive name on the server, the type of the archive, and the archive source at
+the client. The format is:
+
+    <archive-name>.<type>:<source-path>
+
+Common types are ``.pxar`` for file archives and ``.img`` for block
+device images. To create a backup of a block device, run the following command:
+
+.. code-block:: console
+
+  # proxmox-backup-client backup mydata.img:/dev/mylvm/mydata
+
+
+Excluding Files/Directories from a Backup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes it is desired to exclude certain files or directories from a backup
+archive.  To tell the Proxmox Backup client when and how to ignore files and
+directories, place a text file named ``.pxarexclude`` in the filesystem
+hierarchy.  Whenever the backup client encounters such a file in a directory,
+it interprets each line as a glob match pattern for files and directories that
+are to be excluded from the backup.
+
+The file must contain a single glob pattern per line. Empty lines and lines
+starting with ``#`` (indicating a comment) are ignored.
+A ``!`` at the beginning of a line reverses the glob match pattern from an
+exclusion to an explicit inclusion. This makes it possible to exclude all
+entries in a directory except for a few single files/subdirectories.
+Lines ending in ``/`` match only on directories.
+The directory containing the ``.pxarexclude`` file is considered to be the root
+of the given patterns. It is only possible to match files in this directory and
+its subdirectories.
+
+.. Note:: Patterns without a leading ``/`` will also match in subdirectories,
+   while patterns with a leading ``/`` will only match in the current directory.
+
+``\`` is used to escape special glob characters.
+``?`` matches any single character.
+``*`` matches any character, including an empty string.
+``**`` is used to match current directory and subdirectories. For example, with
+the pattern ``**/*.tmp``, it would exclude all files ending in ``.tmp`` within
+a directory and its subdirectories.
+``[...]`` matches a single character from any of the provided characters within
+the brackets. ``[!...]`` does the complementary and matches any single
+character not contained within the brackets. It is also possible to specify
+ranges with two characters separated by ``-``. For example, ``[a-z]`` matches
+any lowercase alphabetic character, and ``[0-9]`` matches any single digit.
+
+The order of the glob match patterns defines whether a file is included or
+excluded, that is to say, later entries override earlier ones.
+This is also true for match patterns encountered deeper down the directory
+tree, which can override a previous exclusion.
+
+.. Note:: Excluded directories will **not** be read by the backup client. Thus,
+   a ``.pxarexclude`` file in an excluded subdirectory will have no effect.
+   ``.pxarexclude`` files are treated as regular files and will be included in
+   the backup archive.
+
+For example, consider the following directory structure:
+
+.. code-block:: console
+
+    # ls -aR folder
+    folder/:
+    .  ..  .pxarexclude  subfolder0  subfolder1
+
+    folder/subfolder0:
+    .  ..  file0  file1  file2  file3  .pxarexclude
+
+    folder/subfolder1:
+    .  ..  file0  file1  file2  file3
+
+The different ``.pxarexclude`` files contain the following:
+
+.. code-block:: console
+
+    # cat folder/.pxarexclude
+    /subfolder0/file1
+    /subfolder1/*
+    !/subfolder1/file2
+
+.. code-block:: console
+
+    # cat folder/subfolder0/.pxarexclude
+    file3
+
+This would exclude ``file1`` and ``file3`` in ``subfolder0`` and all of
+``subfolder1`` except ``file2``.
+
+Restoring this backup will result in:
+
+.. code-block:: console
+
+    ls -aR restored
+    restored/:
+    .  ..  .pxarexclude  subfolder0  subfolder1
+
+    restored/subfolder0:
+    .  ..  file0  file2  .pxarexclude
+
+    restored/subfolder1:
+    .  ..  file2
+
+
+.. _client_encryption:
+
+Encryption
+----------
+
+Proxmox Backup supports client-side encryption with AES-256 in GCM_
+mode. To set this up, you first need to create an encryption key:
+
+.. code-block:: console
+
+  # proxmox-backup-client key create my-backup.key
+  Encryption Key Password: **************
+
+The key is password protected by default. If you do not need this
+extra protection, you can also create it without a password:
+
+.. code-block:: console
+
+  # proxmox-backup-client key create /path/to/my-backup.key --kdf none
+
+Having created this key, it is now possible to create an encrypted backup, by
+passing the ``--keyfile`` parameter, with the path to the key file.
+
+.. code-block:: console
+
+  # proxmox-backup-client backup etc.pxar:/etc --keyfile /path/to/my-backup.key
+  Password: *********
+  Encryption Key Password: **************
+  ...
+
+.. Note:: If you do not specify the name of the backup key, the key will be
+  created in the default location
+  ``~/.config/proxmox-backup/encryption-key.json``. ``proxmox-backup-client``
+  will also search this location by default, in case the ``--keyfile``
+  parameter is not specified.
+
+You can avoid entering the passwords by setting the environment
+variables ``PBS_PASSWORD`` and ``PBS_ENCRYPTION_PASSWORD``.
+
+
+Using a Master Key to Store and Recover Encryption Keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also use ``proxmox-backup-client key`` to create an RSA public/private
+key pair, which can be used to store an encrypted version of the symmetric
+backup encryption key alongside each backup and recover it later.
+
+To set up a master key:
+
+1. Create an encryption key for the backup:
+
+   .. code-block:: console
+
+     # proxmox-backup-client key create
+     creating default key at: "~/.config/proxmox-backup/encryption-key.json"
+     Encryption Key Password: **********
+     ...
+
+   The resulting file will be saved to ``~/.config/proxmox-backup/encryption-key.json``.
+
+2. Create an RSA public/private key pair:
+
+   .. code-block:: console
+
+     # proxmox-backup-client key create-master-key
+     Master Key Password: *********
+     ...
+
+   This will create two files in your current directory, ``master-public.pem``
+   and ``master-private.pem``.
+
+3. Import the newly created ``master-public.pem`` public certificate, so that
+   ``proxmox-backup-client`` can find and use it upon backup.
+
+   .. code-block:: console
+
+     # proxmox-backup-client key import-master-pubkey /path/to/master-public.pem
+     Imported public master key to "~/.config/proxmox-backup/master-public.pem"
+
+4. With all these files in place, run a backup job:
+
+   .. code-block:: console
+
+     # proxmox-backup-client backup etc.pxar:/etc
+
+   The key will be stored in your backup, under the name ``rsa-encrypted.key``.
+
+   .. Note:: The ``--keyfile`` parameter can be excluded, if the encryption key
+     is in the default path. If you specified another path upon creation, you
+     must pass the ``--keyfile`` parameter.
+
+5. To test that everything worked, you can restore the key from the backup:
+
+   .. code-block:: console
+
+     # proxmox-backup-client restore /path/to/backup/ rsa-encrypted.key /path/to/target
+
+   .. Note:: You should not need an encryption key to extract this file. However, if
+     a key exists at the default location
+     (``~/.config/proxmox-backup/encryption-key.json``) the program will prompt
+     you for an encryption key password. Simply moving ``encryption-key.json``
+     out of this directory will fix this issue.
+
+6. Then, use the previously generated master key to decrypt the file:
+
+   .. code-block:: console
+
+     # proxmox-backup-client key import-with-master-key /path/to/target --master-keyfile /path/to/master-private.pem --encrypted-keyfile /path/to/rsa-encrypted.key
+     Master Key Password: ******
+     New Password: ******
+     Verify Password: ******
+
+7. The target file will now contain the encryption key information in plain
+   text. The success of this can be confirmed by passing the resulting ``json``
+   file, with the ``--keyfile`` parameter, when decrypting files from the backup.
+
+.. warning:: Without their key, backed up files will be inaccessible. Thus, you should
+  keep keys ordered and in a place that is separate from the contents being
+  backed up. It can happen, for example, that you back up an entire system, using
+  a key on that system. If the system then becomes inaccessible for any reason
+  and needs to be restored, this will not be possible, as the encryption key will be
+  lost along with the broken system.
+
+It is recommended that you keep your master key safe, but easily accessible, in
+order for quick disaster recovery. For this reason, the best place to store it
+is in your password manager, where it is immediately recoverable. As a backup to
+this, you should also save the key to a USB drive and store that in a secure
+place. This way, it is detached from any system, but is still easy to recover
+from, in case of emergency. Finally, in preparation for the worst case scenario,
+you should also consider keeping a paper copy of your master key locked away in
+a safe place. The ``paperkey`` subcommand can be used to create a QR encoded
+version of your master key. The following command sends the output of the
+``paperkey`` command to a text file, for easy printing.
+
+.. code-block:: console
+
+  proxmox-backup-client key paperkey --output-format text > qrkey.txt
+
+
+Restoring Data
+--------------
+
+The regular creation of backups is a necessary step in avoiding data loss. More
+importantly, however, is the restoration. It is good practice to perform
+periodic recovery tests to ensure that you can access the data in case of
+disaster.
+
+First, you need to find the snapshot which you want to restore. The snapshot
+list command provides a list of all the snapshots on the server:
+
+.. code-block:: console
+
+  # proxmox-backup-client snapshot list
+  ┌────────────────────────────────┬─────────────┬────────────────────────────────────┐
+  │ snapshot                       │        size │ files                              │
+  ╞════════════════════════════════╪═════════════╪════════════════════════════════════╡
+  │ host/elsa/2019-12-03T09:30:15Z │ 51788646825 │ root.pxar catalog.pcat1 index.json │
+  ├────────────────────────────────┼─────────────┼────────────────────────────────────┤
+  │ host/elsa/2019-12-03T09:35:01Z │ 51790622048 │ root.pxar catalog.pcat1 index.json │
+  ├────────────────────────────────┼─────────────┼────────────────────────────────────┤
+  ...
+
+
+.. tip:: List will by default only output the backup snapshots of the root
+   namespace itself. To list backups from another namespace use the ``--ns
+   <ns>`` option
+
+You can inspect the catalog to find specific files.
+
+.. code-block:: console
+
+  # proxmox-backup-client catalog dump host/elsa/2019-12-03T09:35:01Z
+  ...
+  d "./root.pxar.didx/etc/cifs-utils"
+  l "./root.pxar.didx/etc/cifs-utils/idmap-plugin"
+  d "./root.pxar.didx/etc/console-setup"
+  ...
+
+The restore command lets you restore a single archive from the
+backup.
+
+.. code-block:: console
+
+  # proxmox-backup-client restore host/elsa/2019-12-03T09:35:01Z root.pxar /target/path/
+
+To get the contents of any archive, you can restore the ``index.json`` file in the
+repository to the target path '-'. This will dump the contents to the standard output.
+
+.. code-block:: console
+
+  # proxmox-backup-client restore host/elsa/2019-12-03T09:35:01Z index.json -
+
+
+Interactive Restores
+~~~~~~~~~~~~~~~~~~~~
+
+If you only want to restore a few individual files, it is often easier
+to use the interactive recovery shell.
+
+.. code-block:: console
+
+  # proxmox-backup-client catalog shell host/elsa/2019-12-03T09:35:01Z root.pxar
+  Starting interactive shell
+  pxar:/ > ls
+  bin        boot       dev        etc        home       lib        lib32
+  ...
+
+The interactive recovery shell is a minimal command line interface that
+utilizes the metadata stored in the catalog to quickly list, navigate and
+search for files in a file archive.
+To restore files, you can select them individually or match them with a glob
+pattern.
+
+Using the catalog for navigation reduces the overhead considerably because only
+the catalog needs to be downloaded and, optionally, decrypted.
+The actual chunks are only accessed if the metadata in the catalog is
+insufficient or for the actual restore.
+
+Similar to common UNIX shells, ``cd`` and ``ls`` are the commands used to change
+working directory and list directory contents in the archive.
+``pwd`` shows the full path of the current working directory with respect to the
+archive root.
+
+The ability to quickly search the contents of the archive is a commonly required
+feature. That's where the catalog is most valuable. For example:
+
+.. code-block:: console
+
+  pxar:/ > find etc/**/*.txt --select
+  "/etc/X11/rgb.txt"
+  pxar:/ > list-selected
+  etc/**/*.txt
+  pxar:/ > restore-selected /target/path
+  ...
+
+This will find and print all files ending in ``.txt`` located in ``etc/`` or its
+subdirectories, and add the corresponding pattern to the list for subsequent restores.
+``list-selected`` shows these patterns and ``restore-selected`` finally restores
+all files in the archive matching the patterns to ``/target/path`` on the local
+host. This will scan the whole archive.
+
+The ``restore`` command can be used to restore all the files contained within
+the backup archive. This is most helpful when paired with the ``--pattern
+<glob>`` option, as it allows you to restore all files matching a specific
+pattern. For example, if you wanted to restore configuration files
+located in ``/etc``, you could do the following:
+
+.. code-block:: console
+
+  pxar:/ > restore target/ --pattern etc/**/*.conf
+  ...
+
+The above will scan through all the directories below ``/etc`` and restore all
+files ending in ``.conf``.
+
+.. todo:: Explain interactive restore in more detail
+
+Mounting of Archives via FUSE
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :term:`FUSE` implementation for the pxar archive allows you to mount a
+file archive as a read-only filesystem to a mount point on your host.
+
+.. code-block:: console
+
+  # proxmox-backup-client mount host/backup-client/2020-01-29T11:29:22Z root.pxar /mnt/mountpoint
+  # ls /mnt/mountpoint
+  bin   dev  home  lib32  libx32      media  opt   root  sbin  sys  usr
+  boot  etc  lib   lib64  lost+found  mnt    proc  run   srv   tmp  var
+
+This allows you to access the full contents of the archive in a seamless manner.
+
+.. note:: As the FUSE connection needs to fetch and decrypt chunks from the
+    backup server's datastore, this can cause some additional network and CPU
+    load on your host, depending on the operations you perform on the mounted
+    filesystem.
+
+To unmount the filesystem, use the ``umount`` command on the mount point:
+
+.. code-block:: console
+
+  # umount /mnt/mountpoint
+
+Login and Logout
+----------------
+
+The client tool prompts you to enter the login password as soon as you
+want to access the backup server. The server checks your credentials
+and responds with a ticket that is valid for two hours. The client
+tool automatically stores that ticket and uses it for further requests
+to this server.
+
+You can also manually trigger this login/logout using the login and
+logout commands:
+
+.. code-block:: console
+
+  # proxmox-backup-client login
+  Password: **********
+
+To remove the ticket, issue a logout:
+
+.. code-block:: console
+
+  # proxmox-backup-client logout
+
+
+.. _changing-backup-owner:
+
+Changing the Owner of a Backup Group
+------------------------------------
+
+By default, the owner of a backup group is the user which was used to originally
+create that backup group (or in the case of sync jobs, ``root@pam``). This
+means that if a user ``mike@pbs`` created a backup, another user ``john@pbs``
+can not be used to create backups in that same backup group. In case you want
+to change the owner of a backup, you can do so with the below command, using a
+user that has ``Datastore.Modify`` privileges on the datastore.
+
+.. code-block:: console
+
+  # proxmox-backup-client change-owner vm/103 john@pbs
+
+This can also be done from within the web interface, by navigating to the
+`Content` section of the datastore that contains the backup group and selecting
+the user icon under the `Actions` column. Common cases for this could be to
+change the owner of a sync job from ``root@pam``, or to repurpose a backup
+group.
+
+
+.. _backup-pruning:
+
+Pruning and Removing Backups
+----------------------------
+
+You can manually delete a backup snapshot using the ``forget`` command:
+
+.. code-block:: console
+
+  # proxmox-backup-client snapshot forget <snapshot>
+
+
+.. caution:: This command removes all archives in this backup snapshot. They
+   will be inaccessible and *unrecoverable*.
+
+Don't forget to add the namespace ``--ns`` parameter if you want to forget a
+snapshot that is contained in the root namespace:
+
+.. code-block:: console
+
+  # proxmox-backup-client snapshot forget <snapshot> --ns <ns>
+
+
+
+
+Although manual removal is sometimes required, the ``prune``
+command is normally used to systematically delete older backups. Prune lets
+you specify which backup snapshots you want to keep. The
+following retention options are available:
+
+``--keep-last <N>``
+  Keep the last ``<N>`` backup snapshots.
+
+``--keep-hourly <N>``
+  Keep backups for the last ``<N>`` hours. If there is more than one
+  backup for a single hour, only the latest is kept.
+
+``--keep-daily <N>``
+  Keep backups for the last ``<N>`` days. If there is more than one
+  backup for a single day, only the latest is kept.
+
+``--keep-weekly <N>``
+  Keep backups for the last ``<N>`` weeks. If there is more than one
+  backup for a single week, only the latest is kept.
+
+  .. note:: Weeks start on Monday and end on Sunday. The software
+     uses the `ISO week date`_ system and handles weeks at
+     the end of the year correctly.
+
+``--keep-monthly <N>``
+  Keep backups for the last ``<N>`` months. If there is more than one
+  backup for a single month, only the latest is kept.
+
+``--keep-yearly <N>``
+  Keep backups for the last ``<N>`` years. If there is more than one
+  backup for a single year, only the latest is kept.
+
+The retention options are processed in the order given above. Each option
+only covers backups within its time period. The next option does not take care
+of already covered backups. It will only consider older backups.
+
+Unfinished and incomplete backups will be removed by the prune command unless
+they are newer than the last successful backup. In this case, the last failed
+backup is retained.
+
+.. code-block:: console
+
+  # proxmox-backup-client prune <group> --keep-daily 7 --keep-weekly 4 --keep-monthly 3
+
+
+You can use the ``--dry-run`` option to test your settings. This only
+shows the list of existing snapshots and what actions prune would take.
+
+.. code-block:: console
+
+  # proxmox-backup-client prune host/elsa --dry-run --keep-daily 1 --keep-weekly 3
+  ┌────────────────────────────────┬──────┐
+  │ snapshot                       │ keep │
+  ╞════════════════════════════════╪══════╡
+  │ host/elsa/2019-12-04T13:20:37Z │    1 │
+  ├────────────────────────────────┼──────┤
+  │ host/elsa/2019-12-03T09:35:01Z │    0 │
+  ├────────────────────────────────┼──────┤
+  │ host/elsa/2019-11-22T11:54:47Z │    1 │
+  ├────────────────────────────────┼──────┤
+  │ host/elsa/2019-11-21T12:36:25Z │    0 │
+  ├────────────────────────────────┼──────┤
+  │ host/elsa/2019-11-10T10:42:20Z │    1 │
+  └────────────────────────────────┴──────┘
+
+.. note:: Neither the ``prune`` command nor the ``forget`` command free space
+   in the chunk-store. The chunk-store still contains the data blocks. To free
+   space you need to perform :ref:`client_garbage-collection`.
+
+It is also possible to protect single snapshots from being pruned or deleted:
+
+.. code-block:: console
+
+  # proxmox-backup-client snapshot protected update <snapshot> true
+
+This will set the protected flag on the snapshot and prevent pruning or manual
+deletion of this snapshot untilt he flag is removed again with:
+
+.. code-block:: console
+
+  # proxmox-backup-client snapshot protected update <snapshot> false
+
+When a group is with a protected snapshot is deleted, only the non-protected
+ones are removed and the group will remain.
+
+.. note:: This flag will not be synced when using pull or sync jobs. If you
+   want to protect a synced snapshot, you have to manually to this again on
+   the target backup server.
+
+.. _client_garbage-collection:
+
+Garbage Collection
+------------------
+
+The ``prune`` command removes only the backup index files, not the data
+from the datastore. This task is left to the garbage collection
+command. It is recommended to carry out garbage collection on a regular basis.
+
+The garbage collection works in two phases. In the first phase, all
+data blocks that are still in use are marked. In the second phase,
+unused data blocks are removed.
+
+.. note:: This command needs to read all existing backup index files
+  and touches the complete chunk-store. This can take a long time
+  depending on the number of chunks and the speed of the underlying
+  disks.
+
+.. note:: The garbage collection will only remove chunks that haven't been used
+   for at least one day (exactly 24h 5m). This grace period is necessary because
+   chunks in use are marked by touching the chunk which updates the ``atime``
+   (access time) property. Filesystems are mounted with the ``relatime`` option
+   by default. This results in a better performance by only updating the
+   ``atime`` property if the last access has been at least 24 hours ago. The
+   downside is that touching a chunk within these 24 hours will not always
+   update its ``atime`` property.
+
+   Chunks in the grace period will be logged at the end of the garbage
+   collection task as *Pending removals*.
+
+.. code-block:: console
+
+  # proxmox-backup-client garbage-collect
+  starting garbage collection on store store2
+  Start GC phase1 (mark used chunks)
+  Start GC phase2 (sweep unused chunks)
+  percentage done: 1, chunk count: 219
+  percentage done: 2, chunk count: 453
+  ...
+  percentage done: 99, chunk count: 21188
+  Removed bytes: 411368505
+  Removed chunks: 203
+  Original data bytes: 327160886391
+  Disk bytes: 52767414743 (16 %)
+  Disk chunks: 21221
+  Average chunk size: 2486565
+  TASK OK
+
+Garbage collection can also be scheduled using ``promxox-backup-manager`` or
+from the Proxmox Backup Server's web interface.
+
+Benchmarking
+------------
+
+The backup client also comes with a benchmarking tool. This tool measures
+various metrics relating to compression and encryption speeds. If a Proxmox
+Backup repository (remote or local) is specified, the TLS upload speed will get
+measured too.
+
+You can run a benchmark using the ``benchmark`` subcommand of
+``proxmox-backup-client``:
+
+.. note:: The TLS speed test is only included if a :ref:`backup server
+  repository is specified <client_repository>`.
+
+.. code-block:: console
+
+  # proxmox-backup-client benchmark
+  Uploaded 1517 chunks in 5 seconds.
+  Time per request: 3309 microseconds.
+  TLS speed: 1267.41 MB/s
+  SHA256 speed: 2066.73 MB/s
+  Compression speed: 775.11 MB/s
+  Decompress speed: 1233.35 MB/s
+  AES256/GCM speed: 3688.27 MB/s
+  Verify speed: 783.43 MB/s
+  ┌───────────────────────────────────┬─────────────────────┐
+  │ Name                              │ Value               │
+  ╞═══════════════════════════════════╪═════════════════════╡
+  │ TLS (maximal backup upload speed) │ 1267.41 MB/s (103%) │
+  ├───────────────────────────────────┼─────────────────────┤
+  │ SHA256 checksum computation speed │ 2066.73 MB/s (102%) │
+  ├───────────────────────────────────┼─────────────────────┤
+  │ ZStd level 1 compression speed    │ 775.11 MB/s (103%)  │
+  ├───────────────────────────────────┼─────────────────────┤
+  │ ZStd level 1 decompression speed  │ 1233.35 MB/s (103%) │
+  ├───────────────────────────────────┼─────────────────────┤
+  │ Chunk verification speed          │ 783.43 MB/s (103%)  │
+  ├───────────────────────────────────┼─────────────────────┤
+  │ AES256 GCM encryption speed       │ 3688.27 MB/s (101%) │
+  └───────────────────────────────────┴─────────────────────┘
+
+
+.. note:: The percentages given in the output table correspond to a
+  comparison against a Ryzen 7 2700X.
+
+You can also pass the ``--output-format`` parameter to output stats in ``json``,
+rather than the default table format.

docs/backup-protocol.rst

@@ -1,19 +1,141 @@
 Backup Protocol
 ===============
 
-.. todo:: add introduction to HTTP2 based backup protocols
+Proxmox Backup Server uses a REST-based API. While the management
+interface uses normal HTTP, the actual backup and restore interface uses
+HTTP/2 for improved performance. Both HTTP and HTTP/2 are well known
+standards, so the following section assumes that you are familiar with
+how to use them.
+
 
 Backup Protocol API
 -------------------
 
-.. todo:: describe backup writer protocol
+To start a new backup, the API call ``GET /api2/json/backup`` needs to
+be upgraded to a HTTP/2 connection using
+``proxmox-backup-protocol-v1`` as the protocol name::
 
-.. include:: backup-protocol-api.rst
+  GET /api2/json/backup HTTP/1.1
+  UPGRADE: proxmox-backup-protocol-v1
+
+The server replies with the ``HTTP 101 Switching Protocol`` status code,
+and you can then issue REST commands on the updated HTTP/2 connection.
+
+The backup protocol allows you to upload three different kind of files:
+
+- Chunks and blobs (binary data)
+
+- Fixed indexes (List of chunks with fixed size)
+
+- Dynamic indexes (List of chunks with variable size)
+
+The following section provides a short introduction on how to upload such
+files. Please use the `API Viewer <api-viewer/index.html>`_ for
+details about the available REST commands.
 
 
-Reader Protocol API
+Upload Blobs
--------------------
+~~~~~~~~~~~~
 
-.. todo:: describe backup reader protocol
+Blobs are uploaded using ``POST /blob``. The HTTP body contains the
+data encoded as :ref:`Data Blob <data-blob-format>`.
 
-.. include:: reader-protocol-api.rst
+The file name must end with ``.blob``, and is automatically added
+to the backup manifest, following the call to ``POST /finish``.
+
+
+Upload Chunks
+~~~~~~~~~~~~~
+
+Chunks belong to an index, so you first need to open an index (see
+below). After that, you can upload chunks using ``POST /fixed_chunk``
+and ``POST /dynamic_chunk``. The HTTP body contains the chunk data
+encoded as :ref:`Data Blob <data-blob-format>`).
+
+
+Upload Fixed Indexes
+~~~~~~~~~~~~~~~~~~~~
+
+Fixed indexes are used to store VM image data. The VM image is split
+into equally sized chunks, which are uploaded individually. The index
+file simply contains a list of chunk digests.
+
+You create a fixed index with ``POST /fixed_index``. Then, upload
+chunks with ``POST /fixed_chunk``, and append them to the index with
+``PUT /fixed_index``. When finished, you need to close the index using
+``POST /fixed_close``.
+
+The file name needs to end with ``.fidx``, and is automatically added
+to the backup manifest, following the call to ``POST /finish``.
+
+
+Upload Dynamic Indexes
+~~~~~~~~~~~~~~~~~~~~~~
+
+Dynamic indexes are used to store file archive data. The archive data
+is split into dynamically sized chunks, which are uploaded
+individually. The index file simply contains a list of chunk digests
+and offsets.
+
+You can create a dynamically sized index with ``POST /dynamic_index``. Then,
+upload chunks with ``POST /dynamic_chunk``, and append them to the index with
+``PUT /dynamic_index``. When finished, you need to close the index using
+``POST /dynamic_close``.
+
+The filename needs to end with ``.didx``, and is automatically added
+to the backup manifest, following the call to ``POST /finish``.
+
+
+Finish Backup
+~~~~~~~~~~~~~
+
+Once you have uploaded all data, you need to call ``POST /finish``. This
+commits all data and ends the backup protocol.
+
+
+Restore/Reader Protocol API
+---------------------------
+
+To start a new reader, the API call ``GET /api2/json/reader`` needs to
+be upgraded to a HTTP/2 connection using
+``proxmox-backup-reader-protocol-v1`` as protocol name::
+
+  GET /api2/json/reader HTTP/1.1
+  UPGRADE: proxmox-backup-reader-protocol-v1
+
+The server replies with the ``HTTP 101 Switching Protocol`` status code,
+and you can then issue REST commands on that updated HTTP/2 connection.
+
+The reader protocol allows you to download three different kinds of files:
+
+- Chunks and blobs (binary data)
+
+- Fixed indexes (list of chunks with fixed size)
+
+- Dynamic indexes (list of chunks with variable size)
+
+The following section provides a short introduction on how to download such
+files. Please use the `API Viewer <api-viewer/index.html>`_ for details about
+the available REST commands.
+
+
+Download Blobs
+~~~~~~~~~~~~~~
+
+Blobs are downloaded using ``GET /download``. The HTTP body contains the
+data encoded as :ref:`Data Blob <data-blob-format>`.
+
+
+Download Chunks
+~~~~~~~~~~~~~~~
+
+Chunks are downloaded using ``GET /chunk``. The HTTP body contains the
+data encoded as :ref:`Data Blob <data-blob-format>`.
+
+
+Download Index Files
+~~~~~~~~~~~~~~~~~~~~
+
+Index files are downloaded using ``GET /download``. The HTTP body
+contains the data encoded as :ref:`Fixed Index <fixed-index-format>`
+or :ref:`Dynamic Index <dynamic-index-format>`.

docs/calendarevents.rst

@@ -0,0 +1,99 @@
+.. _calendar-event-scheduling:
+
+Calendar Events
+===============
+
+Introduction and Format
+-----------------------
+
+Certain tasks, for example pruning and garbage collection, need to be
+performed on a regular basis. Proxmox Backup Server uses a format inspired
+by the systemd Time and Date Specification (see `systemd.time manpage`_)
+called `calendar events` for its schedules.
+
+`Calendar events` are expressions to specify one or more points in time.
+They are mostly compatible with systemd's calendar events.
+
+The general format is as follows:
+
+.. code-block:: console
+  :caption: Calendar event
+
+  [WEEKDAY] [[YEARS-]MONTHS-DAYS] [HOURS:MINUTES[:SECONDS]]
+
+Note that there either has to be at least a weekday, date or time part.
+If the weekday or date part is omitted, all (week)days are included.
+If the time part is omitted, the time 00:00:00 is implied.
+(e.g. '2020-01-01' refers to '2020-01-01 00:00:00')
+
+Weekdays are specified with the abbreviated English version:
+`mon, tue, wed, thu, fri, sat, sun`.
+
+Each field can contain multiple values in the following formats:
+
+* comma-separated: e.g.,  01,02,03
+* as a range: e.g., 01..10
+* as a repetition: e.g, 05/10 (means starting at 5 every 10)
+* and a combination of the above: e.g., 01,05..10,12/02
+* or a `*` for every possible value: e.g., \*:00
+
+There are some special values that have a specific meaning:
+
+=================================  ==============================
+Value                              Syntax
+=================================  ==============================
+`minutely`                         `*-*-* *:*:00`
+`hourly`                           `*-*-* *:00:00`
+`daily`                            `*-*-* 00:00:00`
+`weekly`                           `mon *-*-* 00:00:00`
+`monthly`                          `*-*-01 00:00:00`
+`yearly` or `annually`              `*-01-01 00:00:00`
+`quarterly`                        `*-01,04,07,10-01 00:00:00`
+`semiannually` or `semi-annually`  `*-01,07-01 00:00:00`
+=================================  ==============================
+
+
+Here is a table with some useful examples:
+
+======================== =============================  ===================================
+Example                  Alternative                    Explanation
+======================== =============================  ===================================
+`mon,tue,wed,thu,fri`    `mon..fri`                     Every working day at 00:00
+`sat,sun`                `sat..sun`                     Only on weekends at 00:00
+`mon,wed,fri`            --                             Monday, Wednesday, Friday at 00:00
+`12:05`                  --                             Every day at 12:05 PM
+`*:00/5`                 `0/1:0/5`                      Every five minutes
+`mon..wed *:30/10`       `mon,tue,wed *:30/10`          Monday, Tuesday, Wednesday 30, 40 and 50 minutes after every full hour
+`mon..fri 8..17,22:0/15` --                             Every working day every 15 minutes between 8 AM and 6 PM and between 10 PM and 11 PM
+`fri 12..13:5/20`        `fri 12,13:5/20`               Friday at 12:05, 12:25, 12:45, 13:05, 13:25 and 13:45
+`12,14,16,18,20,22:5`    `12/2:5`                       Every day starting at 12:05 until 22:05, every 2 hours
+`*:*`                    `0/1:0/1`                      Every minute (minimum interval)
+`*-05`                   --                             On the 5th day of every Month
+`Sat *-1..7 15:00`       --                             First Saturday each Month at 15:00
+`2015-10-21`             --                             21st October 2015 at 00:00
+======================== =============================  ===================================
+
+
+Differences to systemd
+----------------------
+
+Not all features of systemd calendar events are implemented:
+
+* no Unix timestamps (e.g. `@12345`): instead use date and time to specify
+  a specific point in time
+* no timezone: all schedules use the timezone of the server
+* no sub-second resolution
+* no reverse day syntax (e.g. 2020-03~01)
+* no repetition of ranges (e.g. 1..10/2)
+
+Notes on Scheduling
+-------------------
+
+In `Proxmox Backup`_, scheduling for most tasks is done in the
+`proxmox-backup-proxy`. This daemon checks all job schedules
+every minute, to see if any are due. This means that even though
+`calendar events` can contain seconds, it will only be checked
+once per minute.
+
+Also, all schedules will be checked against the timezone set
+in the `Proxmox Backup`_ server.

docs/certificate-management.rst

@@ -0,0 +1,333 @@
+.. _sysadmin_certificate_management:
+
+Certificate Management
+----------------------
+
+Access to the API and thus the web-based administration interface is always
+encrypted through ``https``. Each `Proxmox Backup`_ host creates by default its
+own (self-signed) certificate. This certificate is used for encrypted
+communication with the host’s ``proxmox-backup-proxy`` service, for any API
+call between a user or backup-client and the web-interface.
+
+Certificate verification when sending backups to a `Proxmox Backup`_ server
+is either done based on pinning the certificate fingerprints in the storage/remote
+configuration, or by using certificates, signed by a trusted certificate authority.
+
+.. _sysadmin_certs_api_gui:
+
+Certificates for the API and SMTP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Proxmox Backup`_ stores it certificate and key in:
+
+-  ``/etc/proxmox-backup/proxy.pem``
+
+-  ``/etc/proxmox-backup/proxy.key``
+
+You have the following options for the certificate:
+
+1. Keep using the default self-signed certificate in
+   ``/etc/proxmox-backup/proxy.pem``.
+
+2. Use an externally provided certificate (for example, signed by a
+   commercial Certificate Authority (CA)).
+
+3. Use an ACME provider like Let’s Encrypt to get a trusted certificate
+   with automatic renewal; this is also integrated in the `Proxmox Backup`_
+   API and web interface.
+
+Certificates are managed through the `Proxmox Backup`_
+web-interface/API or using the the ``proxmox-backup-manager`` CLI tool.
+
+.. _sysadmin_certs_upload_custom:
+
+Upload Custom Certificate
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you already have a certificate which you want to use for a Proxmox
+Mail Gateway host, you can simply upload that certificate over the web
+interface.
+
+
+.. image:: images/screenshots/pbs-gui-certs-upload-custom.png
+  :align: right
+  :alt: Upload a custom certificate
+
+Note that any certificate key files must not be password protected.
+
+.. _sysadmin_certs_get_trusted_acme_cert:
+
+Trusted certificates via Let’s Encrypt (ACME)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Proxmox Backup`_ includes an implementation of the **A**\ utomatic
+**C**\ ertificate **M**\ anagement **E**\ nvironment (**ACME**)
+protocol, allowing `Proxmox Backup`_ admins to use an ACME provider
+like Let’s Encrypt for easy setup of TLS certificates, which are
+accepted and trusted by modern operating systems and web browsers out of
+the box.
+
+Currently, the two ACME endpoints implemented are the `Let’s Encrypt
+(LE) <https://letsencrypt.org>`_ production and staging environments.
+Our ACME client supports validation of ``http-01`` challenges using a
+built-in web server and validation of ``dns-01`` challenges using a DNS
+plugin supporting all the DNS API endpoints
+`acme.sh <https://acme.sh>`_ does.
+
+.. _sysadmin_certs_acme_account:
+
+ACME Account
+^^^^^^^^^^^^
+
+.. image:: images/screenshots/pbs-gui-acme-create-account.png
+  :align: right
+  :alt: Create ACME Account
+
+You need to register an ACME account per cluster, with the endpoint you
+want to use. The email address used for that account will serve as the
+contact point for renewal-due or similar notifications from the ACME
+endpoint.
+
+You can register or deactivate ACME accounts over the web interface
+``Certificates -> ACME Accounts`` or using the ``proxmox-backup-manager`` command
+line tool.
+
+::
+
+    proxmox-backup-manager acme account register <account-name> <mail@example.com>
+
+.. tip::
+
+   Because of
+   `rate-limits <https://letsencrypt.org/docs/rate-limits/>`_ you
+   should use LE ``staging`` for experiments or if you use ACME for the
+   very first time until all is working there, and only then switch over
+   to the production directory.
+
+.. _sysadmin_certs_acme_plugins:
+
+ACME Plugins
+^^^^^^^^^^^^
+
+The ACME plugin’s role is to provide automatic verification that you,
+and thus the `Proxmox Backup`_ server under your operation, are the
+real owner of a domain. This is the basic building block of automatic
+certificate management.
+
+The ACME protocol specifies different types of challenges, for example
+the ``http-01``, where a web server provides a file with a specific
+token to prove that it controls a domain. Sometimes this isn’t possible,
+either because of technical limitations or if the address of a record is
+not reachable from the public internet. The ``dns-01`` challenge can be
+used in such cases. This challenge is fulfilled by creating a certain
+DNS record in the domain’s zone.
+
+.. image:: images/screenshots/pbs-gui-acme-create-challenge-plugin.png
+  :align: right
+  :alt: Create ACME Account
+
+`Proxmox Backup`_ supports both of those challenge types out of the
+box, you can configure plugins either over the web interface under
+``Certificates -> ACME Challenges``, or using the
+``proxmox-backup-manager acme plugin add`` command.
+
+ACME Plugin configurations are stored in ``/etc/proxmox-backup/acme/plugins.cfg``.
+
+.. _domains:
+
+Domains
+^^^^^^^
+
+You can add new or manage existing domain entries under
+``Certificates``, or using the ``proxmox-backup-manager`` command.
+
+.. image:: images/screenshots/pbs-gui-acme-add-domain.png
+  :align: right
+  :alt: Add a Domain for ACME verification
+
+After configuring the desired domain(s) for a node and ensuring that the
+desired ACME account is selected, you can order your new certificate
+over the web-interface. On success, the interface will reload after
+roughly 10 seconds.
+
+Renewal will happen `automatically <#sysadmin-certs-acme-automatic-renewal>`_
+
+.. _sysadmin_certs_acme_http_challenge:
+
+ACME HTTP Challenge Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is always an implicitly configured ``standalone`` plugin for
+validating ``http-01`` challenges via the built-in web server spawned on
+port 80.
+
+.. note::
+
+   The name ``standalone`` means that it can provide the validation on
+   its own, without any third party service.
+
+There are a few prerequisites to use this for certificate management
+with Let’s Encrypts ACME.
+
+-  You have to accept the ToS of Let’s Encrypt to register an account.
+
+-  **Port 80** of the node needs to be reachable from the internet.
+
+-  There **must** be no other listener on port 80.
+
+-  The requested (sub)domain needs to resolve to a public IP of the
+   `Proxmox Backup`_ host.
+
+.. _sysadmin_certs_acme_dns_challenge:
+
+ACME DNS API Challenge Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On systems where external access for validation via the ``http-01``
+method is not possible or desired, it is possible to use the ``dns-01``
+validation method. This validation method requires a DNS server that
+allows provisioning of ``TXT`` records via an API.
+
+.. _sysadmin_certs_acme_dns_api_config:
+
+Configuring ACME DNS APIs for validation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`Proxmox Backup`_ re-uses the DNS plugins developed for the
+``acme.sh``  [1]_ project. Please refer to its documentation for details
+on configuration of specific APIs.
+
+The easiest way to configure a new plugin with the DNS API is using the
+web interface (``Certificates -> ACME Accounts/Challenges``).
+
+Here you can add a new challenge plugin by selecting your API provider
+and entering the credential data to access your account over their API.
+
+.. tip::
+
+   See the acme.sh `How to use DNS
+   API <https://github.com/acmesh-official/acme.sh/wiki/dnsapi#how-to-use-dns-api>`_
+   wiki for more detailed information about getting API credentials for
+   your provider. Configuration values do not need to be quoted with
+   single or double quotes; for some plugins that is even an error.
+
+As there are many DNS providers and API endpoints, `Proxmox Backup`_
+automatically generates the form for the credentials, but not all
+providers are annotated yet. For those you will see a bigger text area,
+into which you simply need to copy all the credential’s
+``KEY``\ =\ ``VALUE`` pairs.
+
+.. _dns_validation_through_cname_alias:
+
+DNS Validation through CNAME Alias
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A special ``alias`` mode can be used to handle validation on a different
+domain/DNS server, in case your primary/real DNS does not support
+provisioning via an API. Manually set up a permanent ``CNAME`` record
+for ``_acme-challenge.domain1.example`` pointing to
+``_acme-challenge.domain2.example``, and set the ``alias`` property in
+the `Proxmox Backup`_ node configuration file ``/etc/proxmox-backup/node.cfg``
+to ``domain2.example`` to allow the DNS server of ``domain2.example`` to
+validate all challenges for ``domain1.example``.
+
+.. _sysadmin_certs_acme_dns_wildcard:
+
+Wildcard Certificates
+^^^^^^^^^^^^^^^^^^^^^
+
+Wildcard DNS names start with a ``*.`` prefix and are considered valid
+for all (one-level) subdomain names of the verified domain. So a
+certificate for ``*.domain.example`` is valid for ``foo.domain.example``
+and ``bar.domain.example``, but not for ``baz.foo.domain.example``.
+
+Currently, you can only create wildcard certificates with the `DNS
+challenge
+type <https://letsencrypt.org/docs/challenge-types/#dns-01-challenge>`_.
+
+.. _combination_of_plugins:
+
+Combination of Plugins
+^^^^^^^^^^^^^^^^^^^^^^
+
+Combining ``http-01`` and ``dns-01`` validation is possible in case your
+node is reachable via multiple domains with different requirements / DNS
+provisioning capabilities. Mixing DNS APIs from multiple providers or
+instances is also possible by specifying different plugin instances per
+domain.
+
+.. tip::
+
+   Accessing the same service over multiple domains increases complexity
+   and should be avoided if possible.
+
+.. _sysadmin_certs_acme_automatic_renewal:
+
+Automatic renewal of ACME certificates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a node has been successfully configured with an ACME-provided
+certificate (either via ``proxmox-backup-manager`` or via the web-interface/API), the
+certificate will be renewed automatically by the ``proxmox-backup-daily-update.service``.
+Currently, renewal is triggered if the certificate either has already
+expired or if it will expire in the next 30 days.
+
+.. _manually_change_certificate_over_command_line:
+
+Manually Change Certificate over Command-Line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to get rid of certificate verification warnings, you have to
+generate a valid certificate for your server.
+
+Log in to your `Proxmox Backup`_ via ssh or use the console:
+
+::
+
+   openssl req -newkey rsa:2048 -nodes -keyout key.pem -out req.pem
+
+Follow the instructions on the screen, for example:
+
+::
+
+   Country Name (2 letter code) [AU]: AT
+   State or Province Name (full name) [Some-State]:Vienna
+   Locality Name (eg, city) []:Vienna
+   Organization Name (eg, company) [Internet Widgits Pty Ltd]: Proxmox GmbH
+   Organizational Unit Name (eg, section) []:Proxmox Backup
+   Common Name (eg, YOUR name) []: yourproxmox.yourdomain.com
+   Email Address []:support@yourdomain.com
+
+   Please enter the following 'extra' attributes to be sent with your certificate request
+   A challenge password []: not necessary
+   An optional company name []: not necessary
+
+After you have finished the certificate request, you have to send the
+file ``req.pem`` to your Certification Authority (CA). The CA will issue
+the certificate (BASE64 encoded), based on your request – save this file
+as ``cert.pem`` to your `Proxmox Backup`_.
+
+To activate the new certificate, do the following on your `Proxmox Backup`_
+
+::
+
+   cp key.pem /etc/proxmox-backup/proxy.key
+   cp cert.pem /etc/proxmox-backup/proxy.pem
+
+Then restart the API servers:
+
+::
+
+   systemctl restart proxmox-backup-proxy
+
+Test your new certificate, using your browser.
+
+.. note::
+
+   To transfer files to and from your `Proxmox Backup`_, you can use
+   secure copy: If your desktop runs Linux, you can use the ``scp``
+   command line tool. If your desktop PC runs windows, please use an scp
+   client like WinSCP (see https://winscp.net/).
+
+.. [1]
+   acme.sh https://github.com/acmesh-official/acme.sh

docs/command-line-tools.rst

@@ -11,8 +11,32 @@ Command Line Tools
 
 .. include:: proxmox-backup-manager/description.rst
 
+``proxmox-tape``
+~~~~~~~~~~~~~~~~
+
+.. include:: proxmox-tape/description.rst
+
+``pmt``
+~~~~~~~
+
+.. include:: pmt/description.rst
+
+``pmtx``
+~~~~~~~~
+
+.. include:: pmtx/description.rst
+
 ``pxar``
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~
 
 .. include:: pxar/description.rst
 
+``proxmox-file-restore``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: proxmox-file-restore/description.rst
+
+``proxmox-backup-debug``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: proxmox-backup-debug/description.rst

docs/command-syntax.rst

@@ -10,7 +10,7 @@ Command Syntax
 Catalog Shell Commands
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Those command are available when you start an intercative restore shell:
+The following commands are available in an interactive restore shell:
 
 .. code-block:: console
 
@@ -26,7 +26,38 @@ Those command are available when you start an intercative restore shell:
 .. include:: proxmox-backup-manager/synopsis.rst
 
 
+``proxmox-tape``
+----------------
+
+.. include:: proxmox-tape/synopsis.rst
+
+``pmt``
+-------
+
+.. include:: pmt/options.rst
+
+....
+
+.. include:: pmt/synopsis.rst
+
+
+``pmtx``
+--------
+
+.. include:: pmtx/synopsis.rst
+
+
 ``pxar``
 --------
 
 .. include:: pxar/synopsis.rst
+
+
+``proxmox-file-restore``
+------------------------
+.. include:: proxmox-file-restore/synopsis.rst
+
+
+``proxmox-backup-debug``
+------------------------
+.. include:: proxmox-backup-debug/synopsis.rst

docs/conf.py

@@ -18,9 +18,12 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
-# import sys
+import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+# custom extensions
+sys.path.append(os.path.abspath("./_ext"))
+
 # -- Implement custom formatter for code-blocks ---------------------------
 #
 # * use smaller font
@@ -46,7 +49,7 @@ PygmentsBridge.latex_formatter = CustomLatexFormatter
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 
-extensions = ["sphinx.ext.graphviz", "sphinx.ext.todo"]
+extensions = ["sphinx.ext.graphviz", 'sphinx.ext.mathjax', "sphinx.ext.todo", "proxmox-scanrefs"]
 
 todo_link_only = True
 
@@ -71,10 +74,10 @@ rst_epilog = epilog_file.read()
 
 # General information about the project.
 project = 'Proxmox Backup'
-copyright = '2019-2020, Proxmox Support Team'
+copyright = '2019-2021, Proxmox Server Solutions GmbH'
 author = 'Proxmox Support Team'
 
-# The version info for the project you're documenting, acts as replacement for
+# The version info for the project you're documenting, acts as a replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
@@ -94,26 +97,25 @@ language = None
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
-#
 # today = ''
 #
 # Else, today_fmt is used as the format for a strftime call.
-#
+today_fmt = '%A, %d %B %Y'
-# today_fmt = '%B %d, %Y'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = [
     '_build', 'Thumbs.db', '.DS_Store',
-    'proxmox-backup-client/man1.rst',
+    '*/man1.rst',
-    'proxmox-backup-manager/man1.rst',
+    'certificate-management.rst',
-    'proxmox-backup-proxy/man1.rst',
+    'config/*/man5.rst',
-    'pxar/man1.rst',
     'epilog.rst',
     'pbs-copyright.rst',
-    'local-zfs.rst'
+    'local-zfs.rst',
     'package-repositories.rst',
+    'system-booting.rst',
+    'traffic-control.rst',
 ]
 
 # The reST default role (used for this markup: `text`) to use for all
@@ -145,7 +147,7 @@ pygments_style = 'sphinx'
 # keep_warnings = False
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
+todo_include_todos = not tags.has('release')
 
 
 # -- Options for HTML output ----------------------------------------------
@@ -153,13 +155,54 @@ todo_include_todos = True
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinxdoc'
+html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'fixed_sidebar': True,
+    'sidebar_includehidden': False,
+    'sidebar_collapse': False,
+    'globaltoc_collapse': False,
+    'show_relbar_bottom': True,
+    'show_powered_by': False,
+
+    'extra_nav_links': {
+        'Proxmox Homepage': 'https://proxmox.com',
+        'PDF': 'proxmox-backup.pdf',
+        'API Viewer' : 'api-viewer/index.html',
+        'Prune Simulator' : 'prune-simulator/index.html',
+        'LTO Barcode Generator' : 'lto-barcode/index.html',
+    },
+
+    'sidebar_width': '320px',
+    'page_width': '1320px',
+    # font styles
+    'head_font_family': 'Lato, sans-serif',
+    'caption_font_family': 'Lato, sans-serif',
+    'caption_font_size': '20px',
+    'font_family': 'Open Sans, sans-serif',
+}
+
+# Alabaster theme recommends setting this fixed.
+# If you switch theme this needs to removed, probably.
+html_sidebars = {
+    '**': [
+        'sidebar-header.html',
+        'searchbox.html',
+        'navigation.html',
+        'relations.html',
+    ],
+
+    'index': [
+        'sidebar-header.html',
+        'searchbox.html',
+        'index-sidebar.html',
+    ]
+}
+
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -176,7 +219,7 @@ html_theme = 'sphinxdoc'
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-html_logo = 'images/proxmox-logo.svg'
+#html_logo = 'images/proxmox-logo.svg' # replaced by html_theme_options.logo
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -189,6 +232,10 @@ html_favicon = 'images/favicon.ico'
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_js_files = [
+    'custom.js',
+]
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
@@ -201,14 +248,8 @@ html_static_path = ['_static']
 #
 # html_last_updated_fmt = None
 
-# If true, SmartyPants will be used to convert quotes and dashes to
+# We need to disable smatquotes, else Option Lists do not display long options
-# typographically correct entities.
+smartquotes = False
-#
-# html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#
-# html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -229,7 +270,7 @@ html_static_path = ['_static']
 
 # If true, links to the reST sources are added to the pages.
 #
-# html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 #
@@ -269,6 +310,9 @@ html_static_path = ['_static']
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'ProxmoxBackupdoc'
 
+# use local mathjax package, symlink comes from debian/proxmox-backup-docs.links
+mathjax_path = "mathjax/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
+
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_engine = 'xelatex'

docs/config/acl/format.rst

@@ -0,0 +1,22 @@
+This file contains the access control list for the Proxmox Backup
+Server API.
+
+Each line starts with ``acl:``, followed by 4 additional values
+separated by colon.
+
+:propagate: Propagate permissions down the hierarchy
+
+:path: The object path
+
+:User/Token: List of users and tokens
+
+:Role: List of assigned roles
+
+Here is an example list::
+
+   acl:1:/:root@pam!test:Admin
+   acl:1:/datastore/store1:user1@pbs:DatastoreAdmin
+
+
+You can use the ``proxmox-backup-manager acl`` command to manipulate
+this file.

docs/config/acl/man5.rst

@@ -0,0 +1,35 @@
+==========================
+acl.cfg
+==========================
+
+.. include:: ../../epilog.rst
+
+-------------------------------------------------------------
+Access Control Configuration
+-------------------------------------------------------------
+
+:Author: |AUTHOR|
+:Version: Version |VERSION|
+:Manual section: 5
+
+Description
+===========
+
+The file /etc/proxmox-backup/user.cfg is a configuration file for Proxmox
+Backup Server. It contains the access control configuration for the API.
+
+File Format
+===========
+
+.. include:: format.rst
+
+
+Roles
+=====
+
+The following roles exist:
+
+.. include:: roles.rst
+
+
+.. include:: ../../pbs-copyright.rst

docs/config/datastore/format.rst

@@ -0,0 +1,18 @@
+This file contains a list of datastore configuration sections. Each
+section starts with the header ``datastore: <name>``, followed by the
+datastore configuration options.
+
+::
+
+  datastore: <name1>
+     path <path1>
+     <option1> <value1>
+     ...
+
+  datastore: <name2>
+     path <path2>
+     ...
+
+
+You can use the ``proxmox-backup-manager datastore`` command to manipulate
+this file.

docs/config/datastore/man5.rst

@@ -0,0 +1,33 @@
+==========================
+datastore.cfg
+==========================
+
+.. include:: ../../epilog.rst
+
+-------------------------------------------------------------
+Datastore Configuration
+-------------------------------------------------------------
+
+:Author: |AUTHOR|
+:Version: Version |VERSION|
+:Manual section: 5
+
+Description
+===========
+
+The file /etc/proxmox-backup/datastore.cfg is a configuration file for Proxmox
+Backup Server. It contains the Datastore configuration.
+
+File Format
+===========
+
+.. include:: format.rst
+
+
+Options
+=======
+
+.. include:: config.rst
+
+
+.. include:: ../../pbs-copyright.rst

docs/config/media-pool/format.rst

@@ -0,0 +1,13 @@
+Each entry starts with the header ``pool: <name>``, followed by the
+media pool configuration options.
+
+::
+
+  pool: company1
+	allocation always
+	retention overwrite
+
+  pool: ...
+
+
+You can use the ``proxmox-tape pool`` command to manipulate this file.

docs/config/media-pool/man5.rst

@@ -0,0 +1,35 @@
+==========================
+media-pool.cfg
+==========================
+
+.. include:: ../../epilog.rst
+
+-------------------------------------------------------------
+Media Pool Configuration
+-------------------------------------------------------------
+
+:Author: |AUTHOR|
+:Version: Version |VERSION|
+:Manual section: 5
+
+Description
+===========
+
+The file /etc/proxmox-backup/media-pool.cfg is a configuration file
+for Proxmox Backup Server. It contains the medila pool configuration
+for tape backups.
+
+
+File Format
+===========
+
+.. include:: format.rst
+
+
+Options
+=======
+
+.. include:: config.rst
+
+
+.. include:: ../../pbs-copyright.rst

docs/config/remote/format.rst

@@ -0,0 +1,17 @@
+This file contains information used to access remote servers.
+
+Each entry starts with the header ``remote: <name>``, followed by the
+remote configuration options.
+
+::
+
+  remote: server1
+	host server1.local
+	auth-id sync@pbs
+	...
+
+  remote: ...
+
+
+You can use the ``proxmox-backup-manager remote`` command to manipulate
+this file.

docs/config/remote/man5.rst

@@ -0,0 +1,35 @@
+==========================
+remote.cfg
+==========================
+
+.. include:: ../../epilog.rst
+
+-------------------------------------------------------------
+Remote Server Configuration
+-------------------------------------------------------------
+
+:Author: |AUTHOR|
+:Version: Version |VERSION|
+:Manual section: 5
+
+Description
+===========
+
+The file /etc/proxmox-backup/remote.cfg is a configuration file for
+Proxmox Backup Server. It contains information about remote servers,
+usable for synchronization jobs.
+
+
+File Format
+===========
+
+.. include:: format.rst
+
+
+Options
+=======
+
+.. include:: config.rst
+
+
+.. include:: ../../pbs-copyright.rst

docs/config/sync/format.rst

@@ -0,0 +1,15 @@
+Each entry starts with the header ``sync: <name>``, followed by the
+job configuration options.
+
+::
+
+  sync: job1
+	store store1
+	remote-store store1
+	remote lina
+
+  sync: ...
+
+
+You can use the ``proxmox-backup-manager sync-job`` command to manipulate
+this file.

docs/config/sync/man5.rst

@@ -0,0 +1,35 @@
+==========================
+sync.cfg
+==========================
+
+.. include:: ../../epilog.rst
+
+-------------------------------------------------------------
+Synchronization Job Configuration
+-------------------------------------------------------------
+
+:Author: |AUTHOR|
+:Version: Version |VERSION|
+:Manual section: 5
+
+Description
+===========
+
+The file /etc/proxmox-backup/sync.cfg is a configuration file for
+Proxmox Backup Server. It contains the synchronization job
+configuration.
+
+
+File Format
+===========
+
+.. include:: format.rst
+
+
+Options
+=======
+
+.. include:: config.rst
+
+
+.. include:: ../../pbs-copyright.rst

docs/config/tape-job/format.rst

@@ -0,0 +1,16 @@
+Each entry starts with the header ``backup: <name>``, followed by the
+job configuration options.
+
+::
+
+  backup: job1
+	drive hh8
+	pool p4
+	store store3
+	schedule daily
+
+  backup: ...
+
+
+You can use the ``proxmox-tape backup-job`` command to manipulate
+this file.

docs/config/tape-job/man5.rst

@@ -0,0 +1,34 @@
+==========================
+tape-job.cfg
+==========================
+
+.. include:: ../../epilog.rst
+
+-------------------------------------------------------------
+Tape Job Configuration
+-------------------------------------------------------------
+
+:Author: |AUTHOR|
+:Version: Version |VERSION|
+:Manual section: 5
+
+Description
+===========
+
+The file ``/etc/proxmox-backup/tape-job.cfg`` is a configuration file for
+Proxmox Backup Server. It contains the tape job configuration.
+
+
+File Format
+===========
+
+.. include:: format.rst
+
+
+Options
+=======
+
+.. include:: config.rst
+
+
+.. include:: ../../pbs-copyright.rst

docs/config/tape/format.rst

@@ -0,0 +1,22 @@
+Each LTO drive configuration section starts with the header ``lto: <name>``,
+followed by the drive configuration options.
+
+Tape changer configurations start with the header ``changer: <name>``,
+followed by the changer configuration options.
+
+::
+
+  lto: hh8
+	changer sl3
+	path /dev/tape/by-id/scsi-10WT065325-nst
+
+  changer: sl3
+	export-slots 14,15,16
+	path /dev/tape/by-id/scsi-CJ0JBE0059
+
+
+You can use the ``proxmox-tape drive`` and ``proxmox-tape changer``
+commands to manipulate this file.
+
+.. NOTE:: The ``virtual:`` drive type is experimental and should only be used
+   for debugging.

docs/config/tape/man5.rst

@@ -0,0 +1,33 @@
+==========================
+tape.cfg
+==========================
+
+.. include:: ../../epilog.rst
+
+-------------------------------------------------------------
+Tape Drive and Changer Configuration
+-------------------------------------------------------------
+
+:Author: |AUTHOR|
+:Version: Version |VERSION|
+:Manual section: 5
+
+Description
+===========
+
+The file /etc/proxmox-backup/tape.cfg is a configuration file for Proxmox
+Backup Server. It contains the tape drive and changer configuration.
+
+File Format
+===========
+
+.. include:: format.rst
+
+
+Options
+=======
+
+.. include:: config.rst
+
+
+.. include:: ../../pbs-copyright.rst

docs/config/user/format.rst

@@ -0,0 +1,28 @@
+This file contains the list of API users and API tokens.
+
+Each user configuration section starts with the header ``user: <name>``,
+followed by the user configuration options.
+
+API token configuration starts with the header ``token:
+<userid!token_name>``, followed by the token configuration. The data
+used to authenticate tokens is stored in a separate file
+(``token.shadow``).
+
+
+::
+
+  user: root@pam
+	comment Superuser
+	email test@example.local
+	...
+
+  token: root@pam!token1
+	comment API test token
+	enable true
+	expire 0
+
+  user: ...
+
+
+You can use the ``proxmox-backup-manager user`` command to manipulate
+this file.

docs/config/user/man5.rst

@@ -0,0 +1,33 @@
+==========================
+user.cfg
+==========================
+
+.. include:: ../../epilog.rst
+
+-------------------------------------------------------------
+User Configuration
+-------------------------------------------------------------
+
+:Author: |AUTHOR|
+:Version: Version |VERSION|
+:Manual section: 5
+
+Description
+===========
+
+The file /etc/proxmox-backup/user.cfg is a configuration file for Proxmox
+Backup Server. It contains the user configuration.
+
+File Format
+===========
+
+.. include:: format.rst
+
+
+Options
+=======
+
+.. include:: config.rst
+
+
+.. include:: ../../pbs-copyright.rst

docs/config/verification/format.rst

@@ -0,0 +1,16 @@
+Each entry starts with the header ``verification: <name>``, followed by the
+job configuration options.
+
+::
+
+  verification: verify-store2
+	ignore-verified true
+	outdated-after 7
+	schedule daily
+	store store2
+
+  verification: ...
+
+
+You can use the ``proxmox-backup-manager verify-job`` command to manipulate
+this file.

docs/config/verification/man5.rst

@@ -0,0 +1,35 @@
+==========================
+verification.cfg
+==========================
+
+.. include:: ../../epilog.rst
+
+-------------------------------------------------------------
+Verification Job Configuration
+-------------------------------------------------------------
+
+:Author: |AUTHOR|
+:Version: Version |VERSION|
+:Manual section: 5
+
+Description
+===========
+
+The file /etc/proxmox-backup/sync.cfg is a configuration file for
+Proxmox Backup Server. It contains the verification job
+configuration.
+
+
+File Format
+===========
+
+.. include:: format.rst
+
+
+Options
+=======
+
+.. include:: config.rst
+
+
+.. include:: ../../pbs-copyright.rst

docs/configuration-files.rst

@@ -0,0 +1,142 @@
+Configuration Files
+===================
+
+All Proxmox Backup Server configuration files reside in the directory
+``/etc/proxmox-backup/``.
+
+
+``acl.cfg``
+~~~~~~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/acl/format.rst
+
+
+Roles
+^^^^^
+
+The following roles exist:
+
+.. include:: config/acl/roles.rst
+
+
+``datastore.cfg``
+~~~~~~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/datastore/format.rst
+
+
+Options
+^^^^^^^
+
+.. include:: config/datastore/config.rst
+
+
+``media-pool.cfg``
+~~~~~~~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/media-pool/format.rst
+
+
+Options
+^^^^^^^
+
+.. include:: config/media-pool/config.rst
+
+
+``tape.cfg``
+~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/tape/format.rst
+
+
+Options
+^^^^^^^
+
+.. include:: config/tape/config.rst
+
+
+``tape-job.cfg``
+~~~~~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/tape-job/format.rst
+
+
+Options
+^^^^^^^
+
+.. include:: config/tape-job/config.rst
+
+
+``user.cfg``
+~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/user/format.rst
+
+
+Options
+^^^^^^^
+
+.. include:: config/user/config.rst
+
+
+``remote.cfg``
+~~~~~~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/remote/format.rst
+
+
+Options
+^^^^^^^
+
+.. include:: config/remote/config.rst
+
+
+``sync.cfg``
+~~~~~~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/sync/format.rst
+
+
+Options
+^^^^^^^
+
+.. include:: config/sync/config.rst
+
+
+``verification.cfg``
+~~~~~~~~~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/verification/format.rst
+
+
+Options
+^^^^^^^
+
+.. include:: config/verification/config.rst

docs/custom.css

@@ -0,0 +1,88 @@
+div.sphinxsidebar {
+    height: calc(100% - 20px);
+    overflow: auto;
+}
+
+h1.logo-name {
+    font-size: 24px;
+}
+
+div.body img {
+    width: 250px;
+}
+pre {
+    padding: 5px 10px;
+}
+
+div.topic {
+    background-color: #FAFAFA;
+}
+
+li a.current {
+    font-weight: bold;
+    border-bottom: 1px solid #000;
+}
+ul li.toctree-l1 {
+    margin-top: 0.5em;
+}
+ul li.toctree-l1 > a {
+    color: #000;
+}
+
+div.sphinxsidebar ul {
+    color: #444;
+}
+div.sphinxsidebar ul ul {
+    list-style: circle;
+}
+div.sphinxsidebar ul ul ul {
+    list-style: square;
+}
+
+div.sphinxsidebar ul a code {
+    font-weight: normal;
+}
+div.sphinxsidebar ul ul a {
+    border-bottom: 1px dotted #CCC;
+}
+
+div.sphinxsidebar form.search {
+    margin-bottom: 5px;
+}
+
+div.sphinxsidebar h3 {
+    width: 100%;
+}
+
+div.sphinxsidebar h1.logo-name {
+    display: none;
+}
+
+div.document, div.footer {
+    width: min(100%, 1320px);
+}
+
+@media screen and (max-width: 875px) {
+    div.sphinxsidebar p.logo {
+        display: initial;
+    }
+    div.sphinxsidebar h1.logo-name {
+        display: block;
+    }
+    div.sphinxsidebar span {
+        color: #EEE;
+    }
+    .sphinxsidebar ul li.toctree-l1 > a, div.sphinxsidebar a {
+        color: #FFF;
+    }
+    div.sphinxsidebar {
+        background-color: #555;
+    }
+    div.body {
+        min-width: 300px;
+    }
+    div.footer {
+        display: block;
+        margin: 15px auto 0px auto;
+    }
+}

docs/custom.js

@@ -0,0 +1,7 @@
+window.addEventListener('DOMContentLoaded', (event) => {
+    let activeSection = document.querySelector("a.current");
+    if (activeSection) {
+        // https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
+        activeSection.scrollIntoView({ block: 'center' });
+    }
+});

docs/epilog.rst

@@ -1,6 +1,6 @@
 .. Epilog (included at top of each file)
 
-   We use this file to define external links and commone replacement
+   We use this file to define external links and common replacement
    patterns.
 
 .. |VERSION| replace:: 1.0
@@ -13,7 +13,7 @@
 .. _Proxmox: https://www.proxmox.com
 .. _Proxmox Community Forum: https://forum.proxmox.com
 .. _Proxmox Virtual Environment: https://www.proxmox.com/proxmox-ve
-.. _Proxmox Backup: https://pbs.proxmox.com/wiki/index.php/Main_Page  // FIXME
+.. _Proxmox Backup: https://pbs.proxmox.com/wiki/index.php/Main_Page
 .. _PBS Development List: https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel
 .. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
 .. _Rust: https://www.rust-lang.org/
@@ -22,6 +22,7 @@
 .. _Virtual machine: https://en.wikipedia.org/wiki/Virtual_machine
 .. _APT: http://en.wikipedia.org/wiki/Advanced_Packaging_Tool
 .. _QEMU: https://www.qemu.org/
+.. _LXC: https://linuxcontainers.org/lxc/introduction/
 
 .. _Client-server model: https://en.wikipedia.org/wiki/Client-server_model
 .. _AE: https://en.wikipedia.org/wiki/Authenticated_encryption
@@ -34,6 +35,9 @@
 .. _ZFS: https://en.wikipedia.org/wiki/ZFS
 .. _Proxmox VE: https://pve.proxmox.com
 
-.. _RFC3399: https://tools.ietf.org/html/rfc3339
+.. _RFC3339: https://tools.ietf.org/html/rfc3339
 .. _UTC: https://en.wikipedia.org/wiki/Coordinated_Universal_Time
 .. _ISO Week date: https://en.wikipedia.org/wiki/ISO_week_date
+
+.. _systemd.time manpage: https://manpages.debian.org/buster/systemd/systemd.time.7.en.html
+

docs/faq.rst

@@ -0,0 +1,74 @@
+FAQ
+===
+
+What distribution is Proxmox Backup Server (PBS) based on?
+----------------------------------------------------------
+
+Proxmox Backup Server is based on `Debian GNU/Linux <https://www.debian.org/>`_.
+
+
+Which platforms are supported as a backup source (client)?
+----------------------------------------------------------
+
+The client tool works on most modern Linux systems, meaning you are not limited
+to Debian-based backups.
+
+
+Will Proxmox Backup Server run on a 32-bit processor?
+-----------------------------------------------------
+
+Proxmox Backup Server only supports 64-bit CPUs (AMD or Intel). There are no
+future plans to support 32-bit processors.
+
+
+How long will my Proxmox Backup Server version be supported?
+------------------------------------------------------------
+
++-----------------------+----------------------+---------------+------------+--------------------+
+|Proxmox Backup Version | Debian Version       | First Release | Debian EOL | Proxmox Backup EOL |
++=======================+======================+===============+============+====================+
+|Proxmox Backup 2.x     | Debian 11 (Bullseye) | 2021-07       | tba        | tba                |
++-----------------------+----------------------+---------------+------------+--------------------+
+|Proxmox Backup 1.x     | Debian 10 (Buster)   | 2020-11       | 2022-08    | 2022-07            |
++-----------------------+----------------------+---------------+------------+--------------------+
+
+
+Can I copy or synchronize my datastore to another location?
+-----------------------------------------------------------
+
+Proxmox Backup Server allows you to copy or synchronize datastores to other
+locations, through the use of *Remotes* and *Sync Jobs*. *Remote* is the term
+given to a separate server, which has a datastore that can be synced to a local store.
+A *Sync Job* is the process which is used to pull the contents of a datastore from
+a *Remote* to a local datastore.
+
+
+Can Proxmox Backup Server verify data integrity of a backup archive?
+--------------------------------------------------------------------
+
+Proxmox Backup Server uses a built-in SHA-256 checksum algorithm, to ensure
+data integrity. Within each backup, a manifest file (index.json) is created,
+which contains a list of all the backup files, along with their sizes and
+checksums. This manifest file is used to verify the integrity of each backup.
+
+
+When backing up to remote servers, do I have to trust the remote server?
+------------------------------------------------------------------------
+
+Proxmox Backup Server transfers data via `Transport Layer Security (TLS)
+<https://en.wikipedia.org/wiki/Transport_Layer_Security>`_ and additionally
+supports client-side encryption. This means that data is transferred securely
+and can be encrypted before it reaches the server.  Thus, in the event that an
+attacker gains access to the server or any point of the network, they will not
+be able to read the data.
+
+.. note:: Encryption is not enabled by default. To set up encryption, see the
+  :ref:`backup client encryption section <client_encryption>`.
+
+
+Is the backup incremental/deduplicated?
+---------------------------------------
+
+With Proxmox Backup Server, backups are sent incrementally to the server, and
+data is then deduplicated on the server. This minimizes both the storage
+consumed and the impact on the network.

docs/file-formats.rst

@@ -6,7 +6,115 @@ File Formats
 Proxmox File Archive Format (``.pxar``)
 ---------------------------------------
 
-
 .. graphviz:: pxar-format-overview.dot
 
 
+.. _data-blob-format:
+
+Data Blob Format (``.blob``)
+----------------------------
+
+The data blob format is used to store small binary data. The magic number
+decides the exact format:
+
+.. list-table::
+   :widths: auto
+
+   * - ``[66, 171, 56, 7, 190, 131, 112, 161]``
+     - unencrypted
+     - uncompressed
+   * - ``[49, 185, 88, 66, 111, 182, 163, 127]``
+     - unencrypted
+     - compressed
+   * - ``[123, 103, 133, 190, 34, 45, 76, 240]``
+     - encrypted
+     - uncompressed
+   * - ``[230, 89, 27, 191, 11, 191, 216, 11]``
+     - encrypted
+     - compressed
+
+The compression algorithm used is ``zstd``. The encryption cipher is
+``AES_256_GCM``.
+
+Unencrypted blobs use the following format:
+
+.. list-table::
+   :widths: auto
+
+   * - ``MAGIC: [u8; 8]``
+   * - ``CRC32: [u8; 4]``
+   * - ``Data: (max 16MiB)``
+
+Encrypted blobs additionally contain a 16 byte initialization vector (IV),
+followed by a 16 byte authenticated encryption (AE) tag, followed by the
+encrypted data:
+
+.. list-table::
+
+   * - ``MAGIC: [u8; 8]``
+   * - ``CRC32: [u8; 4]``
+   * - ``IV: [u8; 16]``
+   * - ``TAG: [u8; 16]``
+   * - ``Data: (max 16MiB)``
+
+
+.. _fixed-index-format:
+
+Fixed Index Format  (``.fidx``)
+-------------------------------
+
+All numbers are stored as little-endian.
+
+.. list-table::
+
+   * - ``MAGIC: [u8; 8]``
+     - ``[47, 127, 65, 237, 145, 253, 15, 205]``
+   * - ``uuid: [u8; 16]``,
+     - Unique ID
+   * - ``ctime: i64``,
+     - Creation Time (epoch)
+   * - ``index_csum: [u8; 32]``,
+     - SHA-256 over the index (without header) ``SHA256(digest1||digest2||...)``
+   * - ``size: u64``,
+     - Image size
+   * - ``chunk_size: u64``,
+     - Chunk size
+   * - ``reserved: [u8; 4016]``,
+     - Overall header size is one page (4096 bytes)
+   * - ``digest1: [u8; 32]``
+     - First chunk digest
+   * - ``digest2: [u8; 32]``
+     - Second chunk digest
+   * - ...
+     - Next chunk digest ...
+
+
+.. _dynamic-index-format:
+
+Dynamic Index Format (``.didx``)
+--------------------------------
+
+All numbers are stored as little-endian.
+
+.. list-table::
+
+   * - ``MAGIC: [u8; 8]``
+     - ``[28, 145, 78, 165, 25, 186, 179, 205]``
+   * - ``uuid: [u8; 16]``,
+     - Unique ID
+   * - ``ctime: i64``,
+     - Creation Time (epoch)
+   * - ``index_csum: [u8; 32]``,
+     - SHA-256 over the index (without header) ``SHA256(offset1||digest1||offset2||digest2||...)``
+   * - ``reserved: [u8; 4032]``,
+     - Overall header size is one page (4096 bytes)
+   * - ``offset1: u64``
+     - End of first chunk
+   * - ``digest1: [u8; 32]``
+     - First chunk digest
+   * - ``offset2: u64``
+     - End of second chunk
+   * - ``digest2: [u8; 32]``
+     - Second chunk digest
+   * - ...
+     - Next chunk offset/digest

docs/glossary.rst

@@ -11,7 +11,7 @@ Glossary
    `Container`_
 
       A container is an isolated user space. Programs run directly on
-      the host's kernel, but with limited access to the host resources.
+      the host's kernel, but with limited access to the host's resources.
 
    Datastore
 
@@ -23,19 +23,19 @@ Glossary
       Rust is a new, fast and memory-efficient system programming
       language. It has no runtime or garbage collector. Rust’s rich type
       system and ownership model guarantee memory-safety and
-      thread-safety. I can eliminate many classes of bugs
+      thread-safety. This can eliminate many classes of bugs
       at compile-time.
 
    `Sphinx`_
 
-      Is a tool that makes it easy to create intelligent and
+      Is a tool that makes it easy to create intelligent and nicely formatted
-      beautiful documentation. It was originally created for the
+      documentation. It was originally created for the documentation of the
-      documentation of the Python programming language. It has excellent facilities for the
+      Python programming language. It has excellent facilities for the
       documentation of software projects in a range of languages.
 
    `reStructuredText`_
 
-      Is an easy-to-read, what-you-see-is-what-you-get plaintext
+      Is an easy-to-read, what-you-see-is-what-you-get, plaintext
       markup syntax and parser system.
 
    `FUSE`
@@ -51,14 +51,3 @@ Glossary
       A remote Proxmox Backup Server installation and credentials for a user on it.
       You can pull datastores from a remote to a local datastore in order to
       have redundant backups.
-
-   Schedule
-
-      Certain tasks, for example pruning and garbage collection, need to be
-      performed on a regular basis. Proxmox Backup Server uses a subset of the
-      `systemd Time and Date Specification
-      <https://www.freedesktop.org/software/systemd/man/systemd.time.html#>`_.
-      The subset currently supports time of day specifications and weekdays, in
-      addition to the shorthand expressions 'minutely', 'hourly', 'daily'.
-      There is no support for specifying timezones, the tasks are run in the
-      timezone configured on the server.

docs/gui.rst

@@ -0,0 +1,164 @@
+Graphical User Interface
+========================
+
+Proxmox Backup Server offers an integrated, web-based interface to manage the
+server. This means that you can carry out all administration tasks through your
+web browser, and that you don't have to worry about installing extra management
+tools. The web interface also provides a built-in console, so if you prefer the
+command line or need some extra control, you have this option.
+
+The web interface can be accessed via https://youripaddress:8007. The default
+login is `root`, and the password is either the one specified during the
+installation process or the password of the root user, in case of installation
+on top of Debian.
+
+
+Features
+--------
+
+* Simple management interface for Proxmox Backup Server
+* Monitoring of tasks, logs and resource usage
+* Management of users, permissions, datastores, etc.
+* Secure HTML5 console
+* Support for multiple authentication sources
+* Support for multiple languages
+* Based on ExtJS 6.x JavaScript framework
+
+
+Login
+-----
+
+.. image:: images/screenshots/pbs-gui-login-window.png
+  :align: right
+  :alt: PBS login window
+
+When you connect to the web interface, you will first see the login window.
+Proxmox Backup Server supports various languages and authentication back ends
+(*Realms*), both of which can be selected here.
+
+.. note:: For convenience, you can save the username on the client side, by
+  selecting the "Save User name" checkbox at the bottom of the window.
+
+
+GUI Overview
+------------
+
+.. image:: images/screenshots/pbs-gui-dashboard.png
+  :align: right
+  :alt: PBS GUI Dashboard
+
+The Proxmox Backup Server web interface consists of 3 main sections:
+
+* **Header**: At the top. This shows version information and contains buttons to
+  view documentation, monitor running tasks, set the language, configure various
+  display settings, and logout.
+* **Sidebar**: On the left. This contains the administration options for
+  the server.
+* **Configuration Panel**: In the center. This contains the respective control
+  interfaces for the administration options in the *Sidebar*.
+
+
+Sidebar
+-------
+
+In the sidebar, on the left side of the page, you can see various items relating
+to specific management activities.
+
+
+Dashboard
+^^^^^^^^^
+
+The Dashboard shows a summary of activity and resource usage on the server.
+Specifically, this displays hardware usage, a summary of
+previous and currently running tasks, and subscription information.
+
+
+Configuration
+^^^^^^^^^^^^^
+
+The Configuration section contains some system options, such as time, network,
+WebAuthn, and HTTP proxy configuration. It also contains the following
+subsections:
+
+* **Access Control**: Add and manage users, API tokens, and the permissions
+  associated with these items
+* **Remotes**: Add, edit and remove remotes (see :term:`Remote`)
+* **Certificates**: Manage ACME accounts and create SSL certificates.
+* **Subscription**: Upload a subscription key, view subscription status and
+  access a text-based system report.
+
+
+Administration
+^^^^^^^^^^^^^^
+
+.. image:: images/screenshots/pbs-gui-administration-serverstatus.png
+  :align: right
+  :alt: Administration: Server Status overview
+
+The Administration section contains a top panel, with further administration
+tasks and information. These are:
+
+* **ServerStatus**: Provides access to the console, power options, and various
+  resource usage statistics
+* **Services**: Manage and monitor system services
+* **Updates**: An interface for upgrading packages
+* **Repositories**: An interface for configuring APT repositories
+* **Syslog**: View log messages from the server
+* **Tasks**: Task history with multiple filter options
+
+.. image:: images/screenshots/pbs-gui-disks.png
+  :align: right
+  :alt: Administration: Disks
+
+The administration menu item also contains a disk management subsection:
+
+* **Disks**: View information on available disks
+
+  * **Directory**: Create and view information on *ext4* and *xfs* disks
+  * **ZFS**: Create and view information on *ZFS* disks
+
+Tape Backup
+^^^^^^^^^^^
+
+.. image:: images/screenshots/pbs-gui-tape-changer-overview.png
+  :align: right
+  :alt: Tape Backup: Tape changer overview
+
+The `Tape Backup`_ section contains a top panel, with options for managing tape
+media sets, inventories, drives, changers, encryption keys, and the tape backup
+jobs itself. The tabs are as follows:
+
+* **Content**: Information on the contents of the tape backup
+* **Inventory**: Manage the tapes attached to the system
+* **Changers**: Manage tape loading devices
+* **Drives**: Manage drives used for reading and writing to tapes
+* **Media Pools**: Manage logical pools of tapes
+* **Encryption Keys**: Manage tape backup encryption keys
+* **Backup Jobs**: Manage tape backup jobs
+
+The section also contains a subsection per standalone drive and per changer,
+with a status and management view for those devices.
+
+Datastore
+^^^^^^^^^
+
+.. image:: images/screenshots/pbs-gui-datastore-summary.png
+  :align: right
+  :alt: Datastore Configuration
+
+The Datastore section contains interfaces for creating and managing
+datastores. It also contains a button for creating a new datastore on the
+server, as well as a subsection for each datastore on the system, in which you
+can use the top panel to view:
+
+* **Summary**: Access a range of datastore usage statistics
+* **Content**: Information on the datastore's backup groups and their respective
+  contents
+* **Prune & GC**: Schedule :ref:`pruning <backup-pruning>` and :ref:`garbage
+  collection <client_garbage-collection>` operations, and run garbage collection
+  manually
+* **Sync Jobs**: Create, manage and run :ref:`syncjobs` from remote servers
+* **Verify Jobs**: Create, manage and run :ref:`maintenance_verification` jobs
+  on the datastore
+* **Options**: Configure notification and verification settings
+* **Permissions**: Manage permissions on the datastore